spawn_agent documents pointing several workers at one shared collab dir; reserveParentReportPath rejects the second child

[EtanHey]

Symptom

spawn_agent's own guidance tells a lead to point several workers' reports at one shared collab dir so it can watch a single place. The shipped code rejects the second child that tries it. A lead following the documentation gets each child requires a distinct report path on spawn two.

This is not cosmetic: it is the concrete blocker under #516's ruling ("workers should report to leads via monitored collabs… maximum send a pointer"). The one affordance cmuxlayer offers for that pattern is documented as supported and enforced as forbidden.

The incident that produced this filing

coachClaude (registry role orchestrator) ran four workers in ~/Gits/coach, 2026-09-03/04.

agent	cli	state	report.md	closure
coachCodex-579fba4e	codex	done, task_done_detected_at 2026-09-03T13:16:54Z	0 bytes	artifact_missing
coachClaude-57873920 / -fa0c40e9 / -e034377f	claude	done	93 / 132 / 79 lines	verified

Records at ~/.local/state/cmux-agents/coach*/state.json: all four carry parent_agent_id: "coachClaude", a report_path, a done_marker, halt_escalation: true, and closure_artifact_verified: null (closure is computed at read time, never persisted). The Codex worker hit a provider usage limit after closing PR #31, opening PR #32 and producing an ATS receipt — all pane pixels only; the lead learned it from a screenshot the human pasted. ~/Gits/coach/docs.local/collabs/ holds 7 files, all mtime 2026-08-13: zero writes during the run.

Forensic diagnosis was read-only against cmuxlayer HEAD 2d1fb62 (v0.4.69 line); every src/… reference below is verbatim from it.

In this run, ~/Gits/coach/docs.local/collabs/ held 7 files, all mtime 2026-08-13 — zero writes across a four-worker, two-day run. No brief named a collab path, and the tooling offers no way for four workers to share one.

Evidence (verbatim from the diagnosis)

• c. Collab-file concept in cmuxlayer? None. grep -ri collab src/ yields only comments and tool prose. The one affordance is the optional report_path override, described as "place the report somewhere you already watch (e.g. a collab dir)" (server.ts:14362), and coordination-paths.ts:37-40 claims it "lets a parent point several workers' reports at one shared collab dir". That claim is false in shipped code: reserveParentReportPath rejects a second child on the same path — "each child requires a distinct report path" (server.ts:13912-13965, enforced :14454, :14727, :14770). docs.local/collabs/ is pure golems convention, no tooling.

• 5. The documented shared-collab reporting pattern is prohibited by the code. Symptom: a lead following spawn_agent's own guidance to point several workers at one watched collab dir has its second spawn rejected. Evidence: claim coordination-paths.ts:37-40 + server.ts:14362 vs. enforcement server.ts:13912-13965, applied :14454, :14727, :14770.

The design intent — Etan, verbatim (2026-09-04)

"workers should NEVER output to screen for user something that isnt in the collab.... whats on screen should be a very consice output for incase the user wants to see"

and the 2026-08-23 ruling already carried in #516:

"workers should interact with leads through monitored collabs, not sending cmuxlayer messages… unless left stranded but yeah… or maximum send a pointer to a collab."

cmuxlayer has no agent-to-agent shared artifact surface at all — grep -ri collab src/ is comments and tool prose; inbox.jsonl is inbound-only (inbox.ts:126); report_to_parent (server.ts:13967) carries a short blocker string to one parent, not work product. The report_path override is the closest thing to that surface, and this guard is what stops it being one. Filed here rather than as a separate feature issue because #516 already owns the rule; this owns the code contradiction that makes the rule unimplementable.

Did the last sprint touch this path?

Yes, adjacent, and it did not reach this. 533f2f8 (09-01, #581) is the only post-08-20 commit in coordination-paths.ts — it derives contract-pointer delivery from the verified boot receipt (honesty about whether the pointer was delivered). The doc claim at coordination-paths.ts:37-40 and the reserveParentReportPath guard are untouched.

Proposed fix shape

Pick one and make the docs match it — the defect is the contradiction, not the guard:

(a) Make the documented pattern real (preferred). Keep the reservation guard for unique file paths, and allow a shared directory: a parent supplies report_dir, the engine derives <report_dir>/<agent_id>.md per child. Every worker writes into one place the lead already watches; each file is still uniquely owned, so the guard's real invariant (two children must not clobber one file) is preserved, not weakened.

(b) Fix the docs. Correct coordination-paths.ts:37-40 and the server.ts:14362 description to say one report path per child, no sharing — and make the rejection message name the workaround.

(b) is minutes and removes the trap; (a) is what #516's ruling actually needs.

Size

XS for (b). S for (a) — one path-derivation helper plus the three enforcement sites (:14454, :14727, :14770).

Related

• workers should report to leads via monitored collabs, not send_to — pointer at most #516 (workers should report to leads via monitored collabs, not send_to — pointer at most) — the rule this unblocks; the incident's verbatim rule above is filed there too
• Codex workers cannot git/network from their own pane, and their engine-issued report_path is unwritable #501 (Codex workers' engine-issued report_path is unwritable) — the other reason report paths fail on Codex
• false blocking closure_without_artifact: fires on agents with no engine contract, and repo-written reports are invisible to closure detection #474 (repo-written reports are invisible to closure detection) — a shared collab dir must not read as artifact_missing
• Siblings from the same 2026-09-04 diagnosis: A worker killed mid-run loses 100% of its product — the contract obliges no durable write until the end report #587 (mid-run checkpoint obligation), artifact_missing is blocking-severity and pull-only — a lead that never polls is never told its worker died empty #588 (artifact_missing has no push path), Engine-armed report watches cannot fire on an empty report and never notify — and arming one is what creates the 0-byte report.md #589 (report watches cannot fire), A provider-usage-limit kill reads as normal completion on Codex — state:done, no halt episode, no escalation #590 (usage-limit kill reads as done)

— orcClaude (lead) · claude-code/claude-opus-5[1m] · filed from coachClaude's read-only forensic diagnosis, 2026-09-04