code-coordinator 0.5.167__tar.gz → 0.5.170__tar.gz

{code_coordinator-0.5.167 → code_coordinator-0.5.170}/PKG-INFO

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

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

@@ -125,6 +125,7 @@ coord/reports.py
 coord/revalidate.py
 coord/review.py
 coord/scorecard.py
+coord/self_health.py
 coord/serve_app.py
 coord/smoke.py
 coord/spend_ceiling.py
@@ -492,6 +493,7 @@ tests/test_cli_chat_continue.py
 tests/test_cli_decide.py
 tests/test_cli_diagnose_config_provenance.py
 tests/test_cli_diagnose_graph.py
+tests/test_cli_diagnose_self.py
 tests/test_cli_doctor.py
 tests/test_cli_doctor_config_free_1801.py
 tests/test_cli_doctor_config_mismatch_1712.py
@@ -726,6 +728,7 @@ tests/test_review_verdict_relay.py
 tests/test_review_zero_commits.py
 tests/test_scoped_review_wiring.py
 tests/test_scorecard.py
+tests/test_self_health.py
 tests/test_serve.py
 tests/test_serve_app_board_trim.py
 tests/test_session.py

{code_coordinator-0.5.167 → code_coordinator-0.5.170}/code_coordinator.egg-info/scm_file_list.json

@@ -306,6 +306,7 @@
     "coord/revalidate.py",
     "coord/review.py",
     "coord/scorecard.py",
+    "coord/self_health.py",
     "coord/serve_app.py",
     "coord/skills/coord-dispatch-verbs/SKILL.md",
     "coord/skills/drive-queue-preflight/SKILL.md",
@@ -538,6 +539,7 @@
     "tests/test_cli_decide.py",
     "tests/test_cli_diagnose_config_provenance.py",
     "tests/test_cli_diagnose_graph.py",
+    "tests/test_cli_diagnose_self.py",
     "tests/test_cli_doctor.py",
     "tests/test_cli_doctor_config_free_1801.py",
     "tests/test_cli_doctor_config_mismatch_1712.py",
@@ -772,6 +774,7 @@
     "tests/test_review_zero_commits.py",
     "tests/test_scoped_review_wiring.py",
     "tests/test_scorecard.py",
+    "tests/test_self_health.py",
     "tests/test_serve.py",
     "tests/test_serve_app_board_trim.py",
     "tests/test_session.py",

{code_coordinator-0.5.167 → code_coordinator-0.5.170}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.167",
+  "tag": "0.5.170",
   "distance": 0,
-  "node": "g9016461101b4920502a7937e28cfdc70410ffc2f",
+  "node": "g8abd90cf35709226356d93ec35209ccca9e9ee6c",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-19"

{code_coordinator-0.5.167 → code_coordinator-0.5.170}/coord/commands/status.py

@@ -1561,6 +1561,30 @@ def _diagnose_via_daemon(svc, params: dict) -> None:
         "daemon host / operator box.  Read-only, no network required."
     ),
 )
+@click.option(
+    "--self",
+    "self_check",
+    is_flag=True,
+    help=(
+        "#2436: report whether THIS coordinator process's own editable "
+        "`coord` install — wherever `coord.__file__` actually resolves, "
+        "never an assumed ~/src/<name> path — is behind "
+        "origin/<default_branch>.  A merged coord/** fix (other than "
+        "agent.py/serve_app.py) is silently inert here until this checkout "
+        "is pulled (docs/OPERATING_GOTCHAS.md #1).  Fetches from origin "
+        "unless --no-fetch is passed."
+    ),
+)
+@click.option(
+    "--no-fetch",
+    "self_no_fetch",
+    is_flag=True,
+    help=(
+        "With --self, skip the `git fetch` and compare HEAD against "
+        "whatever origin/<default_branch> the last fetch already left "
+        "behind."
+    ),
+)
 
 
 @_CONFIG_OPTION
@@ -1575,6 +1599,8 @@ def diagnose(
     orphan_worktrees: bool = False,
     graph_health: bool = False,
     config_provenance_check: bool = False,
+    self_check: bool = False,
+    self_no_fetch: bool = False,
 ) -> None:
     """Per-stage doctor — diagnose, best-effort recover, optional reset."""
     # ── graphify graph freshness sweep (read-only) ───────────────────────────
@@ -1587,6 +1613,11 @@ def diagnose(
         _diagnose_config_provenance()
         return
 
+    # ── #2436: THIS process's own editable coord install freshness ──────────
+    if self_check:
+        _diagnose_self(fetch=not self_no_fetch)
+        return
+
     # ── #618: --orphan-worktrees fleet sweep ─────────────────────────────────
     if orphan_worktrees:
         _diagnose_orphan_worktrees(config_path, dry_run=dry_run)
@@ -1762,6 +1793,40 @@ def _diagnose_config_provenance() -> None:
     click.echo(summary_line(prov))
 
 
+def _diagnose_self(*, fetch: bool) -> None:
+    """Report whether THIS process's own editable ``coord`` install is
+    behind origin (#2436).
+
+    Read-only, local-machine only — same family as ``--graph``/
+    ``--config-provenance``/``--orphan-worktrees``. Answers the question
+    ``docs/OPERATING_GOTCHAS.md`` #1 names but nothing previously checked:
+    "did the `git pull` this editable install depends on for `coord/**`
+    fixes to go live actually happen?" A coordinator host running last
+    week's code gives zero signal of it otherwise — every board row and
+    escalation reads exactly as if a merged fix were still unfixed (the
+    #2286/#2426 incident this closes).
+
+    Locates the install via ``coord.self_health.default_install_path()`` —
+    ``Path(coord.__file__).resolve().parents[1]``, never an assumed
+    ``~/src/<name>`` path (the doc's own assumption had drifted from reality
+    on the host that hit this).  Each coordinator/drive-queue host has its
+    own independent editable checkout that can drift independently, so this
+    is deliberately per-machine, run where it's invoked, exactly like
+    ``--graph``.
+    """
+    from coord.self_health import (  # noqa: PLC0415
+        default_install_path,
+        format_status_lines,
+        self_freshness,
+        summary_line as self_summary_line,
+    )
+
+    st = self_freshness(install_path=default_install_path(), fetch=fetch)
+    for line in format_status_lines(st):
+        click.echo(f"  {line}")
+    click.echo(self_summary_line(st))
+
+
 def _diagnose_orphan_worktrees(config_path: Path, *, dry_run: bool) -> None:
     """#618: local fleet sweep — find and prune orphaned coordinator worktrees.
 

{code_coordinator-0.5.167 → code_coordinator-0.5.170}/coord/drive.py

@@ -1254,6 +1254,30 @@ class MergeVerifier(Protocol):
     def branch_head_sha(self, state: IssueState) -> str | None: ...
 
 
+def _remote_matches_repo(remote_url: str, repo_github: str) -> bool:
+    """Loosely compare a ``git remote get-url origin`` URL against the
+    ``owner/repo`` GitHub identifier it should point at (#2437).
+
+    Tolerant of the URL shapes git actually produces: ``https://github.com/
+    owner/repo(.git)``, ``git@github.com:owner/repo(.git)``, and
+    ``ssh://git@github.com/owner/repo(.git)``. Anything else (a bare path, a
+    non-GitHub host) simply won't match — which is the correct, fail-closed
+    outcome: this is a sanity check that the checkout points at the expected
+    project, not a general-purpose git URL parser.
+    """
+    url = remote_url.strip()
+    if url.endswith(".git"):
+        url = url[:-4]
+    if "://" in url:
+        _scheme, _, rest = url.partition("://")
+        _host, _, path = rest.partition("/")
+        url = path
+    elif "@" in url and ":" in url:
+        _user_host, _, path = url.partition(":")
+        url = path
+    return url.strip("/").lower() == repo_github.strip("/").lower()
+
+
 @dataclass
 class GitMergeVerifier:
     """Real implementation: ``git`` for commits, ``gh`` for merge state.
@@ -1264,12 +1288,60 @@ class GitMergeVerifier:
 
     repo_path: str = ""
     warn: Callable[[str], None] = lambda msg: None
+    # #2437: memoizes which (base, reason) pairs have already been warned
+    # about, so a checkout that stays broken across many drive-loop polls
+    # gets exactly one loud warning instead of one per poll. Keyed on the
+    # reason text too, so a checkout that later fails a *different* check
+    # (e.g. it grows a valid `.git` but the wrong `origin`) still warns once
+    # for the new problem.
+    _warned: set[tuple[str, str]] = field(default_factory=set, init=False, repr=False)
 
     def _base(self, state: IssueState) -> Path | None:
         base = Path(self.repo_path).expanduser() if self.repo_path else (
             Path.home() / "src" / state.repo
         )
-        return base if (base / ".git").exists() else None
+        if not (base / ".git").exists():
+            return None
+        reason = self._unusable_reason(base, state)
+        if reason is None:
+            return base
+        key = (str(base), reason)
+        if key not in self._warned:
+            self._warned.add(key)
+            self.warn(
+                f"local checkout {base} cannot be used for merge "
+                f"verification of {state.repo} — {reason} (#2437). Merge "
+                "verification will keep returning \"could not verify\" "
+                "(never a false empty-branch) until this is fixed: replace "
+                "it with a real clone of the repo, or point `coord drive` "
+                "at one via --repo-path."
+            )
+        return None
+
+    def _unusable_reason(self, base: Path, state: IssueState) -> str | None:
+        """Why *base* can't be trusted for merge verification, or ``None`` if
+        it can.
+
+        A ``.git`` directory existing is necessary but not sufficient
+        (claude-coordinator#2437): an interrupted/stub `git init` leaves a
+        `.git` directory with no `HEAD`/`objects`/`refs`, and a checkout of
+        the wrong project entirely leaves a perfectly valid `.git` that
+        still can't answer questions about *this* repo. Both must be caught
+        here rather than surfacing as an unexplained, indefinitely-retried
+        ``None`` from :meth:`branch_has_commits`.
+        """
+        if self._git(base, "rev-parse", "--is-inside-work-tree").returncode != 0:
+            return "not a usable git working tree (`git rev-parse --is-inside-work-tree` failed)"
+        remote = self._git(base, "remote", "get-url", "origin")
+        url = (remote.stdout or "").strip()
+        if remote.returncode != 0 or not url:
+            return "has no 'origin' remote configured"
+        if state.repo_github and not _remote_matches_repo(url, state.repo_github):
+            return (
+                f"'origin' remote ({url!r}) does not match the expected "
+                f"repo {state.repo_github!r}"
+            )
+        return None
 
     @staticmethod
     def _git(base: Path, *args: str) -> subprocess.CompletedProcess[str]:

code_coordinator-0.5.170/coord/self_health.py

@@ -0,0 +1,270 @@
+"""Freshness of THIS coordinator process's own editable ``coord`` install
+(#2436).
+
+``docs/OPERATING_GOTCHAS.md`` #1 already names the risk: any fix to
+``coord/**`` (other than ``agent.py``/``serve_app.py``, which have their own
+deploy steps) is live the instant ``git pull`` lands in whatever checkout
+``coord.__file__`` resolves into — no restart needed. But nothing has ever
+checked whether that ``git pull`` happened. A coordinator host can keep
+running last week's code indefinitely with zero signal: every board row,
+every ``coord diagnose`` finding, every escalation reads exactly as if the
+bug behind it were still unfixed, because the process producing them
+genuinely does not have the fix.
+
+This is the #2286 incident: a fix had already merged to ``origin/main``, but
+this host's installed ``coord`` was one commit behind — nothing had pulled it
+— so every symptom looked identical to "still broken", and the actual cause
+took manual ``git log``/``ps aux``/``tmux capture-pane`` archaeology to find.
+
+Mirrors :mod:`coord.graph_health` / :mod:`coord.fleet_config_health`'s shape:
+one read-only, best-effort probe (:func:`self_freshness`) plus a renderer,
+wired into ``coord diagnose --self``.
+
+**Locates the ACTUAL running install, never an assumed path.** The #2436
+incident's second half was exactly a doc/reality mismatch:
+``docs/OPERATING_GOTCHAS.md`` assumed the editable install lives at
+``~/src/claude-coordinator``; the real install on that host resolved to
+``~/src/code-coordinator``, a second, disconnected checkout. So this module
+never guesses a ``~/src/<name>`` path — it asks the interpreter that is
+actually running: ``Path(coord.__file__).resolve().parents[1]``.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def default_install_path() -> Path:
+    """Where THIS process's ``coord`` import resolves to.
+
+    ``$COORD_SELF_CHECKOUT`` overrides it (tests, and an operator who wants
+    to point this at a different checkout than the one currently running);
+    otherwise ``Path(coord.__file__).resolve().parents[1]`` — the package's
+    grandparent directory, i.e. the checkout/site-packages root, never an
+    assumed ``~/src/<name>`` path (see module docstring).
+
+    Computed fresh on every call, not a module-level constant, so a test can
+    override it via ``monkeypatch.setenv`` without fighting a value baked in
+    at import time — same convention as
+    :func:`coord.fleet_config_health.default_settings_dir`.
+    """
+    env = os.environ.get("COORD_SELF_CHECKOUT")
+    if env:
+        return Path(env).expanduser()
+    import coord as _coord  # noqa: PLC0415 — avoid a self-import at module load
+
+    return Path(_coord.__file__).resolve().parents[1]
+
+
+@dataclass
+class SelfFreshness:
+    """Freshness of one checkout's ``coord`` install against its origin."""
+
+    install_path: Path
+    is_git_checkout: bool = False
+    default_branch: str | None = None
+    head_sha: str | None = None
+    origin_sha: str | None = None
+    commits_behind: int | None = None
+    # Whether a `git fetch` was attempted/succeeded before comparing. `None`
+    # means fetch was skipped (`fetch=False`); the comparison then reads
+    # whatever origin/<branch> the last fetch left behind — same
+    # never-fetch-by-default posture as coord.graph_health's origin check,
+    # available here as an opt-out for callers on a fast/tight budget.
+    fetch_ok: bool | None = None
+    fetch_error: str | None = None
+    # Set when freshness could not be determined at all (no report, no git,
+    # no origin ref) — never silently reported as "up to date".
+    unknown_reason: str | None = None
+
+    @property
+    def stale(self) -> bool:
+        """HEAD is behind ``origin/<default_branch>`` by at least one commit.
+
+        Deliberately False — not True — when this could not be proven
+        (``unknown_reason`` set): an unknown must never be counted as drift,
+        the same rule :func:`coord.graph_health.GraphStatus.stale` follows.
+        """
+        return bool(self.commits_behind)
+
+    @property
+    def healthy(self) -> bool:
+        return self.is_git_checkout and self.unknown_reason is None and not self.stale
+
+
+def _git_out(repo_path: Path, *args: str) -> str | None:
+    try:
+        r = subprocess.run(
+            ["git", *args],
+            cwd=str(repo_path),
+            capture_output=True,
+            text=True,
+            timeout=10.0,
+        )
+    except (subprocess.SubprocessError, OSError):
+        return None
+    if r.returncode != 0:
+        return None
+    return r.stdout.strip() or None
+
+
+def _fetch(repo_path: Path, branch: str, timeout: float) -> tuple[bool, str | None]:
+    try:
+        r = subprocess.run(
+            ["git", "fetch", "--quiet", "origin", branch],
+            cwd=str(repo_path),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except (subprocess.SubprocessError, OSError) as exc:
+        return False, f"{type(exc).__name__}: {exc}"
+    if r.returncode != 0:
+        return False, (r.stderr or r.stdout).strip() or f"git fetch exited {r.returncode}"
+    return True, None
+
+
+def _commits_behind(repo_path: Path, head: str, origin: str) -> int | None:
+    """Count of commits reachable from *origin* that are not in *head*
+    (``git rev-list --count head..origin``). ``None`` (never raises) when
+    git can't answer — an unproven comparison must not be reported as drift.
+    """
+    out = _git_out(repo_path, "rev-list", "--count", f"{head}..{origin}")
+    if out is None:
+        return None
+    try:
+        return int(out)
+    except ValueError:
+        return None
+
+
+def _detect_default_branch(repo_path: Path) -> str:
+    """``origin/HEAD``'s branch name, falling back to ``"main"``.
+
+    Read-only (``symbolic-ref``, not a network call) — relies on whatever a
+    prior ``git clone``/``git remote set-head`` already recorded.
+    """
+    ref = _git_out(repo_path, "symbolic-ref", "refs/remotes/origin/HEAD")
+    if ref and "/" in ref:
+        return ref.rsplit("/", 1)[-1]
+    return "main"
+
+
+def self_freshness(
+    *,
+    install_path: Path | None = None,
+    default_branch: str | None = None,
+    fetch: bool = True,
+    timeout: float = 10.0,
+) -> SelfFreshness:
+    """Freshness of *install_path* (default: :func:`default_install_path`)
+    against ``origin/<default_branch>``.
+
+    Read-only w.r.t. the working tree and best-effort: a missing ``.git``, an
+    unreadable HEAD, or a git failure all return a populated
+    :class:`SelfFreshness` with ``unknown_reason`` set rather than raising.
+
+    *fetch* (default ``True``) runs a bounded ``git fetch --quiet origin
+    <branch>`` before comparing — unlike :mod:`coord.graph_health`'s
+    never-fetch origin check, this probe's entire purpose is answering "did
+    anyone actually pull", so reading a stale remote-tracking ref by default
+    would silently defeat the point. A failed fetch is reported (never
+    raised) and the comparison falls back to whatever ``origin/<branch>`` the
+    last successful fetch left behind. Pass ``fetch=False`` to skip it
+    entirely (e.g. a caller on a tight time budget, or offline).
+    """
+    install_path = install_path or default_install_path()
+    st = SelfFreshness(install_path=install_path)
+
+    if not (install_path / ".git").exists():
+        st.unknown_reason = (
+            f"{install_path} is not a git checkout (release install, or no "
+            ".git directory found here) — nothing to compare against origin"
+        )
+        return st
+    st.is_git_checkout = True
+
+    st.head_sha = _git_out(install_path, "rev-parse", "HEAD")
+    if not st.head_sha:
+        st.unknown_reason = f"could not read HEAD of {install_path}"
+        return st
+
+    branch = default_branch or _detect_default_branch(install_path)
+    st.default_branch = branch
+
+    if fetch:
+        st.fetch_ok, st.fetch_error = _fetch(install_path, branch, timeout)
+
+    origin_sha = _git_out(install_path, "rev-parse", f"origin/{branch}")
+    if not origin_sha:
+        st.unknown_reason = (
+            f"no origin/{branch} ref for {install_path} — never fetched, no "
+            f"'origin' remote, or {branch!r} is not this checkout's default branch"
+        )
+        return st
+    st.origin_sha = origin_sha
+    st.commits_behind = _commits_behind(install_path, st.head_sha, origin_sha)
+    if st.commits_behind is None:
+        st.unknown_reason = (
+            f"could not compare HEAD ({st.head_sha[:8]}) against "
+            f"origin/{branch} ({origin_sha[:8]}) — git rev-list failed"
+        )
+    return st
+
+
+def format_status_lines(st: SelfFreshness) -> list[str]:
+    """Human-readable report lines for *st* (used by ``coord diagnose
+    --self``)."""
+    lines: list[str] = []
+    where = str(st.install_path)
+
+    if not st.is_git_checkout:
+        lines.append(f"✓ {where}: {st.unknown_reason}")
+        return lines
+
+    if st.fetch_ok is False:
+        lines.append(
+            f"  ⚠ git fetch failed ({st.fetch_error}) — comparing against "
+            "whatever origin ref the last successful fetch left behind"
+        )
+
+    if st.unknown_reason:
+        lines.append(f"? {where}: freshness unknown — {st.unknown_reason}")
+        return lines
+
+    if st.commits_behind:
+        n = st.commits_behind
+        lines.append(
+            f"✗ STALE: recorded HEAD {(st.head_sha or '')[:8]}, "
+            f"origin/{st.default_branch} is now {(st.origin_sha or '')[:8]} — "
+            f"{n} commit{'' if n == 1 else 's'} behind. This process is "
+            "running OLD coord/** code — a merged fix here is silently inert "
+            "until this checkout is pulled (docs/OPERATING_GOTCHAS.md #1). "
+            f"Fix: git -C {where} pull"
+        )
+    else:
+        lines.append(
+            f"✓ {where}: up to date with origin/{st.default_branch} "
+            f"({(st.head_sha or '')[:8]})"
+        )
+    return lines
+
+
+def summary_line(st: SelfFreshness) -> str:
+    """The machine-readable trailer ``coord diagnose --self`` prints,
+    mirroring ``GRAPH_HEALTH:``/``CONFIG_PROVENANCE:``."""
+    if not st.is_git_checkout:
+        return f"SELF_FRESHNESS: git_checkout=false path={st.install_path}"
+    if st.unknown_reason:
+        return (
+            f"SELF_FRESHNESS: git_checkout=true unknown=true path={st.install_path}"
+        )
+    return (
+        "SELF_FRESHNESS: git_checkout=true "
+        f"stale={'true' if st.stale else 'false'} "
+        f"commits_behind={st.commits_behind if st.commits_behind is not None else '?'} "
+        f"path={st.install_path}"
+    )

{code_coordinator-0.5.167 → code_coordinator-0.5.170}/docs/OPERATING_GOTCHAS.md

@@ -30,6 +30,20 @@ against #1491's milestone-#50 exit gate — see
 [`MERGE_AUTO_DRAIN_TRUST_BAR.md`](MERGE_AUTO_DRAIN_TRUST_BAR.md) for the full
 deploy-status audit this produced.
 
+**#2436: `~/src/claude-coordinator` is only an assumption — verify, don't
+guess.** That path is where the "editable install" row above imagines the
+checkout to be; it is not necessarily where a given host's `coord` import
+actually resolves. One coordinator host's install turned out to live at
+`~/src/code-coordinator` instead — a second, disconnected checkout nobody had
+reconciled with this doc, discovered only via manual `git log`/`ps aux`/`tmux
+capture-pane` archaeology while chasing a bug that had, in fact, already been
+fixed on `origin/main`. Don't assume the path and don't assume the pull
+happened: run `coord diagnose --self` on the host in question. It resolves the
+*actual* running install (`Path(coord.__file__).resolve().parents[1]`, not this
+doc's guess) and reports STALE with a commit count when it hasn't been pulled
+since a `coord/**` fix merged — the checkable gate for this row, the same way
+`coord diagnose --graph` is the checkable gate for graphify freshness.
+
 Not academic. #1394 (worker strands uncommitted work, then cleanup destroys it)
 sat merged-but-undeployed, and the very next dispatch — #1402 — hit the
 identical bug: **$3.44 and 10 minutes lost to something already fixed on

code_coordinator-0.5.170/tests/test_cli_diagnose_self.py

@@ -0,0 +1,115 @@
+"""End-to-end tests for `coord diagnose --self` — driven through the real
+Click command against real git checkouts, asserting on rendered output
+(CLAUDE.md black-box coverage bar).
+
+#2436: nothing previously checked whether the coordinator's own editable
+`coord/**` install had actually been `git pull`ed since a fix merged — a
+coordinator host could run stale code indefinitely with zero signal, because
+every symptom (board rows, `coord diagnose` findings, escalations) reads
+exactly as if the bug were still unfixed. This drives `coord diagnose --self`
+hermetically via $COORD_SELF_CHECKOUT, never touching the real running
+install.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from coord.commands.status import diagnose
+
+pytestmark = pytest.mark.skipif(shutil.which("git") is None, reason="git not available")
+
+
+def _git(*args: str, cwd: Path) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-c", "user.email=t@t", "-c", "user.name=t", *args],
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+        timeout=30.0,
+    )
+
+
+def _make_checkout(root: Path) -> Path:
+    checkout = root / "coord"
+    checkout.mkdir(parents=True)
+    _git("init", "-q", "-b", "main", ".", cwd=checkout)
+    (checkout / "marker.txt").write_text("v1\n", encoding="utf-8")
+    _git("add", "-A", cwd=checkout)
+    _git("commit", "-q", "-m", "init", cwd=checkout)
+    remote = root / "coord-remote.git"
+    _git("init", "-q", "-b", "main", "--bare", str(remote), cwd=root)
+    _git("remote", "add", "origin", str(remote), cwd=checkout)
+    _git("push", "-q", "-u", "origin", "HEAD:main", cwd=checkout)
+    return checkout
+
+
+def _run(monkeypatch, checkout: Path, *extra_args: str) -> str:
+    monkeypatch.setenv("COORD_SELF_CHECKOUT", str(checkout))
+    result = CliRunner().invoke(
+        diagnose, ["--self", *extra_args], catch_exceptions=False
+    )
+    assert result.exit_code == 0, result.output
+    return result.output
+
+
+def test_reports_up_to_date_install(tmp_path: Path, monkeypatch) -> None:
+    checkout = _make_checkout(tmp_path)
+    out = _run(monkeypatch, checkout)
+
+    assert "up to date with origin/main" in out
+    assert "SELF_FRESHNESS: git_checkout=true stale=false commits_behind=0" in out
+
+
+def test_reports_stale_with_commit_count_behind(tmp_path: Path, monkeypatch) -> None:
+    """The core #2436/#2286 acceptance: a merged fix nobody pulled shows up
+    as STALE with a commit count, not silently as healthy."""
+    checkout = _make_checkout(tmp_path)
+
+    clone = tmp_path / "other-clone"
+    _git("clone", "-q", str(tmp_path / "coord-remote.git"), str(clone), cwd=tmp_path)
+    (clone / "marker.txt").write_text("v2 - the fix\n", encoding="utf-8")
+    _git("add", "-A", cwd=clone)
+    _git("commit", "-q", "-m", "the fix", cwd=clone)
+    _git("push", "-q", "origin", "HEAD:main", cwd=clone)
+
+    out = _run(monkeypatch, checkout)
+
+    assert "STALE" in out
+    assert "1 commit behind" in out
+    assert f"git -C {checkout} pull" in out
+    assert "SELF_FRESHNESS: git_checkout=true stale=true commits_behind=1" in out
+
+
+def test_no_fetch_flag_skips_the_network_call(tmp_path: Path, monkeypatch) -> None:
+    """--no-fetch must compare against the last known ref without ever
+    running `git fetch` — a stale-but-unfetched checkout reads as caught up
+    on the axis it can actually see (still not silently 'stale')."""
+    checkout = _make_checkout(tmp_path)
+
+    clone = tmp_path / "other-clone"
+    _git("clone", "-q", str(tmp_path / "coord-remote.git"), str(clone), cwd=tmp_path)
+    (clone / "marker.txt").write_text("v2\n", encoding="utf-8")
+    _git("add", "-A", cwd=clone)
+    _git("commit", "-q", "-m", "v2", cwd=clone)
+    _git("push", "-q", "origin", "HEAD:main", cwd=clone)
+
+    out = _run(monkeypatch, checkout, "--no-fetch")
+
+    assert "STALE" not in out
+    assert "SELF_FRESHNESS: git_checkout=true stale=false commits_behind=0" in out
+
+
+def test_reports_a_non_git_install_neutrally(tmp_path: Path, monkeypatch) -> None:
+    install = tmp_path / "site-packages" / "coord"
+    install.mkdir(parents=True)
+
+    out = _run(monkeypatch, install)
+
+    assert "not a git checkout" in out
+    assert f"SELF_FRESHNESS: git_checkout=false path={install}" in out