Blog

Three trees, kept apart

A workspace, an agent, and a conversation each form a hierarchy. Conflating any two of them is the design bug that keeps coming back.

Bridge keeps three kinds of hierarchy, and the recurring design mistake is treating them as one. The workspace tree runs from a repository to a task worktree to a worker worktree. The agent tree runs from an orchestrator to the workers its policy authorized. The conversation tree runs from immutable entries to whichever branch is currently active.

They are related. They are not the same shape, they do not change together, and an operation on one does not imply a matching operation on another.

What that rules out

Forking a conversation changes the active history branch. It does not undo a filesystem change, revert a commit, or roll back provider state. Ending a session does not discard a worktree. Reclaiming a worktree is a decision the coordinator makes against the filesystem, never a side effect of a conversation moving.

That last one has teeth. Because branch refs survive reclamation, losing a checkout never loses a session its project.

Making divergence visible

If the trees can move independently, they can disagree, and the honest thing is to say so rather than paper over it. Every controller append stamps its entry with the repository HEAD and a deterministic hash of the full dirty state. A snapshot compares the selected entry's stamp against the current worktree, and a mismatch surfaces as conversation and file divergence.

Entries that predate the stamp are reported as unknown rather than assumed aligned. The stamp belongs to the controller, so it is stripped before anything is projected into an agent's context.

Why the separation is worth the cost

A single tree would be simpler to explain and would lie constantly. It would let a rewind imply a revert, and let ending a chat quietly delete work. Keeping the three apart costs a stamp on every append and a reconciliation path for every restart. What it buys is that no operation silently means more than it says.

The storage model and its projection rules are in docs/session-forest.md, and the retention policy that reclaims checkouts is in docs/worktree-lifecycle.md.