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

{code_coordinator-0.5.81 → code_coordinator-0.5.82}/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.82}/PKG-INFO

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

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

@@ -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.82}/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.82}/code_coordinator.egg-info/scm_version.json

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

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

@@ -715,36 +715,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).
-
-    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).
+    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.
+
+    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` —
@@ -4151,6 +4135,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()
@@ -4224,6 +4223,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 +4300,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 +4329,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 +4390,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 +5370,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.
 

{code_coordinator-0.5.81 → code_coordinator-0.5.82}/coord/agent_app.py

@@ -980,6 +980,48 @@ def _openapi_spec() -> dict:
                 "responses": {"200": {"description": "OK"}},
             }
         },
+        "/graph-fix": {
+            "post": {
+                "summary": (
+                    "Build a missing graphify graph and set core.hooksPath for "
+                    "one repo on this machine (#2237)"
+                ),
+                "description": (
+                    "The machine-local half of graphify onboarding only: "
+                    "`graphify update .` when no graph exists here, plus "
+                    "`git config core.hooksPath .githooks`. Idempotent. "
+                    "Refuses (200, `refused` set) when the repo does not ship "
+                    "`.githooks/post-checkout` — porting those is a versioned "
+                    "change and is never automated."
+                ),
+                "requestBody": {
+                    "required": True,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "type": "object",
+                                "required": ["repo"],
+                                "properties": {
+                                    "repo": {"type": "string"},
+                                    "timeout": {
+                                        "type": "number",
+                                        "description": (
+                                            "seconds for `graphify update .`; a "
+                                            "first build on a large repo is "
+                                            "minutes, so this defaults to 600."
+                                        ),
+                                    },
+                                },
+                            }
+                        }
+                    },
+                },
+                "responses": {
+                    "200": {"description": "OK (including a refusal)"},
+                    "400": {"description": "repo missing from the body"},
+                },
+            }
+        },
         "/artifact/{repo}/{branch}": {
             "get": {
                 "summary": "Manifest of stashed build artifacts for a (repo, branch) pair",
@@ -1874,6 +1916,40 @@ def build_app(
             }
         )
 
+    async def graph_fix(request: Request) -> JSONResponse:
+        """Repair graphify's machine-local half for one repo on THIS machine
+        (#2237) — ``coord repo doctor --fix`` fans this out to every machine
+        that clones the repo.
+
+        Body: ``{"repo": "<name>", "timeout": 600}``. ``repo`` is required;
+        anything else is ignored, so an older coordinator posting extra
+        fields and a newer one omitting optional ones both work.
+
+        Idempotent by construction (``git config core.hooksPath`` +
+        ``graphify update .``), and it **refuses** rather than acting when
+        the repo does not ship ``.githooks/post-checkout`` — see
+        :func:`coord.graph_health.apply_local_graph_fix`. Never writes a
+        tracked file, so this can never turn into "the tool silently
+        committed hooks into my repo".
+
+        Runs off the event loop: a first build is minutes of AST work, and
+        blocking the loop here would stall /health for the whole fleet.
+        """
+        body: dict = {}
+        try:
+            body = await request.json()
+        except Exception:
+            pass
+        repo = body.get("repo")
+        if not isinstance(repo, str) or not repo:
+            return JSONResponse({"error": "repo is required"}, status_code=400)
+        try:
+            timeout = float(body.get("timeout", 600.0))
+        except (TypeError, ValueError):
+            timeout = 600.0
+        result = await asyncio.to_thread(server.fix_graph, repo, timeout=timeout)
+        return JSONResponse(result)
+
     routes = [
         Route("/health", health, methods=["GET"]),
         Route("/status", status, methods=["GET"]),
@@ -1895,6 +1971,10 @@ def build_app(
         Route("/rollback", rollback, methods=["POST"]),
         Route("/restart", restart, methods=["POST"]),
         Route("/worktree-clean", worktree_clean, methods=["POST"]),
+        # #2237: `coord repo doctor --fix`'s per-machine leg — build a
+        # missing graph and set core.hooksPath, on the machines that
+        # actually run workers rather than only on the operator's laptop.
+        Route("/graph-fix", graph_fix, methods=["POST"]),
         # #305: artifact stash manifest (GET /artifact/<repo>/<branch>)
         Route("/artifact/{repo}/{branch}", artifact_manifest, methods=["GET"]),
         # #207: CPU + memory snapshot for TUI sparklines

{code_coordinator-0.5.81 → code_coordinator-0.5.82}/coord/commands/repo.py

@@ -293,9 +293,27 @@ def repo_add(  # noqa: PLR0913 — one option per thing the command can set
         "for this repo's paths, and (if it joins the oracle loop) "
         "`acceptance.drivers`."
     )
+    # #2237: layer 5 used to be one vague line here and nothing else — so
+    # every repo onboarded from this command started with no graph, and the
+    # only thing that would ever say so was a `repo doctor` nobody is obliged
+    # to run. Split into the two halves that have genuinely different owners:
+    # the versioned port (a PR against the repo, never automated) and the
+    # machine-local half (idempotent, and `--fix` does it on every machine).
     click.echo(
-        "  7. graphify build + `graphify hook install` + `core.hooksPath`, in "
-        "that order, per machine (docs/GRAPHIFY_SETUP.md)."
+        "  7. GRAPH, versioned half — port `.githooks/` (_lib.sh, "
+        "post-checkout, post-commit, post-merge) into the repo and commit "
+        "them. Tracked files, so one PR reaches every machine. Without them "
+        "worktrees get no linked graph and every worker falls back to grep "
+        "(docs/GRAPHIFY_SETUP.md)."
+    )
+    click.echo(
+        "  8. GRAPH, machine-local half — once the repo is cloned on each "
+        f"machine: `coord repo doctor {name} --fix` builds the graph "
+        "(`graphify update .`) and sets `core.hooksPath .githooks` on every "
+        "machine that runs workers. Idempotent; safe to re-run. Do it AFTER "
+        "step 7 — pointing core.hooksPath at a .githooks/ that does not "
+        "exist silently disables every hook in the checkout, so --fix refuses "
+        "until the hooks are ported."
     )
     click.echo("")
     click.echo(f"Then: coord repo doctor {name}")
@@ -306,8 +324,10 @@ def repo_add(  # noqa: PLR0913 — one option per thing the command can set
     help=(
         "Probe all five onboarding layers for a repo and report per-layer "
         "status. Reads LIVE state — each agent's /health repo list, the labels "
-        "that exist on GitHub, whether any workflow triggers on pull_request — "
-        "not config. Exits non-zero on any CRIT so it can gate."
+        "that exist on GitHub, whether any workflow triggers on pull_request, "
+        "and (since #2237) each machine's graph readiness rather than only "
+        "this one's — not config. Exits non-zero on any CRIT so it can gate. "
+        "Use --fix to repair the machine-local half of the graph layer."
     ),
 )
 @click.argument("name")
@@ -324,12 +344,28 @@ def repo_add(  # noqa: PLR0913 — one option per thing the command can set
     "--verbose", "-v", is_flag=True, default=False,
     help="Show passing checks too, not just the residue.",
 )
-def repo_doctor(
+@click.option(
+    "--fix", "do_fix", is_flag=True, default=False,
+    help=(
+        "Repair graphify's MACHINE-LOCAL half on every machine that clones "
+        "this repo: build a missing graph (`graphify update .`) and set "
+        "`core.hooksPath .githooks`. Idempotent, never touches a tracked "
+        "file, and refuses on a repo that has not ported `.githooks/` — that "
+        "port is a PR against the repo, reported here as remaining work."
+    ),
+)
+@click.option(
+    "--fix-timeout", default=900.0, show_default=True, type=float,
+    help="Per-machine timeout for --fix (a first graph build is minutes).",
+)
+def repo_doctor(  # noqa: PLR0913 — one option per thing the command can do
     name: str,
     config_path: Path,
     timeout: float,
     probe_github: bool,  # noqa: FBT001
     verbose: bool,  # noqa: FBT001
+    do_fix: bool,  # noqa: FBT001
+    fix_timeout: float,
 ) -> None:
     from coord import repo_onboard  # noqa: PLC0415
     from coord.network import check_all  # noqa: PLC0415
@@ -355,6 +391,14 @@ def repo_doctor(
     machines = [m for m in cfg.machines if name in (m.repos or [])]
     statuses = check_all(machines, timeout=timeout) if machines else []
 
+    if do_fix:
+        # Repair BEFORE reporting, so the report an operator reads is the
+        # state they are actually leaving behind — a --fix run that printed
+        # the pre-fix findings would be indistinguishable from one that did
+        # nothing.
+        _run_graph_fix(cfg, name, machines, statuses, timeout=fix_timeout)
+        statuses = check_all(machines, timeout=timeout) if machines else []
+
     facts = repo_onboard.gather_facts(
         cfg, name,
         statuses=statuses,
@@ -366,3 +410,85 @@ def repo_doctor(
         click.echo(line)
     if not report.ok:
         sys.exit(1)
+
+
+def _run_graph_fix(cfg, name: str, machines, statuses, *, timeout: float) -> None:
+    """``--fix``: graphify's machine-local half, on every machine (#2237).
+
+    Fans out to each machine's agent (``POST /graph-fix``) rather than
+    repairing the local clone, because the local clone is the one that
+    matters least: workers run on dellserver and precision, the operator runs
+    this on elitebook. A fixer that only ever fixed here would recreate
+    layer 5's original blind spot one level up.
+
+    The local clone is still repaired directly when this machine has one that
+    no agent covers — an operator's laptop is a legitimate place to want a
+    graph, it just isn't a place workers run.
+
+    Everything it does is idempotent and machine-local (``graphify update .``,
+    ``git config core.hooksPath``); the versioned ``.githooks/`` port is
+    reported as remaining work by the report that follows, never performed.
+    """
+    import httpx  # noqa: PLC0415
+    from coord.network import AGENT_PORT  # noqa: PLC0415
+
+    click.echo(f"--fix: repairing graphify's machine-local half for {name}")
+    online = {s.machine.name for s in statuses if s.is_online}
+    fixed_paths: set[str] = set()
+
+    for machine in machines:
+        if machine.name not in online:
+            click.echo(
+                f"  ⚠ {machine.name}: skipped — agent not reachable, so nothing "
+                f"here could be repaired (it is NOT known to be fine)"
+            )
+            continue
+        try:
+            resp = httpx.post(
+                f"http://{machine.host}:{AGENT_PORT}/graph-fix",
+                json={"repo": name, "timeout": timeout},
+                timeout=timeout + 30.0,
+            )
+            resp.raise_for_status()
+            result = resp.json()
+        except Exception as exc:  # noqa: BLE001 — one machine must not abort the sweep
+            click.echo(f"  ✗ {machine.name}: /graph-fix failed — {exc}")
+            continue
+        for line in _format_fix_result(machine.name, result):
+            click.echo(line)
+        if result.get("repo_path"):
+            fixed_paths.add(str(Path(result["repo_path"]).expanduser()))
+
+    # The local clone, when it is not one of the checkouts just repaired.
+    from coord import repo_onboard  # noqa: PLC0415
+    from coord.graph_health import apply_local_graph_fix  # noqa: PLC0415
+
+    local = repo_onboard.local_clone_path(cfg, name)
+    if local is not None and str(local.expanduser()) not in fixed_paths:
+        result = apply_local_graph_fix(local, timeout=timeout).to_dict()
+        for line in _format_fix_result("this machine", result):
+            click.echo(line)
+    click.echo("")
+
+
+def _format_fix_result(where: str, result: dict) -> list[str]:
+    """Render one machine's ``/graph-fix`` result.
+
+    A refusal reads as a refusal, not a failure and emphatically not a
+    success: "no `.githooks/` in this repo" means the fixer deliberately did
+    nothing, and the operator's next move is a PR, not a re-run.
+    """
+    if result.get("refused"):
+        return [f"  ⊘ {where}: refused — {result['refused']}"]
+    lines: list[str] = []
+    for step in result.get("steps") or []:
+        if step.get("ok") and step.get("changed"):
+            mark = "✓"
+        elif step.get("ok"):
+            mark = "·"  # already in the desired state — the idempotent no-op
+        else:
+            mark = "✗"
+        lines.append(f"  {mark} {where}: {step.get('action')} — {step.get('detail')}")
+    if not lines:
+        lines.append(f"  · {where}: nothing to do")
+    return lines

{code_coordinator-0.5.81 → code_coordinator-0.5.82}/coord/commands/status.py

@@ -963,12 +963,13 @@ def _repo_onboarding_lines(cfg, statuses) -> list[tuple[bool, str]]:
     two-thirds onboarded for days and the only thing that ever noticed was a
     queue entry dying of it.
 
-    Runs with ``probe_github=False`` and no graph probe, so it costs **zero**
-    extra round trips — it re-reads the ``/health`` bodies this command has
-    already fetched. That is enough for the finding that actually bit: the
-    #2219 agent/config repo skew is visible from ``/health`` alone. The GitHub
-    and repo-contents layers need ``coord repo doctor <name>``, which the
-    footer below points at.
+    Runs with ``probe_github=False`` and no local-disk graph probe, so it costs
+    **zero** extra round trips — it re-reads the ``/health`` bodies this
+    command has already fetched. That is enough for the two findings that
+    actually bit: the #2219 agent/config repo skew, and (since #2237) a repo
+    with no graph on any machine that runs workers — both visible from
+    ``/health`` alone. The GitHub and repo-contents layers need ``coord repo
+    doctor <name>``, which the footer below points at.
 
     Mirrors :func:`_unit_drift_lines`/:func:`_release_lag_lines`: same
     computation as the dedicated command (#2096's "two surfaces, one