The stream's worktree

What a stream's worktree is

A stream is one unit of work under one slug — the name that appears in the record, in the channel documents, and in every command about it. A stream's worktree is a working tree of your repository, on its own branch, forked from a named commit, at its own filesystem path. One stream, one worktree, one branch. Nothing else shares it.

At the root of that worktree the stream's channel documents sit side by side with the code: the order the agent works from, the status it returns, and — when the stream has a review lane — the reviewer's verdict. Those three are the subject of The channel documents. Inputs the coordinating role wants an agent to read, rather than to be told about, are placed in a .provision/ directory at the same root.

An agent that lands in a worktree therefore finds: a branch, a fork point, its order, and the files it was given. That is the whole of its world, and it is the point.

Who creates it

The coordinating role does — the master — before the agent is spawned, never the agent itself. Locally that is one pinned operation inside the product; onto a remote machine it is a dialled call that creates the tree over there. Either way the branch, the fork point and the path are decided by the dispatch and land in the record before an agent exists to have an opinion about them.

Why an agent never creates its own

Two reasons, and the second one is mechanical.

A worktree that an agent chose is a worktree nobody recorded. The whole value of the record is that "which commit was this work cut from" is answerable afterwards by someone who was not in the room. An agent that forks its own tree answers that question with its own memory.

And under path confinement it cannot. Creating a working tree writes outside the confined directory — it writes bookkeeping into the parent repository and it writes the new tree's own path — so the confinement layer refuses it before git runs. This is not a git error and no flag spelling gets around it.

⚠ An agent that genuinely needs a second tree — to read one commit while its own tree sits at another — has one reachable method, in this order:

git clone --shared --no-checkout <repo> <destination inside your confinement>
git -C <destination> checkout --detach <sha>
git -C <destination> rev-parse HEAD

--shared avoids re-copying the object store. --no-checkout keeps the clone off whatever branch happened to be current. The third line is the point, not a courtesy: a clone that silently landed somewhere else gives you a tree that looks right and answers every later question about the wrong code.