code-coordinator 0.5.300__tar.gz → 0.5.302__tar.gz

{code_coordinator-0.5.300 → code_coordinator-0.5.302}/PKG-INFO

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

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

@@ -248,6 +248,7 @@ coord/health/checks/timer_active.py
 coord/health/checks/toolchain.py
 coord/health/checks/unit_drift.py
 coord/health/checks/unit_enablement.py
+coord/health/checks/wedged_drive_queue.py
 coord/health/checks/worktrees.py
 coord/notifier/__init__.py
 coord/notifier/baseline.py
@@ -601,6 +602,7 @@ tests/test_health_timer_active.py
 tests/test_health_toolchain.py
 tests/test_health_unit_drift.py
 tests/test_health_unit_enablement.py
+tests/test_health_wedged_drive_queue.py
 tests/test_hooks.py
 tests/test_human_attended_437.py
 tests/test_init.py

{code_coordinator-0.5.300 → code_coordinator-0.5.302}/code_coordinator.egg-info/scm_file_list.json

@@ -165,6 +165,7 @@
     "coord/health/checks/toolchain.py",
     "coord/health/checks/unit_drift.py",
     "coord/health/checks/unit_enablement.py",
+    "coord/health/checks/wedged_drive_queue.py",
     "coord/health/checks/worktrees.py",
     "coord/health/cli.py",
     "coord/health/context.py",
@@ -627,6 +628,7 @@
     "tests/test_health_toolchain.py",
     "tests/test_health_unit_drift.py",
     "tests/test_health_unit_enablement.py",
+    "tests/test_health_wedged_drive_queue.py",
     "tests/test_hooks.py",
     "tests/test_human_attended_437.py",
     "tests/test_init.py",

{code_coordinator-0.5.300 → code_coordinator-0.5.302}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.300",
+  "tag": "0.5.302",
   "distance": 0,
-  "node": "g94e4815fd8f9649dea8eb46637198841f2c99a16",
+  "node": "g4db839a79669e9ada2d3461267662cb4cefd6e52",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-30"

{code_coordinator-0.5.300 → code_coordinator-0.5.302}/coord/commands/drive_queue.py

@@ -72,6 +72,7 @@ from coord.drive_queue import (
     TickPlan,
     add_preflight_notice,
     build_board_view,
+    detect_unreachable_waits,
     diagnose_blocked_after,
     effective_max_fix_rounds,
     entries_from_rows,
@@ -87,6 +88,7 @@ from coord.drive_queue import (
     pending_probe_targets,
     plan_tick,
     render_plan,
+    unreachable_wait_alert,
     validate_enqueue,
 )
 from coord.overlap_predict import (
@@ -1523,6 +1525,30 @@ def _queue_alert() -> dict | None:
     return get_drive_escalation(QUEUE_ALERT_REPO, QUEUE_ALERT_ISSUE)
 
 
+def _unreachable_wait_alert_dict(rows: list[Mapping[str, Any]]) -> dict | None:
+    """#2944's synthetic queue-level alert, or ``None`` when nothing qualifies.
+
+    Computed fresh from the CURRENT queue rows on every call — deliberately
+    independent of :func:`_queue_alert`'s per-tick escalation record, which a
+    busy queue overwrites (and clears — see the tick's own ``else:
+    _clear_queue_alert()`` branch) every single tick it finds *something*
+    else to launch. A wedged entry with `attempts=0` sits in `blocked`/
+    `parked` for as long as it likes regardless of what else the queue is
+    doing, so its visibility must not depend on a tick ever having nothing
+    better to report — see :func:`coord.drive_queue.detect_unreachable_waits`
+    for the predicate and the #2900/#2907 incident this closes.
+    """
+    waits = detect_unreachable_waits(entries_from_rows(rows))
+    if not waits:
+        return None
+    synthetic = unreachable_wait_alert(waits)
+    return {
+        "reason": synthetic.reason,
+        "gate_readings": " | ".join(synthetic.details),
+        "proposed_command": synthetic.command,
+    }
+
+
 @drive_queue_group.command("status")
 @click.option("--json", "output_json", is_flag=True, default=False, help="Emit counts + alert as JSON.")
 @_CONFIG_OPTION
@@ -1532,7 +1558,13 @@ def drive_queue_status(output_json: bool, config_path: Path) -> None:
 
     rows = list_drive_queue()
     counts = _counts(rows)
-    alert = _queue_alert()
+    # #2944: a tick-raised alert (a HELD gate, "nothing eligible to launch")
+    # takes priority when one exists — it is fresher and, on a busy queue,
+    # `_unreachable_wait_alert_dict` would silently win-and-hide it every
+    # time a real, actionable alert IS present. Only when the tick has
+    # nothing to say (the common, dangerous case a queue with free slots
+    # sits in for hours) does the guaranteed-false-wait check get to speak.
+    alert = _queue_alert() or _unreachable_wait_alert_dict(rows)
     held = fired_holds(entries_from_rows(rows))
     # #2587: read directly from the marker file, not from the last tick's
     # `TickPlan` — `status` may run between ticks (or on a machine that never

{code_coordinator-0.5.300 → code_coordinator-0.5.302}/coord/drive_queue.py

@@ -2260,6 +2260,129 @@ def is_unsatisfiable_prereq_reason(text: str | None) -> bool:
     return _is_unsatisfiable_prereq_reason(text)
 
 
+# ── #2944: the guaranteed-false wait ─────────────────────────────────────────
+#
+# An entry with `attempts == 0` has never been dispatched: no `coord drive`
+# ever ran for it, so it has no branch, no PR, and no merge-queue row — and
+# never can have one, because nothing was ever built. A `blocked` or `parked`
+# entry in that state is not waiting on a gate that MIGHT clear; it is
+# waiting on a gate that structurally cannot exist. Whatever swept this row
+# last (#2230's merge-gate probe, #2935's after= graph, anything future)
+# cannot ever answer "yes" for it — the only exit is an operator's `remove` +
+# `add`.
+#
+# Deliberately independent of #2935/#2230: those fix (or will fix) individual
+# sweeps so they stop MISTAKING this shape for a real probe target. This
+# predicate does not care which sweep produced the block, or whether one
+# exists at all — it is the backstop that makes the NEXT undiscovered
+# instance of "a sweep declines to guess and therefore never terminates"
+# visible, instead of silent for another 32 hours (claude-coordinator#2900/
+# #2907: 207 and 186 deferrals, 0 attempts, ~10h and 22.7h blocked
+# respectively, `alert: (none)` the entire time — see #2944).
+#
+# `min_deferrals` is grace, not evidence: `deferrals` on a `blocked`/`parked`
+# row is whatever it had accumulated before the transition (subsequent ticks
+# do not bump it further — neither `_reconcile_blocked` nor
+# `_reconcile_blocked_unreadable` touches `deferrals`), so a fresh entry that
+# races straight from `waiting` to `blocked` on its very first tick reads
+# `deferrals=0` here regardless of how long it then sits. ~5 ticks (~15
+# minutes at the fleet's ~3-minute cadence) is enough that a row flagged here
+# has genuinely been sitting, not merely landed there this instant.
+UNREACHABLE_WAIT_MIN_DEFERRALS = 5
+
+
+@dataclass(frozen=True)
+class UnreachableWait:
+    """One queue entry stuck in the #2944 guaranteed-false wait.
+
+    See :func:`detect_unreachable_waits` for the predicate. Carries just
+    enough for a caller to build an operator-facing message without
+    re-deriving anything: the key names the entry, `deferrals` is the
+    evidence a genuine transient wouldn't have, and `last_reason` is
+    whatever the last sweep to touch this row recorded — useful context,
+    never re-interpreted here.
+    """
+
+    key: str
+    state: str
+    deferrals: int
+    last_reason: str
+
+
+def detect_unreachable_waits(
+    entries: Iterable[QueueEntry],
+    *,
+    min_deferrals: int = UNREACHABLE_WAIT_MIN_DEFERRALS,
+) -> list[UnreachableWait]:
+    """Entries sitting in the #2944 guaranteed-false wait.
+
+    ``state in (blocked, parked) AND attempts == 0 AND deferrals >
+    min_deferrals`` — see the module comment above this function for why
+    that combination can never resolve itself. Pure and cheap (a predicate
+    over already-loaded rows, no clock, no I/O), so the same function backs
+    both `coord drive-queue status`'s `alert:` line
+    (`coord.commands.drive_queue._queue_alert`) and the `coord doctor` WARN
+    (`coord.health.checks.wedged_drive_queue`) — one definition of "wedged",
+    not two that could drift apart.
+
+    An entry with ``attempts > 0`` is excluded unconditionally, however long
+    it has sat: it WAS dispatched at least once, so it has (or had) a real
+    branch/PR/merge-queue row for a sweep to have a genuine opinion about —
+    that is a legitimate wait, not an unreachable one.
+    """
+    return [
+        UnreachableWait(
+            key=e.key, state=e.state, deferrals=e.deferrals, last_reason=e.last_reason
+        )
+        for e in entries
+        if e.state in (STATE_BLOCKED, STATE_PARKED)
+        and e.attempts == 0
+        and e.deferrals > min_deferrals
+    ]
+
+
+def unreachable_wait_alert(waits: Sequence[UnreachableWait]) -> QueueAlert:
+    """The queue-level record #2944's predicate raises, in :func:`_hold_alert`'s
+    shape — a message naming the entry (or entries), the deferral count that
+    is the evidence, and the ONE remedy that actually clears it.
+
+    ``add`` alone does not clear ``blocked`` (the queue list already
+    documents this as a footgun elsewhere) — only ``remove`` then ``add``
+    does, so that is the command surfaced here rather than the generic
+    ``coord drive-queue list`` other alerts fall back on; naming the wrong
+    remedy on a state this non-obvious defeats the point of alerting at all.
+    Named INLINE in ``reason`` (not only in ``command``, which
+    ``drive-queue status``'s plain-text rendering never echoes — only its
+    ``gate_readings``/``details`` lines are printed) so the remedy is visible
+    wherever this alert's ``reason`` is, not just to a caller that also reads
+    the structured field.
+    """
+    names = ", ".join(
+        f"{w.key} ({w.state}, {w.deferrals} deferrals)" for w in waits[:5]
+    )
+    more = ", ..." if len(waits) > 5 else ""
+    plural = len(waits) != 1
+    return QueueAlert(
+        reason=(
+            f"{len(waits)} queue entr{'ies' if plural else 'y'} stuck in a "
+            "guaranteed-false wait — never dispatched (attempts=0) yet "
+            f"blocked/parked past {UNREACHABLE_WAIT_MIN_DEFERRALS} deferrals; "
+            f"no sweep can ever clear this on its own: {names}{more}. Fix: "
+            "coord drive-queue remove <repo> <issue> && "
+            "coord drive-queue add <repo> <issue> for each entry named above."
+        ),
+        details=tuple(
+            f"{w.key}: {w.state}, {w.deferrals} deferrals, "
+            f"last_reason={w.last_reason!r}"
+            for w in waits
+        ),
+        command=(
+            "coord drive-queue remove <repo> <issue> && "
+            "coord drive-queue add <repo> <issue> — for each entry named above"
+        ),
+    )
+
+
 def _reconcile_blocked_after(
     entry: QueueEntry,
     board: BoardView,

code_coordinator-0.5.302/coord/health/checks/wedged_drive_queue.py

@@ -0,0 +1,124 @@
+"""Drive-queue entries stuck in a guaranteed-false wait (#2944).
+
+``coord drive-queue status``'s ``alert:`` line is a per-tick record — a busy
+queue with free capacity elsewhere clears it every tick that finds
+*something* to launch (see ``coord.commands.drive_queue._run_tick``'s own
+``else: _clear_queue_alert()`` branch), even while an unrelated entry sits
+wedged for hours. That is exactly what happened to claude-coordinator#2900
+and #2907 on 2026-08-29: both sat ``blocked``, ``attempts=0``, 207 and 186
+deferrals, ~10h and 22.7h respectively — and ``alert: (none)`` read clean the
+entire time, because the rest of the queue kept launching fine.
+
+An entry with ``attempts == 0`` has never been dispatched — no branch, no
+PR, no merge-queue row ever existed for it, and none ever can, because
+nothing was ever built. A ``blocked``/``parked`` entry in that state is not
+waiting on a gate that MIGHT clear; it is waiting on a gate that structurally
+cannot exist. ``coord.drive_queue.detect_unreachable_waits`` is the one
+predicate for that shape (also what backs the ``status`` alert line itself,
+so this check and that line can never say different things) — this probe
+just re-derives it, live, from ``drive_queue`` state every time ``coord
+doctor`` runs, independent of whatever the last tick happened to report.
+
+This is deliberately independent of #2935 (which fixes the specific sweep
+that produced the #2900/#2907 incident) and #2230 (the sweep's origin): both
+are about *why* a row gets wedged this way; this check is about the row
+being wedged *at all*, whatever sweep — present or future — produced it.
+
+WARN, not CRIT: the fix costs an operator ~10 seconds (``coord drive-queue
+remove`` + ``add``) once they know, and this check exists to make sure they
+know — it is not itself an outage.
+
+``cost=COST_NETWORK``, not ``COST_CHEAP``: ``coord.state.list_drive_queue``
+routes to the daemon over HTTP whenever ``board_service`` is set, which is
+the common case on a thin-client fleet machine (same situation
+``release_cordon.py`` documents for its own board-state read) — so this is a
+real network call on most of the fleet, not a local DB read, and must be
+skippable by ``--no-network``/timer runs and the automatic per-agent health
+poll exactly like the other network-costed checks.
+"""
+
+from __future__ import annotations
+
+from coord.health.models import CheckResult, HealthContext, Severity
+from coord.health.registry import COST_NETWORK, check
+
+
+@check(
+    id="wedged_drive_queue",
+    scope="machine",
+    title="wedged drive-queue entries",
+    order=23,
+    cost=COST_NETWORK,
+    description=(
+        "Drive-queue rows in `coord.drive_queue`'s #2944 guaranteed-false "
+        "wait: `blocked`/`parked`, `attempts == 0` (never dispatched — no "
+        "branch, no PR, no merge-queue row ever existed or ever can), "
+        "sitting past a few ticks of grace. Reads via `coord.state."
+        "list_drive_queue`, which — per its own docstring — routes to the "
+        "daemon over HTTP when `board_service` is set (the common case on a "
+        "thin-client fleet machine, see `release_cordon.py`) and only reads "
+        "the local DB directly otherwise; `cost=network` so `--no-network`/"
+        "timer runs and the automatic per-agent health poll skip it exactly "
+        "like the other network-costed checks, same precedent as "
+        "`release_cordon`."
+    ),
+)
+def probe_wedged_drive_queue(ctx: HealthContext) -> CheckResult:
+    del ctx  # unused: this check reads local queue state directly, not config
+    from coord.drive_queue import (  # noqa: PLC0415
+        detect_unreachable_waits,
+        entries_from_rows,
+    )
+    from coord.state import list_drive_queue  # noqa: PLC0415
+
+    try:
+        rows = list_drive_queue()
+        waits = detect_unreachable_waits(entries_from_rows(rows))
+    except Exception as exc:  # noqa: BLE001 — a probe must never raise
+        return CheckResult(
+            check_id="wedged_drive_queue",
+            scope="machine",
+            severity=Severity.UNKNOWN,
+            headroom=f"could not read the drive queue: {exc}",
+            error=str(exc),
+        )
+
+    if not waits:
+        return CheckResult(
+            check_id="wedged_drive_queue",
+            scope="machine",
+            severity=Severity.OK,
+            headroom="0 wedged drive-queue entries",
+        )
+
+    sample = ", ".join(
+        f"{w.key} ({w.state}, {w.deferrals} deferrals)" for w in waits[:5]
+    )
+    return CheckResult(
+        check_id="wedged_drive_queue",
+        scope="machine",
+        severity=Severity.WARN,
+        headroom=(
+            f"{len(waits)} wedged drive-queue entr"
+            f"{'y' if len(waits) == 1 else 'ies'}"
+        ),
+        detail=(
+            f"e.g. {sample}" + (", ..." if len(waits) > 5 else "")
+            + " — never dispatched (attempts=0), cannot clear on its own; "
+            "fix: coord drive-queue remove <repo> <issue> && "
+            "coord drive-queue add <repo> <issue>"
+        ),
+        threshold="warn when any entry is blocked/parked, attempts=0, past a few ticks of grace",
+        values={
+            "count": len(waits),
+            "entries": [
+                {
+                    "key": w.key,
+                    "state": w.state,
+                    "deferrals": w.deferrals,
+                    "last_reason": w.last_reason,
+                }
+                for w in waits
+            ],
+        },
+    )

{code_coordinator-0.5.300 → code_coordinator-0.5.302}/coord/machine_onboard.py

@@ -51,6 +51,7 @@ one distinct, *named* finding per defect, with no network and no live agents.
 
 from __future__ import annotations
 
+import re
 from collections import Counter
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
@@ -183,6 +184,13 @@ class MachineFacts:
     linger: bool | None = None
     linger_error: str | None = None
 
+    # ── Layer 6: coord resolvable from a WORKER-shaped PATH (needs SSH —
+    # `/health` cannot see it either: it answers from the AGENT's own
+    # process, which still has ~/.coord-venv/bin on PATH) ────────────────
+    coord_on_worker_path: bool | None = None
+    coord_on_worker_path_error: str | None = None
+    coord_on_worker_path_version: str | None = None
+
     def check(self, check_id: str, subject: str | None = None) -> HealthCheckFact | None:
         for row in self.health_checks:
             if row.check_id == check_id and (subject is None or row.subject == subject):
@@ -288,6 +296,108 @@ def probe_linger(host: str, *, timeout: float = 20.0) -> tuple[bool | None, str
     return None, "`loginctl` did not report a Linger property (not systemd?)"
 
 
+# #2937 review: this probe must answer "can a worker resolve `coord`?" using
+# the exact same algorithm the agent itself uses to spawn a worker — not a
+# second, hand-rolled PATH-stripping implementation that can silently
+# disagree with it (e.g. on a trailing slash, or a PATH entry that's already
+# an unresolved `.blue`/`.green` path rather than the `~/.coord-venv`
+# symlink name). `coord.agent.worker_coord_reachable()` (#2936) is the
+# canonical, already-shipped answer to that exact question — built on
+# `_worker_subprocess_env`'s realpath-based strip
+# (`coord.agent._pinned_venv_bin_dirs`), the same function every real worker
+# spawn goes through. So instead of re-deriving the strip over SSH, this
+# probe SSHes in and asks the remote host's own pinned interpreter to import
+# and call that function directly — the machine-doctor check and the agent's
+# own startup check are then provably the same code, not two
+# implementations that happen to agree today. The script is sent over
+# stdin (`python3 -`) rather than embedded as a `-c` argument so no
+# shell-quoting layer stands between it and the interpreter.
+_COORD_ON_WORKER_PATH_PROBE_SCRIPT = """\
+import subprocess
+from coord.agent import worker_coord_reachable, _worker_subprocess_env
+
+ok, _msg = worker_coord_reachable()
+version = ""
+if ok:
+    env = _worker_subprocess_env()
+    try:
+        result = subprocess.run(
+            ["coord", "--version"], env=env, capture_output=True, text=True, timeout=10
+        )
+        version = (result.stdout or result.stderr or "").strip()
+    except Exception:
+        version = ""
+print("COORD_ON_WORKER_PATH_OK=" + ("1" if ok else "0"))
+print("VERSION=" + version.replace("\\n", " "))
+"""
+
+
+def probe_coord_on_worker_path(
+    host: str, *, timeout: float = 20.0
+) -> tuple[bool | None, str | None, str | None]:
+    """Can a WORKER-shaped shell on *host* resolve ``coord`` at all?
+
+    This is #2937's whole gap: workers are spawned with ``~/.coord-venv/bin``
+    stripped from ``PATH`` (#402, hardened by #2569) so a `pip install` in a
+    worktree can never land in the agent's own runtime venv — but nothing
+    upstream of that check ever asks whether ``coord`` is *still resolvable*
+    once that directory is gone. dell64 passed every existing layer of
+    ``coord machine doctor`` — including ``runtime.agent_venv`` (which only
+    proves the AGENT can find its own venv) — while being structurally
+    incapable of recording a single test verdict, because the agent's PATH
+    was the only PATH anything had checked.
+
+    Delegates the actual found/absent decision to
+    :func:`coord.agent.worker_coord_reachable` (#2936), invoked on *host* via
+    its own pinned interpreter (``~/.coord-venv/bin/python3``) — see
+    :data:`_COORD_ON_WORKER_PATH_PROBE_SCRIPT`. This is deliberately NOT a
+    reimplementation of the PATH strip: it is the same function every real
+    worker spawn's environment is built from, run where it matters (the
+    worker host), so this check and the agent's own startup warning
+    (``worker_coord_reachable`` logged at ``AgentServer`` init) can never
+    silently disagree.
+
+    Returns ``(found, error, version)``. Fail-soft, same discipline as
+    :func:`probe_linger`: this needs SSH, which ``/health`` structurally
+    cannot substitute for (the agent process answering a probe still has its
+    own venv on PATH — proving nothing about a worker's shell) — so an SSH
+    failure, or the pinned interpreter itself being unreachable/absent,
+    reports ``(None, reason, None)``, UNKNOWN, never a fabricated CRIT.
+    ``found=False`` — the actual defect this check exists to catch — is the
+    one outcome that must never collapse into UNKNOWN.
+    """
+    import subprocess  # noqa: PLC0415
+
+    try:
+        result = subprocess.run(
+            [
+                "ssh", "-o", "BatchMode=yes",
+                "-o", f"ConnectTimeout={max(1, int(timeout))}",
+                host, "$HOME/.coord-venv/bin/python3 -",
+            ],
+            input=_COORD_ON_WORKER_PATH_PROBE_SCRIPT,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return None, f"ssh probe failed: {exc}", None
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip().splitlines()[-1:]
+        return None, f"ssh probe failed: {detail[0] if detail else 'no output'}", None
+
+    text = (result.stdout or "").strip()
+    if "COORD_ON_WORKER_PATH_OK=1" in text:
+        version = None
+        for line in text.splitlines():
+            if line.startswith("VERSION="):
+                version = line[len("VERSION="):].strip() or None
+        return True, None, version
+    if "COORD_ON_WORKER_PATH_OK=0" in text:
+        return False, None, None
+    return None, "worker-PATH probe produced no parseable output", None
+
+
 def gather_facts(
     cfg: "Config",
     machine_name: str,
@@ -382,6 +492,11 @@ def gather_facts(
         facts.linger, facts.linger_error = probe_linger(
             machine.host, timeout=ssh_timeout
         )
+        (
+            facts.coord_on_worker_path,
+            facts.coord_on_worker_path_error,
+            facts.coord_on_worker_path_version,
+        ) = probe_coord_on_worker_path(machine.host, timeout=ssh_timeout)
     return facts
 
 
@@ -938,6 +1053,24 @@ def evaluate_graph(facts: MachineFacts) -> list[Finding]:
 # ── Layer 6: runtime ─────────────────────────────────────────────────────────
 
 
+_VERSION_NUMBER_RE = re.compile(r"\d+(?:\.\d+)+")
+
+
+def _extract_version_number(text: str | None) -> str | None:
+    """Pull the dotted version number out of free-form text, e.g.
+    ``"coord, version 0.5.290"`` -> ``"0.5.290"``.
+
+    Used so version comparisons here are an EXACT match on the number, never
+    a substring test (``"0.5.29" in "coord, version 0.5.290"`` is ``True``
+    even though those are different releases — #2937 review). Returns
+    ``None`` when no dotted number is found.
+    """
+    if not text:
+        return None
+    match = _VERSION_NUMBER_RE.search(text)
+    return match.group(0) if match else None
+
+
 def evaluate_runtime(facts: MachineFacts) -> list[Finding]:
     """The agent's own installation: its venv, and whether it survives logout.
 
@@ -947,9 +1080,12 @@ def evaluate_runtime(facts: MachineFacts) -> list[Finding]:
     because an editable one pins the live fleet's runtime to whatever branch a
     worktree happens to have checked out.
 
-    ``linger`` is the one thing ``/health`` structurally cannot see (the agent
-    answering the probe is proof only that the user manager is up *right
-    now*), so it is UNKNOWN unless the caller opted into the SSH probe.
+    ``linger`` and ``coord_on_worker_path`` are the two things ``/health``
+    structurally cannot see: the agent answering a probe is proof only that
+    the AGENT's own user manager / PATH is fine *right now*, not that a
+    WORKER spawned on this host (with ``~/.coord-venv/bin`` stripped from
+    PATH, #402/#2569) can survive logout or resolve ``coord`` at all. Both
+    are UNKNOWN unless the caller opted into the SSH probe.
     """
     out: list[Finding] = []
 
@@ -990,6 +1126,74 @@ def evaluate_runtime(facts: MachineFacts) -> list[Finding]:
                 )
             )
 
+    if facts.coord_on_worker_path is False:
+        out.append(
+            Finding(
+                layer="runtime", check="runtime.coord_on_worker_path_missing", severity=CRIT,
+                summary=(
+                    "`coord` does not resolve on a WORKER-shaped PATH (with "
+                    "~/.coord-venv/bin stripped, as #402/#2569 spawn workers) — "
+                    "this machine can dispatch and run a worker, but that worker "
+                    "cannot run `coord test` to record a verdict. This is exactly "
+                    "the #2937 gap: every other layer here, and `/health` itself, "
+                    "only ever sees the AGENT's own PATH"
+                ),
+                subject=facts.name,
+                fix=(
+                    "install `coord` somewhere on the agent user's PATH outside "
+                    "~/.coord-venv (e.g. `pipx install code-coordinator`, or a "
+                    "system-wide non-editable install) — the fix must survive "
+                    "~/.coord-venv/bin being removed from PATH, because that is "
+                    "exactly what a worker's shell does."
+                ),
+            )
+        )
+    elif facts.coord_on_worker_path is True:
+        expected_raw = (facts.version or "").strip()
+        reported_raw = facts.coord_on_worker_path_version or ""
+        expected = _extract_version_number(expected_raw)
+        reported = _extract_version_number(reported_raw)
+        # #2937 review: an EXACT comparison of the extracted version numbers,
+        # not `expected in reported` — a substring test reads a genuine skew
+        # as a match whenever the shorter string happens to be a substring of
+        # the longer one (this project's own scheme: "0.5.29" in "coord,
+        # version 0.5.290" is True even though those are different releases).
+        if expected and expected != (reported or ""):
+            out.append(
+                Finding(
+                    layer="runtime", check="runtime.coord_on_worker_path_version_mismatch",
+                    severity=WARN,
+                    summary=(
+                        f"`coord` on the worker PATH reports {reported_raw!r}, but the "
+                        f"agent's own /health reports version {expected_raw!r} — a "
+                        "worker may record verdicts against a stale or unrelated "
+                        "install"
+                    ),
+                    subject=facts.name,
+                    fix="reinstall/upgrade the worker-PATH `coord` to match the agent's version.",
+                )
+            )
+        else:
+            out.append(
+                Finding(
+                    layer="runtime", check="runtime.coord_on_worker_path", severity=OK,
+                    summary=f"`coord` resolves on a worker-shaped PATH ({reported_raw or 'version unreported'})",
+                    subject=facts.name,
+                )
+            )
+    else:
+        out.append(
+            Finding(
+                layer="runtime", check="runtime.coord_on_worker_path_unknown", severity=UNKNOWN,
+                summary=(
+                    "worker-PATH `coord` resolution not checked — /health cannot "
+                    f"see it (it only proves the AGENT can find coord); "
+                    f"{facts.coord_on_worker_path_error or 'pass --ssh to probe it'}"
+                ),
+                subject=facts.name,
+            )
+        )
+
     if facts.linger is True:
         out.append(
             Finding(