code-coordinator 0.5.332__py3-none-any.whl → 0.5.334__py3-none-any.whl

{code_coordinator-0.5.332.dist-info → code_coordinator-0.5.334.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.332
+Version: 0.5.334
 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.332.dist-info → code_coordinator-0.5.334.dist-info}/RECORD

@@ -1,4 +1,4 @@
-code_coordinator-0.5.332.dist-info/licenses/LICENSE,sha256=851BVZZwf_pEv2ydSlMmcZrwnwSS5YJ98wdLze7lyL8,4212
+code_coordinator-0.5.334.dist-info/licenses/LICENSE,sha256=851BVZZwf_pEv2ydSlMmcZrwnwSS5YJ98wdLze7lyL8,4212
 coord/__init__.py,sha256=3FN2qrrxtW87xSsSD557YcMwHLDahnFK8LvqQI7Wlf4,9783
 coord/_board_mapping.py,sha256=SGq8hC-gsyXHEZe2L58qy6pyOVQvswTpQ5FzPa_vZ8w,11012
 coord/acceptance.py,sha256=v7k1e_shUIjWKolKDQ9oJv67o0O8L659El3grvcF8ns,75452
@@ -63,7 +63,7 @@ coord/interactive.py,sha256=AEK-5S2aMknpP6k3Xx-aBuTEulw0_c-gbYPEKTwUjRE,219083
 coord/issue_store.py,sha256=abywea0vpXE_BZ5F3QHLDxLKYKDYF7iQYabZhppVYto,69451
 coord/issues_sync_status.py,sha256=_6ucx7oW3TUGZZvs93wRbzR_SUQcNlz-7RptOzr4alo,9262
 coord/liveness_auditor.py,sha256=sf_xBklt37DUnrIEeD4fVp4_gWPDaXbydZgfuWAPFRE,12478
-coord/machine_metrics.py,sha256=mBEciin6gdYJaPw73gY7mrDnalm01WhX7kpzt8t0NEk,9396
+coord/machine_metrics.py,sha256=paWqBTZgeIi7w1pgH5QSJL59UxwetxE8bXblzzcspSI,16300
 coord/machine_onboard.py,sha256=BTUAC7bdERcDyaIvO2yKkQ8xPwsdR063yHUrOznmHWk,58555
 coord/machine_pause.py,sha256=6s7Dtr5zLs1qB2NWI2-cfbMdPyigK62FTtLjzmY6slE,47521
 coord/merge_queue.py,sha256=UdwyoyfE9DplS6Mia4_aY6TK5a-f933M04Ns5mVHnsw,392677
@@ -108,7 +108,7 @@ coord/revalidate.py,sha256=fQaYCvObqUawSZWMEOkVWFtYswz9PQQwSMApAyP5zeA,66266
 coord/review.py,sha256=hsY6HUif44HL3pY52H7SoqNuMMZzA_9gfHfJKnC-fWE,183282
 coord/scorecard.py,sha256=axe_doBJBBFWtN21JZDRSijwDI0xaZrt2oVYbwJPW7U,20211
 coord/self_health.py,sha256=9PLVdaEReFLUY6y2QXMGVd6U1CdHAh9_8MzduwBOzAY,10651
-coord/serve_app.py,sha256=_vyNSXqAUWVfsQfYCjJRnqefczof7qKObrMnTysyUkw,509398
+coord/serve_app.py,sha256=8xveD7Y9zmP-J-dIE6GcJJJl0CVMIubIZqJFojrbIw0,516163
 coord/smoke.py,sha256=INLh9Wu57WOcCoOY4CMOcbzArIhMxMolsV2D8hAW7zw,70481
 coord/spend_ceiling.py,sha256=hfuiXlnD4or7Wqoqf6BHcOMT2CXd92FBZuVdnQVlI2M,13573
 coord/split_work.py,sha256=Gp_cNtYBe7nDxBN7cDRs8CJG3V_Y0C1QUi35fHGcvnY,8502
@@ -163,8 +163,8 @@ coord/commands/test_gate.py,sha256=8y_u-otEXUIBoY0m6gzcqdOq78cbG4lSW0o1N0u1z9Y,3
 coord/commands/tui.py,sha256=GX4LsgMk08itlURCgkOKqWgjnv38uIfFSWM3xrz9T_A,18193
 coord/dashboard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 coord/dashboard/fixture.py,sha256=YQrm_EvpsddqAa8d5fT7iEbUXLH2KQNxEST5NA1NgpA,18941
-coord/dashboard/index.html,sha256=bN5-JFQKQWeFpFAZTUBZ1wg4LRDmIr0InPttSE2MTgY,31376
-coord/dashboard/server.py,sha256=v5wBRtmQXJZgs3uQPuN-5bDCqS5xr-yejFAhhgHgj40,135440
+coord/dashboard/index.html,sha256=XzipoURZAP46Tggas-pSMq8Fb1ETX9TyAJy2ItNVigc,31463
+coord/dashboard/server.py,sha256=rzygqs9P7D8Mu9f0LtqS8fcAeDNutYjmbvmLG6CVIhc,142424
 coord/dashboard/terminal.py,sha256=wR5rfWQCZ0yO5bXCkqa0t-a1g5YAQ-20LC6icZdGWHM,14647
 coord/deploy/README.md,sha256=DG_q36KeW0LQ32ElU11wjfjULO7xGUoiPIFEGPW41k0,1391
 coord/deploy/coord-agent.service,sha256=GSo_2iqCx4zv4-85LGnaINsu-BdPHpG64I8xfULKcUk,6392
@@ -190,7 +190,7 @@ coord/health/__init__.py,sha256=fvda5KAAaycBk7kXcNm_7wkLm28BTU3_TjyF6Nr3DnA,1990
 coord/health/aggregate.py,sha256=MFPEe5JiS5gRsD0uc4zXAg86YhqnKFvEeSa1e9RAUnY,5694
 coord/health/cli.py,sha256=CYMWO_UsjpmjvVOSk3AuRa26zmfIEiz8_pnx_QvFxYQ,5931
 coord/health/context.py,sha256=pbc5qq-1DMbgjsFKTR52hg-igHtK7HazGLq-LTgzwuU,4060
-coord/health/fleet_snapshot.py,sha256=1zDMmekejRiRnoUsuvPs4ziqNxmM4eblAoo4mz7inpg,22660
+coord/health/fleet_snapshot.py,sha256=H0oqWFsdVw6vWW35P7w84pG_4n9aA1zzVkjJsA4Qh1Y,25595
 coord/health/models.py,sha256=h-rT3SqYjaM5obrldbhMN5BC97WKBVvN-4wDxFCM890,11516
 coord/health/pypi.py,sha256=L1CDtuWYrmaF_XGKiHh2R9PkDQNMjBdTxAWIpWZpS4c,10409
 coord/health/registry.py,sha256=TLzPSY-HCkKGWRamJdOkPc9A-2EYmQxTqS4n-kr3cqg,15713
@@ -249,8 +249,8 @@ coord/skills/release-now/SKILL.md,sha256=u5JY0Jm0IiZYs2JGjRSqNj265CUWcIA6pMaeulb
 coord/skills/review-verdict-recovery/SKILL.md,sha256=Grg8GWkJLK20ct2YiigbTFfNOkit7tNrdRIhdocKGJk,3941
 coord/skills/tui-quadraui-workflow/SKILL.md,sha256=4hUZza9wSSnPhf0eRAOh2r_MQZxK2pXYO5g-kxmJq-U,3832
 coord/skills/update-issue/SKILL.md,sha256=VrPinEmLZrCSNDrnz96hQomyO403o5c4i0RdsnUnWA0,3642
-code_coordinator-0.5.332.dist-info/METADATA,sha256=1zZHh_75sV2go8WtKq1cX-YI4TfozgKZnV3-wkhwgDk,27178
-code_coordinator-0.5.332.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-code_coordinator-0.5.332.dist-info/entry_points.txt,sha256=o-Hq8pvG7ReGePvN_4iOKjLNqiq-MJ43HbPurqjNPZo,41
-code_coordinator-0.5.332.dist-info/top_level.txt,sha256=w5sTrXesTCebhXyYv2qufOZGo0PoD1Lxgn0Q3MAXjh4,6
-code_coordinator-0.5.332.dist-info/RECORD,,
+code_coordinator-0.5.334.dist-info/METADATA,sha256=a8GsHRhSqTf55gDNiGuVjRuRQyQrOhRyOStbDDLkjMs,27178
+code_coordinator-0.5.334.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+code_coordinator-0.5.334.dist-info/entry_points.txt,sha256=o-Hq8pvG7ReGePvN_4iOKjLNqiq-MJ43HbPurqjNPZo,41
+code_coordinator-0.5.334.dist-info/top_level.txt,sha256=w5sTrXesTCebhXyYv2qufOZGo0PoD1Lxgn0Q3MAXjh4,6
+code_coordinator-0.5.334.dist-info/RECORD,,

coord/dashboard/index.html

@@ -521,12 +521,12 @@ async function loadMachines() {
       const a = m.assignments.active[0];
       const spec = a.spec || {};
       detail = `<div class="meta">${badge('busy', 'busy')} #${spec.issue_number}: ${E(spec.issue_title || '')}</div>`;
-      if (a.progress && a.progress.updates && a.progress.updates.length) {
-        detail += `<div class="meta">latest: ${E(a.progress.updates[a.progress.updates.length-1])}</div>`;
-      }
-      if (a.progress && a.progress.stuck) {
-        detail += `<div class="meta" style="color:#da3633">STUCK: ${E(a.progress.stuck)}</div>`;
-      }
+      // #3023: GET /api/machines no longer carries `a.progress` (live
+      // STATUS:/STUCK: tail of the owning machine's own log file) — that
+      // data only ever existed via a fresh per-agent probe, and serving it
+      // here would reintroduce the exact per-request fleet fan-out this
+      // endpoint was reworked to remove. Use `coord status` / `coord log
+      // <id> -f` for live per-worker progress instead.
     }
     return `
       <div class="card">

coord/dashboard/server.py

@@ -51,7 +51,6 @@ from coord.drive_queue import (
     summarize_drive_queue,
 )
 from coord.models import Assignment
-from coord.network import check_all, fetch_status
 from coord.openapi import build_spec, dataclass_schema, openapi_and_docs_routes
 from coord.pipeline import PipelineView
 from coord.state import list_drive_queue, load_proposals
@@ -1142,6 +1141,94 @@ def build_app(
             return
         write_board(board)
 
+    def _read_board_and_machine_health() -> tuple:  # -> tuple[Board, dict[str, dict]]
+        """The board plus every configured machine's latest daemon-tick-
+        refreshed health row, keyed by machine name (#3023).
+
+        Backs ``GET /api/machines``. Fetches both in ONE daemon round trip
+        when this dashboard is a thin client (``board_service`` configured)
+        instead of two independent ``GET /board`` calls — the review found
+        that ``_read_machine_health()`` fetching its own payload and then
+        ``_active_assignments_by_machine(_read_board())`` fetching a SECOND
+        one doubled this endpoint's daemon I/O per client poll, which is
+        exactly the per-request amplification #3023 exists to eliminate
+        (just at a smaller scale than the fan-out it replaced). A thin
+        client reads the daemon-published payload's
+        ``fleet_health.machine_health`` sibling key — the tick-refreshed
+        output of ``coord.health.fleet_snapshot.FleetHealthRefresher``
+        (#1630) a board poll already carries — never a fresh per-request
+        probe of the fleet. A dashboard co-located with the daemon (no
+        ``board_service``) has no network cost to share in the first place:
+        it reads the board from the local DB and the health rows straight
+        out of the same local DB via ``coord.state.load_machine_health`` +
+        ``coord.health.fleet_snapshot.machine_health_rows`` (the public
+        wrapper ``FleetHealthRefresher.refresh()`` itself calls right after
+        persisting) — so the two modes can't drift.
+
+        A machine absent from the health dict was never polled (fresh
+        install, or nothing has ticked the health refresher yet) — callers
+        must treat that the same as an ``unknown`` state, never as healthy
+        (#1485's failure mode).
+        """
+        from coord import board_service  # noqa: PLC0415
+
+        svc = board_service.resolve()
+        if svc is not None:
+            from coord.client import board_from_payload, fetch_board_payload  # noqa: PLC0415
+
+            payload = fetch_board_payload(svc)
+            board = board_from_payload(payload)
+            rows = (payload.get("fleet_health") or {}).get("machine_health") or []
+            return board, {row["machine"]: row for row in rows}
+
+        from coord.health.fleet_snapshot import machine_health_rows  # noqa: PLC0415
+        from coord.state import load_machine_health  # noqa: PLC0415
+
+        board = _read_board()
+        raw = load_machine_health()
+        machine_names = [m.name for m in config.machines]
+        rows = machine_health_rows(machine_names, raw, now=time.time())
+        return board, {row["machine"]: row for row in rows}
+
+    def _active_assignments_by_machine(board) -> dict[str, list[dict]]:  # noqa: ANN001
+        """Group *board*'s RUNNING active assignments by machine (#3023).
+
+        Backs the legacy dashboard's per-machine "busy" card
+        (``coord/dashboard/index.html``'s ``loadMachines()``), which used
+        to come from a live per-agent ``GET /status`` probe. The board
+        already carries the same fact — which issue a machine is currently
+        running — from the normal board read path, so grouping it here
+        costs no extra daemon I/O beyond what ``_read_board_and_machine_health()``
+        already fetches.
+
+        Filters to ``status == "running"`` exactly like
+        ``Board.idle_machines()`` and ``Board.active_files_by_repo()`` in
+        ``coord/models.py`` do before treating an active-list entry as real,
+        in-progress work — an unfiltered read of ``board.active`` would be a
+        second, independent answer to "is this machine busy" that could
+        diverge from those two (epic #2096 "one question, one answer").
+        Every ``board.active.append()`` call site happens to set
+        ``status="running"`` at append time today, and reconcile removes
+        non-running entries the same tick it retags them, so this filter is
+        currently a no-op in practice — which is exactly why the existing
+        code defends against it twice already rather than trusting that
+        invariant to hold forever.
+        """
+        out: dict[str, list[dict]] = {}
+        for a in board.active:
+            if a.status != "running":
+                continue
+            out.setdefault(a.machine_name, []).append({
+                "assignment_id": a.assignment_id,
+                "status": a.status,
+                "spec": {
+                    "issue_number": a.issue_number,
+                    "issue_title": a.issue_title,
+                    "repo_name": a.repo_name,
+                },
+            })
+        return out
+
     def _read_drive_queue() -> list[dict]:
         """Every drive-queue row — seeded fixture or the daemon/local DB (#2428).
 
@@ -1350,27 +1437,61 @@ def build_app(
         })
 
     async def api_machines(request: Request) -> JSONResponse:
+        """GET /api/machines — the fleet panel, from daemon-refreshed state (#3023).
+
+        Used to do a synchronous fan-out probe on every request: ``GET
+        /health`` against every configured machine, then ``GET /status``
+        against every one that answered — seconds of worst-case latency,
+        multiplied by every connected client polling this panel live. Now
+        serves the SAME state the board daemon's tick loop already
+        refreshes on its own cadence, plus the board this dashboard reads
+        for every other panel anyway, both from ONE combined read
+        (``_read_board_and_machine_health()``) — zero per-request network
+        fan-out to the fleet, whether this dashboard is co-located with the
+        daemon or a thin client of it.
+
+        Design decision (#3023 review): each active assignment's ``spec``
+        (issue/repo) is included, but the live ``STATUS:``/``STUCK:``
+        per-worker progress tail (``a.progress.updates`` / ``a.progress.stuck``
+        in the pre-#3023 shape) is NOT. That data only ever existed as a
+        fresh tail-read of the OWNING machine's own log file — see
+        ``AgentServer.progress()``/``list_assignments()`` in ``coord/agent.py``
+        ("only this machine can see its own log file — the coordinator
+        cannot stat a remote path") — so serving it here would mean putting
+        the exact per-request fan-out probe this endpoint exists to remove
+        right back in, just hidden one level down. ``coord/dashboard/index.html``
+        no longer reads those two keys; live per-worker progress is still
+        available via ``coord status`` / ``coord log <id> -f``, which DO pay
+        for a targeted probe of the one machine in question rather than
+        every machine on every dashboard poll.
+        """
         if _fixture is not None:
             # Seeded reachability — never probe the fleet in fixture mode.
             return JSONResponse(_fixture.machines())
-        statuses = check_all(config.machines, timeout=3.0)
+        board, health_by_name = _read_board_and_machine_health()
+        assignments_by_machine = _active_assignments_by_machine(board)
         result = []
-        for s in statuses:
+        for m in config.machines:
+            row = health_by_name.get(m.name) or {}
             machine_data = {
-                "name": s.machine.name,
-                "host": s.machine.host,
-                "repos": s.machine.repos,
-                "state": s.state,
-                "reason": s.reason,
-                "latency_ms": s.latency_ms,
+                "name": m.name,
+                "host": m.host,
+                "repos": m.repos,
+                "state": row.get("state", "unknown"),
+                "reason": row.get("reason", ""),
+                "latency_ms": row.get("latency_ms"),
+                # #3023: agent's own running version — compared against
+                # this coordinator's local version by consumers (coord-tui's
+                # `machine_detail_list` shows it red on a mismatch) — and
+                # total on-disk size of this agent's git worktrees. Both
+                # ride the same tick-refreshed health blob as everything
+                # else here; see `coord.health.fleet_snapshot.refresh`.
+                "agent_version": row.get("agent_runtime_version"),
+                "worktree_bytes": row.get("worktree_bytes"),
             }
-            if s.is_online:
-                status_result = fetch_status(s.machine, timeout=3.0)
-                if status_result.ok:
-                    machine_data["assignments"] = status_result.data
-                else:
-                    machine_data["assignments"] = None
-                    machine_data["status_error"] = status_result.error
+            active = assignments_by_machine.get(m.name)
+            if active:
+                machine_data["assignments"] = {"active": active}
             result.append(machine_data)
         return JSONResponse(result)
 

coord/health/fleet_snapshot.py

@@ -209,6 +209,19 @@ def _effective_severity(entry: dict, *, now: float) -> tuple[str, bool]:
     return (severity or "unknown"), stale
 
 
+def machine_health_rows(machine_names: list[str], raw: dict, *, now: float) -> list[dict]:
+    """Public wrapper around :func:`_machine_health_rows` (#3023).
+
+    ``coord.dashboard.server`` reads this from outside the module (the
+    local-mode half of ``GET /api/machines``, mirroring the thin-client half
+    that reads the daemon-published ``fleet_health.machine_health`` block
+    ``FleetHealthRefresher.refresh()`` builds from this same function) —
+    exposed as a real entry point instead of reaching across the module
+    boundary for the underscore-prefixed helper below.
+    """
+    return _machine_health_rows(machine_names, raw, now=now)
+
+
 def _machine_health_rows(machine_names: list[str], raw: dict, *, now: float) -> list[dict]:
     rows: list[dict] = []
     for name in machine_names:
@@ -234,6 +247,11 @@ def _machine_health_rows(machine_names: list[str], raw: dict, *, now: float) ->
                 "severity": severity,
                 "checked_at": checks.get("checked_at"),
                 "results": checks.get("results", []),
+                # #3023: sibling facts `refresh()` stashes on the same
+                # persisted `health` blob — see its docstring comment for
+                # why they live here instead of inside `results`.
+                "worktree_bytes": checks.get("worktree_bytes"),
+                "agent_runtime_version": checks.get("agent_runtime_version"),
             }
         )
     return rows
@@ -310,6 +328,36 @@ class FleetHealthRefresher:
             health_block = (
                 status.health.get("health") if status.health else None
             ) or last_known_health
+            # #3023: the coord-web Machines panel (GET /api/machines) needs
+            # two more whole-payload facts that live OUTSIDE the H-1
+            # check-registry block above — the agent's own running
+            # `version` (compared against the coordinator's local version to
+            # flag skew) and `worktree_bytes` (total on-disk size of this
+            # agent's git worktrees). Both are real facts about the agent
+            # PROCESS, not a health check result, so they ride as sibling
+            # keys on the same persisted `health` blob rather than a schema
+            # change — advisory only, same as everything else in this
+            # module (see the module docstring). Freshly measured whenever
+            # this poll actually reached the agent; carried forward from the
+            # last successful poll otherwise, same "last-known, not
+            # blanked" posture as the H-1 `results` above, so a machine
+            # that's merely offline for one tick doesn't flash to "no data"
+            # in the panel. Named `agent_runtime_version` (not
+            # `agent_version`) to avoid colliding with the unrelated
+            # `agent_version` H-1 *check* already inside `results`, which
+            # measures installed-vs-latest-on-PyPI skew, not this.
+            if status.health is not None:
+                worktree_bytes = status.health.get("worktree_bytes")
+                agent_runtime_version = status.health.get("version")
+            else:
+                worktree_bytes = (last_known_health or {}).get("worktree_bytes")
+                agent_runtime_version = (last_known_health or {}).get("agent_runtime_version")
+            if health_block is not None:
+                health_block = {
+                    **health_block,
+                    "worktree_bytes": worktree_bytes,
+                    "agent_runtime_version": agent_runtime_version,
+                }
             state.save_machine_health(
                 machine.name,
                 state=status.state,

coord/machine_metrics.py

@@ -48,10 +48,12 @@ for exactly this reason) are not this module's job.
 from __future__ import annotations
 
 import logging
+import re
 import time
 from collections import deque
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass
+from datetime import datetime
 
 import httpx
 
@@ -215,3 +217,174 @@ class MachineMetricsSampler:
         except Exception as exc:  # noqa: BLE001 — one bad machine must never abort the refresh
             log.warning("machine-metrics poll: %s raised %s", machine.name, exc)
             return _unknown(f"poll raised: {exc}")
+
+
+# ── read path: GET /machines/metrics (#3021) ────────────────────────────────
+#
+# Everything below is pure — no I/O, no dependence on the sampler's internal
+# deques beyond the plain ``list[dict]`` returned by ``series()``/
+# ``all_series()``. That keeps it trivially unit-testable and reusable from
+# `coord.serve_app`'s request handler without either side needing to know
+# about the other's internals.
+
+_DURATION_RE = re.compile(r"^\s*(\d+(?:\.\d+)?)\s*([smhdw])\s*$", re.IGNORECASE)
+_UNIT_SECONDS = {"s": 1.0, "m": 60.0, "h": 3600.0, "d": 86400.0, "w": 604800.0}
+
+
+def resolve_since(raw: str | None, *, now: float | None = None) -> float | None:
+    """Resolve a ``?since=`` query value to an absolute epoch timestamp.
+
+    Accepts three forms (mirrors the vocabulary the issue asks for,
+    ``<epoch|duration>``, plus ISO-8601 for parity with ``coord audit``'s
+    ``since``/``until``):
+
+    - ``None`` or ``""`` → ``None``, meaning "no lower bound" (the full
+      retained window — the endpoint's documented default).
+    - A duration like ``"6h"``, ``"90m"``, ``"3d"`` (units: s, m, h, d, w) →
+      ``now - duration``.
+    - An epoch number (``"1699999999"``) or an ISO-8601 timestamp
+      (``"2026-01-01T00:00:00Z"``) → that instant, verbatim.
+
+    Raises :class:`ValueError` on anything else, so the HTTP handler can
+    turn it into a 400 with the bad value quoted back.
+    """
+    if raw is None or raw == "":
+        return None
+    now = now if now is not None else time.time()
+    match = _DURATION_RE.match(raw)
+    if match:
+        return now - float(match.group(1)) * _UNIT_SECONDS[match.group(2).lower()]
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        pass
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00")).timestamp()
+    except ValueError as exc:
+        raise ValueError(
+            f"not an epoch number, ISO-8601 timestamp, or duration: {raw!r} "
+            "(duration units: s, m, h, d, w)"
+        ) from exc
+
+
+def _filter_since(samples: list[dict], since: float | None) -> list[dict]:
+    if since is None:
+        return list(samples)
+    return [s for s in samples if s["timestamp"] >= since]
+
+
+def _sample_intensity(sample: dict) -> float:
+    """How "interesting" a sample is for peak-preserving downsampling.
+
+    An ``unknown`` sample never outranks a real one — it always scores
+    below every possible real reading (percentages are 0-100) — so a bucket
+    with even one real sample surfaces that reading rather than the gap.
+    """
+    if sample.get("status") != STATUS_OK:
+        return -1.0
+    cpu = sample.get("cpu_percent") or 0.0
+    mem = sample.get("mem_percent") or 0.0
+    return max(cpu, mem)
+
+
+def _pick_representative(bucket: list[dict]) -> dict:
+    """The single sample that best represents ``bucket``.
+
+    Picks the highest-intensity real sample in the bucket (see
+    :func:`_sample_intensity`) so a brief spike survives downsampling
+    instead of being averaged away or dropped by naive striding. A bucket
+    with no real samples at all — every poll in that span came back
+    ``unknown`` — reports its first ``unknown`` sample, so a renderer still
+    sees the gap rather than the bucket silently vanishing.
+    """
+    best = bucket[0]
+    best_score = _sample_intensity(best)
+    for sample in bucket[1:]:
+        score = _sample_intensity(sample)
+        if score > best_score:
+            best, best_score = sample, score
+    return best
+
+
+def downsample(samples: list[dict], resolution: int) -> list[dict]:
+    """Reduce ``samples`` (oldest-first) to at most ``resolution`` points.
+
+    A 6h window at the default ~15s cadence is ~1440 points per machine; a
+    phone asking for ``resolution=100`` must get **at most** 100 back, and
+    the server must do the reduction — never ship the raw buffer and let
+    the client thin it (the whole point of #3021).
+
+    Buckets ``samples`` into ``resolution`` roughly-equal, chronologically
+    contiguous spans and keeps one representative per bucket (see
+    :func:`_pick_representative`) — naive fixed-stride sampling (every Nth
+    point) would silently skip over a spike that lands on a dropped index;
+    this always surfaces the bucket's peak instead.
+
+    Raises :class:`ValueError` if ``resolution`` is not positive.
+    """
+    if resolution <= 0:
+        raise ValueError("resolution must be positive")
+    n = len(samples)
+    if n <= resolution:
+        return list(samples)
+    out: list[dict] = []
+    for i in range(resolution):
+        lo = (i * n) // resolution
+        hi = ((i + 1) * n) // resolution
+        bucket = samples[lo:hi]
+        if bucket:
+            out.append(_pick_representative(bucket))
+    return out
+
+
+def build_metrics_response(
+    series_by_machine: dict[str, list[dict]],
+    *,
+    machine: str | None = None,
+    since: float | None = None,
+    resolution: int | None = None,
+    now: float | None = None,
+) -> dict:
+    """Assemble the versioned ``GET /machines/metrics`` response body.
+
+    ``series_by_machine`` is exactly :meth:`MachineMetricsSampler.all_series`'s
+    shape (name → oldest-first list of :meth:`MetricsSample.to_dict`), kept
+    as a plain argument rather than the sampler itself so this stays a pure
+    function a test can call with a synthetic dict.
+
+    - ``machine`` narrows to a single machine's series; a name with no
+      buffer yet (never polled, or simply unknown) comes back as ``[]``,
+      same as :meth:`MachineMetricsSampler.series` — never a 404, since "no
+      data yet" and "no such machine" are indistinguishable from here and
+      both mean the same thing to a renderer: nothing to draw.
+    - ``since`` filters to samples at or after that epoch timestamp
+      (:func:`resolve_since` turns the query string into this).
+    - ``resolution`` server-side downsamples each machine's filtered series
+      independently (:func:`downsample`); omitted means the full filtered
+      series.
+
+    ``schema: 1`` — versioned explicitly, matching
+    ``FleetHealthSnapshot.to_dict()``'s posture, so a client can detect a
+    future incompatible reshape rather than guess from field presence.
+    """
+    now = now if now is not None else time.time()
+    selected = (
+        {machine: series_by_machine.get(machine, [])}
+        if machine is not None
+        else series_by_machine
+    )
+
+    machines_out: dict[str, list[dict]] = {}
+    for name, series in selected.items():
+        windowed = _filter_since(series, since)
+        if resolution is not None:
+            windowed = downsample(windowed, resolution)
+        machines_out[name] = windowed
+
+    return {
+        "schema": 1,
+        "generated_at": now,
+        "since": since,
+        "resolution": resolution,
+        "machines": machines_out,
+    }

coord/serve_app.py

@@ -4957,6 +4957,91 @@ def openapi_spec() -> dict:
                 },
             }
         },
+        "/machines/metrics": {
+            "get": {
+                "summary": (
+                    "#3021: server-downsampled cpu/mem history from #3020's "
+                    "bounded per-machine ring buffers (~6h at ~15s cadence). "
+                    "Never ships the raw buffer for the client to thin — pass "
+                    "`resolution` and the server reduces it."
+                ),
+                "parameters": [
+                    {
+                        "name": "since",
+                        "in": "query",
+                        "schema": {"type": "string"},
+                        "description": (
+                            "epoch seconds, ISO-8601, or a duration like '6h' "
+                            "('now minus 6h'). Omitted = the full retained window."
+                        ),
+                    },
+                    {
+                        "name": "resolution",
+                        "in": "query",
+                        "schema": {"type": "integer"},
+                        "description": (
+                            "max points per machine per series in the response, "
+                            "e.g. 100. Downsampling is peak-preserving (keeps the "
+                            "highest cpu/mem reading per bucket, never naive "
+                            "striding). Omitted = full filtered series."
+                        ),
+                    },
+                    {
+                        "name": "machine",
+                        "in": "query",
+                        "schema": {"type": "string"},
+                        "description": "narrow to a single machine's series",
+                    },
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "schema": {"type": "integer", "enum": [1]},
+                                        "generated_at": {"type": "number"},
+                                        "since": {"type": ["number", "null"]},
+                                        "resolution": {"type": ["integer", "null"]},
+                                        "machines": {
+                                            "type": "object",
+                                            "description": (
+                                                "machine name -> oldest-first list "
+                                                "of samples; status=unknown carries "
+                                                "no cpu/mem values so a renderer "
+                                                "draws a gap instead of interpolating"
+                                            ),
+                                            "additionalProperties": {
+                                                "type": "array",
+                                                "items": {
+                                                    "type": "object",
+                                                    "properties": {
+                                                        "timestamp": {"type": "number"},
+                                                        "status": {
+                                                            "type": "string",
+                                                            "enum": ["ok", "unknown"],
+                                                        },
+                                                        "cpu_percent": {"type": ["number", "null"]},
+                                                        "mem_percent": {"type": ["number", "null"]},
+                                                        "mem_used_mb": {"type": ["number", "null"]},
+                                                        "mem_total_mb": {"type": ["number", "null"]},
+                                                        "reason": {"type": "string"},
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    },
+                                    "required": ["schema", "generated_at", "machines"],
+                                }
+                            }
+                        },
+                    },
+                    "400": {"description": "Bad `since` or `resolution`"},
+                },
+            }
+        },
         "/report": {
             "get": {
                 "summary": (
@@ -5304,11 +5389,23 @@ def openapi_spec() -> dict:
     )
 
 
-def build_app(store: CoordStore, config: Config, *, token: str | None = None) -> Starlette:
+def build_app(
+    store: CoordStore,
+    config: Config,
+    *,
+    token: str | None = None,
+    machine_metrics_sampler: MachineMetricsSampler | None = None,
+) -> Starlette:
     """Build the read-only control-center Starlette app bound to *store* + *config*.
 
     *token* — when set, every endpoint except ``/healthz`` requires
     ``Authorization: Bearer <token>``.
+
+    *machine_metrics_sampler* — injectable for tests (#3021): a fresh
+    :class:`~coord.machine_metrics.MachineMetricsSampler` is created when
+    omitted, exactly as before. Passing a pre-seeded instance lets a test
+    drive ``GET /machines/metrics`` against known ring-buffer contents
+    without waiting on the tick loop or a live agent poll.
     """
     # #1081: track the backing coordinator.yml's mtime so the handlers below
     # can swap in a freshly-reloaded Config when it changes on disk, instead
@@ -5343,11 +5440,12 @@ def build_app(store: CoordStore, config: Config, *, token: str | None = None) ->
     # #3020: same shape again — polling every agent's own /metrics is real
     # per-machine I/O, so it runs on the tick loop's cadence
     # (`_machine_metrics_loop` below), never inline off a request handler.
-    # Series live only in this sampler's bounded in-memory ring buffers; no
-    # read endpoint exists yet (that's #A2) and nothing here touches /board.
+    # Series live only in this sampler's bounded in-memory ring buffers;
+    # `GET /machines/metrics` (#3021, below) is the read endpoint and does
+    # bare in-memory reads only. Nothing here touches /board.
     from coord.machine_metrics import MachineMetricsSampler  # noqa: PLC0415
 
-    _machine_metrics_sampler = MachineMetricsSampler()
+    _machine_metrics_sampler = machine_metrics_sampler or MachineMetricsSampler()
 
     # Short-TTL cache for the computed /board projection so burst polls from the
     # TUI don't each pay the full board_projection + merge-plan + stage-projection
@@ -8882,6 +8980,39 @@ def build_app(store: CoordStore, config: Config, *, token: str | None = None) ->
             )
         return JSONResponse(result.to_dict())
 
+    async def get_machine_metrics(request: Request) -> Response:
+        # #3021: the read side of #3020's sampler. Bare in-memory reads +
+        # pure filtering/downsampling — no I/O, so (unlike /board) this
+        # never needs a threadpool hop and can't be slowed by a hanging
+        # agent (that's `_machine_metrics_loop`'s problem, not this
+        # handler's).
+        from coord.machine_metrics import build_metrics_response, resolve_since  # noqa: PLC0415
+
+        qp = request.query_params
+
+        resolution_raw = qp.get("resolution")
+        try:
+            resolution = int(resolution_raw) if resolution_raw else None
+            if resolution is not None and resolution <= 0:
+                raise ValueError("resolution must be a positive integer")
+        except ValueError as e:
+            return JSONResponse(
+                {"error": f"bad resolution={resolution_raw!r}: {e}"}, status_code=400
+            )
+
+        try:
+            since = resolve_since(qp.get("since"))
+        except ValueError as e:
+            return JSONResponse({"error": str(e)}, status_code=400)
+
+        result = build_metrics_response(
+            _machine_metrics_sampler.all_series(),
+            machine=qp.get("machine") or None,
+            since=since,
+            resolution=resolution,
+        )
+        return JSONResponse(result)
+
     async def post_merge(request: Request) -> Response:
         # #584: the merge queue + board live in THIS (canonical) DB, and gh is
         # authenticated here — so a thin client's `coord merge` / TUI 'Go' routes
@@ -10292,6 +10423,9 @@ def build_app(store: CoordStore, config: Config, *, token: str | None = None) ->
         # read-only, both alongside /audit because they read the same data.
         Route("/report", get_report_catalogue, methods=["GET"]),
         Route("/report/{report_id}", get_report, methods=["GET"]),
+        # #3021: read side of #3020's sampler — server-downsampled machine
+        # cpu/mem history for the coord-web Machines panel.
+        Route("/machines/metrics", get_machine_metrics, methods=["GET"]),
         Route("/config", serve_config, methods=["GET"]),
         Route("/result", post_result, methods=["POST"]),
         Route("/completion", post_completion, methods=["POST"]),