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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.80
+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.80 → 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.80
+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.80 → 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.80 → 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.80 → code_coordinator-0.5.82}/code_coordinator.egg-info/scm_version.json

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

{code_coordinator-0.5.80 → 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` —
@@ -756,13 +740,11 @@ def _graphify_update(repo_path: Path, *, timeout: float = 600.0) -> tuple[bool,
 # across N consecutive legs means the prompt instruction isn't landing.
 # Deliberately NOT a DB column: this is a cheap, best-effort signal, not a
 # gate anything blocks on, so it stays out of the Assignment schema/migrations.
-# Separators recognized before a command token: `;`, `&`, `|` (covers `&&`
-# and `||` too, since `\s*` after the class soaks up the second char) and a
-# bare newline — Claude Code's Bash tool very commonly emits multi-line
-# command strings (e.g. `cd repo\ngraphify query "foo"`) that aren't joined
-# with `;`/`&&`, so newline must count as a separator or those legs
-# undercount to 0 (#2212 review).
-_GRAPHIFY_INVOCATION_RE = re.compile(r"(?:^|[\n;&|]\s*)graphify(?:\s|$)")
+# #2236: the pattern itself now lives in `coord.worker_events`, which grew a
+# need for it when the summary parser started recording each query's OUTCOME
+# and not just the count. Imported lazily (like every other
+# `coord.worker_events` use in this module) rather than duplicated, so the two
+# halves of the measurement can never drift apart on what counts as a query.
 
 
 def _count_graphify_invocations(bash_commands: list[str]) -> int:
@@ -781,7 +763,68 @@ def _count_graphify_invocations(bash_commands: list[str]) -> int:
     b"`` counts once, not twice. Treat the result as an "at least one graph
     query this leg" signal, not an exact invocation tally.
     """
-    return sum(1 for cmd in bash_commands if cmd and _GRAPHIFY_INVOCATION_RE.search(cmd))
+    from coord.worker_events import is_graphify_command  # noqa: PLC0415
+
+    return sum(1 for cmd in bash_commands if is_graphify_command(cmd))
+
+
+def _worktree_graph_present(
+    worktree_path: str | None, repo_path_fallback: str | None = None
+) -> bool:
+    """True iff the worker's checkout has a **resolvable** ``graphify-out/graph.json``.
+
+    #2236: ``graphify_invocations=0`` is ambiguous on its own. Two of five
+    repos ship no graph and no ``.githooks/post-checkout``, so their worktrees
+    get an empty ``graphify-out/`` — and the worker prompt's own escape hatch
+    ("no graph? skip straight to grep, silently") then fires correctly and
+    says nothing. Those workers were *obeying* the rule, not ignoring it, and
+    the counter cannot tell them apart from a worker that had a graph and
+    never asked. Recording this alongside the count is what disambiguates.
+
+    *repo_path_fallback* mirrors the branch-capture logic a few hundred
+    lines up in ``_reap`` ("for legacy assignments (no worktree_path) we
+    fall back to the main repo clone"): a legacy/non-worktree assignment has
+    no ``worktree_path`` at all, but its worker still ran against
+    ``spec.repo_path`` directly, which may have a perfectly good graph.
+    Without this fallback, every legacy assignment logs ``graph_present=0``
+    regardless — conflating "no worktree" with "no graph".
+
+    ``exists()`` follows symlinks deliberately: a linked worktree's
+    ``graph.json`` is a symlink into the base checkout (see
+    ``coord/graph_health.py``), and a *dangling* symlink is exactly as
+    graph-blind as no file at all — so both must read as absent.
+    """
+    path = worktree_path or repo_path_fallback
+    if not path:
+        return False
+    try:
+        return (Path(path) / "graphify-out" / "graph.json").exists()
+    except OSError:
+        return False
+
+
+def _format_graphify_query_lines(queries: Iterable[Any]) -> list[str]:
+    """Render per-query ``# graphify_query …`` log lines (#2236).
+
+    ``graphify_invocations=N`` counts attempts but cannot distinguish
+    "queried and got a useful answer" from "queried, got nothing, fell back to
+    grep" — and those imply opposite fixes (a habit problem the prompt can
+    move, vs. a graph coverage/quality problem no amount of prompting helps).
+    One line per query, ``grep``-able on ``outcome=``, with the command text
+    last because it is the only free-form field.
+    """
+    lines: list[str] = []
+    for q in queries:
+        results = getattr(q, "results", None)
+        # `worker_events._truncate` already newline-strips and trims this
+        # when the `GraphifyQuery` entry is built — no need to redo it here.
+        command = str(getattr(q, "command", ""))
+        lines.append(
+            f"# graphify_query: outcome={getattr(q, 'outcome', 'unknown')} "
+            f"results={results if results is not None else '?'} "
+            f"cmd={command!r}\n"
+        )
+    return lines
 
 
 def _infer_repo_github_slug(repo_path: str) -> str | None:
@@ -4092,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()
@@ -4165,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:
@@ -4229,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
@@ -4245,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
@@ -4301,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:
@@ -5262,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.
 
@@ -7511,9 +7664,27 @@ class AgentServer:
                 _graphify_invocations = _count_graphify_invocations(
                     _worker_summary.bash_commands if _worker_summary is not None else []
                 )
+                # #2236: the count alone can't separate "didn't try" from
+                # "couldn't try" (no graph in this worktree — the prompt's own
+                # escape hatch fires silently) or from "tried, got nothing".
+                # `graph_present` answers the first; the per-query lines below
+                # answer the second. Read while the worktree still exists —
+                # `_cleanup_worktree` runs further down this same function.
+                _graph_present = _worktree_graph_present(
+                    getattr(assignment, "worktree_path", None) if assignment else None,
+                    getattr(assignment.spec, "repo_path", None) if assignment else None,
+                )
                 reopen.write(
                     f"# reap: done (exit_code={exit_code} status={final_status} "
-                    f"graphify_invocations={_graphify_invocations})\n"
+                    f"graphify_invocations={_graphify_invocations} "
+                    f"graph_present={int(_graph_present)})\n"
+                )
+                reopen.writelines(
+                    _format_graphify_query_lines(
+                        _worker_summary.graphify_queries
+                        if _worker_summary is not None
+                        else []
+                    )
                 )
         except (OSError, AttributeError):
             pass

{code_coordinator-0.5.80 → 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