code-coordinator 0.5.46__py3-none-any.whl

coord/goal.py

@@ -0,0 +1,125 @@
+"""#978: GOAL.md → Plans-panel north-star header projection.
+
+`GOAL.md` (repo root) is the living cross-repo/cross-machine intent doc —
+`coordinator.yml` is the source of truth for *topology*, GOAL.md is the
+source of truth for *intent* (see the project's own CLAUDE.md). The coord-tui
+Plans panel pins a short read-only excerpt of it above the plan roster.
+
+**Fail-open, server-computed (mirrors `coord.plans` / #975-#976).** GOAL.md is
+a repo-root doc, not shipped in the `coord` PyPI package (`pyproject.toml`
+only packages `coord*`) — so it only exists on disk when `coord serve` is
+running from an actual git checkout of this repo (the coordinator's own dev/
+always-on host, typically an editable install). `read_goal_header()` never
+raises: any failure to locate/read/parse the file returns
+`{"available": False}`, and the coord-tui Plans panel simply renders without
+the pinned header in that case — identical to today's behaviour, no
+regression for older daemons or packaged installs.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date
+from pathlib import Path
+
+# Matches the italic "_Last updated: 2026-07-04_" line convention used at the
+# top of GOAL.md.
+_LAST_UPDATED_RE = re.compile(r"_Last updated:\s*(\d{4}-\d{2}-\d{2})_")
+
+# The "## \U0001F3AF North star" heading (or a plain "## North star" fallback)
+# — matched case-insensitively so an emoji-less rewrite still resolves.
+# Restricted to heading levels 2-6: GOAL.md's own H1 title
+# ("# Current Goal — North Star") also contains the words "north star", and a
+# level-1-inclusive match would bind here instead of the intended `## North
+# star` section below it (#978 review) — the first bold text after the H1
+# would then be the blockquote's framing sentence, not the real headline.
+_NORTH_STAR_HEADING_RE = re.compile(r"^#{2,6}[^\n]*north star[^\n]*$", re.IGNORECASE | re.MULTILINE)
+
+_BOLD_RE = re.compile(r"\*\*(.+?)\*\*")
+_H1_RE = re.compile(r"^#\s+(.+)$", re.MULTILINE)
+
+_HEADLINE_MAX_LEN = 220
+
+
+def _resolve_goal_md_path() -> Path | None:
+    """Best-effort location of this checkout's GOAL.md.
+
+    Reuses the same editable-checkout detection as `cli.py`'s
+    `_warn_if_editable_checkout_moved()`: `coord.__file__`'s grandparent
+    directory is the repo root only when running from a checkout (not a
+    `site-packages` install, which has no repo root at all). Returns `None`
+    when GOAL.md can't be resolved to an existing file.
+    """
+    try:
+        import coord as _coord  # noqa: PLC0415
+
+        coord_file = _coord.__file__ or ""
+        if "site-packages" in coord_file:
+            return None  # PyPI install — GOAL.md was never shipped with it.
+        repo_root = Path(coord_file).resolve().parents[1]
+        candidate = repo_root / "GOAL.md"
+        return candidate if candidate.is_file() else None
+    except Exception:  # noqa: BLE001 — best-effort, never raise
+        return None
+
+
+def parse_goal_header(text: str) -> dict:
+    """Pure parser: GOAL.md text -> the Plans-panel header projection.
+
+    Split out from `read_goal_header()` so tests can exercise parsing edge
+    cases (malformed/missing date, missing north-star section, ...) directly
+    against a string fixture, independent of the on-disk file-resolution
+    story above.
+    """
+    result: dict = {
+        "available": True,
+        "headline": "",
+        "last_updated": None,
+        "days_since_update": None,
+    }
+
+    m = _LAST_UPDATED_RE.search(text)
+    if m:
+        date_str = m.group(1)
+        result["last_updated"] = date_str
+        try:
+            parsed = date.fromisoformat(date_str)
+            result["days_since_update"] = (date.today() - parsed).days
+        except ValueError:
+            pass  # leave days_since_update as None — an unparseable date still surfaces as text
+
+    # Headline: first bolded sentence under the "North star" heading — falls
+    # back to the document's H1 title so a reformatted GOAL.md still surfaces
+    # *something* rather than an empty pinned header.
+    headline = ""
+    heading = _NORTH_STAR_HEADING_RE.search(text)
+    if heading:
+        bold = _BOLD_RE.search(text[heading.end():])
+        if bold:
+            headline = bold.group(1).strip()
+    if not headline:
+        h1 = _H1_RE.search(text)
+        if h1:
+            headline = h1.group(1).strip()
+    if len(headline) > _HEADLINE_MAX_LEN:
+        headline = headline[: _HEADLINE_MAX_LEN - 1].rstrip() + "…"
+    result["headline"] = headline
+    return result
+
+
+def read_goal_header() -> dict:
+    """#978: fail-open GOAL.md -> Plans-panel-header projection.
+
+    Returns `{"available": False}` when GOAL.md can't be located (packaged
+    install, no discoverable repo root, missing file) or read. Never raises —
+    called from `coord/serve_app.py`'s `board()` handler, where a failure
+    here must never blank the rest of the board payload.
+    """
+    try:
+        path = _resolve_goal_md_path()
+        if path is None:
+            return {"available": False}
+        text = path.read_text(encoding="utf-8")
+        return parse_goal_header(text)
+    except Exception:  # noqa: BLE001 — best-effort, never raise
+        return {"available": False}

coord/graph_health.py

@@ -0,0 +1,348 @@
+"""Graphify knowledge-graph freshness + worktree-bootstrap health.
+
+The repo ships a graphify graph in ``graphify-out/`` that agents are told to
+query first (see CLAUDE.md).  Two things silently break it, and neither is
+visible from the code:
+
+**1. Linked worktrees are graph-blind.**  ``graphify-out/`` is gitignored by
+design (only its ``.gitignore`` is tracked), so ``git worktree add`` produces
+an empty one — and ``graphify query`` resolves ``graphify-out/graph.json``
+strictly relative to cwd, with no upward walk and no ``--graph`` override.
+``.githooks/post-checkout`` fixes this by symlinking each entry of the base
+checkout's graph (``graph.json``, ``manifest.json``, ``cache/``, ...) into
+the worktree's ``graphify-out/`` — the directory itself, and its tracked
+``.gitignore``, are never touched (#1617: replacing the whole directory with
+a symlink deleted the tracked ``.gitignore`` out from under git).  This hook
+only runs where ``core.hooksPath`` points at ``.githooks`` — a one-time,
+per-machine ``git config`` that nothing enforces.  :func:`hooks_path_status`
+checks it.
+
+**2. The graph drifts out of sync with HEAD.**  graphify's own hooks are
+best-effort and structurally cannot cover every ref-moving operation:
+
+* ``post-commit``/``post-checkout``/``post-merge`` all ``exit 0`` during a
+  rebase, merge, or cherry-pick — so the merge agent's proactive rebase
+  (#306), the single most common ref move in the fleet, never rebuilds.
+* ``git reset --hard`` fires no rebuild hook at all; git has none.
+* Every hook failure path is ``exit 0``, and the rebuild itself is a detached
+  background process with a 600s ``SIGALRM`` timeout that logs to
+  ``~/.cache/graphify-rebuild.log`` — a timeout, an OOM, or an ENOENT from a
+  reaped worktree all fail invisibly.
+* Concurrent triggers coalesce ("Rebuild already in progress — changes
+  queued").
+* The hooks' own ``[ ! -f graphify-out/graph.json ] && exit 0`` guard is a
+  permanent off-switch: purge the graph once and they no-op forever.
+
+So the hooks are an optimization, not the correctness mechanism.  Correctness
+comes from a cheap *check*, which is possible because ``GRAPH_REPORT.md``
+records the commit it was built from::
+
+    - Built from commit: `5be69d08`
+
+:func:`graph_status` compares that to HEAD.  ``coord diagnose --graph``
+surfaces it, so drift shows up in a routine health check instead of being
+discovered by a confused agent mid-task.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+# ``- Built from commit: `5be69d08` `` in GRAPH_REPORT.md.  This is the only
+# machine-readable record of the graph's source commit — manifest.json holds
+# per-file hashes, not a commit.
+_BUILT_FROM_RE = re.compile(r"^-\s*Built from commit:\s*`([0-9a-fA-F]+)`", re.MULTILINE)
+
+# The versioned hooks directory this repo expects core.hooksPath to point at.
+HOOKS_PATH = ".githooks"
+
+
+@dataclass
+class GraphStatus:
+    """Freshness of one checkout's graphify graph."""
+
+    repo_path: Path
+    present: bool = False
+    # True when graphify-out/graph.json is a symlink — i.e. a worktree
+    # borrowing the base checkout's graph (the .githooks/post-checkout
+    # bootstrap ran).  graphify-out/ itself is always a real directory (its
+    # tracked .gitignore has to survive — see #1617); only the entries
+    # inside it are symlinked.
+    is_symlink: bool = False
+    # The base checkout's graphify-out/ directory (graph.json's resolved
+    # parent), not graph.json itself — kept as a directory path so existing
+    # "owner checkout" math (``link_target.parent``) still lands on the base
+    # checkout root.
+    link_target: Path | None = None
+    built_sha: str | None = None
+    head_sha: str | None = None
+    in_sync: bool = False
+    age_seconds: float | None = None
+    # mtime of graphify-out/manifest.json — the last time graphify *checked* the
+    # graph against the working tree, whether or not it rewrote anything.
+    verified_at: float | None = None
+    # Commit timestamp of HEAD, to compare against verified_at.
+    head_committed_at: float | None = None
+    # Set when we could not determine freshness at all (no report, no git).
+    unknown_reason: str | None = None
+
+    @property
+    def stamp_behind(self) -> bool:
+        """``GRAPH_REPORT.md``'s "Built from commit" differs from HEAD."""
+        return bool(self.present and self.built_sha and self.head_sha and not self.in_sync)
+
+    @property
+    def verified_current(self) -> bool:
+        """graphify has checked the graph against the tree since HEAD landed.
+
+        ``graphify update`` re-extracts, compares topology, and when nothing
+        changed prints "No code-graph topology changes detected; outputs left
+        untouched" — it deliberately does NOT rewrite ``graph.json`` or
+        ``GRAPH_REPORT.md``, so the "Built from commit" stamp stays at whatever
+        HEAD was the last time the content actually changed.  It *does* still
+        call ``save_manifest``, so ``manifest.json``'s mtime is the honest
+        record of "last verified".
+
+        Without this, a checkout whose graph is genuinely current but whose
+        stamp is behind would be reported STALE on every run, forever — a
+        health check that cries wolf is worse than none.
+        """
+        if self.verified_at is None or self.head_committed_at is None:
+            return False
+        return self.verified_at >= self.head_committed_at
+
+    @property
+    def stale(self) -> bool:
+        """The stamp is behind AND graphify has not verified the graph against
+        the tree since HEAD landed.  Deliberately False when freshness is
+        *unknown* — an unknown is reported separately, not counted as drift."""
+        return self.stamp_behind and not self.verified_current
+
+
+def read_built_sha(report_path: Path) -> str | None:
+    """The commit ``GRAPH_REPORT.md`` says the graph was built from."""
+    try:
+        text = report_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    m = _BUILT_FROM_RE.search(text)
+    return m.group(1) if m else None
+
+
+def _git_out(repo_path: Path, *args: str) -> str | None:
+    try:
+        r = subprocess.run(
+            ["git", *args],
+            cwd=str(repo_path),
+            capture_output=True,
+            text=True,
+            timeout=10.0,
+        )
+    except (subprocess.SubprocessError, OSError):
+        return None
+    if r.returncode != 0:
+        return None
+    return r.stdout.strip() or None
+
+
+def _head_sha(repo_path: Path) -> str | None:
+    return _git_out(repo_path, "rev-parse", "HEAD")
+
+
+def _head_committed_at(repo_path: Path) -> float | None:
+    raw = _git_out(repo_path, "log", "-1", "--format=%ct", "HEAD")
+    try:
+        return float(raw) if raw else None
+    except ValueError:
+        return None
+
+
+def _shas_agree(built: str, head: str) -> bool:
+    """Compare on the shorter of the two — the report abbreviates (8 chars by
+    default) while ``git rev-parse HEAD`` is full-length."""
+    n = min(len(built), len(head))
+    if n < 4:  # too short to be a meaningful comparison
+        return False
+    return built[:n].lower() == head[:n].lower()
+
+
+def graph_status(repo_path: Path) -> GraphStatus:
+    """Freshness of the graphify graph for the checkout at *repo_path*.
+
+    Read-only and best-effort: a missing graph, a missing report, or a repo
+    git can't read all return a populated :class:`GraphStatus` with
+    ``unknown_reason`` set rather than raising.
+    """
+    st = GraphStatus(repo_path=repo_path)
+    out_dir = repo_path / "graphify-out"
+    graph_file = out_dir / "graph.json"
+
+    # A borrowed graph symlinks graph.json (and friends) individually;
+    # graphify-out/ itself is always a real directory (#1617).
+    st.is_symlink = graph_file.is_symlink()
+    if st.is_symlink:
+        try:
+            st.link_target = graph_file.resolve().parent
+        except OSError:
+            st.link_target = None
+
+    if not graph_file.is_file():
+        st.unknown_reason = "no graphify-out/graph.json (graph never built here)"
+        return st
+    st.present = True
+
+    try:
+        st.age_seconds = max(0.0, time.time() - graph_file.stat().st_mtime)
+    except OSError:
+        st.age_seconds = None
+
+    try:
+        st.verified_at = (out_dir / "manifest.json").stat().st_mtime
+    except OSError:
+        st.verified_at = None
+
+    st.built_sha = read_built_sha(out_dir / "GRAPH_REPORT.md")
+    # Freshness is always judged against the checkout that OWNS the graph.  For
+    # a symlinked worktree that's the base checkout, not the worktree's own
+    # HEAD — the worktree is on a feature branch by definition and comparing
+    # against it would report permanent, meaningless drift.
+    owner = st.link_target.parent if (st.is_symlink and st.link_target) else repo_path
+    st.head_sha = _head_sha(owner)
+    st.head_committed_at = _head_committed_at(owner)
+
+    if not st.built_sha:
+        st.unknown_reason = "GRAPH_REPORT.md has no 'Built from commit' line"
+    elif not st.head_sha:
+        st.unknown_reason = f"could not read HEAD of {owner}"
+    else:
+        st.in_sync = _shas_agree(st.built_sha, st.head_sha)
+    return st
+
+
+def hooks_path_status(repo_path: Path) -> tuple[bool, str]:
+    """``(ok, detail)`` for this checkout's ``core.hooksPath``.
+
+    The versioned ``.githooks/post-checkout`` bootstrap only runs when
+    ``core.hooksPath`` points at it — a one-time per-machine ``git config``.
+    Without it, worktrees on this machine stay graph-blind and nothing says so.
+    """
+    try:
+        r = subprocess.run(
+            ["git", "config", "--get", "core.hooksPath"],
+            cwd=str(repo_path),
+            capture_output=True,
+            text=True,
+            timeout=10.0,
+        )
+    except (subprocess.SubprocessError, OSError) as exc:
+        return False, f"could not read core.hooksPath ({exc})"
+    value = r.stdout.strip()
+    have_hook = (repo_path / HOOKS_PATH / "post-checkout").is_file()
+    if not value:
+        if not have_hook:
+            # The repo doesn't ship the bootstrap at all — telling the operator
+            # to point core.hooksPath at a directory that isn't there would
+            # silently disable ALL hooks for that checkout.
+            return False, (
+                f"no {HOOKS_PATH}/post-checkout in this repo — worktrees here get "
+                f"no linked graph (port the hook to this repo to enable it)"
+            )
+        return False, (
+            f"core.hooksPath is unset — worktrees on this machine will NOT get "
+            f"a linked graph. Fix: git -C {repo_path} config core.hooksPath {HOOKS_PATH}"
+        )
+    if Path(value).name != Path(HOOKS_PATH).name:
+        return False, (
+            f"core.hooksPath is {value!r}, expected {HOOKS_PATH!r} — the worktree "
+            f"graph bootstrap will not run"
+        )
+    if not have_hook:
+        return False, (
+            f"core.hooksPath={value} but {HOOKS_PATH}/post-checkout is missing "
+            f"(stale checkout?)"
+        )
+    orphaned = orphaned_hooks(repo_path)
+    if orphaned:
+        return False, (
+            f"core.hooksPath={value} but {', '.join(orphaned)} exist(s) only in "
+            f".git/hooks — git no longer runs them, so those graphify rebuilds "
+            f"are SILENTLY DISABLED. Add a shim in {HOOKS_PATH}/"
+        )
+    return True, f"core.hooksPath={value}"
+
+
+def orphaned_hooks(repo_path: Path) -> list[str]:
+    """Hooks installed in the machine-local hooks dir with no counterpart in
+    :data:`HOOKS_PATH`.
+
+    Setting ``core.hooksPath`` makes git ignore ``.git/hooks`` **entirely** —
+    it does not merge or fall back.  So any hook graphify installed there
+    (``post-commit``, ``post-checkout``, ``post-merge``) that has no shim in
+    the versioned directory stops running, with no error and no log line.
+    This shipped exactly once: only ``post-checkout`` had a shim, which
+    silently killed graphify's commit- and merge-triggered rebuilds.
+
+    Returns hook names, sorted.  Empty when nothing is orphaned (including
+    when ``core.hooksPath`` isn't set — then ``.git/hooks`` is live and
+    there is nothing to orphan).
+    """
+    local_dir = _git_out(repo_path, "rev-parse", "--git-common-dir")
+    if not local_dir:
+        return []
+    common = Path(local_dir)
+    if not common.is_absolute():
+        common = repo_path / common
+    hooks_dir = common / "hooks"
+    versioned = repo_path / HOOKS_PATH
+    if not hooks_dir.is_dir() or not versioned.is_dir():
+        return []
+
+    out: list[str] = []
+    for entry in hooks_dir.iterdir():
+        name = entry.name
+        # graphify keeps .bak copies alongside; only real, executable hooks
+        # matter, and only ones git would actually invoke.
+        if name.endswith(".sample") or name.endswith(".bak") or "." in name:
+            continue
+        if not entry.is_file():
+            continue
+        if not (versioned / name).is_file():
+            out.append(name)
+    return sorted(out)
+
+
+def format_status_lines(st: GraphStatus) -> list[str]:
+    """Human-readable report lines for *st* (used by ``coord diagnose --graph``)."""
+    lines: list[str] = []
+    where = str(st.repo_path)
+    if not st.present:
+        lines.append(f"✗ {where}: {st.unknown_reason}")
+        return lines
+
+    if st.is_symlink:
+        lines.append(f"↳ {where}/graphify-out → {st.link_target} (linked worktree)")
+
+    if st.unknown_reason:
+        lines.append(f"? {where}: freshness unknown — {st.unknown_reason}")
+    elif st.in_sync:
+        lines.append(f"✓ {where}: graph in sync (built from {st.built_sha})")
+    elif st.verified_current:
+        # Stamp behind, but graphify has re-checked the tree since HEAD landed
+        # and found no topology change — the graph content is current.
+        lines.append(
+            f"✓ {where}: graph content current — stamp says {st.built_sha} "
+            f"(HEAD {(st.head_sha or '')[:8]}), but verified against the tree "
+            f"since; graphify leaves outputs untouched when topology is unchanged"
+        )
+    else:
+        lines.append(
+            f"⚠ {where}: graph is STALE — built from {st.built_sha}, "
+            f"HEAD is {(st.head_sha or '')[:8]}"
+        )
+    if st.age_seconds is not None:
+        lines.append(f"    graph.json age: {st.age_seconds / 3600.0:.1f}h")
+    return lines

coord/health/__init__.py

@@ -0,0 +1,69 @@
+"""Fleet-health check engine (#1628).
+
+Answers one question for a catalogue of fleet-degradation signals: **how much
+headroom is left?**  Runs on one machine, against that machine and the
+checkouts ``coordinator.yml`` says live on it.  No transport, no board state,
+no renderer beyond ``coord health`` — those are H-3 and H-4.
+
+The shape, in the order you'd meet it:
+
+* ``models`` — :class:`~coord.health.models.CheckResult`, which carries raw
+  values **and** the rendered headroom string.  Renderers never re-derive
+  severity from raw numbers; that rule is what keeps the logic from forking
+  once there is more than one surface.
+* ``registry`` — the ``@check`` decorator and ``run_all``.  Adding a check
+  means adding one module under ``checks/``; discovery is ``pkgutil`` over
+  that package, so nothing central needs editing.
+* ``checks/`` — the seed probes: disk, cargo targets, worktrees, agent
+  install/version, claude binary, repo branch/dirt, graph freshness, plan
+  usage.  Two of them (``graph``, ``plan_usage``) are thin wrappers over
+  ``coord.graph_health`` and ``coord.usage_limits`` rather than forks.
+* ``render`` / ``cli`` — the one surface this child ships.
+
+Every probe is cheap, read-only, and fails soft: a probe that raises becomes
+an ``unknown`` result carrying the error text, never a failed run.
+"""
+
+from coord.health.models import (
+    SCOPES,
+    CheckResult,
+    Checkout,
+    HealthContext,
+    Severity,
+    unknown_result,
+    worst,
+)
+from coord.health.registry import (
+    COST_CHEAP,
+    COST_NETWORK,
+    Check,
+    HealthReport,
+    all_checks,
+    check,
+    discover,
+    get,
+    register,
+    run_all,
+    run_check,
+)
+
+__all__ = [
+    "COST_CHEAP",
+    "COST_NETWORK",
+    "SCOPES",
+    "Check",
+    "CheckResult",
+    "Checkout",
+    "HealthContext",
+    "HealthReport",
+    "Severity",
+    "all_checks",
+    "check",
+    "discover",
+    "get",
+    "register",
+    "run_all",
+    "run_check",
+    "unknown_result",
+    "worst",
+]

coord/health/aggregate.py

@@ -0,0 +1,129 @@
+"""Fleet-wide health aggregation for the always-visible surfaces (#1631, H-4).
+
+Consumes the ``fleet_health`` block H-3 computes
+(:mod:`coord.health.fleet_snapshot`) — either straight off ``GET /board``
+(thin client) or reassembled locally from :func:`coord.state.load_machine_health`
+(host mode, no ``board_service`` configured, so there is no daemon process to
+ask for the fleet-scope checks). Every unit counted here already carries its
+own ``severity`` string, chosen by a probe upstream; this module only counts
+and picks the worst — it never looks at a check's raw ``values``.
+
+Two renderers consume :class:`FleetHealthSummary`: ``coord status``'s footer
+(:func:`render_fleet_footer`, this module) and coord-tui's status-bar
+indicator + detail overlay (``tui/src/app``, a from-scratch Rust port of the
+same counting rule — see that crate's ``fleet_health`` module for the
+mirrored logic and its own doc comment on why it can't just call this file).
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+from coord.health.models import Severity
+
+# Ascending severity order for the footer's non-OK enumeration — mirrors
+# Severity.rank, so "FLEET: WARN 2, CRIT 1" lists the worst last (#1631's
+# own example). OK is never listed here: zero non-OK units *is* "OK".
+_FOOTER_ORDER = (Severity.UNKNOWN, Severity.WARN, Severity.CRIT)
+
+
+@dataclass(frozen=True)
+class FleetHealthSummary:
+    """One aggregate verdict + per-severity counts.
+
+    One *unit* per machine (its own already-rolled-up ``severity`` — H-3's
+    ``_effective_severity``: unknown when stale/never-polled/offline, never
+    silently carried forward as green) plus one unit per fleet-scope check
+    (``fleet_checks``, each already a ``CheckResult.to_dict()``). Counting at
+    this granularity — not per individual per-machine check row — is what
+    keeps "3 machines, 8 checks each" from reading as "24 problems" when
+    really it's "1 machine is unhappy".
+    """
+
+    worst: Severity
+    counts: dict[str, int]  # "ok"/"unknown"/"warn"/"crit" -> count
+    unit_count: int  # total machines + fleet checks contributing
+
+
+def _severity_of(value: "str | None") -> Severity:
+    try:
+        return Severity(value or "unknown")
+    except ValueError:
+        return Severity.UNKNOWN
+
+
+def summarize_fleet_health(fleet_health: "dict | None") -> FleetHealthSummary:
+    """Aggregate a ``fleet_health`` block into one :class:`FleetHealthSummary`.
+
+    *fleet_health* is either the dict at ``/board``'s ``fleet_health`` key
+    (schema: ``{"machine_health": [...], "fleet_checks": [...]}``, see
+    ``coord.health.fleet_snapshot.FleetHealthSnapshot.to_dict``) or the
+    locally-assembled equivalent from :func:`local_fleet_health_block`.
+    ``None``/missing keys degrade to "no units" (``worst=OK``, all counts
+    zero) rather than raising — a daemon predating #1630 simply never sends
+    this key.
+    """
+    counts = {"ok": 0, "warn": 0, "crit": 0, "unknown": 0}
+    worst = Severity.OK
+    block = fleet_health or {}
+    machine_health = block.get("machine_health") or []
+    fleet_checks = block.get("fleet_checks") or []
+    units = [m.get("severity") for m in machine_health] + [
+        c.get("severity") for c in fleet_checks
+    ]
+    for raw in units:
+        sev = _severity_of(raw)
+        counts[sev.value] += 1
+        if sev.rank > worst.rank:
+            worst = sev
+    return FleetHealthSummary(worst=worst, counts=counts, unit_count=len(units))
+
+
+def render_fleet_footer(summary: FleetHealthSummary) -> str:
+    """``FLEET: <state>  (coord health for detail)`` — the ``coord status``
+    footer.
+
+    ``OK`` states its OK-ness rather than printing nothing (#1631's own
+    framing: silence is indistinguishable from a broken check). Always
+    returns a non-empty string — callers should always print it, never
+    conditionally skip it.
+    """
+    if summary.worst is Severity.OK:
+        state = "OK"
+    else:
+        parts = [
+            f"{sev.label} {summary.counts[sev.value]}"
+            for sev in _FOOTER_ORDER
+            if summary.counts[sev.value]
+        ]
+        state = ", ".join(parts) if parts else "OK"
+    return f"FLEET: {state}  (coord health for detail)"
+
+
+def local_fleet_health_block(machine_names: "list[str]") -> dict:
+    """Best-effort ``fleet_health``-shaped block for host mode (no
+    ``board_service`` configured — see ``coord.commands.status.status``).
+
+    Per-machine severities come straight from the local DB's
+    ``machine_health`` table (written by whichever ``coord serve`` tick loop
+    last ran on this host) via the SAME row-assembly H-3's daemon-side
+    projection uses (:func:`coord.health.fleet_snapshot._machine_health_rows`)
+    — so a machine that never reported reads ``unknown`` here exactly like it
+    does on ``/board``, not silently green.
+
+    ``fleet_checks`` is always empty on this path: those probes (board
+    latency, phantom-running rows, deploy-lane skew, …) only exist inside a
+    live ``coord serve`` process's in-memory ``FleetHealthRefresher`` — a
+    separate ``coord status`` invocation has no way to reach into that
+    process's memory, and re-running the probes here would mean duplicating
+    daemon-only, subprocess-heavy fact-gathering into a read path that must
+    stay cheap. A thin client (``board_service`` configured) gets the full
+    picture via ``GET /board`` instead.
+    """
+    from coord.health.fleet_snapshot import _machine_health_rows
+    from coord.state import load_machine_health
+
+    raw = load_machine_health()
+    rows = _machine_health_rows(machine_names, raw, now=time.time())
+    return {"machine_health": rows, "fleet_checks": []}

coord/health/checks/__init__.py

@@ -0,0 +1,13 @@
+"""Seed health checks (#1628).
+
+**This file imports nothing on purpose.**  ``coord.health.registry.discover``
+walks this package with :func:`pkgutil.iter_modules` and imports every module
+it finds, so a new check is installed by dropping ``coord/health/checks/
+<name>.py`` here and decorating its probe with ``@check(...)`` — no edit to
+this ``__init__``, no edit to a renderer, no edit to the CLI.
+
+``tests/test_health_registry.py::test_adding_a_check_touches_only_its_own_module``
+enforces that: it writes a throwaway module into this directory, asserts it
+shows up in the report and the JSON, and asserts the renderer/CLI/registry
+files are byte-identical before and after.
+"""