# Agent Branch

*Each run works on a copy-on-write branch. Only a reviewed merge reaches the main line.*

> **An Agent Branch** lets each run work on a copy-on-write branch. Changes reach the protected main line only through a reviewed merge (an Agent PR), and you can checkpoint and restore at any time.

**AN-02** · Conformance level: L0 Files · Cluster: Work

## The problem

Agents make mistakes at machine speed, and shared data has no way to “try it, see the diff, review, undo”. Parallel agents also step on each other.

In an April 2026 incident, an agent used an over-broad token to delete a production volume and the backups on the same volume within 9 seconds. If it could only have written to a branch, if deletes were soft, and if snapshots were outside its authority, that would have been far smaller.

## How it works

- **Branches are cheap** (depending on the engine, ideally close to O(1)). A lease grants writes **inside the branch** and `propose` towards the target.
- **Protected trees.** The main line can only be updated through a merge: even a leaked credential cannot write to it directly.
- **Agent PR.** The diff, intent, provenance (a read-manifest summary), check results and a label summary. If checks pass and policy allows, it merges automatically; otherwise it goes to a [Human Gate](https://agentnas.com/concepts/human-gate/).
- **Soft delete.** Deletes in a protected tree go to a recycle area, kept for 7 days by default; snapshots are owned by the owner and are **outside the authority of any lease**.
- **Checkpoints.** Named snapshots; `restore` rolls files back to a checkpoint.
- **Merging.** Text uses a three-way merge and other files merge per file. On conflict it stops and **never overwrites silently**; structured data needs a registered merger, or a person.
- **TTL and quota,** to prevent branch bombs.
- **Parallel attempts.** Open N branches for one task, merge the best and recycle the rest.

## Start small

- Git branches and worktrees, plus a **protected main** on Forgejo, Gitea or GitHub.
- For big directories use btrfs or ZFS snapshots and clones; for object storage use Tigris or lakeFS forks.
- Get “deletes go to the recycle area” and “snapshots belong to the owner” right first. They are the cheapest and prevent the most damage.

## Interface sketch

Illustrative only. Field names may change before specification v0.3.

*nas cli*

```bash
nas branch create cleo/release-notes --from main --ttl 48h
nas checkpoint create before-refactor
nas propose --into main --checks links,schema
nas restore before-refactor
nas trash list                    # recycle area, kept 7 days by default
nas trash restore <path>
```

## What the specification asks for

- A protected tree MUST be updatable only through a merge; no credential may write to it directly.
- A merge MUST produce a commit that carries provenance (run, lease, principal).
- No lease MAY allow deleting a snapshot or a backup.
- A delete in a protected tree MUST be soft and recoverable within the configured window (7 days by default).
- A conflict MUST NOT be resolved silently; the merge MUST stop and report.
- A branch MUST have a TTL and a quota.

## Borrowed, and what is new

What follows is all established practice. **What is new:** binding the branch to a **run and a lease**, so the branch is the unit of authorization and the merge is the unit of review. Branches and snapshots themselves are not new.

- [Git worktree](https://git-scm.com/docs/git-worktree)
- [lakeFS for agents](https://lakefs.io/agentic-ai/)
- [Tigris Agent Kit](https://www.tigrisdata.com/docs/ai/agent-kit/)
- [Cloudflare Artifacts](https://blog.cloudflare.com/artifacts-git-for-agents-beta/)

## Honest limits

- A branch only protects data inside the NAS. It **does not undo external side effects**: an email already sent, an API already called.
- Large binary files and database files are hard to merge.
- Review fatigue can still happen, so low-risk paths may merge automatically and the approval rate is measured.

## Open questions

- How are semantic mergers registered and trusted?
- How should interaction around binary conflicts work?

## Questions

### How is this different from a Git branch?

Mechanically it is not magic: you can build it on Git. The difference is that it ties the branch to one run and one lease, so “can only write its own branch” becomes an authorization rule and the merge becomes the single review point.

### Does a branch prevent every accident?

No. It only protects data inside the NAS: an email already sent or an external API already called is not undone by rolling back a branch. Such actions should go through `egress` in the lease and a Human Gate.

### Does every merge need a person to approve it?

No. A merge whose checks pass, whose run read no external content and that does not involve deleting or sharing can go through automatically. A person is needed only in a few cases; see [Human Gate](https://agentnas.com/concepts/human-gate/).

## Related concepts

- [Human Gate](https://agentnas.com/concepts/human-gate/): Appears only before irreversible, outward-facing or privilege-raising actions, and shows the real diff.
- [Agent Home](https://agentnas.com/concepts/agent-home/): A directory per role, with history. Plain files you can take with you.
- [Flight Recorder](https://agentnas.com/concepts/flight-recorder/): A per-run, hash-linked record that includes what the run read.

---

Canonical URL: https://agentnas.com/concepts/agent-branch/
Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0