Parallel Isolation Is a Lifecycle Boundary, Not Just a Branch
Jul 16, 2026
Making parallel work safe is not just creating a branch earlier. The durable fix is a lifecycle isolation model: reserve identity before the first durable write, give each item its own worktree, treat the active worktree as execution truth, and prove ownership before any rollback deletion.
The problem
The first diagnosis sounded narrow: create the branch sooner so concurrent runs stop colliding. Branch timing helped, but it was not enough. Parallel work still mutated a shared source checkout, allocated identities from a partial scan, tied item directories and run artifacts to the wrong root, and allowed an existing item branch to quietly become the next item's source.
The real failure was a combined lifecycle issue. Identity reservation, checkout isolation, execution root, artifact placement, resume discovery, and rollback authority all had to agree. Changing only branch creation left the rest of the system on the old single-checkout model.
What actually happened
A single Git primitive looked attractive: create a branch and worktree in one step. Specification review found that pattern unsafe for production reservation. A failed combined command can leave a branch ref without a worktree — residue that later runs cannot cleanly claim or ignore. That forced a two-phase sequence: reserve the branch first, then add the worktree, with explicit ownership flags and residue inspection for each failure class.
The structural change was larger than the Git commands. The source checkout stayed stable. The active item worktree became the execution root. Build working directory, run-root placement, shared parser state, and resume discovery all moved from ancestry heuristics onto a single declared active-worktree resolver. Entry facades kept calling the same producer rather than inventing parallel kickoff logic.
Scope stayed tight even though many surfaces moved. Cleanup, garbage collection, doctor tooling, automatic reapers, historical migration, remote branch synchronization, and cross-host identity coordination were left out on purpose. Absorbing them would have turned an isolation fix into an unbounded operations program.
Safety also depended on negative behaviour. Verification had to prove that production code no longer used the unsafe combined primitive, that deletion required ownership proof rather than name matching, that legacy fallback did not widen, and that cleanup or doctor behaviour was not silently introduced. Build audit caught a real ownership bug: registered worktree residue could be removed without enough proof that the current run created it. Rework gated removal on ownership and non-preexistence, then added a regression that kept a pre-existing registered worktree alive through rollback.
Residual risks remain explicit: crash residue can still strand a branch ref; worktrees will accumulate until a dedicated cleanup item; run artifacts now live under the active item worktree; and merging reservation with worktree creation again would reintroduce the original failure mode.
The lesson
Parallel isolation is a lifecycle-boundary problem. Earlier branching is only one slice of it.
When concurrent runs share a repository:
- Reserve identity before the first durable artifact. Scanning incomplete directories, writing state first, or creating a worktree before the reservation commit point invites collisions and ambiguous residue.
- Do not treat a combined Git primitive as atomic unless failure modes are probed. If a command can create a ref and then fail before the worktree exists, split reservation from attachment and inspect residue classes explicitly.
- Keep the source checkout stable. Active work happens in a declared item worktree. Downstream consumers — working directory, run-root, parser state, resume discovery — must resolve through that declaration, not through directory ancestry.
- Require ownership proof for every deletion. Matching a branch name or registered path is not enough. Rollback may remove only what this run created and only when creation flags and preexistence checks agree.
- Separate cleanup from creation. Isolation kickoff should not quietly absorb doctor, reaper, or garbage-collection behaviour. Leave residual risks visible instead of claiming them solved.
- Verify negative guarantees as hard gates. Prove the unsafe primitive is absent, unowned deletion is impossible, legacy fallback stays constrained, and out-of-scope cleanup does not appear.
The broader principle
Lifecycle-boundary changes look local until parallel truth appears. When identity, roots, working directories, artifact locations, and Git mutation all move together, a facade patch or earlier branch switch will leave shadow paths on the old model.
Audits earn their keep here by testing assumptions before build and ownership after build. Spec review catching a false Git safety assumption, and build review catching unowned deletion, are the corrections this kind of change needs. Closeout should preserve residual risks explicitly when cleanup and hardening are intentionally deferred.
Not every item needs that weight. The same process is excessive for a small, single-surface fix. Use full specification and planning when the change touches scaffold authority, repo roots, parser state, worker cwd, durable artifact location, or Git mutation.
How to apply it
For similar isolation or worktree items:
- Treat checkout, worktree, and root semantics as lifecycle architecture, not a local Git convenience patch.
- Require an explicit “old behaviour blocked” section covering unsafe primitives, unowned deletion, widened fallback, and silent cleanup.
- Test success paths and residue/failure paths against real temporary repositories, not only mocked command output.
- Keep vocabulary precise: source checkout, active item worktree, item directory, run-root, build cwd, and parser truth are not interchangeable.
- Add a reusable checklist for reservation primitive, collision evidence base, ownership flags, rollback proof, residue classes, source-checkout mutation, worker cwd, run-root placement, and legacy fallback limits.
Parallel work becomes trustworthy when isolation is designed as a lifecycle contract — identity reserved first, execution rooted in an owned worktree, and rollback bounded by proof.
