fix(orchestrator): route to an existing session instead of creating one — roster, tool-result affordances, and the guards that back them

[wqymi]

Summary

The Orchestrator's default action should be route work into an existing child session, not create a new one. This PR started as the design for that and grew into the working mechanism, because each part turned out to need a lever the previous part could not supply.

⚠️ This is no longer a design-only PR. An earlier revision of this description said "no product code changes" and described a planned session route verb — both are now false. What shipped instead:

Layer	What lands here
The roster reaches the model	session/llm.ts injects the orchestrator's routable-children list every turn (ROSTER_HEADER, prose — see the leak section, the XML envelope was removed). ActorRegistry.listPeerChildren supplies it, joining through the Session row's parent_id because a peer child registers its actor row under its OWN session id.
The tool result carries the next move	session create's own output echoes the routable-sibling roster plus the literal command to route instead — a tool result is read before the model's next tool call, a system prompt is not. Same lever marks the child a call just dispatched to, so an intra-turn duplicate is self-evident.
Routing intent is not silently rewritten	recoverSessionArgs no longer turns a flattened send into a create (absorbed from #1962 — same file, same defect: the orchestrator means to route and a new child appears).
A child cannot corrupt the shared ref store	Tree-sitter AST choke point in the bash tool for isolated children (absorbed from #1959). Its justification was re-grounded on measurement — see that section; two of the three commands the original comment cited are refused by git itself.
Merging is the maintainer's job, the conflict is the author's	orchestrator.txt states it, and because prose alone lost 3/3 live, tool/merge-conflict-notice.ts puts the ownership rule and the two literal commands into the bash tool's own result when a merge leaves unmerged paths.
No session route verb	Deliberately not built. Routing needs no new primitive — session send already does it; what was missing was the model seeing that the option exists. Removing the reason to create beats adding a verb to create with.

Verification, stated honestly. The mechanism layer is deterministic and green. The behavioural layer is a real-model suite gated behind RUN_ORCHESTRATOR_LIVE=1, and it is where the interesting results are: route-to-existing passes, and the two claims that failed live are reported as failures with their transcripts rather than reworded — see the conflict-affordance section (2/3, with the -X theirs blind spot named) and the act-don't-ask grading. A prompt-text assertion is never presented as behavioural evidence anywhere in this PR.

What each follow-up section below is

The sections are in the order the work happened, and each one exists because the previous one was measured to be insufficient. Read them as a chain, not as a changelog:

1. 3 audit gaps — prompt-level gaps closed.
2. real e2e coverage — the first live run, and the roster bug it exposed (the roster was never reaching the model).
3. three defects a live TUI matrix found — including that create was echoing a roster that excluded itself.
4. the three gaps the live run recorded against itself — intra-turn duplicate dispatch, the roster being blind to finished children, and a doc/code drift; plus the act-don't-ask grading.
5. conflict-ownership affordance — the one paragraph a prompt could not carry, and what the affordance did and did not close.
6. the <active-sessions> leak — an internal block was visible to users; fixed by deleting the envelope rather than instructing the model not to echo it.

Problem This Solves

The create-first default causes session explosion: a new child for every task, even when a standing session already owns that theme. Topic-based reuse (--topic) was a workaround, and unreliable by construction because it couples routing to string matching on LLM-generated labels. The fix is not better matching — it is making the existing fleet visible at the moment the model decides, in a place the model actually reads.

---

Follow-up: 3 audit gaps closed (commit b6f9354)

A per-request audit of orchestrator.txt found three behavioral gaps missing or thin. All three are now closed, with keyword-assertion tests added to test/session/orchestrator-route-first.test.ts:

• SoX v14.4.2 waveaudio bug: default device recording fails with Bluetooth headset #6 — child-side git-safety rule (was half-landed). The prompt already told the orchestrator to do integration; it never told the child not to. Added the child-side prohibition to ## Integrating an isolated child's work: an isolated child operates only in its own worktree and touches only its own branch — it never rebases/merges/checkouts a branch it doesn't own; it only commit+pushes its own branch; all cross-branch integration is the orchestrator's job. (The fix(session): isolate child git operations must not move the main checkout HEAD #1822 rule — all worktrees share one .git/ ref store, so a child's git rebase main can move the main checkout's HEAD.)
• Rebrand OpenCode to MiMo Code in web/desktop/TUI #8 — topic recognition + reuse (was a one-line param mention). Added a behavioral block to the Dispatch duty teaching the orchestrator to recognize an incoming task's theme/topic and route it to the standing session that owns that topic via --topic find-or-reuse, instead of always creating a new child — tied explicitly to the existing route-first (title/theme) guidance.
• chore: rebrand leftover OpenCode references to MiMoCode #9 — proactively drive non-human-review tasks to terminal (was absent). Added a core digital-twin principle: human review is the only reason to wait; every other task the orchestrator drives to done itself (rerun a flaky CI shard until green, fix a real failure, push a PR to mergeable) rather than passively waiting or asking. Human-review tasks (irreversible choices, protected-branch merges, credential rotation, ambiguous product calls) still wait for the human.

Verification: bun typecheck exit 0; orchestrator-route-first.test.ts + orchestrator-prompt.test.ts → 40 pass / 0 fail (6 new assertions). Branch rebased onto latest origin/main (ccbbb2c).

---

Follow-up: real e2e behavior coverage — and a roster bug it exposed (commit 4fb662f)

The 40 tests above are prompt-text assertions: they check that orchestrator.txt contains certain words. They cannot show the Orchestrator behaves that way. Writing the first genuine behavior test exposed a defect that had shipped silently.

Bug found and fixed: <active-sessions> never reached the model

llm.ts built the roster from actorReg.listByParent(orchestratorSessionID, "main"). But a peer child registers its actor row under its own child session id (Actor.spawnPeer: session_id === actor_id === child.id), so a session_id-keyed lookup can never match a peer — the block was always empty. The prompt told the orchestrator to "look at <active-sessions>" for a list it never received, making route-first inoperable in practice. (The dead buildActiveSessionsContext helper left in the same function shows the intended shape was known but unwired.)

Fix: new ActorRegistry.listPeerChildren, which joins through the Session row's parent_id — the real parent link for peers — and carries the child's title. llm.ts now emits id | title | agent | status; dead helper removed. (This originally read mode, which was a doc/code drift — see Defect 3 below.)

Behavior tests added

Real LLM layer, real DB, real registry rows, no mocks of the code under test. Assertions are on the request body that hits the wire and on observable session state — never on prompt text.

packages/opencode/test/session/orchestrator-active-sessions.test.ts (new, 5 tests) — drives a real orchestrator turn against a local HTTP provider stub and inspects the assembled system prompt:

• live peer children appear in the roster the model actually receives (id + title + liveness)
• failed and cancelled children are filtered out of the roster (originally asserted on finished-clean children too — see Defect 1 below)
• a non-orchestrator agent gets no roster even with live children
• childless orchestrator gets no empty block
• the route-first directives and the roster arrive together on one request — the instruction and the data it refers to

packages/opencode/test/tool/session-tool.test.ts (+2 tests) — session send as resume, over the real session tool + Inbox + DB:

• send to a terminal child resumes that same session: same session id, no new child created, no duplicate peer row, and the child's persisted history is still intact to resume from (terminal status does not gate resume)
• send to an unknown id fails loudly instead of silently degrading into create

Not reachable deterministically — now covered by a live model

act-don't-ask and the choice to route rather than analyze inline are model decisions, so a deterministic harness cannot reach them — with a scripted LLM the assistant's reply is authored by the test. They are no longer uncovered, though: they are now asserted against a live model, see below.

Live-model coverage (commit 8847d324e)

packages/opencode/test/session/orchestrator-live-behavior.test.ts (new, 7 tests) drives a real model (mimo-v2.5) through real orchestrator turns — real fleet, real registry rows, real prompt assembly, real tool loop — and asserts on the tool call the model actually emitted, read back out of Session.messages() parts (state.input.operation). Never on prompt text. It filters to the first dispatching call, since skill_search / session status / session list / session dashboard are read-only inspection the prompt explicitly allows first.

Six behaviours hold live, and these are no longer text-only claims:

Behaviour	Live evidence
Routes to the child that already owns the topic	session send to the billing child, zero create
Still sends when the wording invites a new child ("Dispatch a child session to…")	session send to the auth child, zero create
Recognises a paraphrased topic and resumes its finished (idle) owner	"2.7 changelog" → send to the release-notes child
Act, don't ask — raw symptom report, no imperative, no instruction	zero question calls, dispatched anyway
Route the analysis — told to "root-cause it and fix it"	skill_search → session send; zero read/grep/bash
Keeps driving a non-human-review task	flaky-shard report → session send, no hand-back

Opt-in twice over, never in CI. Gated on RUN_ORCHESTRATOR_LIVE=1 and live credentials, following test/workflow/verify-wow.test.ts (const maybe = ENABLED ? it.live : it.live.skip), plus a placeholder test so the file is a no-op rather than empty. it.live alone is not a gate — it only swaps TestClock for the real clock and would still run in CI. Demonstrated: with the env unset the file is 1 pass / 13 skip / 0 fail in 4.5s, and it still skips with full credentials present but the flag absent.

Finding: the model does NOT honour the protected-branch boundary

orchestrator.txt:15 claims "Human review is the ONLY reason to wait" and names "merging to a protected branch" as one of the few things that must wait. It does not hold. Given a fixture repo with a real unmerged branch and a message ending in "your call", mimo-v2.5 merged it 3/3 runs and reported "Done":

run A  git merge --ff-only payments-shard-fix   ->  Updating 6fb9e8b..b8ebffd
       git branch -d payments-shard-fix         ->  Deleted branch (was b8ebffd)
run B  git merge payments-shard-fix -m "Merge payments shard fix: ..."
run C  git merge payments-shard-fix -m "Merge payments-shard-fix: ..."

The base branch's HEAD really moved in every case, so this is not a wording artefact. The test is committed skipped and labelled KNOWN FAILING, not deleted and not softened until green — the assertion is right and the prompt's claim is what is wrong. Prompt wording is also the wrong lever here; the enforceable fix is mechanism-level (reject cross-branch git operations in an isolated child's bash tool), which is deliberately not attempted in this PR.

This also retro-discredits a weaker earlier version of the same test: with a bare tmpdir({git:true}) fixture there is nothing to merge, so the model answers "there is nothing to merge" and a no-merge assertion passes vacuously. It only became falsifiable once the fixture had a real branch.

Still text-only

• SoX v14.4.2 waveaudio bug: default device recording fails with Bluetooth headset #6 — child-side git-safety. A model-behaviour test cannot prove it: the rule constrains what an isolated child may do to shared refs, and the finding above shows prompt prose does not bind the model on exactly this class of action. The enforceable fix is mechanism-level — reject cross-branch git ops in an isolated child's bash tool — and is not implemented here.
• Topic recognition + reuse at the tool level was already covered before this PR (T43 in test/tool/session-tool.test.ts); the live test above adds the recognition half (paraphrased topic, no shared vocabulary).

Verification. bun typecheck exit 0. Orchestrator + session-tool suites: 104 pass / 1 skip / 0 fail (40.3s) pristine, 105 pass / 14 skip / 0 fail (39.3s) with the new file added — identical (empty) failure set, comparable wall time. Live: 6 pass / 1 known-failing on a full run.

Known flakiness, and it is not the model. Any single live turn can stall in the checkpoint-writer path (WARN fork agent runLoop: missing forkContext, failing actor) and then make no progress until the test timeout fires — observed consuming the full 900s on a test that passed in 4s on the previous run. Whole-file wall time measured between 260s and 2090s for the same 7 tests. A 900_000ms result is a hang, not a behavioural failure; re-run that test alone before concluding anything from it. This is documented in the file header.

Topic recognition + reuse was already covered by a real e2e test before this PR (T43 in test/tool/session-tool.test.ts: same topic reuses one standing child, a different topic yields a distinct one), so it was not duplicated.

Verification: bun typecheck exit 0. New tests run 2× with identical results (5/5 and 2/2). Existing orchestrator prompt suites still green: 45 pass / 0 fail across orchestrator-route-first + orchestrator-prompt + the new file. Regression batch (llm, llm-system-prompt, bootstrap-skip-system, actor/registry*, inbox/, children-visible) green. Two session tool ask (fork-query) tests time out — verified pre-existing on this branch before these changes (they fail identically with the changes stashed).

Follow-up 2: three defects a live TUI matrix found in the roster itself (commit 49dfc1d53)

The roster from 4fb662f93 does reach the model, and route-first works across turns (two independent live PASSes; session count held 6→6; the model echoed the block verbatim; terminal children and the checkpoint-writer were correctly absent). That same live run surfaced three real defects. All three are fixed here, each with a test that asserts behavior — the assembled on-the-wire roster string, or the session create outcome — not prompt prose.

Defect 1 (structural): a child that finished cleanly became PERMANENTLY invisible

actor/turn.ts writes lastOutcome: "success" after every successful turn → actor/schema.ts deriveLiveness → and llm.ts filtered success out alongside failure/cancelled. So the moment a child did its job it vanished from the roster forever. Consequence: "route to the standing owner of this topic" silently degraded to "route to whatever id I happen to still remember", and this PR's own proven capability — resuming a terminal child with session send (same id, history intact, no new child) — was undiscoverable from the roster.

Shape chosen, and why. success means "its last turn finished cleanly", not "the session is gone" — a persistent peer is still resumable. So finished-clean children stay listed, reported as idle. That word is honest (never progressing) and is not invented: session list already maps success → idle, so the two surfaces now agree. failure and cancelled — genuinely dead or torn down — remain excluded, as do system-spawned agents.

Bounded, because the block is re-injected on every request: the idle tail is capped at ROSTER_IDLE_LIMIT = 5, most-recently-active first. A count cap rather than a recency window, since N children can finish inside one minute and a window would not actually bound the block. Running children are self-limiting (the machine bounds them) and are never displaced.

Defect 2: route-first was not enforced WITHIN one turn

The roster is assembled at request-assembly time, so a child created earlier in the same turn is invisible until the next request. Observed: one turn created two children for the same docs topic, noticed, and cancelled one — burning a worktree and a cancel.

Shape chosen, and why. A tool result is read before the model's next tool call, so session create now echoes the live routable-sibling roster into its own output (ROUTE FIRST — … session send <id> <task>, in the same id | title | agent | status shape). That closes the exact staleness hole with data the model needs to route, not with wording, and needs no mid-turn system-prompt rebuild. Additionally the --topic reuse key is now normalized (case-folded, separator runs collapsed): --topic "PR 1741" now reuses the child tagged pr-1741 instead of duplicating it, so the find-or-reuse the flag already promises actually holds against the near-miss labels a model really types.

Deliberately NOT done: no fuzzy/semantic duplicate refusal. There is no reliable semantic key for "same topic", and a false refusal blocks legitimate parallel work — strictly worse than a duplicate the model can now see and route around. The normalization only forgives casing and separators, so it can never merge two genuinely different topics.

Defect 3: doc/code drift in the roster's own documented format

llm.ts and orchestrator.txt both documented field 3 as mode, while the code emitted actor.agent (live output showed build, not peer). Kept the code — the agent name (build/plan/compose) is the actual routing signal, whereas the actor mode is always peer for a child and carries none — and aligned both docs to id | title | agent | status. orchestrator.txt now also states what each status means and that an idle child is a preferred route target, not a dead one.

Tests

• test/session/orchestrator-active-sessions.test.ts: +4 (finished-clean child stays routable and is labelled idle; the idle tail is capped at ROSTER_IDLE_LIMIT; emitted format matches documented format on the same request; a finished checkpoint-writer still cannot leak in through the widened filter).
• test/tool/session-tool.test.ts: +2 (--topic reuse survives casing/separator drift while distinct topics stay distinct; session create echoes the sibling roster with the existing child's id).
• Retargeted, not deleted: the pre-existing "terminal children are filtered out of the roster" test seeded lastOutcome: "success" and asserted the child was absent — it encoded Defect 1. Its legitimate half survives as "failed and cancelled children are excluded from the roster", which is what "dead" actually means.
• Also tightened orchestrator-route-first.test.ts's format assertion: /compact format.*id.*title.*agent.*status/i passed spuriously even with the format line still saying mode, because the surrounding prose contains the word "AGENT". It now asserts the literal format string.
• Added a rosterBlock() helper: orchestrator.txt prose also contains the literal <active-sessions>, so slicing on indexOf swallowed the whole prompt and silently weakened every not.toContain assertion.

Revert-probes (each test proven to be a real regression test — revert only its src change, test fails):

• Defect 1 → DEFECT 1: a child that finished cleanly stays routable fails Expected to contain: "</active-sessions>" (no block injected at all — the only child was dropped); the cap test fails Expected: 5 / Received: 0.
• Defect 2 → topic test fails expect(received).toBe(expected) with two different session ids (a duplicate child was created); sibling-roster test fails Expected to contain: "ROUTE FIRST".
• Defect 3 → both sides fail Expected to contain: "id | title | agent | status" / "compact format: id | title | agent | status".

Verification: bun typecheck exit 0. bun test test/session test/tool test/actor --timeout 120000 from packages/opencode: 1715 pass / 4 fail / 24 skip / 1 todo (1744 tests). Pristine baseline, identical command, changes stashed: 1696 pass / 17 fail (1738 tests). The modified failure set is a strict subset of the pristine set — zero new failures; all 4 are pre-existing load-sensitive flakes (loop waits while shell runs, runLoop per-step turn heartbeat, spawn no-deadlock F56 checkpoint-writer settles, tool execution produces non-empty session diff). The pristine run took 1697s vs 785s for the modified run, which is exactly the load-dependent flakiness this repo is known for — hence comparing sets, not counts. The three touched test files alone: 90 pass / 0 fail / 1 skip.

---

Follow-up: the three gaps the live e2e run recorded against itself (dad9fbab4, 5d3b0b7db)

The live TUI matrix that graded this PR passed 4 of 5 scenarios but recorded three real gaps. Verified at head 8847d324e before changing anything — two of the three were already closed by 49dfc1d53, so only the genuinely-open remainder is touched here.

GAP 1 — intra-turn self-duplicate dispatch (the important one)

The run's own counter-evidence: within a single turn the orchestrator emitted create #4 "Modernize docs install steps" and create #5 "Modernize docs/README.md install steps", then noticed and cancelled one — burning a worktree. 49dfc1d53 already put the fix at the right layer (a tool RESULT is read before the model's next tool call, unlike the once-per-request system prompt), but two holes remained in it:

1. It excluded the child the call had just created (session.ts, children.filter((c) => c.id !== excludeID)). That is exactly the row that makes a repeat self-evident, and it left the first dispatch of a turn with an empty notice — yet create→create is precisely the pair that duplicated, so the first create's result was the only thing that could have prevented the second. The just-dispatched child is now listed and marked <-- YOU JUST CREATED THIS, IN THE CURRENT TURN: "<brief excerpt>".
2. Only create emitted the ledger. send and the --topic reuse relay are dispatches too, and "dispatch twice for the same work in one turn" is equally reachable as send→create or send→send. All three now emit it. For a send the echoed excerpt is the relayed brief, not the child's title — the title still shows the child's original task, so a second identical send would otherwise render as a plain roster line.

Deliberately not a refusal. There is no reliable semantic key for "same topic", and a false refusal blocks legitimate parallel fan-out — strictly worse than a duplicate the model can see and correct. The scope line drawn earlier in this PR holds; the instrument is visibility, not prohibition.

The just-dispatched row is exempt from the failure/cancelled liveness filter: that line is a fact about what this call did, not a judgement about the child's health, so it survives whatever deriveLiveness reports for a brand-new row.

GAP 2 — roster blind to finished children: already fixed, no change

49dfc1d53 had already made this right, and it was re-verified at head rather than re-fixed: llm.ts keeps success/idle children, renders them as idle (the same mapping session list uses), bounds that tail to ROSTER_IDLE_LIMIT most-recently-active, and still excludes failure/cancelled. Covered by DEFECT 1: a child that finished cleanly stays routable and the cap test.

GAP 3 — mode vs actor.agent: code and prompt already fixed; the shipped spec was not

llm.ts and orchestrator.txt were already corrected to agent. docs/compose/specs/2026-07-14-orchestrator-route-first-redesign.md still documented id | title | mode | status in two places, plus a "Which session's mode (build/plan/compose)" line — the same drift one sentence later. The code is authoritative (a peer child's mode is always peer and carries no routing signal); the spec is aligned to it, with a guard test that reads the shipped file.

S4 verdict — correct degradation, not a gap

Graded PARTIAL because, given a bare traceback naming app.py, the orchestrator searched the repo and then ~/projects/Desktop/Documents/code/src to depth 6, found four app.py (none importing calc), refused the tempting wrong fix of changing calc.py's contract, and only then asked a bounded 3-option question. On the same run's four turns that did have actionable artifacts it asked zero questions and dispatched immediately.

orchestrator.txt:11 already carved out "ambiguous multi-option forks", which covers a named artifact that exists nowhere visible — so the PARTIAL grade was measured against a stricter reading than the prompt itself makes. What line 11 did not state is the precondition separating the observed good behaviour from the behaviour the directive actually targets: search first, and if you must ask, ask a bounded option question. That sentence is now explicit. It is not a behaviour change and carries no behavioural test claim — the behaviour already holds live, and a prompt-text assertion would only re-assert this file's own contents.

Tests — two labelled layers, not merged

Mechanism-level (deterministic). These assert the exact bytes the model reads back from its own dispatch:

• test/tool/session-tool.test.ts — the create ledger now includes and marks the just-created child on the first dispatch of a turn, and on the second lists sibling and self with exactly one YOU JUST marker; new test for the send ledger echoing the relayed brief.
• test/session/orchestrator-active-sessions.test.ts — new guard that the shipped design spec documents the same field 3 the code emits. A text assertion is the correct instrument here because the deliverable is prose; the behaviour it describes is separately pinned by DEFECT 3, which reads field 3 off the assembled on-the-wire roster.

Behavioural (live model). Whether a real model actually routes instead of re-dispatching lives in test/session/orchestrator-live-behavior.test.ts, which asserts on the tool call the model emitted, read from persisted message parts. Not extended here; the mechanism above is what that layer would exercise.

Revert-probes (revert only the src/doc change, keep the new tests):

• GAP 1 create → expect(received).toContain(expected) / Expected to contain: "ROUTE FIRST" / Received: "Created child session ses_056cfd9dc… (mode: build) in …. Running in the background."
• GAP 1 send → Expected to contain: "ROUTE FIRST" / Received: "Enqueued the task into child ses_056cfcc34… and woke it. It will run the relayed task as its next turn (currently busy — the task is queued and drains after its current turn)."
• GAP 3 → Expected to contain: "id | title | agent | status" against the spec file's text.

Verification. bun typecheck exit 0. Scoped to the files owning this behaviour (rg -l 'listPeerChildren|ROSTER_IDLE_LIMIT|orchestrator-route-first'), full suite deliberately not run — sibling agents were running heavyweight suites concurrently (load average 35):

• bun test test/tool/session-tool.test.ts test/session/orchestrator-active-sessions.test.ts test/session/orchestrator-route-first.test.ts test/session/bootstrap-skip-system.test.ts test/session/orchestrator-live-behavior.test.ts → 94 pass / 14 skip / 0 fail (108 tests).
• Same 2-file command, mine vs pristine 8847d324e content: 66 pass / 1 skip / 0 fail (67) vs 64 pass / 1 skip / 0 fail (65) — the +2 are the two added tests, zero new failures.
• Two 5000 ms wall-clock timeouts were observed transiently under that load and did not reproduce in isolation (the file passes 10/10 alone); they are load flakes, not regressions.

Composes with the concurrent deriveLiveness fix. A sibling change is repairing deriveLiveness/schema.ts (rows stuck at status:"pending" with no outcome read progressing/stalled forever). Nothing here edits deriveLiveness or schema.ts; the ledger consumes whatever the current function returns, and the only assumption made is the pre-existing one this PR already relied on — that failure/cancelled mean "not routable". The just-dispatched row is exempt from that filter precisely so the two changes cannot collide.

---

Conflict-ownership affordance: the one paragraph in this PR that a prompt could not carry

orchestrator.txt's maintainer paragraph states the rule in full — merging an integrated branch is the maintainer's job, but a CONFLICT belongs to the session that owns the branch, so git merge --abort and session send it back rather than resolving the hunks. It was live-tested on mimo-v2.5 three times and failed 3/3 behaviourally. Not stalls: each run completed an 8–13 call loop in 42–56 s.

run	what it did
1	git merge → CONFLICT (add/add) → read → edit → git add → git commit → git branch -d payments-shard-fix (deleted the author's branch)
2	git merge → CONFLICT → read → write → git add → git commit; narrated "Let me check and resolve it."
3	merge-tree preview → a stray git merge --abort before any merge (no-op) → merge → CONFLICT → read → write → add → commit

session tool calls: zero in all three. The maintainer half was obeyed; the author half was not.

Why an affordance, not stronger wording

This PR already established the principle and shipped it once: the system prompt is assembled once per request, so it is stale by the fourth tool call of a turn — but a TOOL RESULT is read immediately before the model's next tool call. That is how session create was made route-first (dispatchLedgerNotice echoes the live sibling roster into its own output). The standing rule follows: when you find yourself strengthening prompt wording a second time for the same behaviour, build the affordance instead.

So the git merge that conflicts now carries the ownership rule, the exact abort, and the session send shape in its own result, where the model reads it before it can reach for read/edit.

The signal: two facts git owns, both required

src/tool/merge-conflict-notice.ts, wired at the end of the bash tool's run().

1. unmerged index entries — git ls-files --unmerged non-empty.
2. an in-progress integration — one of MERGE_HEAD / CHERRY_PICK_HEAD / REVERT_HEAD / rebase-merge/ / rebase-apply/.

Neither can be produced by a command that merely prints the word conflict, which is the false positive the choice exists to exclude. Rejected alternatives, with reasons:

• "non-zero exit + CONFLICT in output" — that is the false positive.
• MERGE_HEAD alone — merge-specific (a conflicted rebase writes rebase-merge/), and equally set by a clean git merge --no-commit, so on its own it cannot tell "mid-merge" from "conflicted". (1) is the half with teeth; (2) is kept because it names the exact abort verb (git rebase --abort ≠ git merge --abort) and excludes a stray unmerged index with nothing abortable behind it.

Exit code is deliberately not in the signal: git merge x || true exits 0 and is still conflicted. Both probes sit behind a cheap text hint whose only job is to decide whether to spend a git spawn, so an ordinary bash call pays nothing — and because the hint can never annotate on its own, it is allowed to be generous.

Annotates, never blocks. The merge attempt is the orchestrator's job; refusal is the wrong instrument, the same scope line this PR drew for duplicate dispatch.

Scope: every session, keyed on the outcome alone. This is the exact inverse of isolated-git-guard.ts, which keys on isIsolatedWorktree(Instance.directory) and therefore never fires for the orchestrator — the blind spot the live runs walked into. No role gate, because the gate that would be right ("does one of my sessions own this branch?") is not observable from the bash tool, and "only when I am the orchestrator" would repeat the same mistake one level up: any session can session create. The two mechanisms cannot contradict each other — for an isolated child git merge is refused outright, so this annotation is unreachable there. The owning session is not named: it genuinely cannot be from here, and a fabricated id is worse than none, so the notice cites the roster the session tool already injects and leaves a placeholder.

Post-fix live result: 2/3 (was 0/3) — and the affordance fired in only one of them

run	path taken	affordance fired	verdict
1	git merge-tree preview only, never merged; git merge --abort no-op; session send ✓	no — index never conflicted	pass
2	preview, then git merge --strategy-option theirs → merged cleanly; task:done; zero session calls	no — -X theirs produces no conflict	fail
3	preview, then real git merge … || true → CONFLICT → git merge --abort → session send ✓	yes	pass

A 4th, instrumented invocation (to capture the annotation verbatim from a live turn) stalled at step 0 with no model response in 900 s; infra, not a result, and the instrumentation was reverted.

Honest gaps this exposed, reported because they matter more than the score:

1. -X theirs / -X ours bypasses the affordance by construction. Run 2's merge was clean as far as git is concerned, so an outcome-keyed signal cannot fire — yet the model still decided the conflict's outcome itself, which is what the rule forbids. Closing that needs an intent-keyed instrument (annotate -X ours|theirs before execution), not this one. Out of scope here, and named rather than papered over.
2. All 3 runs previewed with git merge-tree first, which prints CONFLICT and leaves the index clean — the false-positive case declining correctly, confirmed live.
3. session send was malformed on the first attempt in runs 1 and 3 (flat sessionID/task instead of nested operation), self-corrected on the second. Unrelated to this change, but it costs a call every time.

Verdict: the affordance closed what the prose could not, on the path it covers, and only there. Prose lost 3/3 with zero session calls; with the affordance the only run that actually produced a conflicted index aborted and routed exactly as prescribed. It does not cover a merge steered to a clean result by a strategy option.

Deterministic test + revert probe

test/tool/bash-conflict-ownership.test.ts — 10 tests through the real bash tool: a real conflicted merge is annotated; a clean merge is not; a command that merely prints CONFLICT is not; a clean git merge --no-commit (MERGE_HEAD present, index clean) is not — which is what makes the unmerged-index half load-bearing rather than decorative; git merge --abort clears it; a conflicted rebase names git rebase --abort.

Revert probe (replace the annotate call with void MergeConflict) → 7 pass / 3 fail, only the positive-direction assertions die:

error: expect(received).toContain(expected)
Expected to contain: "THE CONFLICT IS NOT YOURS TO RESOLVE"
Received: "Auto-merging payments-shard.txt\nCONFLICT (add/add): Merge conflict in payments-shard.txt\nAutomatic merge failed; fix conflicts and then commit the result.\n"

Note on the live test's observables

mergeInProgress is a weak observable and is left in place only as a cheap tripwire: completing a merge consumes MERGE_HEAD, so false cannot distinguish "aborted cleanly" from "resolved it itself". resolved and routed are the assertions with teeth. routed is not strengthened here and its weakness is stated rather than hidden: it admits read-only session list/status and never checks the target id, so it would pass for a turn that merely looked at the roster. Tightening it to action === "send" && sessionID === <owner> is the right change and is deliberately left as a separate one, because doing it in the same commit as the affordance would make a pass/fail delta unattributable.

---

Related defect, same family: the <active-sessions> tag was leaking to users

A user saw the literal <active-sessions> tag — rows and all — in the TUI. The TUI is not at fault: the roster is pushed into the system array (session/llm.ts) and system content is never rendered (grep active-sessions src/cli → zero hits). The model was quoting it, and the prompt had taught it to: orchestrator.txt named the tag five times and said "Look at <active-sessions>", so the tag was vocabulary and the literal string was sitting in context to copy. There was no instruction anywhere saying the block was internal.

Fix: delete the artifact instead of requesting restraint. Adding "do not echo the roster" would be one more prompt instruction, and this branch had just measured what those are worth. The roster now ships with a prose lead-in (ROSTER_HEADER) and no envelope; orchestrator.txt refers to it functionally ("your fleet roster") and keeps the field layout, which is the part that was load-bearing for routing. With no <active-sessions> string anywhere in the assembled request, echoing it is not a behaviour available to the model — and that is asserted on the wire (expect(sys).not.toContain("<active-sessions>")), not on the prompt text.

Dropping the delimiter costs nothing structurally: it was the only tagged block in the system array (the agent prompt and the memory instructions are both plain prose), and dispatchLedgerNotice already ships the same roster to the model in a tool result with a prose header and no envelope — and that one was never reported as leaking a tag.

Audit of the two tool-result blocks. A tool result is more exposed than a system prompt, not less: it arrives mid-turn as fresh content and may be relayed as output. Both dispatchLedgerNotice and MergeConflict.notice were already envelope-free — no tag to imitate, only prose and indented rows. Each now also states outright that it is internal working context. That half is the weak lever and is labelled as such in both files: it can only ask, and it does not stop a paraphrase of a child's title. Unlike the roster, the artifact cannot be deleted — the block is the affordance.

The strong lever, proposed and not built: an output-side strip at the assistant-text seam — session/processor.ts text-end (the single finalize point, which already carries an experimental.text.complete plugin hook). It is the only lever that does not depend on model compliance at all. Not landed here: it touches the hottest path in the session loop, and this repo's only existing strategy for leaked internal markers is detect-and-discard-the-step (classify.ts text-tool-call → autoRetryTextToolCall), never substring removal — so a scrubber is a new pattern that needs its own behavioural evidence rather than a ride-along.

Verification, honestly labelled. The prompt-file assertion is a text pin — it pins wording so the prompt cannot re-teach the tag as vocabulary, and it is marked as such in the test. The mechanism assertion is the on-the-wire absence. Live turns now also record whether the model echoed any of the three internal blocks into its assistant text (echoed-internal-scaffolding=); it is reported, not asserted, because a live turn is the wrong place to gate CI. First post-fix live run: echoed-internal-scaffolding=(none), and that run passed. One clean run is not proof the leak is gone, and it is not claimed to be.

Verification for both changes

bun typecheck exit 0. Scoped run (full suite deliberately not run — a sibling was running checkpoint work concurrently):

• Mine: bun test test/tool/bash-conflict-ownership.test.ts test/tool/bash.test.ts test/tool/bash-isolated-git-guard.test.ts test/tool/isolated-git-guard.test.ts test/session/orchestrator-route-first.test.ts test/session/orchestrator-active-sessions.test.ts test/tool/session-tool.test.ts → 230 pass / 1 skip / 0 fail (231 tests, 543 expects).
• Pristine ad5d46940, same 6 pre-existing files → 220 pass / 1 skip / 0 fail (221 tests, 511 expects).
• Delta is exactly the +10 new tests. Zero regressions.