code-coordinator 0.5.46__py3-none-any.whl

coord/health/checks/graph.py

@@ -0,0 +1,192 @@
+"""graphify graph freshness per checkout (#1628).
+
+**This is a wrapper, not a reimplementation.**  ``coord.graph_health``
+already knows how to answer both halves — :func:`~coord.graph_health.graph_status`
+compares ``GRAPH_REPORT.md``'s "Built from commit" against HEAD (with the
+``manifest.json``-mtime escape hatch that stops a genuinely-current graph
+from reporting STALE forever), and
+:func:`~coord.graph_health.hooks_path_status` checks the ``core.hooksPath``
+setting that decides whether anything will ever rebuild it.  ``coord
+diagnose --graph`` renders them today.  Forking either would guarantee the
+two surfaces drift apart, which is the exact failure this milestone's
+"renderers must never re-derive severity" rule exists to prevent — so this
+module calls them and maps their output to a severity.
+
+**Why hooks-disabled makes a stale graph CRIT rather than WARN.**  A stale
+graph with working hooks is a nuisance: the next commit rebuilds it.  A
+stale graph on a checkout with ``core.hooksPath`` unset (or with hooks
+orphaned into ``.git/hooks``, which git ignores entirely once
+``core.hooksPath`` is set) **will not self-heal at any point in the future**
+— it stays wrong until a human runs ``graphify update`` by hand, and every
+agent that queries it in the meantime gets answers about a commit that is no
+longer HEAD.  That is the 2026-07-30 vimcode incident: 128.8h stale, hooks
+disabled, and nothing in the fleet said so.  Age escalates a
+hooks-working checkout from WARN to CRIT at ``graph_stale_crit_hours``;
+hooks-disabled skips straight to CRIT because time cannot fix it.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+from coord.health.models import CheckResult, HealthContext, Severity
+from coord.health.registry import check
+from coord.health.units import human_hours
+
+
+def _commits_behind(repo_path: str, built_sha: str, head_sha: str) -> int | None:
+    """How many commits separate ``built_sha`` from ``head_sha``.
+
+    Purely informational — an operator (and #1728's H-6 successor, deciding
+    how urgently to rebuild) reads better from "13 commits behind" than from
+    an age in hours, which conflates "how stale" with "how busy was the
+    repo". This does NOT feed severity: :func:`~coord.graph_health.graph_status`
+    already decided ``stale`` from the SHA comparison plus the
+    manifest-mtime escape hatch, and duplicating that decision here from a
+    commit count would be exactly the second copy this module's docstring
+    warns against. Best-effort: returns ``None`` (never raises) when the
+    shas are abbreviated past what git can resolve, the repo can't be read,
+    or the call times out.
+    """
+    try:
+        r = subprocess.run(
+            ["git", "-C", str(repo_path), "rev-list", "--count", f"{built_sha}..{head_sha}"],
+            capture_output=True,
+            text=True,
+            timeout=10.0,
+        )
+    except (subprocess.SubprocessError, OSError):
+        return None
+    if r.returncode != 0:
+        return None
+    try:
+        return int(r.stdout.strip())
+    except ValueError:
+        return None
+
+
+@check(
+    id="graph",
+    scope="checkout",
+    title="graph",
+    order=70,
+    description="graphify graph freshness vs HEAD, and whether hooks can heal it.",
+)
+def probe_graph(ctx: HealthContext) -> list[CheckResult]:
+    from coord.graph_health import graph_status, hooks_path_status  # noqa: PLC0415
+
+    th = ctx.thresholds
+    results: list[CheckResult] = []
+
+    for checkout in ctx.checkouts:
+        status = graph_status(checkout.path)
+        hooks_ok, hooks_detail = hooks_path_status(checkout.path)
+
+        values = {
+            "path": str(checkout.path),
+            "present": status.present,
+            "in_sync": status.in_sync,
+            "stale": status.stale,
+            "stamp_behind": status.stamp_behind,
+            "verified_current": status.verified_current,
+            "built_sha": status.built_sha,
+            "head_sha": status.head_sha,
+            "age_seconds": status.age_seconds,
+            "age_hours": (
+                round(status.age_seconds / 3600.0, 1) if status.age_seconds is not None else None
+            ),
+            "is_symlink": status.is_symlink,
+            "hooks_ok": hooks_ok,
+            "hooks_detail": hooks_detail,
+            "unknown_reason": status.unknown_reason,
+            "warn_hours": th.graph_stale_warn_hours,
+            "crit_hours": th.graph_stale_crit_hours,
+        }
+
+        if not status.present:
+            # No graph at all.  Agents are told to query it first (CLAUDE.md),
+            # so its absence silently downgrades every one of them to grep.
+            results.append(
+                CheckResult(
+                    check_id="graph",
+                    scope="checkout",
+                    subject=checkout.name,
+                    severity=Severity.WARN,
+                    headroom="no graph built here",
+                    detail=status.unknown_reason or "",
+                    threshold="warn when absent",
+                    values=values,
+                )
+            )
+            continue
+
+        if status.unknown_reason and not status.stamp_behind:
+            results.append(
+                CheckResult(
+                    check_id="graph",
+                    scope="checkout",
+                    subject=checkout.name,
+                    severity=Severity.UNKNOWN,
+                    headroom=f"freshness unknown — {status.unknown_reason}",
+                    error=status.unknown_reason,
+                    values=values,
+                )
+            )
+            continue
+
+        age_hours = (status.age_seconds or 0.0) / 3600.0
+        age_text = human_hours(status.age_seconds) if status.age_seconds is not None else "?h"
+
+        # #1728: how many commits separate the stamp from HEAD.  Purely
+        # additive to the message — severity above is still `status.stale`
+        # (SHA comparison + the manifest-mtime escape hatch), never this
+        # count, so a repo that made 1 commit vs. 100 since the graph was
+        # built is still judged identically on "is it stale", only described
+        # differently.
+        commits_behind: int | None = None
+        if status.stale and status.built_sha and status.head_sha:
+            commits_behind = _commits_behind(checkout.path, status.built_sha, status.head_sha)
+        values["commits_behind"] = commits_behind
+        commits_suffix = (
+            ""
+            if commits_behind is None
+            else f", {commits_behind} commit{'' if commits_behind == 1 else 's'} behind"
+        )
+
+        if not status.stale:
+            severity = Severity.OK
+            headroom = f"in sync ({(status.built_sha or '')[:8]}), {age_text} old"
+            if status.verified_current and status.stamp_behind:
+                headroom = f"content current (stamp {(status.built_sha or '')[:8]}), {age_text} old"
+        elif not hooks_ok:
+            severity = Severity.CRIT
+            headroom = f"{age_text} stale{commits_suffix}, hooks disabled -> will not self-heal"
+        elif age_hours >= th.graph_stale_crit_hours:
+            severity = Severity.CRIT
+            headroom = f"{age_text} stale{commits_suffix} (HEAD {(status.head_sha or '')[:8]})"
+        elif age_hours >= th.graph_stale_warn_hours:
+            severity = Severity.WARN
+            headroom = f"{age_text} stale{commits_suffix} (HEAD {(status.head_sha or '')[:8]})"
+        else:
+            severity = Severity.WARN
+            headroom = f"stale, {age_text} old{commits_suffix} (HEAD {(status.head_sha or '')[:8]})"
+
+        detail = ""
+        if severity is not Severity.OK:
+            detail = f"fix: graphify update {checkout.path}"
+            if not hooks_ok:
+                detail = f"{detail}  —  {hooks_detail}"
+
+        results.append(
+            CheckResult(
+                check_id="graph",
+                scope="checkout",
+                subject=checkout.name,
+                severity=severity,
+                headroom=headroom,
+                detail=detail,
+                threshold=f"crit at {th.graph_stale_crit_hours:.0f}h (or any age with hooks off)",
+                values=values,
+            )
+        )
+    return results

coord/health/checks/plan_usage.py

@@ -0,0 +1,88 @@
+"""Max-plan 5h/weekly window headroom (#1628).
+
+Another wrapper, not a rewrite: ``coord.usage_limits`` already probes this
+(``claude -p "/usage" --output-format json``, ~700ms, $0, 0 turns) and
+already caches it for 60s because the endpoint is itself rate-limited and
+Claude Code serves the bars up to an hour stale anyway.  Going through
+:func:`~coord.usage_limits.get_plan_limits` means a ``coord health`` run
+next to a ``coord drive`` preflight shares one probe rather than racing it
+into that rate limit.
+
+Marked ``cost="network"``: it shells out to ``claude`` and hits Anthropic's
+API, so it is excluded from the cheap set that has to fit the ~2s registry
+budget, and ``coord health --no-network`` skips it entirely (recording that
+it was skipped — "we didn't look" must never render as "nothing wrong").
+
+A probe that returns ``status="unknown"`` — no OAuth subscription, an API
+key / Bedrock / Vertex auth mode where the windows simply don't apply, a
+timeout — reports UNKNOWN, never OK.  Same rule as the dispatch gate: a read
+we can't trust is not a clean bill of health.
+"""
+
+from __future__ import annotations
+
+from coord.health.models import CheckResult, HealthContext, Severity
+from coord.health.registry import COST_NETWORK, check
+
+
+@check(
+    id="plan_usage",
+    scope="machine",
+    title="plan usage",
+    order=80,
+    cost=COST_NETWORK,
+    description="Headroom left in the account's Max-plan 5h/weekly windows.",
+)
+def probe_plan_usage(ctx: HealthContext) -> CheckResult:
+    from coord.usage_limits import get_plan_limits  # noqa: PLC0415
+
+    th = ctx.thresholds
+    limits = get_plan_limits()
+
+    if not limits.ok:
+        return CheckResult(
+            check_id="plan_usage",
+            scope="machine",
+            severity=Severity.UNKNOWN,
+            headroom="plan windows unavailable (no subscription probe)",
+            error=limits.error or "probe returned unknown",
+            values=limits.to_dict(),
+        )
+
+    windows: list[tuple[str, float, str | None]] = []
+    if limits.session_pct is not None:
+        windows.append(("session", limits.session_pct, limits.session_resets_at))
+    if limits.week_pct is not None:
+        windows.append(("week", limits.week_pct, limits.week_resets_at))
+
+    peak = max((pct for _, pct, _ in windows), default=0.0)
+    if peak >= th.plan_usage_crit_pct:
+        severity = Severity.CRIT
+    elif peak >= th.plan_usage_warn_pct:
+        severity = Severity.WARN
+    else:
+        severity = Severity.OK
+
+    parts = []
+    for label, pct, resets in windows:
+        reset_note = f" resets {resets}" if resets else ""
+        parts.append(f"{label} {pct:.0f}% used{reset_note}")
+    headroom = "; ".join(parts) or "no windows reported"
+
+    values = limits.to_dict()
+    values.update(
+        {
+            "peak_pct": peak,
+            "warn_pct": th.plan_usage_warn_pct,
+            "crit_pct": th.plan_usage_crit_pct,
+        }
+    )
+
+    return CheckResult(
+        check_id="plan_usage",
+        scope="machine",
+        severity=severity,
+        headroom=headroom,
+        threshold=f"crit at {th.plan_usage_crit_pct:.0f}%",
+        values=values,
+    )

coord/health/checks/repo_state.py

@@ -0,0 +1,161 @@
+"""Per-checkout git hygiene: parked branch, uncommitted changes (#1628).
+
+Both of these are the #561/#601 failure mode.  A Build, a ``coord test``, or
+an interactive agent inspecting a branch does ``git checkout`` in the *live*
+base checkout and doesn't restore it.  From then on the machine builds,
+tests, and (if it's the editable checkout) *runs the coordinator itself*
+from that branch's code, silently — #561 disabled guards that way, #601 ran
+old code against a retired local DB.  ``coord/cli.py`` already shouts about
+this for the editable checkout on every command; this generalises it to
+every checkout in ``coordinator.yml`` and puts it in the same report as the
+rest of the fleet's headroom.
+
+Uncommitted changes in a base checkout are the sibling signal: the merge
+agent rebases and force-pushes in there, and a dirty tree makes that fail in
+ways that read as a coordinator bug.  Both are WARN, never CRIT — they are
+recoverable in one command and a human is often *deliberately* mid-edit.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from coord.health.models import CheckResult, HealthContext, Severity
+from coord.health.registry import check
+
+_GIT_TIMEOUT = 5.0
+
+
+def _git(repo: Path, *args: str) -> tuple[int, str]:
+    """``(returncode, stdout)`` — never raises for the ordinary failures.
+
+    stdout is returned **unstripped**: ``git status --porcelain`` encodes the
+    index/worktree state in the first two columns, so ``" M path"`` and
+    ``"M  path"`` mean different things and a ``.strip()`` here silently ate
+    the leading space (and with it one character of every path).
+    """
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo), *args],
+            capture_output=True,
+            text=True,
+            timeout=_GIT_TIMEOUT,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return 1, f"{type(exc).__name__}: {exc}"
+    return result.returncode, result.stdout
+
+
+@check(
+    id="repo_branch",
+    scope="checkout",
+    title="branch",
+    order=60,
+    description="Base checkouts are on their default (or configured develop) branch.",
+)
+def probe_repo_branch(ctx: HealthContext) -> list[CheckResult]:
+    results: list[CheckResult] = []
+    for checkout in ctx.checkouts:
+        code, raw = _git(checkout.path, "rev-parse", "--abbrev-ref", "HEAD")
+        branch = raw.strip()
+        if code != 0:
+            results.append(
+                CheckResult(
+                    check_id="repo_branch",
+                    scope="checkout",
+                    subject=checkout.name,
+                    severity=Severity.UNKNOWN,
+                    headroom="could not read HEAD",
+                    error=branch,
+                    values={"path": str(checkout.path)},
+                )
+            )
+            continue
+
+        home = checkout.home_branches
+        detached = branch == "HEAD"
+        parked = detached or branch not in home
+        results.append(
+            CheckResult(
+                check_id="repo_branch",
+                scope="checkout",
+                subject=checkout.name,
+                severity=Severity.WARN if parked else Severity.OK,
+                headroom=("detached HEAD" if detached else branch)
+                + (f" (expected {home[0]})" if parked else ""),
+                threshold="warn when off the default branch",
+                detail=(
+                    f"restore with: git -C {checkout.path} checkout {home[0]}"
+                    if parked
+                    else ""
+                ),
+                values={
+                    "path": str(checkout.path),
+                    "branch": branch,
+                    "expected": list(home),
+                    "detached": detached,
+                    "parked": parked,
+                },
+            )
+        )
+    return results
+
+
+@check(
+    id="repo_dirty",
+    scope="checkout",
+    title="worktree clean",
+    order=61,
+    description="Base checkouts have no uncommitted changes.",
+)
+def probe_repo_dirty(ctx: HealthContext) -> list[CheckResult]:
+    results: list[CheckResult] = []
+    for checkout in ctx.checkouts:
+        # --porcelain is the stable machine format; --untracked-files=normal
+        # (the default) counts a stray build artifact as dirty, which is the
+        # behaviour we want — the merge agent's force-push trips on those too.
+        code, out = _git(checkout.path, "status", "--porcelain")
+        if code != 0:
+            results.append(
+                CheckResult(
+                    check_id="repo_dirty",
+                    scope="checkout",
+                    subject=checkout.name,
+                    severity=Severity.UNKNOWN,
+                    headroom="could not read git status",
+                    error=out,
+                    values={"path": str(checkout.path)},
+                )
+            )
+            continue
+
+        lines = [line for line in out.splitlines() if line.strip()]
+        count = len(lines)
+        if count:
+            plural = "s" if count != 1 else ""
+            # Porcelain v1: two status columns, a space, then the path.
+            sample = ", ".join(line[3:].strip() for line in lines[:3])
+            if count > 3:
+                sample += ", …"
+            headroom = f"{count} uncommitted change{plural}"
+            if sample:
+                headroom = f"{headroom} ({sample})"
+        else:
+            headroom = "clean"
+        results.append(
+            CheckResult(
+                check_id="repo_dirty",
+                scope="checkout",
+                subject=checkout.name,
+                severity=Severity.WARN if count else Severity.OK,
+                headroom=headroom,
+                threshold="warn when dirty",
+                values={
+                    "path": str(checkout.path),
+                    "dirty_count": count,
+                    "entries": lines[:20],
+                },
+            )
+        )
+    return results