code-coordinator 0.5.81__tar.gz → 0.5.83__tar.gz

{code_coordinator-0.5.81 → code_coordinator-0.5.83}/CLAUDE.md

@@ -42,13 +42,29 @@ bootstrap only runs where `core.hooksPath` is set: `git config core.hooksPath
 rebase/merge/cherry-pick (so the merge agent's proactive rebase never rebuilds),
 nothing fires at all for `git reset --hard`, every failure path is a silent
 `exit 0` behind a detached 600s-timeout background process, concurrent triggers
-coalesce, and their `[ ! -f graphify-out/graph.json ]` guard is a permanent
-off-switch once the graph is purged. Treat the hooks as an optimization and check
+coalesce, and their `[ ! -f graphify-out/graph.json ]` guard is an off-switch
+once the graph is purged. Treat the hooks as an optimization and check
 freshness instead — `GRAPH_REPORT.md` records its source commit, and
 **`coord diagnose --graph`** compares that to HEAD for every local checkout (and
 flags an unset `core.hooksPath`). If it reports STALE, `graphify update .` in that
 checkout.
 
+**It mostly heals itself now (#1729, #2237).** Each agent's health tick rebuilds
+a checkout whose graph is stale *or absent* — so `rm -rf graphify-out/` is no
+longer permanent — subject to four guards: idle machines only, base checkouts
+only (never a linked worktree), once per HEAD (a build that cannot succeed is
+never a retry loop), and never `--force`. What it cannot do is anything
+versioned: `.githooks/` are tracked files, so porting them to a repo is a PR
+against that repo.
+
+**`coord repo doctor <repo>`** reports graph readiness **per machine** (folded
+from each agent's `/health`, no extra round trip) — the operator's laptop is
+usually not where the workers run. `--fix` performs the machine-local half
+(`graphify update .` where absent, `core.hooksPath` where unset) on every
+machine that clones the repo; it is idempotent, never writes a tracked file,
+and refuses on a repo whose `.githooks/` were never ported. A repo with no
+graph on *any* machine that runs workers is CRIT and fails the gate.
+
 Setting this up on a new machine: [`docs/GRAPHIFY_SETUP.md`](docs/GRAPHIFY_SETUP.md).
 
 ## Architecture
@@ -155,7 +171,7 @@ One line each — the reasoning behind them is in
 - **`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.** The brain reads issue bodies and infers which files will be touched.
+- **Conflict rules are inferred, not configured** — and only on the `coord plan` path. Overlap avoidance is a line in the planning brain's *prompt*, not a mechanism; the drive queue bypasses the brain entirely, so unattended work gets no file-overlap check. There is no `file_groups`/`exclusive_files` config.
 - **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).

{code_coordinator-0.5.81 → code_coordinator-0.5.83}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.81
+Version: 0.5.83
 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.81 → code_coordinator-0.5.83}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.81
+Version: 0.5.83
 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.81 → code_coordinator-0.5.83}/code_coordinator.egg-info/SOURCES.txt

@@ -187,10 +187,10 @@ coord/dashboard/webapp/dist/index.html
 coord/dashboard/webapp/dist/manifest.webmanifest
 coord/dashboard/webapp/dist/sw.js
 coord/dashboard/webapp/dist/workbox-e4022e15.js
-coord/dashboard/webapp/dist/assets/Gallery-da3qNiIw.js
+coord/dashboard/webapp/dist/assets/Gallery-Cq84itDE.js
 coord/dashboard/webapp/dist/assets/Terminal-9CEnUXvW.css
-coord/dashboard/webapp/dist/assets/Terminal-skVFCxPU.js
-coord/dashboard/webapp/dist/assets/index-DltfZR5f.js
+coord/dashboard/webapp/dist/assets/Terminal-DOXLcMue.js
+coord/dashboard/webapp/dist/assets/index-DHn-RIJ8.js
 coord/dashboard/webapp/dist/assets/index-Dq4kwTdw.css
 coord/dashboard/webapp/dist/assets/workbox-window.prod.es5-BqEJf4Xk.js
 coord/dashboard/webapp/dist/icons/icon-192.png
@@ -311,6 +311,7 @@ coord/health/checks/fleet_deploy_lanes.py
 coord/health/checks/fleet_phantom.py
 coord/health/checks/fleet_unit_drift.py
 coord/health/checks/graph.py
+coord/health/checks/graphify_cli.py
 coord/health/checks/plan_usage.py
 coord/health/checks/repo_state.py
 coord/health/checks/spawned_coord.py
@@ -577,6 +578,7 @@ tests/test_generated_types_fixture.py
 tests/test_github_ops.py
 tests/test_goal.py
 tests/test_graph_health.py
+tests/test_graph_selfheal_absent_2237.py
 tests/test_handoff.py
 tests/test_health_checks.py
 tests/test_health_cli.py
@@ -673,6 +675,7 @@ tests/test_release_window.py
 tests/test_remote_auto_prune.py
 tests/test_remote_interactive_reaper.py
 tests/test_repo_edit_2220.py
+tests/test_repo_graph_fleet_2237.py
 tests/test_repo_onboard_2220.py
 tests/test_report_result_push.py
 tests/test_reports.py

{code_coordinator-0.5.81 → code_coordinator-0.5.83}/code_coordinator.egg-info/scm_file_list.json

@@ -225,6 +225,7 @@
     "coord/health/checks/fleet_phantom.py",
     "coord/health/checks/fleet_unit_drift.py",
     "coord/health/checks/graph.py",
+    "coord/health/checks/graphify_cli.py",
     "coord/health/checks/plan_usage.py",
     "coord/health/checks/repo_state.py",
     "coord/health/checks/spawned_coord.py",
@@ -607,6 +608,7 @@
     "tests/test_github_ops.py",
     "tests/test_goal.py",
     "tests/test_graph_health.py",
+    "tests/test_graph_selfheal_absent_2237.py",
     "tests/test_handoff.py",
     "tests/test_health_checks.py",
     "tests/test_health_cli.py",
@@ -703,6 +705,7 @@
     "tests/test_remote_auto_prune.py",
     "tests/test_remote_interactive_reaper.py",
     "tests/test_repo_edit_2220.py",
+    "tests/test_repo_graph_fleet_2237.py",
     "tests/test_repo_onboard_2220.py",
     "tests/test_report_result_push.py",
     "tests/test_reports.py",

{code_coordinator-0.5.81 → code_coordinator-0.5.83}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.81",
+  "tag": "0.5.83",
   "distance": 0,
-  "node": "gf5568b98773fd08c6165236df1c398d57ecc9260",
+  "node": "gc65c7e49837d7f4990a4606d987a975642e709ae",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-14"

{code_coordinator-0.5.81 → code_coordinator-0.5.83}/coord/agent.py

@@ -82,6 +82,21 @@ CANCELLED = "cancelled"
 # would loop forever on "already implemented" reports); not a clean DONE
 # either. Human should review and decide whether to re-dispatch or close.
 ADVISORY = "advisory"
+# #2234: a NARROWER shape of the #448 zero-commit exit — the worker's own
+# final message shows it stopped because a STANDING repo rule (CLAUDE.md's
+# "only the coordinator writes docs", or similar) makes the dispatched
+# deliverable something no worker can complete, ever, on any attempt (see
+# `_looks_like_policy_refusal`). This is deliberately a status distinct from
+# ADVISORY, not a sub-case reported through it: every downstream consumer of
+# ADVISORY (`coord drive`'s bounded retry, the queue's attempt budget, the
+# terminal `blocked` bucket a human must `remove`) exists to handle "the
+# worker got stuck or found nothing to do" — a condition retrying might fix.
+# A policy refusal is the OPPOSITE: the worker did exactly the right thing,
+# and retrying is guaranteed to reproduce the identical, correct refusal.
+# Landing it in ADVISORY's bucket is what #2234 exists to stop — the #2195
+# incident spent two drive attempts ($0.11 x 2, plus the overnight slot) and
+# a terminal `blocked` rediscovering a rule that was never going to change.
+REFUSED_POLICY = "refused_policy"
 
 # #448: spec types that are expected to push commits, so a clean exit with
 # zero commits is interesting (advisory).  Review/smoke workers commit
@@ -167,6 +182,54 @@ _COMPLETED_HISTORY_CAP = 25
 # within an operator's normal polling cadence.
 _ADVISORY_TERMINAL_CHECK_COOLDOWN_S = 300.0
 
+# #2234: markers that show up when a worker's OWN final message explains
+# that it stopped because of a STANDING repo rule — not because it got stuck
+# or ran out of turns. Matched only against the worker's own account (see
+# `_looks_like_policy_refusal`), never against the briefing or issue body,
+# which quote the same rules on every single dispatch and would false-
+# positive on every assignment if matched directly. `claude.md` is the one
+# filename standing worker-facing rules live in across this repo (see
+# CLAUDE.md's own "Rules for workers" section, "Only the coordinator writes
+# docs"); the rest are lifted verbatim from that same rule's text, which is
+# the shape that triggered this issue (claude-coordinator#2195: an issue
+# whose entire deliverable was a doc edit, dispatched to a worker that
+# correctly refused and stopped). Deliberately permissive rather than
+# requiring an exact quote — a weak/cheap model's terse refusal ("Confirmed:
+# the rule exists verbatim at CLAUDE.md line 156...", the actual #2195
+# transcript) may cite the rule without repeating "must not"/"forbidden"
+# verbatim.
+_POLICY_REFUSAL_MARKERS = (
+    "claude.md",
+    "files_forbidden",
+    "repo rule",
+    "repo's rule",
+    "coordinator work",
+    "only the coordinator",
+    "coordinator-only",
+    "should never have been dispatched",
+)
+
+
+def _looks_like_policy_refusal(text: str | None) -> bool:
+    """#2234: does *text* — the worker's own final message — read as a
+    refusal grounded in a STANDING repo-rule prohibition, rather than a
+    stuck/incomplete session?
+
+    Only ever consulted on the zero-commit/clean-exit shape (`_reap` calls
+    this exactly where it would otherwise set `zero_commit_reason` — see
+    below): a worker that pushed real commits never reaches this check, so a
+    successful run that happens to mention `CLAUDE.md` in passing (e.g.
+    "per CLAUDE.md I ran the build before committing") carries no risk of
+    being reclassified. Within that already-narrow shape, an ordinary
+    `STUCK:`-style report (out of turns, couldn't find the code, a flaky
+    test) mentions none of :data:`_POLICY_REFUSAL_MARKERS`, so it is left
+    exactly as ADVISORY as it always was.
+    """
+    if not text:
+        return False
+    lowered = text.lower()
+    return any(marker in lowered for marker in _POLICY_REFUSAL_MARKERS)
+
 
 # ── Reap tuning ───────────────────────────────────────────────────────────────
 # claude-cli sometimes does not exit after emitting its final
@@ -715,36 +778,20 @@ def _is_linked_worktree(repo_path: Path) -> bool:
 def _graphify_update(repo_path: Path, *, timeout: float = 600.0) -> tuple[bool, str]:
     """Run ``graphify update .`` in *repo_path* (#1729, H-6's self-heal).
 
-    Deliberately the plain, no-flags command graphify's own hooks run (see
-    ``docs/GRAPHIFY_SETUP.md``) — **never** ``--force``: that flag exists
-    only to defeat graphify's node-count refusal guard, and defeating it
-    automatically is exactly what turns a visible stall into silent
-    corruption of the graph agents navigate by (#1729 guard 4).
+    Thin delegate to :func:`coord.graph_health.run_graphify_update` (#2237),
+    which is the single place that decides what command coord shells out to
+    and with which flags — ``coord repo doctor --fix`` repairs checkouts on
+    every machine through the same function, and two copies of "the command
+    graphify's hooks run, never ``--force``" is exactly the split-brain that
+    would let one of them quietly acquire the flag that caused the
+    2026-08-02 incident.
 
-    Returns ``(ok, detail)``. ``ok`` is False on a non-zero exit, a missing
-    ``graphify`` binary, or a timeout — the caller treats all three the
-    same way: surface the reason on the health check and remember this
-    HEAD as attempted so the next tick does not retry it (guard 3).
+    Kept as a module-level name here because it is the seam the self-heal
+    tests patch. Returns ``(ok, detail)``.
     """
-    try:
-        result = subprocess.run(
-            ["graphify", "update", "."],
-            cwd=str(repo_path),
-            capture_output=True,
-            text=True,
-            timeout=timeout,
-        )
-    except FileNotFoundError:
-        return False, "graphify: command not found on this machine's PATH"
-    except subprocess.TimeoutExpired:
-        return False, f"graphify update . timed out after {timeout:.0f}s"
-    except OSError as exc:
-        return False, f"graphify update . failed to start: {exc}"
+    from coord.graph_health import run_graphify_update  # noqa: PLC0415
 
-    if result.returncode != 0:
-        reason = (result.stderr or result.stdout or "").strip()
-        return False, reason or f"graphify update . exited {result.returncode}"
-    return True, (result.stdout or "").strip()
+    return run_graphify_update(repo_path, timeout=timeout)
 
 
 # #2212: count how many Bash commands in a worker's leg invoked `graphify` —
@@ -2941,6 +2988,16 @@ class AgentAssignment:
     # (a normal work assignment's deliverable is the diff itself, already
     # visible on the PR — restating the transcript there would be noise).
     result_text: str | None = None
+    # #2234: the worker's own final message when `_reap` classifies a clean
+    # (exit_code==0), 0-commit exit as a policy refusal (`status ==
+    # REFUSED_POLICY`) rather than the #448 ADVISORY default — see
+    # `_looks_like_policy_refusal`. `None` on every other outcome, including
+    # an ordinary zero-commit ADVISORY (no marker matched) and the #2188
+    # analysis-deliverable success shape (mutually exclusive with this one:
+    # both are decided in the same `_ahead == 0` branch of `_reap`, and only
+    # one of `analysis_deliverable`/`zero_commit_reason`/this field is ever
+    # set for a given assignment).
+    policy_refusal_reason: str | None = None
 
     def to_dict(self) -> dict:
         d = asdict(self)
@@ -4151,6 +4208,21 @@ class AgentServer:
         # already follows.
         self._graph_rebuild_in_progress: set[str] = set()
 
+        # #2237 item 7: guard 1 (the idle-gate) skips the whole self-heal
+        # pass whenever this machine has a RUNNING assignment. Sensible —
+        # a rebuild during a worker's leg fights it for CPU — but it means
+        # the BUSIEST machine in the fleet gets the FEWEST heal windows,
+        # which is the opposite of where drift accumulates. Nothing recorded
+        # that, so "this machine never gets an idle window" was
+        # indistinguishable from "this machine never needed a heal".
+        # Measure before changing the guard: these two counters ride
+        # /health's `graph_self_heal` block so the ratio is observable, and
+        # only if it turns out to be common does the guard need replacing
+        # with a heal window.
+        self._graph_heal_skipped_active: int = 0
+        self._graph_heal_last_skip_at: float | None = None
+        self._graph_heal_passes: int = 0
+
         self.state_dir.mkdir(parents=True, exist_ok=True)
         self.log_dir.mkdir(parents=True, exist_ok=True)
         self._load_state()
@@ -4163,7 +4235,7 @@ class AgentServer:
             completed = sum(
                 1
                 for a in self._assignments.values()
-                if a.status in (DONE, FAILED, CANCELLED, ADVISORY)
+                if a.status in (DONE, FAILED, CANCELLED, ADVISORY, REFUSED_POLICY)
             )
         worktree_bytes = self._cached_worktree_bytes()
         artifact_bytes = self._cached_artifact_bytes()
@@ -4224,6 +4296,19 @@ class AgentServer:
             # block (`_cached_local_health`'s own try/except) rather than
             # omitting the key, so an old/new client can always find it.
             "health": self._cached_local_health(),
+            # #2237 item 7: how often the graph self-heal pass has actually
+            # run on this machine, and how often guard 1 (the idle-gate)
+            # turned it away because an assignment was RUNNING. The busiest
+            # host in the fleet is the one most likely to drift AND the least
+            # likely to be idle, so "never healed" and "never needed healing"
+            # were indistinguishable until this. Cheap, in-memory, resets on
+            # agent restart — it exists to answer "is the idle-gate starving
+            # this machine", not to be a durable metric.
+            "graph_self_heal": {
+                "passes": self._graph_heal_passes,
+                "skipped_active": self._graph_heal_skipped_active,
+                "last_skip_at": self._graph_heal_last_skip_at,
+            },
         }
 
     def _cached_local_health(self) -> dict:
@@ -4288,6 +4373,19 @@ class AgentServer:
         """React to the ``graph`` check's STATE verdict instead of chasing
         the git events that produced it (#1729, H-6).
 
+        Covers a **missing** graph as well as a stale one (#2237 item 5).
+        Ongoing drift was already handled here; absence was not, because
+        ``graph_status`` returns early for a checkout with no
+        ``graphify-out/graph.json`` and never computes ``stale`` — so this
+        pass skipped it, and so did the graphify hooks' own
+        ``[ ! -f graphify-out/graph.json ] && exit 0``. Two independent
+        mechanisms declining to rebuild a graph that is not there made a
+        single ``rm -rf graphify-out/`` (or a fresh clone on a machine that
+        never had one) permanent until a human intervened. The guards below
+        are unchanged and cover the absent case as-is — in particular guard
+        3, which is what stops a repo where ``graphify update .`` genuinely
+        cannot succeed from retrying every poll forever.
+
         The git hooks (`.githooks/`) are event-driven and structurally
         cannot cover every ref-moving operation — rebase/merge/cherry-pick
         `exit 0`, `git reset --hard` fires no hook at all, and every hook
@@ -4304,8 +4402,13 @@ class AgentServer:
         1. **Idle-gate.** Only when this machine has no RUNNING assignment.
            A rebuild is hundreds of files across many workers; running it
            while a worker is mid-build steals the CPU that worker was
-           dispatched for. This reads `self._assignments` under a brief
-           lock and releases it before the (possibly slow) rebuild runs —
+           dispatched for. Every skip is counted
+           (`_graph_heal_skipped_active`, surfaced as /health's
+           `graph_self_heal` block) because the guard's cost lands hardest
+           on the busiest machine — the one most likely to drift — and
+           #2237 item 7 asks for that to be measured before the guard is
+           traded for a heal window. This reads `self._assignments` under a
+           brief lock and releases it before the (possibly slow) rebuild runs —
            load-bearing for guard-adjacent requirement #1625 decision 3:
            health must stay advisory, so a dispatch landing mid-rebuild
            must never be delayed by it (see `_graphify_update`, called
@@ -4360,13 +4463,32 @@ class AgentServer:
         with self._lock:
             active = sum(1 for a in self._assignments.values() if a.status == RUNNING)
         if active:
+            # #2237 item 7: count the skip instead of returning silently, so
+            # "the busiest machine never heals" is a number an operator can
+            # read off /health rather than an inference from a graph that
+            # stays stale.
+            self._graph_heal_skipped_active += 1
+            self._graph_heal_last_skip_at = time.time()
             return
+        self._graph_heal_passes += 1
 
         for i, result in enumerate(report.results):
             if result.check_id != "graph":
                 continue
             values = result.values or {}
-            if not values.get("stale"):
+            # #2237 item 5: ABSENT counts, not just stale. `graph_status`
+            # returns early with `unknown_reason` when there is no
+            # graphify-out/graph.json, so `stale` is never even computed for a
+            # never-built (or `rm -rf`'d) checkout — which meant two
+            # independent mechanisms declined to rebuild a graph that is not
+            # there: this gate, and the graphify hooks' own
+            # `[ ! -f graphify-out/graph.json ] && exit 0`. Between them, a
+            # single `rm -rf graphify-out/` was permanent. Guard 3's
+            # once-per-HEAD bookkeeping below keys on `head_sha`, which a
+            # never-built checkout now carries (#2237 in `graph_health`), so a
+            # repo where the build genuinely cannot succeed still gets exactly
+            # one attempt per HEAD rather than one per poll.
+            if not values.get("stale") and values.get("present", True):
                 continue
             path_str = values.get("path")
             if not path_str:
@@ -5321,6 +5443,51 @@ class AgentServer:
             servable.append(repo_name)
         return servable, degraded
 
+    def fix_graph(self, repo_name: str, *, timeout: float = 600.0) -> dict:
+        """Repair the machine-local half of graphify for *repo_name* here
+        (#2237 item 1 — the agent side of ``coord repo doctor --fix``).
+
+        The whole point of routing this through the agent is that the
+        operator's laptop is *not* where the workers run: layer 5 was the one
+        onboarding layer probed only on the machine running the command, so a
+        repo with a graph on the operator's box and none on dellserver
+        reported clean. Repairing it has the same shape — a fix that only
+        ever repairs the local clone fixes the machine that needed it least.
+
+        Idempotent and never touches a tracked file:
+        :func:`coord.graph_health.apply_local_graph_fix` sets
+        ``core.hooksPath`` and builds a missing graph, and refuses outright
+        when the repo does not ship ``.githooks/post-checkout`` (a versioned
+        change, which is a PR against that repo and must never be automated).
+
+        Returns the :meth:`~coord.graph_health.GraphFixResult.to_dict` shape
+        plus ``repo``. An unknown repo, or one with no checkout on this
+        machine, comes back as a ``refused`` result rather than an error —
+        the caller is sweeping every machine and wants a per-machine answer,
+        not an exception that hides the other machines' results.
+        """
+        from coord.graph_health import GraphFixResult, apply_local_graph_fix  # noqa: PLC0415
+
+        path_str = self.repo_paths.get(repo_name)
+        if not path_str:
+            result = GraphFixResult(
+                repo_path="",
+                refused=f"no repo_path configured for {repo_name!r} on this machine",
+            )
+            return {**result.to_dict(), "repo": repo_name}
+
+        repo_path = Path(path_str).expanduser()
+        result = apply_local_graph_fix(repo_path, timeout=timeout)
+        # A rebuild that succeeds here invalidates whatever this HEAD was
+        # last recorded as failing (guard 3's bookkeeping) — otherwise the
+        # self-heal would keep replaying a stale failure reason at an
+        # operator who just fixed it by hand.
+        if result.ok:
+            with self._lock:
+                self._graph_rebuild_failed.pop(str(repo_path), None)
+            self._local_health_cache = None
+        return {**result.to_dict(), "repo": repo_name}
+
     def list_repos(self) -> dict[str, dict]:
         """Return local HEAD / branch / dirty flag for each configured repo.
 
@@ -6011,17 +6178,28 @@ class AgentServer:
         ``zero_commit_reason`` when the reap already flagged ADVISORY, since
         that is the string `coord status`, the dashboard and the GitHub
         advisory comment all render) is what makes the loss visible.
+
+        #2234 fix-1: mirrors the same rewrite for a REFUSED_POLICY reap —
+        ``policy_refusal_reason`` (not ``zero_commit_reason``) is the string
+        the refused_policy GitHub comment and `coord status` render for that
+        status, so a dirty worktree left behind by an otherwise-correct
+        policy refusal needs the same visibility, on the field that surface
+        actually reads.
         """
         with self._lock:
             live = self._assignments.get(assignment.id, assignment)
             live.dirty_worktree_reason = reason
             if live.status == ADVISORY:
                 live.zero_commit_reason = reason
+            elif live.status == REFUSED_POLICY:
+                live.policy_refusal_reason = reason
             # Keep the caller's object in sync when it isn't the live one, so
             # a caller holding a detached copy still sees the outcome.
             assignment.dirty_worktree_reason = reason
             if assignment.status == ADVISORY:
                 assignment.zero_commit_reason = reason
+            elif assignment.status == REFUSED_POLICY:
+                assignment.policy_refusal_reason = reason
         self._persist()
 
     def _rescue_uncommitted_work(
@@ -7379,6 +7557,11 @@ class AgentServer:
         # assignment.
         _analysis_deliverable = False
         _zero_commit_reason: str | None = None
+        # #2234: set alongside (never together with) `_zero_commit_reason` —
+        # both are decided in the SAME `_ahead == 0` branch below so the two
+        # readings of "0 commits" can never disagree about which one applies
+        # to this assignment.
+        _policy_refusal_reason: str | None = None
         if (exit_code == 0 and assignment is not None
                 and assignment.worktree_path
                 and assignment.spec.type in _ZERO_COMMIT_TYPES):
@@ -7399,6 +7582,30 @@ class AgentServer:
                                 )
                         except OSError:
                             pass
+                    elif _worker_summary is not None and _looks_like_policy_refusal(
+                        _worker_summary.result_text
+                    ):
+                        # #2234: the worker's own final message cites a
+                        # standing repo-rule prohibition as the reason it
+                        # stopped — the #2195 shape. Distinct from the
+                        # ADVISORY fallback below: retrying this assignment
+                        # cannot change a rule that isn't going anywhere, so
+                        # it must not consume the queue's attempt budget or
+                        # land in the same bucket as a genuinely stuck
+                        # worker.
+                        _policy_refusal_reason = _worker_summary.result_text or (
+                            "worker cited a standing repo-rule prohibition"
+                        )
+                        try:
+                            with open(assignment.log_path, "a") as reopen:
+                                reopen.write(
+                                    "# reap: refused_policy — 0 commits ahead "
+                                    f"of {_base}; worker's final message cites "
+                                    "a standing repo-rule prohibition, status "
+                                    "set to refused_policy (#2234)\n"
+                                )
+                        except OSError:
+                            pass
                     else:
                         _zero_commit_reason = (
                             "worker exited cleanly but pushed 0 commits"
@@ -7472,6 +7679,17 @@ class AgentServer:
                         # shrug.
                         assignment.status = FAILED
                         assignment.push_failure_reason = _push_failure_reason
+                    elif _policy_refusal_reason is not None:
+                        # #2234: clean exit, no commits, and the worker's own
+                        # final message cites a standing repo-rule
+                        # prohibition — a distinct, permanent shape of "0
+                        # commits", not the generic #448 ADVISORY. Checked
+                        # BEFORE `_zero_commit_reason` (the two are mutually
+                        # exclusive by construction — see the `_reap`
+                        # computation above — so the order is never actually
+                        # load-bearing, kept parallel to it for readability).
+                        assignment.status = REFUSED_POLICY
+                        assignment.policy_refusal_reason = _policy_refusal_reason
                     elif _zero_commit_reason is not None:
                         # #448: clean exit but no commits → advisory, not done.
                         assignment.status = ADVISORY
@@ -7732,8 +7950,16 @@ class AgentServer:
             ):
                 return
             self._last_advisory_terminal_check = now
+            # #2234: REFUSED_POLICY joins ADVISORY here for the same reason
+            # — both are terminal, zero-commit statuses the agent would
+            # otherwise keep serving indefinitely from its own `/status`
+            # feed once GitHub confirms the work is done, forcing every
+            # downstream consumer (dashboard, TUI, any future client) to
+            # reimplement the same GitHub-terminality filter this method
+            # exists to spare them.
             candidates = [
-                a for a in self._assignments.values() if a.status == ADVISORY
+                a for a in self._assignments.values()
+                if a.status in (ADVISORY, REFUSED_POLICY)
             ]
         if not candidates:
             return
@@ -7805,7 +8031,14 @@ class AgentServer:
             ordered = list(self._assignments.values())
             superseded_ids: list[str] = []
             for i, a in enumerate(ordered):
-                if a.status != ADVISORY:
+                # #2234: REFUSED_POLICY joins ADVISORY here too — a refusal
+                # for issue X can be superseded the same way an advisory can
+                # (e.g. the coordinator re-scopes the issue so a later
+                # dispatch's deliverable is no longer coordinator-only, and
+                # that later attempt reaches DONE). Same in-memory
+                # comparison, same root cause as `_prune_terminal_advisory`
+                # above.
+                if a.status not in (ADVISORY, REFUSED_POLICY):
                     continue
                 key = (a.spec.repo_name, a.spec.issue_number)
                 for later in ordered[i + 1 :]: