code-coordinator 0.5.299__tar.gz → 0.5.301__tar.gz

{code_coordinator-0.5.299 → code_coordinator-0.5.301}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.299",
+  "tag": "0.5.301",
   "distance": 0,
-  "node": "g472c4dff139719a7463904657ff555bbebb076af",
+  "node": "g26f7e1b979b278db2f5c5a9a510debee5bb45a0a",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-30"

{code_coordinator-0.5.299 → code_coordinator-0.5.301}/coord/client.py

@@ -199,6 +199,44 @@ def post_board(svc: ServiceConfig, board: Board, *, timeout: float = _WRITE_TIME
     post_record(svc, "/board", serialize_board(board), timeout=timeout)
 
 
+def _reraise_with_detail(exc: httpx.HTTPStatusError) -> httpx.HTTPStatusError:
+    """#2907: fold the daemon's own ``{"error", "detail"}`` error body into the
+    raised exception's message.
+
+    ``serve_app.py``'s handlers answer a failure with the HTTP status code and
+    a ``{"error": "<label>", "detail": "<reason>"}`` body (see e.g.
+    ``post_assignment_session_id``) — plain ``resp.raise_for_status()``
+    discards that body, so every one of :func:`post_record`'s ~10 callers,
+    which all just catch ``httpx.HTTPError``/``Exception`` and render
+    ``str(e)``, only ever saw the generic status line ("503 Service
+    Unavailable"), never the daemon's own reason (e.g. a GitHub rate-limit
+    backoff active for another N seconds).
+
+    Mirrors ``coord.dispatch._reraise_with_body`` (#1527), the same fix for
+    the sibling ``agent_app.py`` assign-rejection body: always returns a
+    **new** ``httpx.HTTPStatusError`` carrying the *same* ``request``/
+    ``response`` as *exc*, so every existing ``except httpx.HTTPStatusError``
+    that itself inspects ``exc.response.status_code`` / ``exc.response.json()``
+    (e.g. ``coord.issue_store.post_result``, ``coord.state.close_issue``)
+    keeps working unchanged — only the message gains the detail.
+
+    ``detail`` is preferred over ``error`` when both are present, since it
+    carries the specific cause rather than the handler's own short label. A
+    non-JSON/empty body, or one with neither key, falls back to *exc*'s
+    original status-line message unchanged — degrading, never crashing,
+    while handling a failure that's already in flight.
+    """
+    reason = None
+    try:
+        body = exc.response.json()
+    except ValueError:
+        body = None
+    if isinstance(body, dict):
+        reason = body.get("detail") or body.get("error")
+    message = f"{exc} — {reason}" if reason else str(exc)
+    return httpx.HTTPStatusError(message, request=exc.request, response=exc.response)
+
+
 def post_record(
     svc: ServiceConfig,
     path: str,
@@ -213,11 +251,20 @@ def post_record(
     writing the local DB, so a thin client's result lands on the one shared DB.
     Raises ``httpx.HTTPError`` on transport/HTTP failure — the seam decides
     whether that is fatal (``post_result``) or best-effort (``post_completion``).
+
+    #2907: an HTTP error response's message carries the daemon's own
+    ``detail``/``error`` reason (see :func:`_reraise_with_detail`) rather than
+    just the generic status line — a transport failure (connection refused,
+    timeout) never reaches this and is unaffected, since there is no response
+    body to read.
     """
     resp = httpx.post(
         f"{svc.url}{path}", json=payload, headers=_headers(svc), timeout=timeout
     )
-    resp.raise_for_status()
+    try:
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        raise _reraise_with_detail(exc) from exc
     return resp.json()
 
 

{code_coordinator-0.5.299 → code_coordinator-0.5.301}/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(

{code_coordinator-0.5.299 → code_coordinator-0.5.301}/tests/test_board_service.py

@@ -169,3 +169,115 @@ class TestRouteWrite:
         resp = board_service.route_write(svc, "/assignment-usage", {"a": 1})
         assert resp == {"ok": True}
         assert captured == {"path": "/assignment-usage", "payload": {"a": 1}}
+
+
+class TestPostRecordErrorSurfacing:
+    """#2907: ``post_record`` used to call ``resp.raise_for_status()`` and
+    discard the response body — where ``serve_app.py``'s handlers put the
+    actual reason (e.g. a GitHub rate-limit backoff). Every one of
+    ``post_record``'s ~10 callers just catches ``httpx.HTTPError``/
+    ``Exception`` and renders ``str(e)``, so a bare "503 Service Unavailable"
+    was all an operator ever saw. Mirrors ``TestDispatchErrorSurfacing`` in
+    ``tests/test_dispatch.py`` (#1527), the same fix for the sibling
+    ``agent_app.py`` assign-rejection body.
+    """
+
+    @staticmethod
+    def _svc():
+        from coord import client as cc
+
+        return cc.ServiceConfig("http://d:7435")
+
+    def test_detail_is_surfaced_and_preferred_over_error(self, monkeypatch):
+        import httpx
+
+        from coord import client as cc
+
+        request = httpx.Request("POST", "http://d:7435/issue-create")
+        response = httpx.Response(
+            503,
+            json={
+                "error": "issue-create failed",
+                "detail": "GitHub secondary_rate_limit backoff active for 60s more",
+            },
+            request=request,
+        )
+        monkeypatch.setattr(cc.httpx, "post", lambda *a, **k: response)
+        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+            cc.post_record(self._svc(), "/issue-create", {})
+        assert "GitHub secondary_rate_limit backoff active for 60s more" in str(
+            exc_info.value
+        )
+
+    def test_error_is_surfaced_when_no_detail(self, monkeypatch):
+        import httpx
+
+        from coord import client as cc
+
+        request = httpx.Request("POST", "http://d:7435/board")
+        response = httpx.Response(
+            400, json={"error": "missing field: assignment_id"}, request=request,
+        )
+        monkeypatch.setattr(cc.httpx, "post", lambda *a, **k: response)
+        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+            cc.post_record(self._svc(), "/board", {})
+        assert "missing field: assignment_id" in str(exc_info.value)
+
+    @pytest.mark.parametrize(
+        "response_kwargs",
+        [
+            pytest.param({"text": "<html>Bad Gateway</html>"}, id="non_json_body"),
+            pytest.param({}, id="empty_body"),
+        ],
+    )
+    def test_non_json_or_empty_body_falls_back_to_httpx_message(
+        self, monkeypatch, response_kwargs,
+    ):
+        import httpx
+
+        from coord import client as cc
+
+        request = httpx.Request("POST", "http://d:7435/board")
+        response = httpx.Response(502, request=request, **response_kwargs)
+        monkeypatch.setattr(cc.httpx, "post", lambda *a, **k: response)
+        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+            cc.post_record(self._svc(), "/board", {})
+        # No crash while handling the failure, and the original status-line
+        # message survives unchanged (no daemon reason to fold in).
+        assert "502" in str(exc_info.value)
+
+    def test_transport_failure_is_unchanged(self, monkeypatch):
+        import httpx
+
+        from coord import client as cc
+
+        def _raise(*a, **k):
+            raise httpx.ConnectError("connection refused")
+
+        monkeypatch.setattr(cc.httpx, "post", _raise)
+        with pytest.raises(httpx.ConnectError):
+            cc.post_record(self._svc(), "/board", {})
+
+    def test_callers_status_code_and_json_readback_still_work(self, monkeypatch):
+        """Callers like ``coord.issue_store.post_result`` and
+        ``coord.state.close_issue`` catch ``httpx.HTTPStatusError`` themselves
+        and read ``exc.response.status_code`` / ``exc.response.json()`` to
+        decide their own fatal/best-effort handling — the re-raised exception
+        must keep supporting both, or #2907's compatibility guarantee (no
+        caller changes its fatal/best-effort behaviour) breaks."""
+        import httpx
+
+        from coord import client as cc
+
+        request = httpx.Request("POST", "http://d:7435/result")
+        response = httpx.Response(
+            400,
+            json={"error": "cannot claim done from a chat session"},
+            request=request,
+        )
+        monkeypatch.setattr(cc.httpx, "post", lambda *a, **k: response)
+        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+            cc.post_record(self._svc(), "/result", {})
+        exc = exc_info.value
+        assert exc.response.status_code == 400
+        assert exc.response.json()["error"] == "cannot claim done from a chat session"

{code_coordinator-0.5.299 → code_coordinator-0.5.301}/tests/test_machine_onboard.py

@@ -382,6 +382,162 @@ def test_disabled_linger_crits_and_names_the_delayed_symptom():
     assert "enable-linger" in (finding.fix or "")
 
 
+# ── #2937: coord must resolve on a WORKER-shaped PATH, not just the agent's ──
+
+
+def test_probe_coord_on_worker_path_parses_a_found_binary():
+    with patch("subprocess.run", return_value=_ssh_result(
+        "COORD_ON_WORKER_PATH_OK=1\nVERSION=coord, version 0.9.0\n"
+    )):
+        found, error, version = machine_onboard.probe_coord_on_worker_path("host")
+    assert found is True
+    assert error is None
+    assert version == "coord, version 0.9.0"
+
+
+def test_probe_coord_on_worker_path_reports_absence_as_a_defect_not_unknown():
+    """`found=False` is the whole point of #2937 — it must never collapse
+    into the fail-soft UNKNOWN path the way an SSH outage does."""
+    with patch("subprocess.run", return_value=_ssh_result("COORD_ON_WORKER_PATH_OK=0\n")):
+        found, error, version = machine_onboard.probe_coord_on_worker_path("host")
+    assert found is False
+    assert error is None
+    assert version is None
+
+
+def test_probe_coord_on_worker_path_delegates_to_the_canonical_agent_function():
+    """#2937 review: this must not be a second, hand-rolled reimplementation
+    of the #402/#2569 PATH strip — it has to invoke the exact same
+    `coord.agent.worker_coord_reachable()` a real worker spawn's environment
+    is built from, on the worker host's own pinned interpreter, so the two
+    checks can never silently disagree (e.g. on a trailing slash, or a PATH
+    entry that's already a resolved `.blue`/`.green` path)."""
+    with patch("subprocess.run", return_value=_ssh_result(
+        "COORD_ON_WORKER_PATH_OK=1\nVERSION=coord, version 0.9.0\n"
+    )) as run:
+        machine_onboard.probe_coord_on_worker_path("host")
+    args, kwargs = run.call_args
+    argv = args[0]
+    assert argv[0] == "ssh"
+    assert argv[-1] == "$HOME/.coord-venv/bin/python3 -"
+    script = kwargs["input"]
+    assert "from coord.agent import worker_coord_reachable" in script
+    assert "worker_coord_reachable()" in script
+
+
+def test_probe_coord_on_worker_path_fails_soft_when_the_pinned_interpreter_is_gone():
+    """If `~/.coord-venv/bin/python3` itself doesn't resolve on the remote
+    shell (e.g. the venv was never installed), the remote shell reports a
+    nonzero exit — same fail-soft UNKNOWN discipline as any other SSH-layer
+    trouble, never a fabricated found/absent."""
+    with patch("subprocess.run", return_value=_ssh_result(
+        "", returncode=127, stderr="bash: line 1: .coord-venv/bin/python3: No such file or directory"
+    )):
+        found, error, version = machine_onboard.probe_coord_on_worker_path("host")
+    assert found is None
+    assert "No such file" in error
+    assert version is None
+
+
+def test_probe_coord_on_worker_path_fails_soft_on_ssh_trouble():
+    """Same discipline as `probe_linger`: an SSH-layer failure is UNKNOWN,
+    never fabricated as either a pass or the #2937 defect."""
+    with patch("subprocess.run",
+               return_value=_ssh_result("", returncode=255, stderr="No route to host")):
+        found, error, version = machine_onboard.probe_coord_on_worker_path("host")
+    assert found is None
+    assert "No route to host" in error
+    assert version is None
+
+    with patch("subprocess.run", return_value=_ssh_result("garbage, no marker\n")):
+        found, error, version = machine_onboard.probe_coord_on_worker_path("host")
+    assert found is None
+    assert "no parseable output" in error
+    assert version is None
+
+
+def test_coord_absent_from_worker_path_crits():
+    """The #2937 regression itself: dell64 shape — the agent is perfectly
+    healthy (runtime.agent_venv is OK, /health answers fine) but `coord`
+    cannot be found once ~/.coord-venv/bin is stripped from PATH, so a
+    worker dispatched here can never run `coord test` to record a verdict."""
+    facts = MachineFacts(
+        name="dell64", configured=True, host="dell64.tail1234.ts.net",
+        declared_capabilities=["python"], declared_repos=["api"],
+        repo_paths={"api": "~/src/api"}, known_repos=["api"],
+        coord_on_worker_path=False,
+    )
+    finding = _by_check(machine_onboard.evaluate(facts), "runtime.coord_on_worker_path_missing")
+    assert finding.severity == CRIT
+    assert "worker" in finding.summary.lower()
+    assert "~/.coord-venv" in finding.fix
+
+
+def test_coord_on_worker_path_unknown_without_the_ssh_probe(cfg):
+    """Mirrors `runtime.linger_unknown`: /health cannot see this either — the
+    agent process answering a probe still has its own venv on PATH, which
+    proves nothing about a worker's shell."""
+    report = machine_onboard.evaluate(_facts(cfg))
+    finding = _by_check(report, "runtime.coord_on_worker_path_unknown")
+    assert finding.severity == UNKNOWN
+    assert "--ssh" in finding.summary
+
+
+def test_coord_on_worker_path_matching_the_agent_version_is_ok():
+    facts = MachineFacts(
+        name="laptop", configured=True, host="laptop.tail1234.ts.net",
+        declared_capabilities=["python"], declared_repos=["api"],
+        repo_paths={"api": "~/src/api"}, known_repos=["api"],
+        version="0.9.0",
+        coord_on_worker_path=True,
+        coord_on_worker_path_version="coord, version 0.9.0",
+    )
+    finding = _by_check(machine_onboard.evaluate(facts), "runtime.coord_on_worker_path")
+    assert finding.severity == OK
+
+
+def test_coord_on_worker_path_version_skew_from_the_agent_warns():
+    """A worker-PATH `coord` that answers but on a DIFFERENT version than the
+    agent's own /health is real residue — a worker could be recording
+    verdicts from a stale or unrelated install — but not the #2937 total-loss
+    case, so it warns rather than CRITs."""
+    facts = MachineFacts(
+        name="laptop", configured=True, host="laptop.tail1234.ts.net",
+        declared_capabilities=["python"], declared_repos=["api"],
+        repo_paths={"api": "~/src/api"}, known_repos=["api"],
+        version="0.9.0",
+        coord_on_worker_path=True,
+        coord_on_worker_path_version="coord, version 0.7.1",
+    )
+    finding = _by_check(
+        machine_onboard.evaluate(facts), "runtime.coord_on_worker_path_version_mismatch"
+    )
+    assert finding.severity == WARN
+    assert "0.9.0" in finding.summary
+    assert "0.7.1" in finding.summary
+
+
+def test_coord_on_worker_path_version_comparison_is_exact_not_substring():
+    """#2937 review: `expected in reported` is a substring test, and this
+    project's own version scheme makes it a trap — "0.5.29" IS a substring
+    of "coord, version 0.5.290" even though those are different releases.
+    A genuinely-skewed patch version must still warn."""
+    facts = MachineFacts(
+        name="laptop", configured=True, host="laptop.tail1234.ts.net",
+        declared_capabilities=["python"], declared_repos=["api"],
+        repo_paths={"api": "~/src/api"}, known_repos=["api"],
+        version="0.5.29",
+        coord_on_worker_path=True,
+        coord_on_worker_path_version="coord, version 0.5.290",
+    )
+    finding = _by_check(
+        machine_onboard.evaluate(facts), "runtime.coord_on_worker_path_version_mismatch"
+    )
+    assert finding.severity == WARN
+    assert "0.5.29" in finding.summary
+    assert "0.5.290" in finding.summary
+
+
 # ── The doctor fold-in must not duplicate what `coord doctor` already prints ─