code-coordinator 0.5.506__tar.gz → 0.5.508__tar.gz

{code_coordinator-0.5.506 → code_coordinator-0.5.508}/CLAUDE.md

@@ -2,20 +2,21 @@
 
 CLI tool + per-machine agent server that coordinates Claude Code workers across multiple machines and repos over Tailscale.
 
-> **Scope of this file (#2195).** This is the **worker- and reviewer-facing** rulebook: it is
-> loaded into every worker leg, every review leg, and every coordinator session — and re-read on
-> every turn of each — so it holds only what someone *editing this repo* must act on. Operator
-> runbooks live in [`docs/`](docs/), indexed by
-> [`docs/OPERATOR_GUIDES.md`](docs/OPERATOR_GUIDES.md). Settled design rationale lives in
-> [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale).
-> Keep it that way: **if a new rule does not change what a worker does, it belongs in `docs/`.**
-> Operator sessions — the "dispatch, don't do" rule now lives in
-> [`docs/COST_DISCIPLINE.md`](docs/COST_DISCIPLINE.md); read it before hand-editing any tracked
-> repo. If you're a worker or reviewer leg, that one isn't for you.
-
-## Current Goal — read first
-
-**[`GOAL.md`](GOAL.md) holds the current north-star objective** — the living, cross-repo / cross-machine goal that should bias all planning, triage, and dispatch. It is meta-level (above any single issue, repo, or session) and changes as priorities evolve: read it first, plan against it, and keep it current. `coordinator.yml` is the source of truth for *topology*; `GOAL.md` is the source of truth for *intent*.
+> **Scope of this file (#2195, #2817).** This is the **worker- and reviewer-facing**
+> rulebook: it is loaded into every worker leg, every review leg and every coordinator
+> session — and re-read on **every turn** of each, so every byte here is a recurring
+> fleet-wide cost. It holds only what someone *editing this repo* must act on.
+> **If a new rule does not change what a worker does, it belongs in [`docs/`](docs/).**
+> `tests/test_claude_md_budget.py` enforces that with a byte cap — move a section out
+> rather than raise it.
+>
+> Not here: operator runbooks ([`docs/OPERATOR_GUIDES.md`](docs/OPERATOR_GUIDES.md)) ·
+> settled design rationale
+> ([`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale)) ·
+> the `coord` command reference (`coord <cmd> --help`) · operator cost rules and
+> "dispatch, don't do" ([`docs/COST_DISCIPLINE.md`](docs/COST_DISCIPLINE.md)) ·
+> the current north-star objective ([`GOAL.md`](GOAL.md) — read it in a coordinator
+> session when planning or triaging; a worker or reviewer leg does not need it).
 
 ## Codebase navigation — query the graph first
 
@@ -64,22 +65,11 @@ Query the **graphify graph** (`graphify-out/`) for the full module map + relatio
 
 ## Commands
 
-`coord <cmd> --help` documents every command + flags. The core loop:
-
-```bash
-coord plan                 # Brain proposes assignments for idle machines
-coord approve 1,3          # Dispatch approved proposals (comma-separated IDs)
-coord assign <machine> <repo> <issue> [--briefing TEXT | --briefing-file F] [--dry-run]  # Direct dispatch
-coord status [--freshness] # Machines, assignments, connectivity (+ repo freshness vs GitHub HEADs)
-coord log <id> [-f] [--machine NAME]            # claude -p output (remote logs need --machine)
-coord notify               # Poll agents, post completion/failure comments to GitHub
-coord test --passed|--fail|--skipped <id>       # Record the Test-gate verdict (bare `coord test <id>` builds+tests locally)
-coord merge [--dry-run] [--repo NAME] [--method rebase|squash|merge] [--order IDs] [--force-merge]
-coord reconcile-merges     # Backfill missing branches + record out-of-band merges (#609/#611)
-coord retry|stop|resume <id>                    # Recovery; `coord done` ends the session
-```
-
-Setup / diagnostics (discoverable via `--help`): `coord init`, `coord config`, `coord agent`, `coord serve`, `coord web`, `coord diagnose`, `coord sessions [--remote]`, `coord split`, `coord notifier`, `coord repo add` / `coord repo doctor`.
+`coord <cmd> --help` documents every command and flag — that is the reference, not this
+file. The operator-facing core loop (`plan`/`approve`/`assign`/`status`/`merge`/...) is in
+[`docs/OPERATOR_GUIDES.md`](docs/OPERATOR_GUIDES.md#the-core-loop). The one `coord` command
+a **worker** runs is `coord acceptance run --issue N`, in an oracle-loop round (see Testing
+below).
 
 ## Development
 
@@ -133,34 +123,22 @@ computes the routing without actually building or testing anything.
 
 ## Key Design Decisions
 
-One line each — the reasoning behind them is in
-[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale).
-
-- **No API key needed.** Everything uses `claude -p`, which runs on a Max/Pro subscription via OAuth.
-- **Agent servers are dumb dispatchers.** They spawn `claude -p` and track the subprocess; all intelligence is in the coordinator brain.
-- **GitHub issue comments are the message bus.** Briefings, completion notices and failure reports are comments, carrying `<!-- coord:... -->` markers for machine parsing.
-- **`coordinator.yml` is the single source of truth** for repo topology, machine capabilities, dependencies, concurrency limits, review settings, smoke-test rules, and the pipeline gate order (`pipeline.default_gates`). It lives in `~/.coord/`, **not** the repo checkout.
-- **User approves everything.** `coord plan` proposes, the user reviews, `coord approve` dispatches. No autonomous dispatch.
-- **Claim detection prevents duplicate work.** Before dispatching, the coordinator checks the board for active assignments and the remote for `issue-{N}-*` branches.
-- **Conflict rules are inferred, not configured.** There is no `file_groups`/`exclusive_files` config and never will be. `coord drive-queue add` compares an issue's own `## Files` declaration against the **real diffs** of in-flight branches in that repo (`coord/overlap_predict.py`, #2247) and, on an overlap, chains the newcomer `--after` the incumbent. **It ORDERS, never refuses** — a false positive costs latency, a refusal costs work. Accuracy is measured, not assumed: `coord drive-queue overlap-report`.
-- **Adversarial reviews are rule-enforcing, not rubber-stamping.** On worker completion a fresh `claude -p` session on a *different* machine reviews the PR diff against this file and the review checklist, with zero shared context with the worker — that's the whole point.
-- **The pipeline order is `Work → Test → Review → Merge`.** Test precedes Review; the headless auto-loop holds review dispatch until there is a `passed`/`skipped` test verdict.
-- **Merge is gated on CI checks (#240).** `coord merge` refuses when a check failed or is still running — and a PR with *zero* reported checks is not automatically clear either (#1904).
-- **Mechanical merge conflicts auto-rebase (#241).** A `type="conflict-fix"` worker rebases and resolves additive merges; semantic conflicts are left for a human.
-- **Smoke tests validate on capable hardware.** `smoke_tests.capability_rules` map changed files to required machine capabilities (e.g. GTK changes → a machine with GTK).
-- **Progress streaming from workers.** Workers emit `STATUS:` and `STUCK:` lines; the coordinator parses these for real-time progress in `coord status` and the dashboard.
-- **The notifier tells you when NOBODY IS COMING — and nothing else (#1632).** Advisory, isolated, off by default; it is not an error channel and not a progress feed.
-
-## Review Prompt Assembly
-
-The reviewer gets a prompt built from:
-1. **Repo's CLAUDE.md** — the project rules (source of truth, not duplicated)
-2. **Generic checklist** — "did you add tests?", "did you stay in file scope?", "any security issues?"
-3. **Repo overrides** — project-specific patterns from `coordinator.yml` `reviews.repo_overrides`
-4. **The diff** — `gh pr diff` of the worker's branch vs base
-5. **The issue** — title and body for intent verification
-
-The reviewer reads the rules and enforces them against the diff. It does not have the worker's session context — genuinely independent.
+These are the ones a **diff** can violate. The full set, with the reasoning behind each, is
+in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale).
+
+- **`coordinator.yml` is the single source of truth** for repo topology, machine
+  capabilities, dependencies, concurrency limits, review settings, smoke-test rules and the
+  pipeline gate order (`pipeline.default_gates`). It lives in `~/.coord/`, **not** the repo
+  checkout.
+- **Conflict rules are inferred, not configured.** There is no `file_groups` /
+  `exclusive_files` config and never will be — `coord drive-queue add` compares an issue's
+  own `## Files` declaration against the **real diffs** of in-flight branches
+  (`coord/overlap_predict.py`, #2247). **It ORDERS, never refuses.** Do not add such config.
+- **The pipeline order is `Work → Test → Review → Merge`.** Test precedes Review; the
+  headless auto-loop holds review dispatch until there is a `passed`/`skipped` verdict.
+- **Adversarial reviews are rule-enforcing, not rubber-stamping.** A fresh `claude -p`
+  session on a *different* machine reviews your diff against this file, with **zero shared
+  context with you** — so your diff and final message must stand on their own.
 
 ## Rules for workers
 
@@ -212,7 +190,5 @@ versus keep in the coordinator session, and the coordinator session's own
 
 ## Operating the fleet — operator-facing
 
-**Not needed to work on this repo.** A worker or reviewer can stop reading here. Every operator
-runbook — the pre-flight gotchas, agent installs and releases, the drive queue, the customer
-portal, and the two deploy facts that bite most often — is indexed in
+**Not needed to work on this repo.** Every operator runbook is indexed in
 [`docs/OPERATOR_GUIDES.md`](docs/OPERATOR_GUIDES.md).

{code_coordinator-0.5.506 → code_coordinator-0.5.508}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.506
+Version: 0.5.508
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.506 → code_coordinator-0.5.508}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.506
+Version: 0.5.508
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.506 → code_coordinator-0.5.508}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.506",
+  "tag": "0.5.508",
   "distance": 0,
-  "node": "g10b3e0961d928aad40e02740533266e5814d0edd",
+  "node": "g8afe10d6337d6c249497f95932b1a6acd5596222",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-20"

{code_coordinator-0.5.506 → code_coordinator-0.5.508}/coord/agent.py

@@ -5062,6 +5062,136 @@ def _claude_md_system_prompt_suffix(repo_path: str) -> str:
     return "\n\n## Project rules (from CLAUDE.md)\n\n" + claude_md.strip() + "\n"
 
 
+# #3420: every `claude -p` leg loads the full JSON schema for all built-in
+# tools regardless of `--allowedTools`, which is a *permission* filter, not a
+# tool-surface one — a leg with `Read,Bash` in `--allowedTools` still pays
+# the prompt-token cost of the `Workflow`/`Skill`/etc. schemas it can never
+# call. Measured with controlled `claude -p` probes on this repo's own
+# `default_worker_command` flags (Claude Code 2.1.278, `type="work"`): the
+# schemas for these tools cost 12,134 tokens/turn (44% of the static
+# prefix), re-read at cache-read rates on every turn of every leg. None of
+# them has a legitimate use from a headless coord leg:
+#   - `Workflow`: requires explicit user opt-in; a headless leg has no user.
+#   - `Skill`: all `coord` skills are operator-only runbooks.
+#   - `ScheduleWakeup`: every leg is one-shot (WORKER_SYSTEM_PROMPT's
+#     ONE-SHOT section, #1394) — there is no future turn to wake up into.
+#   - `Task`: CLAUDE.md mandates `graphify query` + grep for navigation
+#     instead of spawning a subagent.
+#   - `ReportFindings`, `ListAgents`: unreferenced by any coord system
+#     prompt; no fleet-messaging or review-findings-reporting surface is
+#     exposed to a leg.
+#   - The remainder (`Cron*`, `DesignSync`, `EnterWorktree`/`ExitWorktree`,
+#     `NotebookEdit`, `PushNotification`, `RemoteTrigger`, `SendMessage`):
+#     operator/coordinator-session tools with no worker-leg counterpart —
+#     already deferred behind `ToolSearch` so each costs only ~6-9 tokens,
+#     but included for a consistent, minimal tool surface.
+#
+# Deliberately EXCLUDED, despite being equally unusable:
+#   - `Monitor`: 0 marginal token cost, and WORKER_SYSTEM_PROMPT's ONE-SHOT
+#     polling guidance depends on it (it's the sanctioned way to await a
+#     backgrounded command in bounded steps).
+#   - `ToolSearch`: cheap on its own, and removing it is untested — it's the
+#     mechanism that resolves every deferred tool name at all.
+#   - `TaskOutput`/`TaskStop`: look like `Task`'s output/cancel pair at
+#     first glance, but WORKER_SYSTEM_PROMPT's ONE-SHOT section and
+#     coord/smoke.py's SMOKE_SYSTEM_PROMPT both explicitly teach
+#     `TaskOutput` as the bounded-poll alternative to `Monitor` for a
+#     backgrounded Bash command (`run_in_background`) — disallowing it
+#     would make that documented guidance a dead end. `TaskStop` is kept
+#     alongside it since it's the same background-job-management pair.
+#   - `WebFetch`/`WebSearch`: ~6 tokens each either way (negligible), and a
+#     worker may legitimately need to look up library docs or an error
+#     message mid-task — kept allowed rather than trading real capability
+#     for a rounding error in prompt size.
+UNUSABLE_TOOL_SCHEMAS: list[str] = [
+    "Workflow",
+    "Skill",
+    "ScheduleWakeup",
+    "Task",
+    "ReportFindings",
+    "ListAgents",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
+    "DesignSync",
+    "EnterWorktree",
+    "ExitWorktree",
+    "NotebookEdit",
+    "PushNotification",
+    "RemoteTrigger",
+    "SendMessage",
+]
+
+
+def worker_disallowed_tools(spec: AssignmentSpec, allowed_tools: str) -> list[str]:
+    """Return the ordered ``--disallowedTools`` entries for *spec*.
+
+    **Single source of truth.** Both argv builders that emit
+    ``--disallowedTools`` — :func:`default_worker_command` and
+    :meth:`coord.providers.claude.ClaudeProvider.build_command` — call
+    this, rather than each reimplementing the same four-layer stack. The
+    two previously transcribed the logic independently, which is exactly
+    how #3420's ``UNUSABLE_TOOL_SCHEMAS`` layer landed in one and not the
+    other; the parity suite in ``tests/test_providers.py`` caught it, but
+    a shared function makes the divergence unrepresentable instead of
+    merely detectable.
+
+    Layers, in argv order (each skips entries an earlier layer already
+    added, so the result is de-duplicated but order-stable):
+
+    1. #3420 ``UNUSABLE_TOOL_SCHEMAS`` — unconditional, every spec type.
+    2. #1315 sealed-oracle write guard, from ``spec.files_forbidden``.
+    3. #1642 base-checkout write guard — only when *allowed_tools*
+       actually grants ``Edit``; for the Read/Bash-only chat types the
+       guard would be a no-op cluttering the argv.
+    4. #2461 ``REVIEW_DENY_COMMANDS`` — only for ``spec.type ==
+       "review"``, wiring the mutating-command deny list into the
+       CLI-enforced flag and not just the soft prompt reminder.
+
+    Args:
+        spec: The assignment being dispatched.
+        allowed_tools: The ``--allowedTools`` value computed for this
+            spec — inspected for ``Edit`` to decide layer 3. Passing the
+            caller's own computed value (rather than re-deriving it here)
+            keeps the two flags consistent even when a caller overrides
+            ``--allowedTools`` explicitly, as ``build_command`` allows.
+
+    Returns:
+        A fresh list; callers may mutate it. Empty only in the
+        impossible case where every layer contributes nothing — since
+        #3420, layer 1 is unconditional, so in practice this is always
+        non-empty and ``--disallowedTools`` is always emitted.
+    """
+    # #3420: strip the unusable-tool schemas from every spec type, including
+    # the Read/Bash-only chat legs (plan, refinement, test-chat,
+    # new-issue-chat, smoke, review) — they carry the same
+    # Workflow/Skill/Task/etc. schemas as a work leg and benefit identically.
+    # This is FIRST so the guards below, which each append to this same
+    # list, keep working unchanged.
+    disallowed_tools = list(UNUSABLE_TOOL_SCHEMAS)
+    # #1315: structural sealing enforcement — see _sealed_write_guard_tools.
+    for pattern in _sealed_write_guard_tools(spec.files_forbidden):
+        if pattern not in disallowed_tools:
+            disallowed_tools.append(pattern)
+    # #1642: block Edit/Write on the shared base checkout for any spec.type
+    # that actually gets Edit/Write in --allowedTools — the Read/Bash-only
+    # chat types can't touch files regardless, and adding the guard there
+    # would be a no-op cluttering their argv for nothing.
+    if "Edit" in allowed_tools:
+        for pattern in _base_checkout_write_guard_tools(spec.repo_path):
+            if pattern not in disallowed_tools:
+                disallowed_tools.append(pattern)
+    # #2461: review gets its mutating-command deny list wired into
+    # --disallowedTools too, not just the soft system-prompt reminder from
+    # build_deny_prompt — the CLI enforces this one even if the model
+    # decides to ignore its own prompt.
+    if spec.type == "review":
+        for pattern in REVIEW_DENY_COMMANDS:
+            if pattern not in disallowed_tools:
+                disallowed_tools.append(pattern)
+    return disallowed_tools
+
+
 def default_worker_command(spec: AssignmentSpec, *, binary: str = DEFAULT_WORKER_BINARY) -> list[str]:
     """Build the argv for invoking the worker on this assignment.
 
@@ -5347,24 +5477,10 @@ def default_worker_command(spec: AssignmentSpec, *, binary: str = DEFAULT_WORKER
     ]
     if spec.model:
         argv.extend(["--model", spec.model])
-    # #1315: structural sealing enforcement — see _sealed_write_guard_tools.
-    disallowed_tools = _sealed_write_guard_tools(spec.files_forbidden)
-    # #1642: block Edit/Write on the shared base checkout for any spec.type
-    # that actually gets Edit/Write in --allowedTools — the Read/Bash-only
-    # chat types above can't touch files regardless, and adding the guard
-    # there would be a no-op cluttering their argv for nothing.
-    if "Edit" in allowed_tools:
-        for pattern in _base_checkout_write_guard_tools(spec.repo_path):
-            if pattern not in disallowed_tools:
-                disallowed_tools.append(pattern)
-    # #2461: review gets its mutating-command deny list wired into
-    # --disallowedTools too, not just the soft system-prompt reminder from
-    # build_deny_prompt above — the CLI enforces this one even if the model
-    # decides to ignore its own prompt.
-    if spec.type == "review":
-        for pattern in REVIEW_DENY_COMMANDS:
-            if pattern not in disallowed_tools:
-                disallowed_tools.append(pattern)
+    # #3420 / #1315 / #1642 / #2461: all four --disallowedTools layers live
+    # in worker_disallowed_tools, shared with ClaudeProvider.build_command so
+    # the two argv builders cannot drift apart (see that function's docstring).
+    disallowed_tools = worker_disallowed_tools(spec, allowed_tools)
     if disallowed_tools:
         argv.extend(["--disallowedTools", ",".join(disallowed_tools)])
     # #315: when resuming a prior chat session, load the prior conversation so

{code_coordinator-0.5.506 → code_coordinator-0.5.508}/coord/notify.py

@@ -2477,6 +2477,114 @@ def _confirmed_pass_verdict(
     )
 
 
+def _mechanical_mute_verdict(
+    transition: Transition, entry: dict, parent_id: str,
+) -> tuple[str, str, str] | None:
+    """#3415: for a MUTE Test-stage leg (no `SMOKE:` marker at all, clean
+    session exit), attempt the same out-of-band mechanical re-run #2464 uses
+    to double-check a *claimed* pass — except here there is no claim to
+    confirm, so a decisive result becomes the verdict directly.
+
+    Why this exists: sampling every #3376 "reached done with no verdict"
+    alarm found the identical shape 7 times out of 7 — a headless Test-stage
+    worker backgrounds a suite that exceeds the Bash ceiling, correctly
+    states the rule ("I'll poll with bounded waits"), and then ends its turn
+    anyway. That is not a coord bug to patch around with a sterner prompt;
+    ending a one-shot `claude -p` turn ends the session permanently, so no
+    notification the backgrounded suite eventually produces can ever reach
+    it. The prompt already spends two capitalized bullets on this (#2272,
+    #2301) and the observed compliance rate is 0/7 — more emphasis cannot
+    raise a structural non-starter to a rate the Test gate can depend on.
+
+    `coord.confirm_test.confirm_branch` needs no LLM and no waiting: it
+    re-runs the repo's own build/test command in a throwaway worktree and
+    reads the real exit code. Reusing it here — instead of only as the
+    pass-claim backstop — deletes the mute leg's reason to exist for every
+    repo whose suite this machine can actually run, rather than bounding it
+    with a bigger retry budget.
+
+    Returns ``None`` when the run is inconclusive or unavailable (disabled,
+    no local checkout, no test_command, a timeout, ...) — the existing
+    mute-leg tally (count the leg, clear for one retry, then park at the
+    budget) is exactly the right fallback for "still no answer either way",
+    and this never invents one it doesn't have.
+    """
+    from coord.confirm_test import (  # noqa: PLC0415
+        BASELINE_RED_REASON_PREFIX,
+        TEST_CONFIRMATION_BASELINE_RED,
+        TEST_CONFIRMATION_CONFIRMED,
+        TEST_CONFIRMATION_REFUTED,
+        write_confirmation_output,
+    )
+    from coord.state import load_assignment_review_verdict  # noqa: PLC0415
+
+    result = _run_pass_confirmation(transition, entry)
+    if result is None or result.inconclusive:
+        return None  # no decisive answer — fall back to the mute-leg tally
+
+    try:
+        write_confirmation_output(parent_id, result)
+    except Exception as exc:  # noqa: BLE001
+        log.warning(
+            "smoke %s: could not persist mechanical confirmation output for "
+            "parent %s (%s) — a later fix briefing will fall back to the "
+            "one-line reason (#2563/#3415).",
+            transition.assignment_id, parent_id, exc,
+        )
+
+    if result.refuted:
+        log.warning(
+            "smoke %s: mute Test-stage leg for %s — the mechanical fallback "
+            "re-run (#3415) says FAILED: %s\n%s",
+            transition.assignment_id, transition.repo_name, result.reason,
+            result.output,
+        )
+        # #2579: same race as `_confirmed_pass_verdict` — a review can
+        # approve before this out-of-band run lands (review dispatch gates
+        # on `test_state`, not on confirmation). Plain "failed" would then
+        # be indistinguishable from an ordinary Test-stage failure and
+        # silently bounce an already-approved branch to a fix worker.
+        _review_state, _review_verdict = load_assignment_review_verdict(parent_id)
+        if _review_verdict == "approve":
+            return (
+                TEST_STATE_CONTESTED,
+                f"CONTESTED (#2579/#3415): the Test-stage worker "
+                f"{transition.assignment_id} ended mute (no verdict marker "
+                "line), and the mechanical fallback re-run REFUTED the "
+                f"branch AFTER its review had already approved it "
+                f"(review_state={_review_state!r}) — {result.reason}. The "
+                "merge gate stays shut, but no fix round is auto-dispatched "
+                f"— recover with `coord fix --force --guidance <what's "
+                f"broken> {parent_id}` or re-dispatch the Test stage by "
+                "hand.",
+                TEST_CONFIRMATION_REFUTED,
+            )
+        return (
+            "failed",
+            "headless smoke ended mute (no verdict marker line) — the "
+            f"mechanical fallback re-run (#3415) ran the real suite and it "
+            f"FAILED: {result.reason}",
+            TEST_CONFIRMATION_REFUTED,
+        )
+
+    if result.baseline_red:
+        return (
+            "skipped",
+            f"{BASELINE_RED_REASON_PREFIX}, found by the mechanical fallback "
+            f"re-run after a mute Test-stage leg (#3415): {result.reason}",
+            TEST_CONFIRMATION_BASELINE_RED,
+        )
+
+    # result.confirmed
+    return (
+        "passed",
+        "headless smoke ended mute (no verdict marker line), but the "
+        f"mechanical fallback re-run (#3415) independently ran the real "
+        f"suite and it passed: {result.reason}",
+        TEST_CONFIRMATION_CONFIRMED,
+    )
+
+
 def _record_smoke_verdict(
     transition: Transition, entry: dict, parent_id: str,
 ) -> None:
@@ -2658,6 +2766,29 @@ def _record_smoke_verdict(
 
     # No verdict line, clean session exit. NOT a pass.
     #
+    # #3415: before treating this as "no answer, retry", ask the mechanical
+    # fallback (`coord.confirm_test.confirm_branch`, no LLM, no waiting) for
+    # a real one. 7/7 sampled mute legs backgrounded the suite, correctly
+    # stated the polling rule, and ended their turn anyway — that is a
+    # structural property of a one-shot session, not something a bigger
+    # retry budget fixes. A decisive mechanical result is recorded straight
+    # away, with no leg spent and no tally incremented.
+    mechanical = _mechanical_mute_verdict(transition, entry, parent_id)
+    if mechanical is not None:
+        state, reason, confirmation = mechanical
+        record_test_verdict(
+            assignment_id=parent_id,
+            test_state=state,
+            test_reason=reason,
+            test_confirmation=confirmation,
+        )
+        log.info(
+            "smoke %s: mute Test-stage leg — the #3415 mechanical fallback "
+            "reached a decisive verdict %r with no retry needed.",
+            transition.assignment_id, state,
+        )
+        return
+
     # #2272: count the legs, don't just test for the marker's presence. The
     # tally lives at the FRONT of `test_reason` so a bounded `/board` preview
     # still carries it, and `dispatch_smoke` re-states it across the `running`

{code_coordinator-0.5.506 → code_coordinator-0.5.508}/coord/providers/claude.py

@@ -2,10 +2,13 @@
 
 Parity requirement: ``ClaudeProvider().build_command(spec)`` produces the
 **same argv** as ``coord.agent.default_worker_command(spec)`` for the same
-inputs.  The logic is a direct transcription of that function's body with
-the ``resolved_model`` / ``system_prompt`` / ``allowed_tools`` /
-``permission_mode`` kwargs spliced in; the parity tests in
-``tests/test_providers.py`` enforce this mechanically.
+inputs.  The ``spec.type`` → prompt/allowed-tools branches are a direct
+transcription of that function's body with the ``resolved_model`` /
+``system_prompt`` / ``allowed_tools`` / ``permission_mode`` kwargs spliced
+in; the parity tests in ``tests/test_providers.py`` enforce this
+mechanically.  The ``--disallowedTools`` stack is **not** transcribed —
+both builders call the shared ``coord.agent.worker_disallowed_tools``, so
+a new deny layer lands in both without a sync step (#3420).
 
 Imports from ``coord.agent`` are **deferred** (inside method bodies) to keep
 the import cycle latent until the wiring issue lands.  At that point
@@ -119,10 +122,9 @@ class ClaudeProvider(Provider):
             TEST_CHAT_SYSTEM_PROMPT,
             WORKER_PLAN_PROMPT,
             WORKER_SYSTEM_PROMPT,
-            _base_checkout_write_guard_tools,
             _claude_md_system_prompt_suffix,
-            _sealed_write_guard_tools,
             build_deny_prompt,
+            worker_disallowed_tools,
         )
         from coord.review import REVIEWER_SYSTEM_PROMPT  # noqa: PLC0415
         from coord.smoke import SMOKE_SYSTEM_PROMPT  # noqa: PLC0415
@@ -285,20 +287,16 @@ class ClaudeProvider(Provider):
         ]
         if effective_model:
             argv.extend(["--model", effective_model])
-        # #1315 / #1642: same structural write guards as
-        # default_worker_command — sealed-oracle prefix plus (for any type
-        # with Edit in --allowedTools) the shared base checkout.
-        disallowed_tools = _sealed_write_guard_tools(spec.files_forbidden)
-        if "Edit" in allowed_tools:
-            for pattern in _base_checkout_write_guard_tools(spec.repo_path):
-                if pattern not in disallowed_tools:
-                    disallowed_tools.append(pattern)
-        # #2461: same CLI-enforced hard block as default_worker_command —
-        # see REVIEW_DENY_COMMANDS.
-        if spec.type == "review":
-            for pattern in REVIEW_DENY_COMMANDS:
-                if pattern not in disallowed_tools:
-                    disallowed_tools.append(pattern)
+        # #3420 / #1315 / #1642 / #2461: NOT transcribed from
+        # default_worker_command like the branches above — both builders call
+        # the one shared `worker_disallowed_tools`, so a new deny layer lands
+        # in both by construction. It previously WAS transcribed here, and
+        # #3420's unusable-tool-schema layer went into default_worker_command
+        # only; the parity suite caught the drift, but the shared call means
+        # there is nothing left to keep in sync. Pass this method's own
+        # `allowed_tools` (possibly a caller override) so the two flags stay
+        # consistent.
+        disallowed_tools = worker_disallowed_tools(spec, allowed_tools)
         if disallowed_tools:
             argv.extend(["--disallowedTools", ",".join(disallowed_tools)])
         if spec.resume_session_id:

{code_coordinator-0.5.506 → code_coordinator-0.5.508}/docs/ARCHITECTURE.md

@@ -250,6 +250,21 @@ which is why it lives here rather than in the file every worker leg loads. The o
 statements of these rules remain in `CLAUDE.md`'s "Key Design Decisions"; the reasoning is
 here.
 
+### How the review prompt is assembled
+
+The reviewer gets a prompt built from:
+1. **Repo's CLAUDE.md** — the project rules (source of truth, not duplicated)
+2. **Generic checklist** — "did you add tests?", "did you stay in file scope?", "any security issues?"
+3. **Repo overrides** — project-specific patterns from `coordinator.yml` `reviews.repo_overrides`
+4. **The diff** — `gh pr diff` of the worker's branch vs base
+5. **The issue** — title and body for intent verification
+
+The reviewer reads the rules and enforces them against the diff. It does not have the worker's session context — genuinely independent.
+
+Moved here from [`CLAUDE.md`](../CLAUDE.md) (#3422). The reviewer does not need a description
+of how its own prompt was built, and neither does a worker — this is for someone editing
+`coord/review.py`.
+
 ### Agent servers are dumb dispatchers
 
 They spawn `claude -p` and track the subprocess. All intelligence is in the coordinator

{code_coordinator-0.5.506 → code_coordinator-0.5.508}/docs/OPERATOR_GUIDES.md

@@ -19,6 +19,29 @@ in `docs/`.*
   still manual. Epic #3117.
 - [`DRIVE_QUEUE.md`](DRIVE_QUEUE.md) — the durable, board-backed driver (`coord drive-queue`, #1750). **Read the top section before queuing more than ~2 issues on one repo.**
 
+## The core loop
+
+Moved here from [`CLAUDE.md`](../CLAUDE.md) (#3422): a worker cannot run any of these —
+the coordinator owns dispatch and GitHub — so it was pure operator surface being re-read
+on every turn of every leg. `coord <cmd> --help` remains the authoritative reference.
+
+`coord <cmd> --help` documents every command + flags. The core loop:
+
+```bash
+coord plan                 # Brain proposes assignments for idle machines
+coord approve 1,3          # Dispatch approved proposals (comma-separated IDs)
+coord assign <machine> <repo> <issue> [--briefing TEXT | --briefing-file F] [--dry-run]  # Direct dispatch
+coord status [--freshness] # Machines, assignments, connectivity (+ repo freshness vs GitHub HEADs)
+coord log <id> [-f] [--machine NAME]            # claude -p output (remote logs need --machine)
+coord notify               # Poll agents, post completion/failure comments to GitHub
+coord test --passed|--fail|--skipped <id>       # Record the Test-gate verdict (bare `coord test <id>` builds+tests locally)
+coord merge [--dry-run] [--repo NAME] [--method rebase|squash|merge] [--order IDs] [--force-merge]
+coord reconcile-merges     # Backfill missing branches + record out-of-band merges (#609/#611)
+coord retry|stop|resume <id>                    # Recovery; `coord done` ends the session
+```
+
+Setup / diagnostics (discoverable via `--help`): `coord init`, `coord config`, `coord agent`, `coord serve`, `coord web`, `coord diagnose`, `coord sessions [--remote]`, `coord split`, `coord notifier`, `coord repo add` / `coord repo doctor`.
+
 ## Reference
 
 - [`ARCHITECTURE.md`](ARCHITECTURE.md) — how it all fits together, plus the settled design rationale. Two diagnostic entry points: [why a merge/review isn't happening](ARCHITECTURE.md#when-a-merge-isnt-happening) (**check here first when "Go does nothing"**) and [why an issue is in the Pipeline you never dispatched](ARCHITECTURE.md#when-an-issue-is-sitting-in-the-pipeline-you-never-dispatched).