code-coordinator 0.5.70__tar.gz → 0.5.72__tar.gz

{code_coordinator-0.5.70 → code_coordinator-0.5.72}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.70",
+  "tag": "0.5.72",
   "distance": 0,
-  "node": "g522a9f215942bd8d54b0906c6f672934c636ad73",
+  "node": "gf89a7326b4afe98af0d76d9cbafabea51928013f",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-14"

{code_coordinator-0.5.70 → code_coordinator-0.5.72}/coord/commands/status.py

@@ -1464,6 +1464,15 @@ def _diagnose_graph_health(config_path: Path) -> None:
     checks ``core.hooksPath``, the one-time per-machine setting that decides
     whether worktrees on this box get a linked graph at all.
 
+    #2211: also reports HEAD vs ``origin/<default_branch>``, alongside the
+    existing graph-vs-HEAD comparison.  The base checkout is fetched but
+    never pulled by design (worktrees always branch from a fresh
+    ``origin/<default>``, so a stale base never breaks dispatch) — which
+    means a graph can match HEAD exactly while HEAD itself sits arbitrarily
+    far behind the remote, and the graph-vs-HEAD check alone reports a clean
+    ``✓ in sync`` for it. This never fetches or pulls; it only reads whatever
+    ``origin/<default_branch>`` the last fetch left behind.
+
     Local-machine only, same scope as ``--orphan-worktrees``: it inspects the
     checkouts named in ``coordinator.yml`` that actually exist here.
     """
@@ -1476,7 +1485,7 @@ def _diagnose_graph_health(config_path: Path) -> None:
     cfg = _load_config(config_path)
 
     seen: set[Path] = set()
-    checkouts: list[tuple[str, Path]] = []
+    checkouts: list[tuple[str, Path, str]] = []
     for machine in cfg.machines:
         for repo_cfg in cfg.repos:
             rp = machine.repo_path(repo_cfg.name)
@@ -1486,16 +1495,20 @@ def _diagnose_graph_health(config_path: Path) -> None:
             if path in seen or not (path / ".git").exists():
                 continue
             seen.add(path)
-            checkouts.append((repo_cfg.name, path))
+            checkouts.append((repo_cfg.name, path, repo_cfg.default_branch or "main"))
 
     if not checkouts:
         click.echo("no local checkouts from coordinator.yml exist on this machine.")
         return
 
     stale_count = 0
-    for repo_name, path in checkouts:
+    origin_behind_count = 0
+    for repo_name, path, default_branch in checkouts:
         click.echo(f"── {repo_name}")
-        st = graph_status(path)
+        # #2211: default_branch drives the HEAD-vs-origin comparison
+        # alongside the existing graph-vs-HEAD one — never fetches, only
+        # reads whatever `origin/<default_branch>` the last fetch left.
+        st = graph_status(path, default_branch)
         for line in format_status_lines(st):
             click.echo(f"  {line}")
         if st.stale:
@@ -1504,11 +1517,20 @@ def _diagnose_graph_health(config_path: Path) -> None:
                 "    fix: run `graphify update .` in the checkout "
                 "(the hooks skip rebase/merge/cherry-pick and reset --hard)"
             )
+        if st.origin_behind:
+            origin_behind_count += 1
+            click.echo(
+                f"    fix: HEAD is behind origin/{default_branch} — the base "
+                "checkout is fetched but never auto-pulled (by design; "
+                "checkouts are sometimes deliberately parked). Review and "
+                "pull by hand if it isn't."
+            )
         ok, detail = hooks_path_status(path)
         click.echo(f"  {'✓' if ok else '⚠'} {detail}")
 
     click.echo(
-        f"GRAPH_HEALTH: checkouts={len(checkouts)} stale={stale_count}"
+        f"GRAPH_HEALTH: checkouts={len(checkouts)} stale={stale_count} "
+        f"origin_behind={origin_behind_count}"
     )
 
 

{code_coordinator-0.5.70 → code_coordinator-0.5.72}/coord/drive.py

@@ -413,6 +413,10 @@ class AcceptanceGateChecker(Protocol):
         issue_labels: tuple[str, ...],
     ) -> bool: ...
 
+    def has_authored_slice(
+        self, repo_name: str, milestone_number: int, issue_number: int,
+    ) -> bool: ...
+
 
 @dataclass
 class GitHubAcceptanceGateChecker:
@@ -478,6 +482,35 @@ class GitHubAcceptanceGateChecker:
         )
         return readiness.exempt
 
+    def has_authored_slice(
+        self, repo_name: str, milestone_number: int, issue_number: int,
+    ) -> bool:
+        """#2061: the AUTHORITATIVE answer to "has this issue's JIT slice
+        landed?" — the manifest on the repo's default branch, read via the
+        identical ``test_ids_for_issue`` check the #1138 hard gate
+        (:func:`coord.milestone_dispatch.issue_oracle_ready`) already
+        performs, exposed here as ``OracleReadiness.has_slice``.
+
+        :func:`_decide_acceptance_author` calls this — instead of trusting
+        the `type="test-author"` assignment row alone — at every point
+        where the row is about to be read as "nothing was authored": no
+        row yet, or a terminal (``failed``/``cancelled``/``advisory``/
+        ``done``) status with no branch commits. The assignment row is a
+        PROXY for this question; it can be stale (a drive that died
+        mid-run, a retry, or a #2020-mangled row) while an EARLIER attempt
+        already merged the slice. The manifest cannot lie about that: if
+        the slice is there, it landed, whatever the row says.
+        """
+        from coord.milestone_dispatch import issue_oracle_ready  # noqa: PLC0415
+
+        repo_cfg = self.config.repo(repo_name)
+        if repo_cfg is None:
+            return False
+        readiness = issue_oracle_ready(
+            repo_cfg, self.config, milestone_number, issue_number,
+        )
+        return readiness.has_slice
+
 
 @dataclass(frozen=True)
 class OracleDecision:
@@ -623,11 +656,47 @@ def _decide_acceptance_author(
     Landing that last step is what :func:`_decide_acceptance_landing` does,
     with the same bounded ``coord merge --only <aid>`` call
     :func:`_decide_merge` already makes for the work row.
+
+    **#2061 — the assignment row is a proxy, the manifest is the answer.**
+    Every branch below that would otherwise treat "no row" or "a terminal
+    row with no branch commits" as "nothing was authored" first asks
+    :func:`_slice_already_landed`, which reads the manifest on the repo's
+    default branch — the same ``test_ids_for_issue`` check the #1138 hard
+    gate performs. A drive retry re-dispatches this gate without knowing
+    whether an EARLIER attempt already merged the slice; the second author
+    then correctly does nothing (``DONE`` with zero commits, or a stale
+    row that never even started) and, pre-#2061, that correct no-op was
+    read as a terminal failure — killing a run whose slice was already
+    landed and whose real work was ready to dispatch (coord-portal#13).
     """
     aid = state.acceptance_author_aid
     status = state.acceptance_author_status
 
+    def _slice_already_landed() -> bool:
+        """#2061: the `type="test-author"` row above is a PROXY for "has
+        this issue's slice landed?" — a drive that died mid-run, a retry,
+        or a #2020-mangled row can leave it pointing at nothing (or at a
+        genuine failure) while an EARLIER attempt already merged the slice
+        from a previous run. Ask the AUTHORITATIVE question — the manifest
+        on the default branch, via :meth:`AcceptanceGateChecker.
+        has_authored_slice` — whenever the row is about to be read as
+        "nothing was authored": right before dispatching a fresh author,
+        and right before declaring a terminal, commit-less row a failure.
+        Never consulted for "" / "running" (still authoring — the slice
+        cannot be on the default branch yet) or "merged" (already the
+        strongest signal there is), so this costs one extra fetch at a
+        decision point, not one per poll tick.
+        """
+        return gate_checker.has_authored_slice(
+            state.repo, state.milestone_number, state.issue,
+        )
+
     if not aid:
+        # #2061: a retry (or a drive resuming after this run's own board
+        # row went missing/stale) must not re-dispatch an author for a
+        # slice that already landed from an earlier attempt.
+        if _slice_already_landed():
+            return None
         command = [
             "acceptance", "author", state.repo, str(oracle.tracking_issue),
             "--issue", str(state.issue),
@@ -671,6 +740,12 @@ def _decide_acceptance_author(
         return None
 
     if status == "failed":
+        # #2061: this row's FAILED status describes what happened to THIS
+        # author, not whether the issue's slice exists — a retry's row can
+        # fail (or simply be stale) while an earlier attempt already merged
+        # the slice it was about to re-author.
+        if _slice_already_landed():
+            return None
         return _die(
             f"acceptance author {aid} failed — inspect: coord log {aid} "
             f"--machine {state.acceptance_author_machine or machine}\n"
@@ -679,6 +754,8 @@ def _decide_acceptance_author(
         )
 
     if status == "cancelled":
+        if _slice_already_landed():
+            return None
         return _die(
             f"acceptance author {aid} was cancelled — re-dispatch by hand: "
             f"coord acceptance author {state.repo} {oracle.tracking_issue} "
@@ -700,6 +777,11 @@ def _decide_acceptance_author(
         branch = state.acceptance_author_branch
         probe = replace(state, work_branch=branch) if branch else state
         if not branch or not verifier.branch_has_commits(probe):
+            # #2061: a commit-less ADVISORY row IS what an earlier-landed
+            # slice's stale/retried author row looks like — check the
+            # manifest before declaring failure.
+            if _slice_already_landed():
+                return None
             return _die(
                 f"acceptance author {aid} exited ADVISORY with no commits on "
                 "its branch — nothing was authored, so there is no slice to "
@@ -741,6 +823,13 @@ def _decide_acceptance_author(
         branch = state.acceptance_author_branch
         probe = replace(state, work_branch=branch) if branch else state
         if not branch or not verifier.branch_has_commits(probe):
+            # #2061 (coord-portal#13): a re-dispatched author that lands in
+            # a world where the slice is ALREADY on the default branch
+            # correctly does nothing — DONE with zero commits — and that is
+            # not a failure to re-diagnose, it's the terminal case this
+            # whole gate exists to detect. Check the manifest before dying.
+            if _slice_already_landed():
+                return None
             branch_display = repr(branch) if branch else "(none)"
             return _die(
                 f"acceptance author {aid} exited DONE, but its branch "

{code_coordinator-0.5.70 → code_coordinator-0.5.72}/coord/graph_health.py

@@ -81,6 +81,16 @@ class GraphStatus:
     built_sha: str | None = None
     head_sha: str | None = None
     in_sync: bool = False
+    # HEAD vs origin/<default_branch> — the axis graph<->HEAD alone cannot see
+    # (#2211).  The base checkout is fetched but never pulled by design (see
+    # module docstring), so HEAD can sit arbitrarily far behind origin while
+    # graph == HEAD reports a clean bill of health.  ``default_branch`` is the
+    # branch name the comparison used; ``origin_sha`` / ``commits_behind_origin``
+    # are ``None`` when it could not be determined (no remote, ref never
+    # fetched, or the git call failed) rather than treated as "0 behind".
+    default_branch: str | None = None
+    origin_sha: str | None = None
+    commits_behind_origin: int | None = None
     age_seconds: float | None = None
     # mtime of graphify-out/manifest.json — the last time graphify *checked* the
     # graph against the working tree, whether or not it rewrote anything.
@@ -122,6 +132,19 @@ class GraphStatus:
         *unknown* — an unknown is reported separately, not counted as drift."""
         return self.stamp_behind and not self.verified_current
 
+    @property
+    def origin_behind(self) -> bool:
+        """HEAD (of the checkout that owns the graph) is behind
+        ``origin/<default_branch>`` by at least one commit — i.e. the graph
+        may match HEAD exactly and still describe stale code, because HEAD
+        itself is stale relative to the remote (#2211).
+
+        False — not True — when this could not be proven (no remote, the ref
+        was never fetched, or the git call failed): mirrors ``stale``'s rule
+        that an unknown must never be counted as drift.
+        """
+        return bool(self.commits_behind_origin)
+
 
 def read_built_sha(report_path: Path) -> str | None:
     """The commit ``GRAPH_REPORT.md`` says the graph was built from."""
@@ -161,6 +184,22 @@ def _head_committed_at(repo_path: Path) -> float | None:
         return None
 
 
+def _commits_ahead(repo_path: Path, base: str, ahead_of: str) -> int | None:
+    """Count of commits reachable from *ahead_of* that are not in *base*
+    (``git rev-list --count base..ahead_of``).
+
+    Best-effort like the rest of this module: ``None`` (never raised) when
+    git can't answer — an unproven comparison must not be reported as drift.
+    """
+    out = _git_out(repo_path, "rev-list", "--count", f"{base}..{ahead_of}")
+    if out is None:
+        return None
+    try:
+        return int(out)
+    except ValueError:
+        return None
+
+
 def _shas_agree(built: str, head: str) -> bool:
     """Compare on the shorter of the two — the report abbreviates (8 chars by
     default) while ``git rev-parse HEAD`` is full-length."""
@@ -170,12 +209,20 @@ def _shas_agree(built: str, head: str) -> bool:
     return built[:n].lower() == head[:n].lower()
 
 
-def graph_status(repo_path: Path) -> GraphStatus:
+def graph_status(repo_path: Path, default_branch: str = "main") -> GraphStatus:
     """Freshness of the graphify graph for the checkout at *repo_path*.
 
     Read-only and best-effort: a missing graph, a missing report, or a repo
     git can't read all return a populated :class:`GraphStatus` with
     ``unknown_reason`` set rather than raising.
+
+    *default_branch* names the branch to compare HEAD against on
+    ``origin`` (#2211) — pass the repo's configured default branch
+    (``coordinator.yml``'s ``default_branch``, "main" if unset).  Never
+    fetches: it only reads whatever ``origin/<default_branch>`` the last
+    ``git fetch`` left behind, so a checkout that was never fetched or has
+    no ``origin`` remote simply leaves ``origin_sha``/``commits_behind_origin``
+    unset rather than reporting drift it can't prove.
     """
     st = GraphStatus(repo_path=repo_path)
     out_dir = repo_path / "graphify-out"
@@ -213,6 +260,7 @@ def graph_status(repo_path: Path) -> GraphStatus:
     owner = st.link_target.parent if (st.is_symlink and st.link_target) else repo_path
     st.head_sha = _head_sha(owner)
     st.head_committed_at = _head_committed_at(owner)
+    st.default_branch = default_branch
 
     if not st.built_sha:
         st.unknown_reason = "GRAPH_REPORT.md has no 'Built from commit' line"
@@ -220,6 +268,15 @@ def graph_status(repo_path: Path) -> GraphStatus:
         st.unknown_reason = f"could not read HEAD of {owner}"
     else:
         st.in_sync = _shas_agree(st.built_sha, st.head_sha)
+
+    # HEAD vs origin/<default_branch> — independent of the graph<->HEAD
+    # comparison above.  Best-effort: no remote, or the ref not fetched yet,
+    # just leaves this unset (see docstring).
+    if st.head_sha:
+        origin_sha = _git_out(owner, "rev-parse", f"origin/{default_branch}")
+        if origin_sha:
+            st.origin_sha = origin_sha
+            st.commits_behind_origin = _commits_ahead(owner, st.head_sha, origin_sha)
     return st
 
 
@@ -326,17 +383,39 @@ def format_status_lines(st: GraphStatus) -> list[str]:
     if st.is_symlink:
         lines.append(f"↳ {where}/graphify-out → {st.link_target} (linked worktree)")
 
+    # #2211: graph == HEAD only proves the graph matches the checkout's own
+    # HEAD — it says nothing about whether that HEAD itself is stale relative
+    # to origin (the base checkout is fetched but never pulled, by design;
+    # see module docstring).  Shared by both "graph matches HEAD" branches
+    # below so a genuinely-current-but-unpushed-tracking checkout doesn't
+    # report a false ✓.
+    origin_note = ""
+    if st.origin_behind:
+        n = st.commits_behind_origin or 0
+        origin_note = (
+            f" — HEAD is {n} commit{'' if n == 1 else 's'} behind "
+            f"origin/{st.default_branch}; the graph describes stale code "
+            f"(fix: review + pull — not automatic, see #2211)"
+        )
+
     if st.unknown_reason:
         lines.append(f"? {where}: freshness unknown — {st.unknown_reason}")
     elif st.in_sync:
-        lines.append(f"✓ {where}: graph in sync (built from {st.built_sha})")
+        if origin_note:
+            lines.append(
+                f"⚠ {where}: graph matches HEAD (built from {st.built_sha}){origin_note}"
+            )
+        else:
+            lines.append(f"✓ {where}: graph in sync (built from {st.built_sha})")
     elif st.verified_current:
         # Stamp behind, but graphify has re-checked the tree since HEAD landed
         # and found no topology change — the graph content is current.
+        mark = "⚠" if origin_note else "✓"
         lines.append(
-            f"✓ {where}: graph content current — stamp says {st.built_sha} "
+            f"{mark} {where}: graph content current — stamp says {st.built_sha} "
             f"(HEAD {(st.head_sha or '')[:8]}), but verified against the tree "
-            f"since; graphify leaves outputs untouched when topology is unchanged"
+            f"since; graphify leaves outputs untouched when topology is "
+            f"unchanged{origin_note}"
         )
     else:
         lines.append(

{code_coordinator-0.5.70 → code_coordinator-0.5.72}/coord/health/checks/graph.py

@@ -23,6 +23,14 @@ longer HEAD.  That is the 2026-07-30 vimcode incident: 128.8h stale, hooks
 disabled, and nothing in the fleet said so.  Age escalates a
 hooks-working checkout from WARN to CRIT at ``graph_stale_crit_hours``;
 hooks-disabled skips straight to CRIT because time cannot fix it.
+
+**graph == HEAD is not the whole story (#2211).** ``status.stale`` only
+compares the graph to this checkout's OWN HEAD. The base checkout is fetched
+but never pulled (see ``coord.graph_health``'s module docstring), so HEAD can
+sit arbitrarily far behind ``origin/<default_branch>`` while the graph
+matches it exactly — a confidently-correct-looking graph of stale code. This
+module reports that as its own WARN (``status.origin_behind``), independent
+of and never overriding ``status.stale``'s verdict.
 """
 
 from __future__ import annotations
@@ -79,7 +87,10 @@ def probe_graph(ctx: HealthContext) -> list[CheckResult]:
     results: list[CheckResult] = []
 
     for checkout in ctx.checkouts:
-        status = graph_status(checkout.path)
+        # #2211: default_branch drives the HEAD-vs-origin comparison
+        # alongside the existing graph-vs-HEAD one. Never fetches — only
+        # reads whatever origin/<default_branch> the last `git fetch` left.
+        status = graph_status(checkout.path, checkout.default_branch)
         hooks_ok, hooks_detail = hooks_path_status(checkout.path)
 
         values = {
@@ -91,6 +102,10 @@ def probe_graph(ctx: HealthContext) -> list[CheckResult]:
             "verified_current": status.verified_current,
             "built_sha": status.built_sha,
             "head_sha": status.head_sha,
+            "default_branch": status.default_branch,
+            "origin_sha": status.origin_sha,
+            "commits_behind_origin": status.commits_behind_origin,
+            "origin_behind": status.origin_behind,
             "age_seconds": status.age_seconds,
             "age_hours": (
                 round(status.age_seconds / 3600.0, 1) if status.age_seconds is not None else None
@@ -153,11 +168,35 @@ def probe_graph(ctx: HealthContext) -> list[CheckResult]:
             else f", {commits_behind} commit{'' if commits_behind == 1 else 's'} behind"
         )
 
+        # #2211: graph == HEAD only proves the graph matches this checkout's
+        # OWN HEAD — it says nothing about whether HEAD itself is behind
+        # origin. The base checkout is fetched but never pulled by design
+        # (see coord.graph_health module docstring), so this must be judged
+        # independently of `status.stale`, not folded into it.
+        origin_suffix = (
+            ""
+            if not status.origin_behind
+            else (
+                f", {status.commits_behind_origin} commit"
+                f"{'' if status.commits_behind_origin == 1 else 's'} behind "
+                f"origin/{status.default_branch}"
+            )
+        )
+
         if not status.stale:
-            severity = Severity.OK
-            headroom = f"in sync ({(status.built_sha or '')[:8]}), {age_text} old"
-            if status.verified_current and status.stamp_behind:
-                headroom = f"content current (stamp {(status.built_sha or '')[:8]}), {age_text} old"
+            if status.origin_behind:
+                severity = Severity.WARN
+                headroom = (
+                    f"graph matches HEAD ({(status.built_sha or '')[:8]}){origin_suffix} "
+                    "— describes stale code"
+                )
+            else:
+                severity = Severity.OK
+                headroom = f"in sync ({(status.built_sha or '')[:8]}), {age_text} old"
+                if status.verified_current and status.stamp_behind:
+                    headroom = (
+                        f"content current (stamp {(status.built_sha or '')[:8]}), {age_text} old"
+                    )
         elif not hooks_ok:
             severity = Severity.CRIT
             headroom = f"{age_text} stale{commits_suffix}, hooks disabled -> will not self-heal"
@@ -172,7 +211,17 @@ def probe_graph(ctx: HealthContext) -> list[CheckResult]:
             headroom = f"stale, {age_text} old{commits_suffix} (HEAD {(status.head_sha or '')[:8]})"
 
         detail = ""
-        if severity is not Severity.OK:
+        if not status.stale and status.origin_behind:
+            # Not a graph problem — `graphify update` would rebuild from the
+            # same stale HEAD. Naming a `git pull` here deliberately, but not
+            # running one: automatic pulls are unsafe for a base checkout
+            # (see coord.graph_health module docstring — deliberately-parked
+            # branches, stale .git/index.lock, etc).
+            detail = (
+                f"fix: review, then pull {checkout.path} to catch it up to "
+                f"origin/{status.default_branch} (not automatic)"
+            )
+        elif severity is not Severity.OK:
             detail = f"fix: graphify update {checkout.path}"
             if not hooks_ok:
                 detail = f"{detail}  —  {hooks_detail}"

{code_coordinator-0.5.70 → code_coordinator-0.5.72}/tests/test_cli_diagnose_graph.py

@@ -47,6 +47,36 @@ def _repo_with_graph(root: Path, *, built_sha: str | None = None) -> Path:
     return root
 
 
+def _add_empty_commits(repo: Path, n: int, *, prefix: str = "extra") -> None:
+    for i in range(n):
+        _git("commit", "-q", "--allow-empty", "-m", f"{prefix}-{i}", cwd=repo)
+
+
+def _repo_behind_origin(root: Path, tmp_path: Path, *, behind_by: int) -> Path:
+    """A repo whose graph matches its OWN HEAD, but whose HEAD sits
+    *behind_by* commits behind ``origin/main`` — the exact shape a base
+    checkout accumulates over time, because the agent fetches but
+    deliberately never pulls it (``coord/agent.py``, see
+    ``coord.graph_health``'s module docstring for why).
+
+    ``behind_by=0`` gives a checkout that is in sync on both axes.
+    """
+    repo = _repo_with_graph(root)
+    caught_up_at = _git("rev-parse", "HEAD", cwd=repo).stdout.strip()
+    bare = tmp_path / "origin.git"
+    _git("init", "-q", "-b", "main", "--bare", str(bare), cwd=tmp_path)
+    _git("remote", "add", "origin", str(bare), cwd=repo)
+    _git("push", "-q", "origin", "HEAD:refs/heads/main", cwd=repo)
+    if behind_by:
+        _add_empty_commits(repo, behind_by)
+        _git("push", "-q", "origin", "HEAD:refs/heads/main", cwd=repo)
+        _git("reset", "-q", "--hard", caught_up_at, cwd=repo)
+    # The agent's own behaviour (fetch, never pull) — populates
+    # refs/remotes/origin/main without moving HEAD.
+    _git("fetch", "-q", "origin", cwd=repo)
+    return repo
+
+
 def _config_for(tmp_path: Path, repo_path: Path) -> Path:
     cfg = tmp_path / "coordinator.yml"
     cfg.write_text(
@@ -123,3 +153,64 @@ def test_handles_a_machine_whose_checkout_is_absent(tmp_path: Path) -> None:
     out = _run(cfg)
 
     assert "no local checkouts" in out
+
+
+# ── #2211: graph == HEAD says nothing about HEAD == origin ──────────────────
+#
+# The agent fetches the base checkout but deliberately never pulls it (see
+# coord.graph_health's module docstring) — worktrees always branch from a
+# freshly-fetched origin/<default>, so a stale base never breaks dispatch.
+# But graphify indexes the base checkout's working tree, not origin, so a
+# graph that matches a stale HEAD used to report a clean '✓ in sync' with no
+# way to tell the checkout was ever behind the remote at all.
+
+
+def test_reports_stale_relative_to_origin_when_graph_matches_a_stale_head(
+    tmp_path: Path,
+) -> None:
+    """The exact regression: graph == HEAD, but HEAD is behind origin/main.
+    Must NOT render as '✓ in sync' — that is the confidently-correct-looking-
+    graph-of-the-past failure mode the issue is about. Must also make no
+    writes: HEAD is unchanged after the check runs."""
+    repo = _repo_behind_origin(tmp_path / "api", tmp_path, behind_by=3)
+    head_before = _git("rev-parse", "HEAD", cwd=repo).stdout.strip()
+
+    out = _run(_config_for(tmp_path, repo))
+
+    assert "graph in sync" not in out, (
+        "graph == HEAD must not be reported as fully in sync when HEAD "
+        "itself is behind origin"
+    )
+    assert "3 commits behind origin/main" in out
+    assert "STALE" not in out, "the graph really does match HEAD — not today's drift"
+
+    head_after = _git("rev-parse", "HEAD", cwd=repo).stdout.strip()
+    assert head_after == head_before, "the check must never write to the checkout"
+
+
+def test_reports_in_sync_when_head_matches_both_graph_and_origin(
+    tmp_path: Path,
+) -> None:
+    """A checkout in sync on both axes — graph == HEAD == origin — still
+    reports the plain '✓ in sync' with no origin-drift warning."""
+    repo = _repo_behind_origin(tmp_path / "api", tmp_path, behind_by=0)
+
+    out = _run(_config_for(tmp_path, repo))
+
+    assert "graph in sync" in out
+    assert "behind origin" not in out
+    assert "GRAPH_HEALTH: checkouts=1 stale=0 origin_behind=0" in out
+
+
+def test_graph_vs_head_drift_still_reports_stale_regardless_of_origin(
+    tmp_path: Path,
+) -> None:
+    """graph != HEAD must still render as today's STALE, unchanged — the
+    origin axis is additive, never a replacement for the existing check."""
+    repo = _repo_behind_origin(tmp_path / "api", tmp_path, behind_by=0)
+    _git("commit", "-q", "--allow-empty", "-m", "moves HEAD past the graph", cwd=repo)
+
+    out = _run(_config_for(tmp_path, repo))
+
+    assert "STALE" in out
+    assert "GRAPH_HEALTH: checkouts=1 stale=1" in out