code-coordinator 0.5.335__tar.gz → 0.5.336__tar.gz

{code_coordinator-0.5.335 → code_coordinator-0.5.336}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.335",
+  "tag": "0.5.336",
   "distance": 0,
-  "node": "gb914d712a7d0e11d9f9a30e4f62b05cf9b5e8c5c",
+  "node": "g40054efb9557131858aa5684627e8e9e93b9f6ff",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-01"

{code_coordinator-0.5.335 → code_coordinator-0.5.336}/coord/dashboard/server.py

@@ -631,6 +631,29 @@ def openapi_spec() -> dict:
                 "responses": {"200": {"description": "OK"}},
             }
         },
+        "/api/machines/health": {
+            "get": {
+                "summary": (
+                    "Fleet-wide health snapshot (#3024): per-machine severity/"
+                    "stale/checked_at/results plus fleet-scope checks, verbatim "
+                    "off coord.health.fleet_snapshot.FleetHealthSnapshot"
+                ),
+                "responses": {
+                    "200": {
+                        "description": (
+                            "OK -- {schema, refreshed_at, machine_health: [...], "
+                            "fleet_checks: [...], truncated}, unchanged"
+                        ),
+                    },
+                    "503": {
+                        "description": (
+                            "The daemon is unreachable -- an explicit "
+                            "{error, reachable: false} body, never a stale-looking 200"
+                        ),
+                    },
+                },
+            }
+        },
         "/api/machines/metrics": {
             "get": {
                 "summary": (
@@ -1239,6 +1262,72 @@ def build_app(
         rows = machine_health_rows(machine_names, raw, now=time.time())
         return board, {row["machine"]: row for row in rows}
 
+    _EMPTY_FLEET_HEALTH_BLOCK = {
+        "schema": 1,
+        "refreshed_at": None,
+        "machine_health": [],
+        "fleet_checks": [],
+        "truncated": False,
+    }
+
+    def _read_fleet_health() -> dict:
+        """The full ``FleetHealthSnapshot``-shaped block backing ``GET
+        /api/machines/health`` (#3024).
+
+        Deliberately a SEPARATE read from ``_read_board_and_machine_health()``
+        rather than folding this into it: that helper's ``health_by_name``
+        already carries every field this returns per machine (``severity``,
+        ``stale``, ``checked_at``, ``results``) — see
+        ``coord.health.fleet_snapshot.machine_health_rows`` — but ``GET
+        /api/machines`` deliberately narrows to the small reachability
+        subset the fleet panel renders on every poll, the same way ``GET
+        /api/machines/metrics`` was split out from ``GET /api/machines``
+        (#3021/#3022) instead of inflating it: the per-check ``results``
+        arrays (headroom strings, values, detail) are exactly the
+        bytes-heavy, low-poll-frequency payload that split precedent argues
+        for keeping out of the panel's steady-state response.
+
+        Returns the block **verbatim** — never re-derives, re-ranks, or
+        collapses a severity here. Per #1630/#3023's honesty contract,
+        ``_effective_severity`` (upstream, in ``coord.health.fleet_snapshot``)
+        has already made the one call that matters: ``unknown``, never a
+        carried-forward ``ok``, whenever the daemon can't currently vouch for
+        a machine, while still keeping that machine's last-known
+        ``results``/``checked_at`` so a renderer can distinguish "OK" from
+        "last measured OK, a while ago".
+
+        Thin client (``board_service`` configured): the daemon's own
+        ``fleet_health`` sibling key off ``GET /board`` —
+        ``FleetHealthSnapshot.to_dict()`` (``schema``/``refreshed_at``/
+        ``machine_health``/``fleet_checks``/``truncated``) — forwarded
+        unexamined. Raises on an unreachable daemon; callers degrade
+        explicitly (mirrors ``api_machine_metrics``, #3022).
+
+        Co-located (no ``board_service``): ``fleet_checks`` is always ``[]``
+        here — those probes (board latency, phantom-running rows, deploy-lane
+        skew, …) only exist inside a live ``coord serve`` process's in-memory
+        ``FleetHealthRefresher``; a separate dashboard process has no way to
+        reach into that process's memory, same restriction
+        ``coord.health.aggregate.local_fleet_health_block`` documents for
+        ``coord status``. Per-machine severities still come from the same
+        row-assembly the thin-client path rides (``machine_health_rows``), so
+        the two modes can't drift on that half.
+        """
+        from coord import board_service  # noqa: PLC0415
+
+        svc = board_service.resolve()
+        if svc is not None:
+            from coord.client import fetch_board_payload  # noqa: PLC0415
+
+            payload = fetch_board_payload(svc)
+            return payload.get("fleet_health") or dict(_EMPTY_FLEET_HEALTH_BLOCK)
+
+        from coord.health.aggregate import local_fleet_health_block  # noqa: PLC0415
+
+        machine_names = [m.name for m in config.machines]
+        block = local_fleet_health_block(machine_names)
+        return {**_EMPTY_FLEET_HEALTH_BLOCK, **block}
+
     def _active_assignments_by_machine(board) -> dict[str, list[dict]]:  # noqa: ANN001
         """Group *board*'s RUNNING active assignments by machine (#3023).
 
@@ -1544,6 +1633,66 @@ def build_app(
             result.append(machine_data)
         return JSONResponse(result)
 
+    async def api_machines_health(request: Request) -> JSONResponse:
+        """GET /api/machines/health — the fleet-wide health snapshot (#3024).
+
+        The richest per-machine data the coordinator has, already computed
+        and already refreshed by the daemon's health-poll tick
+        (``coord.health.fleet_snapshot.FleetHealthRefresher``, #1630) and
+        already served on the board daemon's own ``/board`` for coord-tui —
+        this is what makes it reachable from ``coord web`` too, which
+        previously had no view of it at all.
+
+        Kept as its own endpoint rather than folded into ``GET
+        /api/machines``: see ``_read_fleet_health()``'s docstring for why —
+        in short, the same split ``GET /api/machines/metrics`` already made
+        from ``GET /api/machines`` (#3021/#3022), because the per-check
+        ``results`` this carries (headroom strings, values, detail, one row
+        per check per machine) are meaningfully heavier than the small
+        reachability summary the fleet panel polls on every tick.
+
+        Body shape mirrors ``/board``'s own ``fleet_health`` key exactly
+        (``coord.health.fleet_snapshot.FleetHealthSnapshot.to_dict()``):
+        ``{schema, refreshed_at, machine_health: [...], fleet_checks: [...],
+        truncated}``. Every ``machine_health`` row carries ``severity``,
+        ``stale``, ``checked_at`` and ``results`` verbatim from
+        ``_effective_severity``/``machine_health_rows`` — never re-derived,
+        re-ranked, or collapsed at this layer (#1630's honesty contract: a
+        stale/offline/never-polled machine reads ``unknown``, never a
+        carried-forward ``ok``, while its last-known ``results``/
+        ``checked_at`` are retained so a renderer can still tell "OK" apart
+        from "last measured OK, a while ago").
+
+        Degrades honestly on an unreachable daemon (thin-client mode only —
+        same failure mode ``api_machine_metrics`` already guards against,
+        #3022): an explicit ``{error, reachable: false}`` 503, never a 200
+        with an empty/last-known block a renderer could mistake for "fleet
+        quiet, all healthy".
+
+        Fixture mode has no live health poll to simulate, so it serves
+        whatever ``fleet_health`` block (if any) was captured alongside the
+        seeded ``/board`` payload — the same "golden /board capture drops in
+        unchanged" posture ``FixtureServer.board()`` and friends already
+        have — falling back to the same all-empty shape a fresh install with
+        no health data yet would report, rather than fabricating severities.
+        """
+        if _fixture is not None:
+            block = _fixture.board_payload.get("fleet_health")
+            return JSONResponse(block if block else dict(_EMPTY_FLEET_HEALTH_BLOCK))
+
+        try:
+            block = _read_fleet_health()
+        except Exception as e:  # noqa: BLE001 — network failure/timeout/daemon 5xx: all "unreachable"
+            return JSONResponse(
+                {
+                    "error": "fleet health daemon unreachable",
+                    "detail": str(e),
+                    "reachable": False,
+                },
+                status_code=503,
+            )
+        return JSONResponse(block)
+
     def _machine_metrics_daemon_target():  # -> coord.client.ServiceConfig
         """Where ``GET /api/machines/metrics`` actually reaches for data (#3022).
 
@@ -3107,6 +3256,7 @@ def build_app(
         Route("/", index, methods=["GET"]),
         Route("/api/board", api_board, methods=["GET"]),
         Route("/api/machines", api_machines, methods=["GET"]),
+        Route("/api/machines/health", api_machines_health, methods=["GET"]),
         Route("/api/machines/metrics", api_machine_metrics, methods=["GET"]),
         Route("/api/sessions", api_sessions, methods=["GET"]),
         Route("/api/proposals", api_proposals, methods=["GET"]),

{code_coordinator-0.5.335 → code_coordinator-0.5.336}/tests/test_dashboard_api.py

@@ -771,6 +771,199 @@ class TestMachinesAPI:
         assert "progress" not in m["assignments"]["active"][0]
 
 
+class TestMachinesHealthAPI:
+    """#3024: GET /api/machines/health -- the fleet-wide `FleetHealthSnapshot`
+    (severity/stale/headroom detail per machine, plus fleet-scope checks)
+    that `GET /api/machines` deliberately keeps out of its own response.
+    """
+
+    def _health_row(self, *, received_at=None, results=None, **overrides) -> dict:
+        now = time.time()
+        row = {
+            "state": "online",
+            "reason": "",
+            "latency_ms": 7.5,
+            "received_at": now if received_at is None else received_at,
+            "health": {
+                "schema": 1,
+                "checked_at": now,
+                "severity": "ok",
+                "results": results if results is not None else [
+                    {"check_id": "disk", "severity": "ok", "headroom": "42% free"},
+                ],
+                "worktree_bytes": 4096,
+                "agent_runtime_version": "0.42.0",
+            },
+        }
+        row.update(overrides)
+        return row
+
+    def test_local_mode_passes_severity_and_results_through_verbatim(self) -> None:
+        """No `board_service` configured -> the same local-DB reassembly
+        `coord status` uses (`coord.health.aggregate.local_fleet_health_block`),
+        with every per-check field (`severity`, `results`/`headroom`) intact
+        -- never re-derived or collapsed at this layer."""
+        client = _client()
+        with patch(
+            "coord.state.load_machine_health",
+            return_value={"laptop": self._health_row()},
+        ):
+            r = client.get("/api/machines/health")
+
+        assert r.status_code == 200
+        data = r.json()
+        assert data["fleet_checks"] == []
+        rows = {row["machine"]: row for row in data["machine_health"]}
+        laptop = rows["laptop"]
+        assert laptop["severity"] == "ok"
+        assert laptop["stale"] is False
+        assert laptop["results"] == [
+            {"check_id": "disk", "severity": "ok", "headroom": "42% free"},
+        ]
+
+    def test_stale_machine_reads_unknown_but_retains_last_known_results(
+        self,
+    ) -> None:
+        """#1630's honesty contract: a machine whose last poll is older than
+        `STALE_AFTER_SECONDS` must report `severity="unknown"` and
+        `stale=True` -- NEVER a carried-forward `ok` -- while its last-known
+        `results`/`checked_at` are still served, so a renderer can tell
+        "OK" apart from "last measured OK, a while ago"."""
+        from coord.health.fleet_snapshot import STALE_AFTER_SECONDS
+
+        long_ago = time.time() - STALE_AFTER_SECONDS - 100
+        stale_results = [
+            {"check_id": "disk", "severity": "ok", "headroom": "42% free"},
+        ]
+        client = _client()
+        with patch(
+            "coord.state.load_machine_health",
+            return_value={
+                "laptop": self._health_row(
+                    received_at=long_ago, results=stale_results
+                ),
+            },
+        ):
+            r = client.get("/api/machines/health")
+
+        assert r.status_code == 200
+        laptop = {row["machine"]: row for row in r.json()["machine_health"]}["laptop"]
+        assert laptop["severity"] == "unknown"
+        assert laptop["stale"] is True
+        # Last-known detail is retained, not dropped just because the
+        # severity above it was downgraded for staleness.
+        assert laptop["results"] == stale_results
+
+    def test_never_polled_machine_reads_unknown_not_absent(self) -> None:
+        client = _client()
+        with patch("coord.state.load_machine_health", return_value={}):
+            r = client.get("/api/machines/health")
+
+        assert r.status_code == 200
+        data = r.json()
+        assert len(data["machine_health"]) == 1
+        assert data["machine_health"][0]["machine"] == "laptop"
+        assert data["machine_health"][0]["severity"] == "unknown"
+
+    def test_thin_client_forwards_the_daemons_fleet_health_block_verbatim(
+        self, monkeypatch
+    ) -> None:
+        """`board_service` configured -> the daemon's own `GET /board`
+        `fleet_health` key, forwarded unexamined -- including `fleet_checks`,
+        which the local-mode path can never populate (#3024)."""
+        import coord.client as cc
+
+        monkeypatch.setattr(
+            cc, "resolve_board_service",
+            lambda *a, **k: cc.ServiceConfig("http://daemon:7435"),
+        )
+
+        now = time.time()
+        fleet_health = {
+            "schema": 1,
+            "refreshed_at": now,
+            "truncated": False,
+            "machine_health": [
+                {
+                    "machine": "laptop",
+                    "state": "online",
+                    "reason": "",
+                    "latency_ms": 3.2,
+                    "received_at": now,
+                    "stale": False,
+                    "severity": "warn",
+                    "checked_at": now,
+                    "results": [
+                        {"check_id": "disk", "severity": "warn", "headroom": "8% free"},
+                    ],
+                    "worktree_bytes": 999,
+                    "agent_runtime_version": "1.0.0",
+                },
+            ],
+            "fleet_checks": [
+                {"check_id": "fleet_board_latency", "severity": "ok"},
+            ],
+        }
+        payload = {
+            "assignments": [], "plans": {}, "round_number": 0,
+            "fleet_health": fleet_health,
+        }
+
+        calls = []
+
+        def fake_get(url, **kw):
+            calls.append(url)
+
+            class _Resp:
+                status_code = 200
+
+                def raise_for_status(self):
+                    return None
+
+                def json(self):
+                    return payload
+
+            return _Resp()
+
+        monkeypatch.setattr(cc.httpx, "get", fake_get)
+
+        client = _client()
+        r = client.get("/api/machines/health")
+
+        assert len(calls) == 1
+        assert r.status_code == 200
+        assert r.json() == fleet_health
+
+    def test_unreachable_daemon_degrades_to_an_explicit_error(
+        self, monkeypatch
+    ) -> None:
+        """A daemon that can't be reached must come back as an explicit
+        error -- NEVER a 200 with a stale/empty block a renderer could
+        mistake for "fleet quiet, all healthy" (mirrors #3022's
+        `/api/machines/metrics` degradation)."""
+        import httpx
+
+        import coord.client as cc
+
+        monkeypatch.setattr(
+            cc, "resolve_board_service",
+            lambda *a, **k: cc.ServiceConfig("http://daemon:7435"),
+        )
+
+        def raising_get(url, **kw):
+            raise httpx.ConnectError("connection refused")
+
+        monkeypatch.setattr(cc.httpx, "get", raising_get)
+
+        client = _client()
+        r = client.get("/api/machines/health")
+
+        assert r.status_code == 503
+        body = r.json()
+        assert body["reachable"] is False
+        assert "error" in body
+
+
 class TestMachineMetricsAPI:
     """``GET /api/machines/metrics`` — the dashboard's proxy of #3021's daemon
     endpoint (#3022). ``coord web``'s own origin is what the browser (and