Orchestrating parallel coding agents across large repos

Direction locked: N≥2 write agents fanned into parallel worktrees of the same repo, including deliberately-designed SAME-FILE parallelism a shared checkout can never safely give. Merge ownership locked: the orchestrator reviews ALL code, merges the worktrees together, fixes or re-dispatches, then single-commits and pushes to the wave PR. This paper assembles the tooling survey, the orchestrator-owned merge ladder, an honest novel-systems verdict (including jj), and the minimal wave lifecycle we think earns its place.

v0.4 addendum — machine model proven: two workspaces, one machine, same branch (2026-08-01)

The model this paper designs for is now live evidence, not projection. On 2026-08-01 two workspaces on ONE machine ran concurrent orchestrators against the SAME repo (nexartis-ozzydev) on the SAME feature branch (feat/harness-phase4-bakeoff, PR #13): the 0724 workspace landed wave-1.6a/b harness work while the 0730 workspace landed the multi-workspace DX wave (ADR-014) — interleaved within hours, reconciled by re-fetch → fast-forward / rebase-of-unpushed, never force-push. What made it natural instead of fragile: per-workspace codesearch daemons + registries (ADR-012 §D-A — no cross-workspace lock contention after the legacy-daemon dissolve), a shared console + D1 with per-workspace ULID stamping, session IDs namespaced by workstream slug, wave-slug namespacing on every checkpoint, and the new content-aware staleness contract (D20 / ADR-014 D-A — a peer's commits no longer false-dirty this workspace's indexes when the delta has zero indexable content). The one-PR rule was clarified accordingly (ADR-014 D-D): it counts PRs, not branches or workspaces — a shared branch is the normal case. Cross-workspace repo visibility is D1-backed from this date (migration 0006): GET /api/repos/inventory/cross returned both workspaces' checkouts side by side in the live smoke. Remaining machine-model gaps honestly noted: the hint memo is per-process (cross-process memo is tech-debt open); orchestrator-owned branch hygiene on long-lived shared branches (when to cut fresh) is unwritten; the legacy machine-global codesearch daemon dissolves per-workspace as workspaces upgrade (0724/0728 still on it).

Problem statement — why same-repo parallelism is the hard case

• Git repository state is repo-global: the index, the stash, HEAD, the reflog, hooks, and (in practice) formatters, linters, and the validate gate all operate against the whole checkout. Two writers in one checkout share every one of those.
• Parallel coding agents therefore fail in ways parallel humans do not: an agent that observes another agent's in-flight edits has no consistent explanation for them, and its default corrective actions (revert, stash, format, clean) DESTROY the other agent's work silently.
• The optimisation surface has three axes we care about — reliability (no lost or corrupted work), context cost (orchestrator + subagent tokens per merged LOC), and parallelism ceiling (wall-clock speedup over a serial run). These pull against each other; no single isolation strategy is Pareto-dominant across all three.
• The 2026 vendor consensus for coding agents is worktrees. Anthropic ships a first-class --worktree flag and desktop app auto-worktree, OpenAI Codex ships desktop worktrees under $CODEX_HOME, Cursor Composer runs up to 8 parallel worktree agents, and a dedicated tool category — Claude Squad, Uzi, Crystal/Nimbalyst, Conductor, Vibe Kanban, gwq, workmux, ainb, cmux, GitButler — grew up around them. Cognition's "writes stay single-threaded per repo unless filesystem-isolated" rule is the substrate rule; worktrees are the accepted way to satisfy it.
• What the literature does NOT settle: (1) how the ORCHESTRATOR should merge N worktree branches when they may touch overlapping files by design; (2) how the same substrate should support deliberately-designed same-file parallelism (two agents on the same file, disjoint hunks); (3) whether git is even the right substrate — jujutsu (jj) colocated with git has first-class conflicts and cheap workspaces that fit the shape better on paper. This paper is our position on those three.

Case study — C8, the incident behind this paper

Cause

Wave A (benchmark fixtures) and Wave B (codesearch serve-HTTP adapter) ran concurrently in one checkout. Wave A's prompt named Wave B's file scope; Wave B's prompt NEVER MENTIONED Wave A. When B encountered A's in-flight edits, the only consistent explanation available to it was self-caused corruption — so it "cleaned up" (six git checkout -- reverts, a pathspec stash push, a final stash drop that discarded A's R2 work). Two structural amplifiers: Wave B ran repo-wide `pnpm run format` (write-mode prettier reformatted A's in-flight files, cementing the corruption theory); and both prompts required FULL repo-root `pnpm run validate` green before reporting — unsatisfiable while a parallel wave holds in-flight work, so Wave B ran root validate 16× and each failure drove further reverts.

Recovery

Verify-the-artifact held. Wave B's adapter work survived complete with a live-smoke artifact (25 hits via serve-HTTP), though its final report was lost to a trailing tool call (C3 pattern). Wave A's R2 code is recoverable from unreachable stash commits (b13315e / 219647d) and `_WORKSPACE-DOCS/patches/`. Zero permanent loss expected. Full record in `_WORKSPACE-DOCS/SUBAGENT-CRASH-LOG.md` (entry C8).

What C8 was NOT

• Same-checkout parallelism per se — prior sessions have run parallel same-checkout waves without damage.
• The 26 wmcp-bakeoff-* branches — older bakeoff-harness debris, unrelated to this incident, though evidence that worktree GC discipline matters.
• A "double-agent" branch switch — the git reflog shows ZERO checkout-branch entries during the incident window.

Design lessons

• The failure mode is orchestrator dispatch DESIGN, not the number of agents. A single subagent given the same prompt would have behaved identically the moment foreign dirty files appeared.
• A "final message = report text" restatement (from C3/C4/C5/C6) failed AGAIN on Wave B. Empty-report is now the highest-count KPI in the crash log.
• The fix set is structural, not procedural: worktree-per-wave (removes information asymmetry), package-scoped validate inside waves (removes the impossible-shared-gate), and orchestrator-owned merge/commit (removes the write-mode-command collision — subagents never format the repo because they never touch the main checkout).

Isolation-level taxonomy — decision matrix

Five levels of isolation for parallel writers on one repo. Scores are the orchestrator's current best estimate; (c) worktrees is the LOCKED direction and (b) shared-checkout is the explicit fallback. The experiment plan in §experiment-plan is what upgrades the scores from estimate to measurement.

Worktree-tooling survey — what already exists

Before we build, we survey. Our own worktree-mcp (adopted per D15 from joaopaulopresa/worktree-mcp) sits alongside the 2026 tool category. The honest read: it covers the lifecycle + the cross-worktree file-overlap detection cleanly, but leaves merge, package-manager hydration, and port pooling as orchestrator concerns. In the DECIDED direction, that split is right — the orchestrator owns the merge anyway.

Verdict: KEEP + EXTEND worktree-mcp for the lifecycle + overlap detection. Adopt mergiraf as our step-2 merge engine (out-of-repo, low-touch). Do NOT build another orchestrator-GUI — Conductor / Nimbalyst / Vibe Kanban exist. Watch workmux and gwq as reference implementations if we need to reshape the CLI later; consider borrowing Uzi's agents:N fan-out notation for the harness dispatch template.

Orchestrator-owned merge — the technique ladder

Merge is the load-bearing new work in v0.2. Every wave lands here. Escalate only on failure — steps 1–3 are automatable by the harness; steps 4–5 are orchestrator judgment.

1. 1. `git merge-tree --write-tree base A B`
   What: In-memory 3-way merge with the FULL git-merge feature set (rename detection, directory/file conflict handling, virtual merge base). Never touches the working tree or index. Exit 0 = clean, exit 1 = conflicts, exit >1 = error.
   When: ALWAYS FIRST — for every pair (and for every subsequent merge into the accumulated tree). Cheap enough to be default. Emits the resulting toplevel tree OID as stdout for commit-tree.
   Evidence: git-merge-tree(1) modern --write-tree mode (Git 2.38+, stable in 2.54): "Performs a merge, but does not make any new commits and does not read from or write to either the working tree or index." Directly composable via git commit-tree + git update-ref for a serialized apply loop.
2. 2. Structural merge via mergiraf (fall-through)
   What: When (1) reports conflicts, register mergiraf as merge=mergiraf in .gitattributes and re-run. Mergiraf parses via tree-sitter (25+ languages: TS/JS/Rust/Python/Go/YAML/TOML/HTML/JSON/…), resolves at the syntax-tree level, and falls back to line-based when it does not recognise the language.
   When: On conflicts flagged by (1). Especially effective on import-list collisions, adjacent function additions, and JSON/YAML key merges — exactly the shape of same-file parallelism (§same-file-parallelism).
   Evidence: mergiraf 0.16.3 (2026-01-26), Codeberg-native, actively developed. Haacked (2026-03-25) reports it eliminates the majority of textual false conflicts in a typical rebase; the LastMerge 2025 paper reports mergiraf ~42% fewer false-negatives than Spork on Java (generic tree-sitter parity with language-specific). Register once with a wildcard * in .gitattributes; safe fallback on unknown types.
3. 3. Serialised `git apply --3way` of collected diffs
   What: If mergiraf still flags conflicts, format each worktree branch as a diff series (git format-patch --stdout base..branch) and apply them serially with git apply --3way on the accumulated tree. This is the classic 3-way patch fallback and preserves per-hunk conflict markers for orchestrator review.
   When: On persistent conflicts. Useful when the semantics allow "apply A first, then B rebased on A" and we want ordering control.
   Evidence: git-apply --3way (documented since 2.0.x) does exactly a 3-way merge using the blob identities embedded in the diff — no need to have the branches locally, only the diffs and the base blobs.
4. 4. Orchestrator manual fix in the accumulated tree
   What: Orchestrator opens the conflicted region in the primary checkout (or a scratch worktree checked out from step-1's partial tree), reviews both sides, writes the resolution using its normal editing tools (§write-strategy rubric), and re-runs the package validate on the touched packages.
   When: On semantic conflicts the merge engine cannot resolve (both sides changed the same function body with different intent). This is judgement, not automation.
   Evidence: C8 lesson 3 (verify-the-artifact). The orchestrator is the last-mile writer for a reason: it holds the plan and the assumption-validation state.
5. 5. Re-dispatch a fix wave (worktree-per-fix)
   What: If the conflict indicates a plan defect (two branches were told to do overlapping work), the orchestrator does NOT hand-merge. It cancels the merge, updates the plan, and dispatches a new fix wave into a fresh worktree with the corrected scope.
   When: When conflict rate signals the fan-out was designed wrong, not just implemented wrong. High merge-conflict-rate KPI on this arm is the alarm.
   Evidence: Trunk parallel-merge-queues use "impacted targets" (which parts of the codebase a PR touches) to schedule mergeability; that same heuristic works pre-merge for us. High-conflict fan-outs are re-planned.

Same-file parallelism — safe by design (or not)

The operator explicitly wants same-file parallelism where it can be safe. The assumption-validation gate (§lifecycle-v2 step 2) partitions same-file work by shape BEFORE any subagent is dispatched. This section is the taxonomy of shapes.

• DISJOINT HUNKS in the same file (different functions / different regions) — SAFE with the merge ladder. `git merge-tree --write-tree` merges disjoint hunks cleanly; mergiraf handles adjacent hunks that a naïve textual merge would flag. The assumption-validation gate (§lifecycle-v2) pre-partitions the file by symbol (via serena find_symbol) and gives each subagent its symbol scope, mechanically guaranteeing hunk-disjointness.
• MECHANICAL / STRUCTURED EDITS across the same file (renames, import migrations, codemods) — SAFE. When the edits are expressed as ast-grep rules / codemods rather than free-form text, the operations commute — apply A then B, or B then A, get the same tree. Two subagents can each own a rule against the same file; the orchestrator runs both rules pre-merge and confirms the resulting AST is identical from either order. This is the highest-parallelism shape.
• OVERLAPPING PROSE (docs, this research page) — CONDITIONALLY SAFE. Section-scoped: each subagent owns a section header and the assumption-validation gate asserts that no other subagent will edit that header. Mergiraf handles Markdown lists/headings; the gate makes it structural. Free-form prose that could re-flow across sections is NOT safe and must be serialised.
• SAME FUNCTION BODY, DIFFERENT INTENT (two agents rewriting the same function) — NOT SAFE — this is speculative fan-out (level e), not same-file parallelism. Do it only when disagreement is the wanted signal, and pick a winner instead of merging.
• GENERATED / LOCK FILES (pnpm-lock.yaml, JSON snapshots, machine-written data) — BANNED. These files are outputs, not inputs. Two agents regenerating them will diverge on ordering / hashes even with identical intent. The orchestrator regenerates ONCE post-merge in the primary checkout; subagents commit source and package.json only.

Novel-systems verdict — beyond git worktrees

Operator directive: "perhaps we don't need a git-supported system — maybe there is something novel out there." Serious answers below, adopt/trial/hold per our newest-first-evidence-checked convention.

• jujutsu (jj) colocated with git — .git and .jj side by side
  Pitch: Working-copy-as-a-commit (no stash/index concept), operation log with undo, FIRST-CLASS CONFLICTS (a conflicted commit is a valid object, not a wedged state), automatic rebase-of-descendants when a mid-stack commit is edited, and workspaces (jj workspace add) that map cleanly onto the worktree shape. Colocated mode means git tools still see a normal git repo.
  Verdict: TRIAL — narrowly scoped, high leverage, real caveats.
  Trial shape: Run one implementation wave using jj workspaces instead of git worktrees, with the orchestrator merging via `jj new A B` (which produces a first-class-conflict commit that can be resolved incrementally). Measure the merge-conflict resolution latency vs. the git-worktree + merge-ladder path.
  Caveats: (1) Colocated workspaces are still on the tracking issue (jj-vcs/jj#8052) — need to confirm current status before trial. (2) Our memory tools (codesearch daemon-registry, serena per-repo projects, chunkhound live-watch) are all git-repo-shaped — need to confirm they treat a colocated dir as a normal git dir (highly likely) and that jj workspace dirs are indexable (open question). (3) The published agent-skill ecosystem for jj is thin and inconsistent (netresearch PRD reports scoring-out 23% for at least one stub skill in Jun 2026) — the skill layer is DIY. (4) `jj git push` semantics for a multi-branch fan-out are still evolving; the CI/PR handshake needs a first-day test.
• Sapling (Meta) with git-compatible backend
  Pitch: Stacked commits over a git remote, smartlog UI, EdenFS-scale performance, Rust core. Ezyang (Mar 2026) reports it makes parallel-worktree stack coordination "really easy" where git is "terrible".
  Verdict: HOLD. The stacked-PR win is real but tangential to same-file parallelism. Adopting sl adds a whole new client dependency for a benefit our wave PR model (one PR per repo per workstream) does not need. Revisit if we move to stacked-PRs-per-wave.
  Caveats: Sapling is not colocated — sl clones alongside git.
• GitButler virtual branches
  Pitch: Multiple virtual branches over a SINGLE working directory. Parallel-branch agents in one checkout via GitButler MCP + Agents tab.
  Verdict: HOLD as an isolation primitive (worktrees are still safer for same-file cases), but WATCH as a fallback for level (b) when the primary checkout must stay primary. GitButler acknowledges the isolation-vs-worktree question is open (their #12228 discussion).
  Caveats: Single working directory means the same repo-global-state problem C8 uncovered. GitButler mitigates via its own tracking but does NOT filesystem-isolate.
• APFS clonefile / cp -c / cow / cuttlefish / GhostVM
  Pitch: macOS APFS clonefile(2) creates instant, block-level CoW copies. A 5 GB repo cloned N times still costs ~5 GB until agents diverge. cow (joeinnes) and cuttlefish (pieter-ouwerkerk) package this specifically for parallel AI agents; each "pasture" gets node_modules, .env, and build cache for free (unlike git worktrees). Anthropic-verified pattern (Codex/Claude Code hooks integrate).
  Verdict: TRIAL — this is exactly the operator's "novel, non-git" shape. Agents work in a clonefile pasture; orchestrator diffs the pasture back into the primary checkout and commits to a wave branch. Native Mac + our workspace is Mac.
  Caveats: (1) Non-portable (Linux CI/agents would need reflink or fallback). (2) Not git-aware — the pasture is a filesystem copy, not a branch; orchestrator has to build the diff via `git diff --no-index` or per-file mtime scan. (3) Index-tool visibility (codesearch/serena) into pastures is unknown — the daemon-registry likely will not recognise a bare-copy path. Trial should include this measurement.
• CRDT-for-code (Yjs/Automerge as source-of-truth)
  Pitch: Truly parallel same-file editing with mathematical merge guarantees. No conflicts, by construction.
  Verdict: HOLD — overkill for our use case, and the tooling ecosystem (git, PR review, CI, memory tools) is not CRDT-shaped. The published state-of-the-art is still real-time-collab primitives (Yjs, Automerge, Loro), not code-as-CRDT. Revisit only if a substrate emerges that plugs into git remotes.
  Caveats: The merge ladder + assumption-validation gate + mergiraf already gets 90% of the same-file-parallelism win at 5% of the complexity.

The elegant wave lifecycle v2

The centerpiece. Ten steps, minimal. Every clause has to earn its place — the operator finds the v0.1 design clunky, and every subsequent revision has to defend itself against that critique. A = automatable by the parallel-waves harness; J = orchestrator judgment; A → J = automated with an orchestrator escalation path.

1. 1. Plan [J] — Orchestrator names the wave, lists files/symbols each subagent will own, and marks any deliberate same-file overlap with the intended merge shape (disjoint-hunks / mechanical / speculative).
2. 2. Assumption-validation gate [A + J] — BEFORE fan-out: the planned change is validated against existing conventions and design patterns (canonical architecture docs, AGENTS.md rules, ADRs). The harness runs a checklist (no defense-in-depth, no fallbacks/failovers, no repo-wide write-mode commands scheduled, no generated files owned by two subagents, disjoint symbol scope confirmed via serena find_symbol). Orchestrator signs off. If the plan fails the gate, it is revised or split before any code is written.
3. 3. Fan-out N worktrees [A] — worktree-mcp setup_workspace per subagent, base=dev, branch=wt/<wave>/<slug>. pnpm enableGlobalVirtualStore keeps setup fast; env / build-cache hydration follows the tool's .worktreeinclude (or an APFS clonefile pasture on the TRIAL arm).
4. 4. Subagents implement + package-validate + report [A] — Each subagent works in its worktree, runs `pnpm --filter <pkg> validate` only, and reports facts (files changed, diff summary, test counts, tools used + timings, context utilization). Subagents NEVER commit, NEVER push, NEVER format outside their scope, NEVER kill orchestrator-tracked daemons. Final message = report text.
5. 5. Orchestrator: collect diffs + review ALL code [J] — Orchestrator reads every subagent diff (git diff base..wt/<slug> per worktree) — this is where code review happens, before any merge is attempted. Findings that need a fix go back to the subagent (re-dispatch) rather than being patched over.
6. 6. Orchestrator merges — technique ladder [A → J] — Escalate: (1) git merge-tree --write-tree pairwise → (2) mergiraf structural → (3) git apply --3way serialised → (4) manual fix → (5) re-dispatch fix wave. Steps 1–3 automate; 4–5 are judgment. The merged tree is committed via commit-tree, not by checking out.
7. 7. Root validate on the merged tree [A] — Orchestrator materialises the merged tree in the primary checkout (or a fresh worktree from the merge commit), runs `pnpm run validate` at the repo root, and re-generates any generated files (lockfiles, snapshots) in ONE place.
8. 8. Single commit + push to the wave PR [J] — Orchestrator writes a squashed wave commit, pushes to the one open PR-to-dev for the wave. Subagents never touched origin.
9. 9. GC worktrees + branches [A] — worktree-mcp finish_workspace per subagent (confirms no unpushed commits, no stash entries), then cleanup_merged (dry-run first). This is now an ORCHESTRATOR step inside the merge phase — not a delegated post-wave task.
10. 10. Next wave [A] — Only after GC succeeds does the next wave start. No overlap between waves — the primary checkout is quiescent between waves by construction.

Dispatch-prompt contract — the eight clauses

Every concurrent-wave dispatch prompt includes these clauses. "Never commit, never push" is explicit (clause 4) per workspace AGENTS.md §4. C8 is what happens when clauses 1–3 are missing; the trailing clauses close C3–C7 reporting-loss and worktree-GC gaps.

1. Sibling-wave file sets ((b) fallback level; (c/d) when merging same-file by design) — Every concurrent dispatch prompt lists EVERY sibling wave's file scope in full. Asymmetric knowledge is the C8 root cause; symmetric knowledge is the fix. On level (c) with disjoint worktrees this is informational; on (b) it is load-bearing.
2. Foreign-dirty-file rule (all levels) — If git status shows files you did not create dirty, STOP and report. Never revert, format, stash, clean, or "unify" them. They belong to a parallel wave or to the operator.
3. Gate scope ((b) MUST; (c/d) SHOULD during concurrency) — During concurrency, waves run PACKAGE-scoped validate only (pnpm --filter <pkg> validate). Repo-root pnpm run validate is orchestrator-run POST-MERGE only. Requiring root validate green from a subagent is unsatisfiable and forces the C8 collision.
4. Never commit, never push (all levels — AGENTS §4) — Subagents NEVER commit, NEVER push, and NEVER open a PR. The orchestrator reviews all code, merges the worktrees together, ensures the wave is complete, corrects errors or re-dispatches, then commits and pushes once. This makes the write surface auditable and eliminates whole classes of race conditions.
5. Write discipline (rubric + scope) (all levels) — Restate the write-strategy rubric (a–h) from /research/write-strategies in every dispatch — twenty sequential single-line edits on one file is a rubric violation (use morph or weave-patch instead). Repo-wide write-mode commands (pnpm run format, prettier --write . , eslint --fix ., codemods, blanket import sorters) are BANNED inside a concurrent wave — format own paths only. Orchestrator runs any repo-wide format serially POST-MERGE.
6. Final-message = report text (all levels) — Your last message MUST be the report itself; do not end on a tool call. C3/C4/C5/C6/C8-B all lost final reports to trailing tool calls even when the convention was restated. Verify-the-artifact is the reliable defence; the prompt clause is the cheap first line.
7. Never-kill-processes (all levels) — Never kill or restart daemons or background processes you did not start yourself. Console :5173, serena :24283, codesearch :39725, chunkhound watchers, and any test-server the operator started are orchestrator-tracked infrastructure. Killing them silently corrupts a sibling wave.
8. Isolation self-report ((c/d/e)) — Report the exact worktree path or clone path you are writing into, and (for c/d) the branch name. Makes the orchestrator's merge audit — diff, stash list, untracked files — mechanical.

Ecosystem coherence — worktrees vs our stack

Worktrees are decided; these are the open sub-questions the trial has to close. Provisional positions below — measured in trial arm C.

• codesearch daemon-registry — Worktree paths are new project roots. Does `codesearch index --project <worktree-path>` register cheaply, or is the wave short enough that we skip indexing worktrees and only re-index the primary checkout post-merge?
  Position: PROVISIONAL: skip indexing during the wave (waves are typically <30 min, indexing latency is comparable), re-index primary post-merge. Measure orchestrator-tokens-per-merged-LOC to confirm this is the cheap path.
• serena per-repo projects — Each git repo currently has one serena project. Do we activate the primary repo's project from a worktree path (probably fine — the project is repo-shaped, not path-shaped)?
  Position: PROVISIONAL: yes, one project per REPO; activate from any worktree path.
• chunkhound live-watch — Chunkhound watches the workspace root. Worktrees are outside the primary checkout — do they add to the watch set, or are they explicitly ignored?
  Position: PROVISIONAL: worktrees live under a `.worktrees/` prefix (workspace-ignored, but individually indexable on demand). Chunkhound remains paused per D4 regardless.
• pnpm store — `enableGlobalVirtualStore: true` shares content across worktrees. Do we need per-worktree lockfile checks or is the global store lossless?
  Position: ADOPT global virtual store per pnpm docs + ArgoBox report; validate at merge time only.
• receipts / telemetry — `telemetry-emit.mjs` posts to console :5173. Does emission from inside a worktree path work? (Console is not repo-scoped, so almost certainly yes.)
  Position: CONFIRM in the first trial wave — should be free, but verify.
• validate gates — Package-scoped validate inside worktrees, root validate post-merge in the primary checkout. Any package with a build step that requires sibling packages to be built first will fail package-scoped — do we lift that class of package to orchestrator-only?
  Position: CONFIRM per wave; flag any package where `pnpm --filter <pkg> validate` cannot pass in isolation as a design-debt item for the sprint.

Gate design — package-scoped during concurrency, root at integration

Concurrent phase (inside worktrees): subagents run pnpm --filter <pkg> validate. Requiring repo-root validate from a subagent during concurrency is unsatisfiable and forces the C8 collision.

Integration phase (orchestrator): repo-root pnpm run validate is orchestrator-run on the MERGED tree, in the primary checkout (or a fresh worktree from the merge commit). This matches QA gate 2 in the release convention (AGENTS.md §3).

Formatters and codemods are writes. Repo-wide format is orchestrator-run post-merge only. Subagents format own paths only.

Recommended best practice for us

1. When one writer suffices, serialise (level a). Cognition's rule is the operator's rule for a reason: single-threaded writes eliminate the C8 failure mode by construction. Additional agents contribute intelligence (search, review, adversarial critique) — not actions.
2. When N ≥ 2 writers are dispatched, DEFAULT to worktrees (level c) via the adopted worktree-mcp + pnpm global virtual store + the orchestrator-owned merge ladder. This is the decided direction. Deliberately-designed same-file parallelism (disjoint hunks or mechanical edits) is safe HERE, in ways it can never be in a shared checkout.
3. Reserve shared-checkout parallelism (level b) as the FALLBACK when session-critical MCP daemons pin the primary checkout, or when the task is too small to justify worktree setup. Deploy the advisory lease + dispatch-contract before running two writers there.
4. Reserve separate clones / cloud VMs (level d) for adversarial arms (untrusted skills, harness bakeoffs) and for prod-hitting integration smoke where local secrets must not be present. Cognition's brain/machine split and Jules's ephemeral VMs are the reference implementations.
5. Reserve speculative N-fan-out (level e) for genuinely underdetermined tasks where disagreement is the signal. Context cost is N-fold; only spend it when the winning-arm signal is worth it.
6. The dispatch contract (eight clauses) and the assumption-validation gate apply at EVERY level. C8 is a level (b) failure that happened without either.
7. Trial jj colocated workspaces on ONE implementation wave against the same task, in parallel with a git-worktree control arm, and measure the merge-conflict-resolution latency. The novel-systems verdict on jj is TRIAL, not adopt — evidence-checked adoption per the workspace convention.

Experiment plan — upgrading scores from estimate to measurement

v0.2 adds three arms (jj colocated, APFS clonefile pastures, and second-order gate/ladder variation) and the merge-ladder-step-distribution KPI. The plan is the smallest experiment that establishes our defaults + validates the two TRIAL novel-systems calls.

1. Register "parallel-agent-orchestration" as an experiment paper_slug on /research/experimental-framework; register the seven KPIs above with numeric weights matching the reliability > context > parallelism ordering.
2. Design the task corpus: 8 tasks × 4 sizes (single-file, single-package, cross-package-in-repo, cross-repo), curated so each task has a KNOWN disjoint decomposition into 2–4 sub-tasks. Publish the corpus alongside the harness-bandit-experiments task set so results share fixtures. Include at least two DELIBERATELY SAME-FILE tasks (one disjoint-hunk, one mechanical-codemod) as the load-bearing tests for the new direction.
3. Arms: A=(a) serialise; B=(b) shared-checkout+leases via a Limen-shaped MCP; C=(c) worktrees via the adopted worktree-mcp + orchestrator merge ladder (DEFAULT); D=(d) separate clones via nexartis-remote-control; E=(e) N=2 speculative fan-out on top of C; F=(c) worktrees on jj colocated workspaces (TRIAL); G=(c) worktrees on APFS clonefile pastures via cow-shaped tool (TRIAL). Same KYM agent card, same skills, same memory stack — vary only isolation + substrate. Run the SWE-bench Pro standardized-scaffold slice as the external comparator.
4. Report all seven KPIs per arm per task class. Publish reliability × context × parallelism scatter with 95% CIs. Anything with lost-work > 0 fails hard, regardless of speed.
5. Second-order: hold arm=C and vary the assumption-validation gate (turn each clause on/off). Establishes which gate clauses are load-bearing vs cargo.
6. Third-order: hold arm=C and vary the merge ladder (skip mergiraf; skip merge-tree and go straight to checkout+merge). Confirms step 1 and 2 are load-bearing.

KPIs (register into /research/experimental-framework)

• lost-work-incidents-per-wave — Count of writes present in a subagent's report but ABSENT from the merged tree (or only recoverable from unreachable stash / patch backups). C8 = 1 (Wave A R2).
  The reliability floor. Any non-zero value on this KPI is a P0.
• foreign-file-touch-rate — Fraction of concurrent-wave subagents that git checkout -- , git stash push, git clean, or format-writes on a file they did not create. On level (c) this should be zero by construction (worktree-isolated); a non-zero value flags a subagent that reached outside its worktree — a dispatch-contract regression.
  Direct C8 metric. On (c) this should structurally be zero; watching it is the smoke-detector.
• orchestrator-tokens-per-merged-LOC — Orchestrator input+output tokens ÷ net LOC merged to dev (per wave). Compare across isolation levels a/b/c/d/e AND across merge-ladder-step distribution (how often does the wave land at step 1 vs step 4?).
  The context-cost axis. Merge-ladder step distribution is our new lever — a wave that lands at step 1 is cheap; step 4 is expensive.
• wall-clock-speedup-vs-serial — Wall-clock time for the wave divided by wall-clock time for the same work run as (a). Below 1.0 = parallel is winning; above = parallel is losing.
  The parallelism-ceiling axis. Zylos reports 50–70% wall-clock cut on decomposable work at 3–5× token cost; we would measure this ourselves.
• merge-ladder-step-distribution — Fraction of waves resolved at each ladder step (1: merge-tree clean, 2: mergiraf, 3: apply --3way, 4: orchestrator manual, 5: re-dispatch). New in v0.2.
  Reveals whether our fan-out planning is disjoint enough. A rising step-4/5 rate signals plan defect, not tool defect.
• empty-final-report-rate — Fraction of subagent runs whose final message is empty or a stray tool-call remainder. Currently 5 occurrences in the crash log (C3, C4, C5, C6, C8-B).
  Direct predictor of orchestrator recovery cost. The prompt clause helps but does not solve it; verify-the-artifact is the reliable defence.
• stale-branch-worktree-debris — Count of scratch worktrees / branches older than 24h at wave end. On the locked direction this is an ORCHESTRATOR responsibility inside the merge step, not a delegated post-wave task.
  GC discipline metric. Orchestrator-owned commit/push means orchestrator-owned GC.

Open decisions for the operator

AGENTS-1 reframed as FALLBACK level. AGENTS-2 is DECIDED-DIRECTION (worktrees) with open sub-questions. AGENTS-3 RECONCILED via the harness/KYM split — operational enforcement in the harness, dispatch-contract TEXT as KYM-versioned skill content (primary home: harness-bandit-experiments). AGENTS-4 revised per operator directive: orchestrator owns the merge/GC/commit/push end-to-end.

• AGENTS-1: "One checkout = one concurrent writer unless leased" as the FALLBACK rule when worktree isolation is impractical. Two or more concurrent subagents in one checkout MUST hold non-overlapping advisory path leases and MUST run PACKAGE-scoped validate only.
  Status: PROPOSAL — FALLBACK LEVEL. Worktrees are the locked default; leases are the fallback for the narrow case where a session-critical MCP daemon binds the primary checkout. Awaits operator sign-off as a rule; not yet enacted.
• AGENTS-2: Default all N≥2 concurrent writer waves to worktrees (level c) via the adopted worktree-mcp, with pnpm enableGlobalVirtualStore. Subagents own their worktree; the orchestrator reviews, merges (via the ladder), root-validates, single-commits, single-pushes, and GCs.
  Status: LOCKED DIRECTION (operator, 2026-07-15). Open sub-questions: (a) worktree indexing strategy for our memory stack (§ecosystem-coherence); (b) pnpm global virtual store adoption workspace-wide; (c) jj colocated trial (novel-systems). The direction is not conditional on those answers, but the defaults are.
• AGENTS-3: Reconciled with the operator architecture directive (primary home /research/harness-bandit-experiments §architecture-rule): the harness bakes the OPERATIONAL clause enforcement — worktree isolation via worktree-mcp, package-scoped vs root-scoped gate wiring, permission-driven never-commit/never-push/never-open-PR (OPENCODE_PERMISSION + hard-denied git push / gh pr create), never-kill-orchestrator-daemons via process boundary. The dispatch-contract TEXT itself (the eight clauses as prompt content) and the assumption-validation gate checklist are KYM-versioned agent-definition content on the orchestrator Agent Card, not baked strings inside the harness. A clause revision is a KYM skill version bump, not a harness PR.
  Status: RECONCILED. Split: enforcement in the harness (process boundary, permissions, gate scope); contract text in KYM (versioned skill on the orchestrator Agent Card). Roadmap: wave-harness-kym-split.
• AGENTS-4: The orchestrator OWNS the merge step end-to-end: reviews all subagent diffs, merges via the technique ladder, corrects errors or re-dispatches, root-validates, single-commits, single-pushes, THEN GCs worktrees/branches. Subagents NEVER commit or push.
  Status: RESOLVED (2026-07-16) — folded into workspace `AGENTS.md §4`. Operator directive is now the standing rule: the orchestrator reviews ALL code and performs every commit and push; subagents NEVER commit or push. Reflected in §lifecycle-v2 step 9 (GC inside the merge phase) and dispatch-contract clause 4.

Related research pages (do not duplicate — cross-link)

• Context Engineering — self-monitoring, handover-as-checkpointing
• Harness Bandit Experiments — the wave-launch substrate this study reuses
• Experimental Framework — KPI + variant schema this page registers into
• Write Strategies — the write rubric parallel agents must obey
• Scripts as Tools — scratch-worktree lifecycle scripts belong to this loop
• Working with Large Codebases — index freshness under branch switches

How this page stays current

Living white paper. v0.1 assembled the internal C8 forensics, external SOTA scan, and the initial decision matrix. v0.2 folded in the operator directives — worktrees decided, orchestrator-owned merge, assumption-validation gate, novel-systems verdicts, minimal lifecycle. v0.3 (2026-07-16) is the publication pass: C8 compressed to cause/recovery/lessons, dispatch contract normalised to eight clauses, AGENTS-4 RESOLVED (folded into workspace AGENTS.md §4: orchestrator reviews ALL code and performs every commit and push; subagents NEVER commit or push). v0.4 lands measured KPI values from the experiment plan (arms A–G including jj and clonefile trials) and folds the winning defaults into workspace AGENTS.md §4 with operator approval.