code-coordinator 0.5.46__py3-none-any.whl

coord/health/checks/agent_install.py

@@ -0,0 +1,280 @@
+"""How the agent's ``claude-coordinator`` is installed, and how current (#1628).
+
+Two checks, one shared ``pip show`` call:
+
+``agent_venv``
+    The agent venv must be a **PyPI install**, not an editable one.  An
+    editable agent runs whatever is checked out in someone's source tree —
+    including a half-finished feature branch — which makes the machine's
+    behaviour untraceable to any release.  #1182 is the recorded version of
+    this going wrong (a stale non-editable install silently evaluating
+    retired logic and producing a false merge-gate block); an *editable*
+    agent is the same failure with no version number to blame it on.
+
+``agent_version``
+    How many released versions the install is behind.  The comparison is
+    against **PyPI's simple index**, not the JSON API — see
+    ``coord.health.pypi`` for why that distinction is load-bearing rather
+    than pedantic.
+
+Editable detection uses the ``Editable project location:`` line ``pip show``
+prints only for editable installs; a PyPI install has just ``Location:``
+pointing into site-packages.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from coord.dist_name import CANDIDATE_NAMES
+from coord.health.models import CheckResult, HealthContext, Severity
+from coord.health.registry import COST_NETWORK, check
+from coord.health.units import expand, shorten_path
+
+#: #2103: kept only for messages that need "a name" rather than "the
+#: installed name" (e.g. the ``description=`` strings below, which are
+#: static and evaluated before any probe runs). Everything that actually
+#: probes the venv tries every name in :data:`CANDIDATE_NAMES`, preferring
+#: whichever the rename (#2096) is currently shipping.
+PROJECT = CANDIDATE_NAMES[0]
+
+# Where install-agent.sh puts the agent's venv.  Overridable via
+# `health.agent_venv_python`.
+_DEFAULT_AGENT_VENV = "~/.coord-venv/bin/python3"
+
+
+def resolve_agent_python(ctx: HealthContext) -> Path:
+    """The interpreter whose environment we're reporting on.
+
+    Configured value wins; otherwise the standard agent venv when it exists;
+    otherwise the running interpreter (which is the honest answer on a
+    coordinator-only box that never installed an agent venv).
+    """
+    configured = getattr(ctx.thresholds, "agent_venv_python", None)
+    if configured:
+        return expand(configured, ctx.home)
+    candidate = expand(_DEFAULT_AGENT_VENV, ctx.home)
+    if candidate.exists():
+        return candidate
+    return Path(sys.executable)
+
+
+def pip_show(
+    python: Path, names: tuple[str, ...] = CANDIDATE_NAMES, *, timeout: float = 8.0
+) -> dict[str, str]:
+    """Parse ``<python> -m pip show <name>`` into a field dict, trying each
+    of *names* in order and returning the first that resolves (#2103).
+
+    The agent venv this probes may have either ``code-coordinator`` (the
+    name since #2104) or the pre-rename ``claude-coordinator`` installed,
+    depending which side of the #2096 rename it's on — a bare single-name
+    ``pip show`` would report "not installed" for one of them. The dict's
+    ``Name`` field (``pip show`` always prints one) tells the caller which
+    one actually matched.
+
+    Returns ``{}`` when pip isn't there or neither name is installed.
+    Raises only for genuinely unexpected conditions — the probe wrapping this
+    fails soft either way.
+    """
+    for name in names:
+        result = subprocess.run(
+            [str(python), "-m", "pip", "show", name],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        if result.returncode != 0:
+            continue
+        fields = _parse_pip_show(result.stdout)
+        if fields:
+            return fields
+    return {}
+
+
+def _parse_pip_show(stdout: str) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    for line in stdout.splitlines():
+        key, sep, value = line.partition(":")
+        if sep:
+            fields[key.strip()] = value.strip()
+    return fields
+
+
+@check(
+    id="agent_venv",
+    scope="machine",
+    title="agent venv",
+    order=40,
+    description="The agent's coordinator install is a PyPI install, not editable.",
+)
+def probe_agent_venv(ctx: HealthContext) -> CheckResult:
+    python = resolve_agent_python(ctx)
+    try:
+        fields = pip_show(python)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return CheckResult(
+            check_id="agent_venv",
+            scope="machine",
+            severity=Severity.UNKNOWN,
+            headroom=f"could not run pip show ({type(exc).__name__})",
+            error=str(exc),
+            values={"python": str(python)},
+        )
+
+    if not fields:
+        tried = " or ".join(CANDIDATE_NAMES)
+        return CheckResult(
+            check_id="agent_venv",
+            scope="machine",
+            severity=Severity.UNKNOWN,
+            headroom=f"neither {tried} installed for {shorten_path(str(python), str(ctx.home))}",
+            error="pip show returned nothing",
+            values={"python": str(python)},
+        )
+
+    editable_location = fields.get("Editable project location") or ""
+    version = fields.get("Version", "")
+    location = fields.get("Location", "")
+
+    if editable_location:
+        return CheckResult(
+            check_id="agent_venv",
+            scope="machine",
+            severity=Severity.CRIT,
+            headroom=f"editable {version or '?'} from {shorten_path(editable_location, str(ctx.home))}",
+            detail=(
+                "an editable agent runs whatever is checked out in that tree — "
+                "its behaviour is not traceable to any release"
+            ),
+            threshold="crit when editable",
+            values={
+                "python": str(python),
+                "version": version,
+                "editable": True,
+                "editable_location": editable_location,
+                "location": location,
+            },
+        )
+
+    return CheckResult(
+        check_id="agent_venv",
+        scope="machine",
+        severity=Severity.OK,
+        headroom=f"pypi {version or '?'}",
+        detail=shorten_path(location, str(ctx.home)) if location else "",
+        values={
+            "python": str(python),
+            "version": version,
+            "editable": False,
+            "editable_location": None,
+            "location": location,
+        },
+    )
+
+
+@check(
+    id="agent_version",
+    scope="machine",
+    title="agent version",
+    order=41,
+    cost=COST_NETWORK,
+    description="Installed coordinator version vs the latest release on PyPI's simple index.",
+)
+def probe_agent_version(ctx: HealthContext) -> CheckResult:
+    from coord.health.pypi import latest_release, parse_version  # noqa: PLC0415
+
+    th = ctx.thresholds
+    python = resolve_agent_python(ctx)
+    try:
+        fields = pip_show(python)
+    except (OSError, subprocess.SubprocessError) as exc:
+        fields = {}
+        installed_raw = ""
+        pip_error: str | None = f"{type(exc).__name__}: {exc}"
+    else:
+        installed_raw = fields.get("Version", "")
+        pip_error = None
+
+    if not installed_raw:
+        return CheckResult(
+            check_id="agent_version",
+            scope="machine",
+            severity=Severity.UNKNOWN,
+            headroom="installed version unknown",
+            error=pip_error or "pip show reported no Version",
+            values={"python": str(python)},
+        )
+
+    # #2103: query PyPI for whichever name `pip show` actually matched, not
+    # a hardcoded one — `code-coordinator` and `claude-coordinator` are
+    # separate PyPI projects with separate release histories, and comparing
+    # a `code-coordinator` install's version against `claude-coordinator`'s
+    # index would compute nonsense skew.
+    installed_project = fields.get("Name") or PROJECT
+
+    try:
+        latest, finals = latest_release(
+            installed_project,
+            index_url=th.pypi_index_url,
+            timeout=th.network_timeout_secs,
+        )
+    except Exception as exc:  # noqa: BLE001 — any network/parse failure is "unknown"
+        return CheckResult(
+            check_id="agent_version",
+            scope="machine",
+            severity=Severity.UNKNOWN,
+            headroom=f"installed {installed_raw}, PyPI index unreachable",
+            error=f"{type(exc).__name__}: {exc}",
+            values={
+                "python": str(python),
+                "installed": installed_raw,
+                "project": installed_project,
+            },
+        )
+
+    installed = parse_version(installed_raw)
+    if installed is None or latest is None:
+        return CheckResult(
+            check_id="agent_version",
+            scope="machine",
+            severity=Severity.UNKNOWN,
+            headroom=f"installed {installed_raw}, could not compare against the index",
+            error="unparseable version",
+            values={"python": str(python), "installed": installed_raw},
+        )
+
+    behind = sum(1 for v in finals if v > installed)
+    if behind >= th.agent_version_crit_behind:
+        severity = Severity.CRIT
+    elif behind >= th.agent_version_warn_behind:
+        severity = Severity.WARN
+    else:
+        severity = Severity.OK
+
+    if behind == 0:
+        headroom = f"{installed_raw} (latest {latest.raw})"
+    else:
+        headroom = (
+            f"{installed_raw}, {behind} release{'s' if behind != 1 else ''} behind "
+            f"(latest {latest.raw})"
+        )
+
+    return CheckResult(
+        check_id="agent_version",
+        scope="machine",
+        severity=severity,
+        headroom=headroom,
+        threshold=f"crit at {th.agent_version_crit_behind} behind",
+        values={
+            "python": str(python),
+            "installed": installed_raw,
+            "project": installed_project,
+            "latest": latest.raw,
+            "releases_behind": behind,
+            "index_url": th.pypi_index_url,
+            "warn_behind": th.agent_version_warn_behind,
+            "crit_behind": th.agent_version_crit_behind,
+        },
+    )

coord/health/checks/cargo_targets.py

@@ -0,0 +1,171 @@
+"""Total size of every cargo ``target/`` directory this machine keeps (#1628).
+
+The 2026-07-30 incident: **78G** of cargo build artifacts across a handful of
+checkouts plus ``~/.coord/cargo-target`` — which is what actually consumed
+``/home``.  ``coord.cargo_cache`` already GCs the *shared* cache (default 20
+GiB cap), but nothing totals it together with the per-checkout ``target/``
+dirs a human created by building in a live checkout, and that sum is the
+number that fills a disk.
+
+Cost note: this is the one seed probe that can be genuinely slow, because
+"how big is 78G of small files" is a full tree walk.  It is therefore
+budgeted (``health.cargo_scan_budget_secs``, default 1.5s) and reports a
+partial scan when it runs out.  A partial total is a **lower bound**, so a
+CRIT derived from one is still correct; only an OK is downgraded (to
+``unknown``) when the scan didn't finish, because "we didn't finish looking"
+must never render as "nothing there".
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+from coord.health.models import CheckResult, HealthContext, Severity
+from coord.health.registry import check
+from coord.health.units import expand, gib, human_bytes, shorten_path
+
+
+def _dir_size_budgeted(path: Path, deadline: float) -> tuple[int, bool]:
+    """``(bytes, complete)`` for the regular files under *path*.
+
+    Symlinked subdirectories are never followed — a worktree's ``target``
+    symlinked at the shared cache must not be counted twice, and a symlink
+    out of the tree must not be counted at all.
+    """
+    total = 0
+    complete = True
+    checked = 0
+    for root, dirnames, filenames in os.walk(path, onerror=lambda _e: None):
+        dirnames[:] = [d for d in dirnames if not os.path.islink(os.path.join(root, d))]
+        for name in filenames:
+            try:
+                total += os.lstat(os.path.join(root, name)).st_size
+            except OSError:
+                continue
+        # time.monotonic() per file would dominate the walk on a tree with
+        # a million small files; per 200 entries is accurate enough for a
+        # 1.5s budget and costs nothing.
+        checked += len(filenames) + 1
+        if checked >= 200:
+            checked = 0
+            if time.monotonic() >= deadline:
+                complete = False
+                break
+    return total, complete
+
+
+def _candidate_dirs(ctx: HealthContext) -> list[Path]:
+    """Every cargo target dir we know about, deduped, existing only.
+
+    Three sources, in report order:
+
+    1. ``~/.coord/cargo-target/<repo>`` — the shared per-machine cache
+       (``coord.cargo_cache``), one subdirectory per repo.
+    2. ``<checkout>/target`` for each checkout in ``coordinator.yml`` — what
+       a human building in the live checkout creates, invisible to the cache
+       GC.
+    3. ``health.cargo_target_extra_dirs`` — anything else on this box.
+    """
+    from coord.cargo_cache import CACHE_DIRNAME  # noqa: PLC0415
+
+    out: list[Path] = []
+    seen: set[Path] = set()
+
+    def _add(p: Path) -> None:
+        try:
+            resolved = p.resolve()
+        except OSError:
+            resolved = p
+        if resolved in seen or not p.is_dir():
+            return
+        seen.add(resolved)
+        out.append(p)
+
+    cache_root = ctx.coord_dir / CACHE_DIRNAME
+    try:
+        for entry in sorted(cache_root.iterdir()):
+            if entry.is_dir() and not entry.is_symlink():
+                _add(entry)
+    except OSError:
+        pass
+
+    for checkout in ctx.checkouts:
+        _add(checkout.path / "target")
+
+    for raw in getattr(ctx.thresholds, "cargo_target_extra_dirs", ()) or ():
+        _add(expand(raw, ctx.home))
+
+    return out
+
+
+@check(
+    id="cargo_targets",
+    scope="machine",
+    title="cargo targets",
+    order=20,
+    description="Total size of cargo build artifacts across known target dirs.",
+)
+def probe_cargo_targets(ctx: HealthContext) -> CheckResult | None:
+    """One machine-scope result: the total, with the biggest offenders named."""
+    th = ctx.thresholds
+    dirs = _candidate_dirs(ctx)
+    if not dirs:
+        return None  # no Rust on this box — silence beats a green line
+
+    deadline = time.monotonic() + max(0.05, float(th.cargo_scan_budget_secs))
+    sizes: list[tuple[Path, int]] = []
+    complete = True
+    for d in dirs:
+        size, done = _dir_size_budgeted(d, deadline)
+        sizes.append((d, size))
+        if not done:
+            complete = False
+            break
+    # Directories we never reached at all still count as "didn't finish".
+    if len(sizes) < len(dirs):
+        complete = False
+
+    total = sum(s for _, s in sizes)
+    total_gb = gib(total)
+
+    if total_gb > th.cargo_target_crit_gb:
+        severity = Severity.CRIT
+    elif total_gb > th.cargo_target_warn_gb:
+        severity = Severity.WARN
+    elif complete:
+        severity = Severity.OK
+    else:
+        # Below WARN but we stopped early: the real total could be anything.
+        severity = Severity.UNKNOWN
+
+    biggest = sorted(sizes, key=lambda pair: pair[1], reverse=True)[:3]
+    breakdown = ", ".join(
+        f"{shorten_path(str(p), str(ctx.home))} {human_bytes(s)}" for p, s in biggest if s > 0
+    )
+    headroom = human_bytes(total)
+    if breakdown:
+        headroom = f"{headroom}  ({breakdown})"
+    if not complete:
+        headroom = f"{headroom} [partial scan — {th.cargo_scan_budget_secs}s budget hit]"
+
+    return CheckResult(
+        check_id="cargo_targets",
+        scope="machine",
+        severity=severity,
+        headroom=headroom,
+        threshold=f"crit at {th.cargo_target_crit_gb:.0f}G",
+        error=None if complete else "scan budget exhausted; total is a lower bound",
+        values={
+            "total_bytes": total,
+            "total_gb": round(total_gb, 2),
+            "complete": complete,
+            "dirs": [
+                {"path": str(p), "bytes": s, "gb": round(gib(s), 2)}
+                for p, s in sorted(sizes, key=lambda pair: pair[1], reverse=True)
+            ],
+            "warn_gb": th.cargo_target_warn_gb,
+            "crit_gb": th.cargo_target_crit_gb,
+        },
+    )

coord/health/checks/claude_binary.py

@@ -0,0 +1,65 @@
+"""Is the ``claude`` binary actually resolvable where the agent runs? (#1628)
+
+This is the #859 failure in health-check form.  ``coord-serve`` runs under
+``systemd --user`` with an empty ``Environment=``, so a bare ``claude`` on
+``$PATH`` resolves fine in an interactive shell and not at all in the daemon
+— which is why :func:`coord.test_orchestrator.resolve_claude_bin` exists.
+That resolution is reused verbatim here rather than re-derived: if the
+resolver's rules ever change, this check must change with them, and the only
+way to guarantee that is to call it.
+
+A machine whose ``claude`` is missing is not degraded, it is *useless* — it
+will accept dispatches and fail every one — so this is CRIT with no warn
+level, exactly as the issue's table specifies.
+"""
+
+from __future__ import annotations
+
+import os
+
+from coord.health.models import CheckResult, HealthContext, Severity
+from coord.health.registry import check
+from coord.health.units import shorten_path
+
+
+@check(
+    id="claude_binary",
+    scope="machine",
+    title="claude binary",
+    order=50,
+    description="The claude binary resolves and is executable for the agent.",
+)
+def probe_claude_binary(ctx: HealthContext) -> CheckResult:
+    from coord.test_orchestrator import resolve_claude_bin  # noqa: PLC0415
+
+    path = resolve_claude_bin()
+    shown = shorten_path(path, str(ctx.home))
+
+    exists = os.path.exists(path)
+    executable = exists and os.access(path, os.X_OK)
+
+    if executable:
+        severity, headroom = Severity.OK, shown
+    elif exists:
+        severity, headroom = Severity.CRIT, f"{shown} is not executable"
+    else:
+        severity, headroom = Severity.CRIT, f"{shown} does not exist"
+
+    return CheckResult(
+        check_id="claude_binary",
+        scope="machine",
+        severity=severity,
+        headroom=headroom,
+        threshold="crit when unresolvable",
+        detail=(
+            ""
+            if executable
+            else "every dispatch to this machine will fail; set $CLAUDE_BIN or reinstall"
+        ),
+        values={
+            "path": path,
+            "exists": exists,
+            "executable": executable,
+            "claude_bin_env": os.environ.get("CLAUDE_BIN"),
+        },
+    )