code-coordinator 0.5.192__tar.gz → 0.5.194__tar.gz

{code_coordinator-0.5.192 → code_coordinator-0.5.194}/PKG-INFO

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.192
+Version: 0.5.194
 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.192 → code_coordinator-0.5.194}/code_coordinator.egg-info/SOURCES.txt

@@ -71,6 +71,7 @@ coord/events.py
 coord/failure_class.py
 coord/filelock.py
 coord/fleet_config_health.py
+coord/forge_availability.py
 coord/freshness.py
 coord/gate_a.py
 coord/gate_b.py
@@ -391,6 +392,7 @@ tests/test_cli_audit.py
 tests/test_cli_chat_continue.py
 tests/test_cli_decide.py
 tests/test_cli_diagnose_config_provenance.py
+tests/test_cli_diagnose_forge_availability.py
 tests/test_cli_diagnose_graph.py
 tests/test_cli_diagnose_self.py
 tests/test_cli_doctor.py
@@ -494,6 +496,7 @@ tests/test_fix_of_force_override.py
 tests/test_fleet_config_health.py
 tests/test_fleet_health_probes.py
 tests/test_fleet_health_snapshot.py
+tests/test_forge_availability.py
 tests/test_freshness.py
 tests/test_gate_a.py
 tests/test_gate_b.py

{code_coordinator-0.5.192 → code_coordinator-0.5.194}/code_coordinator.egg-info/scm_file_list.json

@@ -117,6 +117,7 @@
     "coord/failure_class.py",
     "coord/filelock.py",
     "coord/fleet_config_health.py",
+    "coord/forge_availability.py",
     "coord/freshness.py",
     "coord/gate_a.py",
     "coord/gate_b.py",
@@ -453,6 +454,7 @@
     "tests/test_cli_chat_continue.py",
     "tests/test_cli_decide.py",
     "tests/test_cli_diagnose_config_provenance.py",
+    "tests/test_cli_diagnose_forge_availability.py",
     "tests/test_cli_diagnose_graph.py",
     "tests/test_cli_diagnose_self.py",
     "tests/test_cli_doctor.py",
@@ -556,6 +558,7 @@
     "tests/test_fleet_config_health.py",
     "tests/test_fleet_health_probes.py",
     "tests/test_fleet_health_snapshot.py",
+    "tests/test_forge_availability.py",
     "tests/test_freshness.py",
     "tests/test_gate_a.py",
     "tests/test_gate_b.py",

code_coordinator-0.5.194/code_coordinator.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.5.194",
+  "distance": 0,
+  "node": "g8dc0f31443ec84d69abafcaaa0a1af05c2152bf4",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-08-21"
+}

{code_coordinator-0.5.192 → code_coordinator-0.5.194}/coord/ci_github.py

@@ -14,11 +14,13 @@ from __future__ import annotations
 import re
 import subprocess
 import time
+from collections import Counter
 from dataclasses import dataclass, field
 from datetime import datetime
 
 from coord import github_ops
 from coord.ci_store import CheckRun, JobRun, JobStep, failed_checks
+from coord.forge_availability import record_ci_check_fetch
 
 
 def _parse_ts(raw: str | None) -> float | None:
@@ -381,6 +383,18 @@ class GitHubCi:
     # ── Internal ────────────────────────────────────────────────────────────
 
     def _fetch(self, repo: str, number: int) -> list[CheckRun]:
+        # #1896 Phase 0: this is the "every CiStore.list_checks_for_pr
+        # outcome" seam the forge-availability program asks for — reachable/
+        # unreachable, plus the check-level conclusion distribution.
+        # `github_ops.get_pr_checks` does NOT go through `_gh()` — it shells
+        # out to `gh pr checks` directly (a non-zero exit there can still
+        # carry usable JSON on stdout, which `_gh()`'s raise-on-nonzero
+        # contract can't express, see `get_pr_checks`'s own docstring) — so
+        # this call is the *only* forge-availability observation this read
+        # produces. It stands alone, not "layered on top" of anything.
+        # Only fires on a real cache miss — a cached `list_checks_for_pr`
+        # hit never reaches here, so this costs nothing extra either.
+        _t0 = time.monotonic()
         try:
             raw = github_ops.get_pr_checks(repo, number)
         except github_ops.GhTooOldForJsonChecks as e:
@@ -394,6 +408,8 @@ class GitHubCi:
             # it into `_unreadable_check`'s generic wording) means an operator
             # reading the merge refusal never has to guess which of the two
             # this was.
+            record_ci_check_fetch(repo, number, outcome="unreachable",
+                                   duration_s=time.monotonic() - _t0, detail="gh too old")
             return [_gh_too_old_check(repo, number, str(e))]
         except (FileNotFoundError, subprocess.TimeoutExpired, RuntimeError, ValueError) as e:
             # #1525: a `gh pr checks` read that outright failed (gh missing,
@@ -407,8 +423,13 @@ class GitHubCi:
             # failing check instead so the gate blocks and says why; a caller
             # that genuinely wants "unknown" treated as clear must pass
             # `force_merge=True` explicitly.
+            record_ci_check_fetch(repo, number, outcome="unreachable",
+                                   duration_s=time.monotonic() - _t0, detail=str(e))
             return [_unreadable_check(repo, number, str(e))]
+        duration = time.monotonic() - _t0
         if not isinstance(raw, list):
+            record_ci_check_fetch(repo, number, outcome="unreachable",
+                                   duration_s=duration, detail="non-list JSON")
             return [_unreadable_check(repo, number, "gh pr checks returned non-list JSON")]
         # #2446: `_all_checks` (this method's only caller) is the single
         # unfiltered fetch shared by both `list_checks_for_pr` (narrowed to
@@ -416,7 +437,7 @@ class GitHubCi:
         # required-contexts narrowing used to happen here, which meant an
         # advisory check's regression was invisible everywhere, not just to
         # the merge gate. See both methods' docstrings.
-        return [
+        checks = [
             CheckRun(
                 name=str(entry.get("name", "")),
                 status=_status_from_bucket(str(entry.get("bucket", ""))),
@@ -429,6 +450,10 @@ class GitHubCi:
             for entry in raw
             if isinstance(entry, dict)
         ]
+        conclusions = Counter(c.conclusion or "pending" for c in checks)
+        record_ci_check_fetch(repo, number, outcome="ok", duration_s=duration,
+                               conclusions=dict(conclusions))
+        return checks
 
     def _required_contexts(self, repo: str) -> frozenset[str] | None:
         now = time.time()

{code_coordinator-0.5.192 → code_coordinator-0.5.194}/coord/commands/status.py

@@ -1585,6 +1585,26 @@ def _diagnose_via_daemon(svc, params: dict) -> None:
         "behind."
     ),
 )
+@click.option(
+    "--forge-availability",
+    "forge_availability",
+    is_flag=True,
+    help=(
+        "#1896: report forge/CI availability over a trailing window — "
+        "uptime %, longest contiguous unavailable stretch, and merge-gate "
+        "CI refusal counts by reason — from observations recorded at the "
+        "gh/CI/merge-gate seams. Read-only, local audit_log only. Pair "
+        "with --window-days to change the window (default 30)."
+    ),
+)
+@click.option(
+    "--window-days",
+    "forge_availability_window_days",
+    default=30.0,
+    show_default=True,
+    type=float,
+    help="With --forge-availability, the trailing window (days) to summarize.",
+)
 
 
 @_CONFIG_OPTION
@@ -1601,6 +1621,8 @@ def diagnose(
     config_provenance_check: bool = False,
     self_check: bool = False,
     self_no_fetch: bool = False,
+    forge_availability: bool = False,
+    forge_availability_window_days: float = 30.0,
 ) -> None:
     """Per-stage doctor — diagnose, best-effort recover, optional reset."""
     # ── graphify graph freshness sweep (read-only) ───────────────────────────
@@ -1608,6 +1630,11 @@ def diagnose(
         _diagnose_graph_health(config_path)
         return
 
+    # ── #1896: forge/CI availability read-out (read-only) ───────────────────
+    if forge_availability:
+        _diagnose_forge_availability(forge_availability_window_days)
+        return
+
     # ── #1779: fleet coordinator.yml provenance (read-only) ─────────────────
     if config_provenance_check:
         _diagnose_config_provenance()
@@ -1762,6 +1789,28 @@ def _diagnose_graph_health(config_path: Path) -> None:
     )
 
 
+def _diagnose_forge_availability(window_days: float) -> None:
+    """Report forge/CI availability over the trailing *window_days* (#1896).
+
+    Read-only: summarizes the ``forge_availability``-category rows in the
+    local ``audit_log`` (recorded best-effort at the ``gh`` call seam, the
+    CI check-fetch seam, and the merge-gate refusal seam — see
+    :mod:`coord.forge_availability`). Same family as ``--graph``/
+    ``--config-provenance``/``--self``: local-machine only, no network call
+    of its own.
+    """
+    from coord.forge_availability import (  # noqa: PLC0415
+        availability_report,
+        format_report_lines,
+        summary_line as forge_summary_line,
+    )
+
+    report = availability_report(window_days=window_days)
+    for line in format_report_lines(report):
+        click.echo(f"  {line}")
+    click.echo(forge_summary_line(report))
+
+
 def _diagnose_config_provenance() -> None:
     """Report whether THIS machine's live ``coordinator.yml`` is still the
     reviewed one (#1779).

code_coordinator-0.5.194/coord/forge_availability.py

@@ -0,0 +1,441 @@
+"""Forge/CI availability instrumentation — Phase 0 of the Forge Independence
+program (#1896).
+
+Phases 3-6 of that program (issue-store split, parentage, message-bus
+cutover) are 20-40 issues of work whose entire justification is "our forge
+is unreliable enough that leaving it pays for itself". Whether that premise
+is even true has never been measured — every data point that exists lives
+in a chat transcript about one bad day (2026-08-06's 7+-hour GitHub Actions
+outage). This module turns that into durable data, cheaply, by observing
+three seams coord already touches on every relevant call, so nothing here
+adds a single extra network round trip:
+
+1. **CI reads** — :func:`record_ci_check_fetch`, called from
+   :meth:`coord.ci_github.GitHubCi._fetch` on every live (non-cached)
+   ``gh pr checks`` read.
+2. **Forge API calls** — :func:`record_gh_call`, called from
+   :func:`coord.github_ops._gh`, the seam the vast majority of that module's
+   public functions funnel through (#1483). A handful of call sites
+   (``edit_issue``, ``close_issue``, ``reopen_issue``, ``rerun_workflow_run``,
+   ``rerun_workflow_run_failed``, plus ``get_pr_checks`` which is covered
+   separately via seam 1 above) shell out to ``gh`` directly instead of
+   through ``_gh`` — each for a documented reason (idempotent-on-a-specific-
+   stderr-message semantics, or a "never raise, return False" contract that
+   ``_gh``'s raise-only contract can't express) — and each calls
+   :func:`record_gh_call` inline at its own call site instead, so none of
+   them is a silent gap in this measurement (#1896 review).
+3. **Merge-gate refusals** — :func:`record_merge_gate_refusal`, called from
+   :func:`coord.merge_queue.process` for each live (never dry-run)
+   ``checks_failed``/``checks_pending``/``checks_stale`` :class:`~coord.
+   merge_queue.MergeEvent`.
+
+Storage deliberately follows the audit-trail grain (#1041/milestone 33)
+rather than inventing a parallel log/table: every observation is one row in
+the existing ``audit_log`` (via :func:`coord.audit.record_audit`), tagged
+``category="forge_availability"``. :func:`availability_report` is the read
+side — ``coord diagnose --forge-availability``.
+
+**Best-effort, unconditionally.** Every ``record_*`` function here is a thin
+wrapper that can never raise, retry, or delay its caller — ``record_audit``
+itself already swallows all exceptions (see its docstring), and each
+function below adds its own belt-and-suspenders ``try/except`` on top so
+that guarantee holds even if this module's own bookkeeping (the periodic
+prune sweep) misbehaves. Measurement must never become a new way for the
+forge's actual unreliability to take coord down with it.
+
+This is measurement only — see the issue for why acting on the data
+(pausing the drive queue when the forge is degraded) is explicitly a
+different, sibling issue (#1893).
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+from coord.audit import MAX_LIMIT as _AUDIT_MAX_LIMIT
+from coord.audit import query_audit_log, record_audit
+
+_log = logging.getLogger(__name__)
+
+CATEGORY = "forge_availability"
+
+EVENT_GH_CALL = "gh_call"
+EVENT_CI_CHECK_FETCH = "ci_check_fetch"
+EVENT_MERGE_GATE_REFUSAL = "merge_gate_refusal"
+
+# gh_call / ci_check_fetch outcomes that count as the forge being reachable.
+# "app_error" is gh running fine and reporting a normal application-level
+# failure (e.g. "label not found") -- that is NOT a forge-availability
+# problem, it is business as usual, so it counts as available. "transient"
+# (an error string matching github_ops._is_transient_error -- auth,
+# rate-limit, network) and "unreachable" (gh missing / timed out / OSError,
+# or a raised read failure on the CI seam) are the two outcomes that
+# actually say something about forge/CI availability.
+_AVAILABLE_OUTCOMES = frozenset({"ok", "app_error"})
+
+# Refusal reasons this issue asks to be tracked (#1896 scope: "checks_failed
+# / checks_pending / checks_stale are already distinct MergeEvent kinds ...
+# persist the counts"). Deliberately narrower than every MergeEvent kind
+# that can block a merge (e.g. checks_absent, checks_unreadable, conflict)
+# -- those are real refusal reasons too, but out of THIS issue's stated
+# scope; widening the set later is additive, not a migration.
+MERGE_GATE_REFUSAL_KINDS = frozenset({"checks_failed", "checks_pending", "checks_stale"})
+
+# How often (seconds, per-process) the opportunistic retention sweep runs
+# after a write. A DELETE scan on every single observation -- the whole
+# point of this module is to be cheap enough to fire on every `gh` call --
+# would defeat that; observations are cheap to lose track of for an hour
+# without threatening the "does not grow unboundedly" acceptance bar.
+_PRUNE_INTERVAL_S = 3600.0
+
+# Retention window (days). ">= 90 days" per the issue's acceptance bar.
+RETENTION_DAYS = 90.0
+
+_last_prune_at = 0.0
+
+
+def record_gh_call(
+    argv: tuple[str, ...], *, outcome: str, duration_s: float, detail: str = "",
+) -> None:
+    """Best-effort: one row per :func:`coord.github_ops._gh` invocation.
+
+    ``outcome`` is one of ``"ok"`` (exit 0), ``"app_error"`` (non-zero exit,
+    not an auth/network/rate-limit failure -- an ordinary application-level
+    error), ``"transient"`` (non-zero exit matching
+    ``github_ops._is_transient_error`` -- auth, rate-limit, network), or
+    ``"unreachable"`` (the ``gh`` binary was missing, the call timed out, or
+    raised some other ``OSError`` before it could even run).
+    """
+    _safe_record(
+        event_type=EVENT_GH_CALL,
+        summary=f"gh {argv[0] if argv else '(no args)'}: {outcome}",
+        details={
+            "argv0": argv[0] if argv else "",
+            "outcome": outcome,
+            "duration_s": round(duration_s, 3),
+            "detail": detail[:200] if detail else "",
+        },
+    )
+
+
+def record_ci_check_fetch(
+    repo: str,
+    number: int,
+    *,
+    outcome: str,
+    duration_s: float,
+    conclusions: dict[str, int] | None = None,
+    detail: str = "",
+) -> None:
+    """Best-effort: one row per live (cache-miss) ``gh pr checks`` read.
+
+    ``outcome`` is ``"ok"`` or ``"unreachable"``. ``conclusions`` is the
+    check-level conclusion distribution (e.g. ``{"success": 3, "failure":
+    1}``) when ``outcome == "ok"`` -- the "check-level conclusion
+    distribution" the issue asks for, alongside reachability.
+    """
+    _safe_record(
+        event_type=EVENT_CI_CHECK_FETCH,
+        summary=f"{repo}#{number}: CI checks {outcome}",
+        repo=repo,
+        issue=number,
+        details={
+            "outcome": outcome,
+            "duration_s": round(duration_s, 3),
+            "conclusions": conclusions or {},
+            "detail": detail[:200] if detail else "",
+        },
+    )
+
+
+def record_merge_gate_refusal(
+    *, repo: str, issue: int | None, reason: str, message: str,
+) -> None:
+    """Best-effort: one row per live merge-gate CI refusal.
+
+    Only ``reason in MERGE_GATE_REFUSAL_KINDS`` (see that constant) should be
+    passed here -- callers filter before calling, this function does not
+    re-filter, so it stays a plain unconditional recorder like its siblings.
+    """
+    _safe_record(
+        event_type=EVENT_MERGE_GATE_REFUSAL,
+        summary=f"{repo}#{issue}: merge blocked ({reason})",
+        repo=repo,
+        issue=issue,
+        details={"reason": reason, "message": message[:300] if message else ""},
+    )
+
+
+def _safe_record(
+    *,
+    event_type: str,
+    summary: str,
+    details: dict[str, Any],
+    repo: str | None = None,
+    issue: int | None = None,
+) -> None:
+    try:
+        record_audit(
+            tier="operational",
+            category=CATEGORY,
+            event_type=event_type,
+            actor="system",
+            summary=summary,
+            repo=repo,
+            issue=issue,
+            details=details,
+        )
+        _maybe_prune()
+    except Exception as exc:  # noqa: BLE001 -- measurement must never affect the caller
+        _log.debug("forge_availability: best-effort record failed: %s", exc)
+
+
+def _maybe_prune(*, force: bool = False) -> None:
+    """Delete ``forge_availability`` rows older than :data:`RETENTION_DAYS`.
+
+    Throttled to once per :data:`_PRUNE_INTERVAL_S` per process (``force``
+    bypasses the throttle, for tests) -- see the module docstring for why a
+    DELETE scan on every single write would defeat the point of this module
+    being cheap enough to fire on every ``gh`` call.
+    """
+    global _last_prune_at
+    now = time.time()
+    if not force and (now - _last_prune_at) < _PRUNE_INTERVAL_S:
+        return
+    _last_prune_at = now
+    try:
+        from coord.db import get_connection  # noqa: PLC0415
+
+        cutoff = now - RETENTION_DAYS * 86400.0
+        conn = get_connection()
+        conn.execute(
+            "DELETE FROM audit_log WHERE category = ? AND ts < ?",
+            (CATEGORY, cutoff),
+        )
+        conn.commit()
+    except Exception as exc:  # noqa: BLE001 -- best-effort, never blocks a caller
+        _log.debug("forge_availability: prune sweep failed: %s", exc)
+
+
+# ── Read side: the `coord diagnose --forge-availability` read-out ──────────
+
+
+class AvailabilityReport:
+    """Summary of forge/CI availability over a trailing window.
+
+    ``uptime_pct`` and ``longest_unavailable_stretch_s`` are computed over
+    the merged, time-ordered sequence of ``gh_call`` + ``ci_check_fetch``
+    observations -- this is an *observation-based* signal, not a continuous
+    heartbeat: a stretch with no forge calls at all (nights, a quiet repo)
+    is not a gap in availability, it's a gap in *observations*, and
+    "longest unavailable stretch" only measures contiguous runs of
+    observations that came back unavailable, not wall-clock silence.
+    """
+
+    def __init__(
+        self,
+        *,
+        window_days: float,
+        since: float,
+        until: float,
+        gh_calls: int,
+        ci_fetches: int,
+        available: int,
+        unavailable: int,
+        longest_unavailable_stretch_s: float,
+        refusals_by_reason: dict[str, int],
+        truncated: bool,
+    ) -> None:
+        self.window_days = window_days
+        self.since = since
+        self.until = until
+        self.gh_calls = gh_calls
+        self.ci_fetches = ci_fetches
+        self.available = available
+        self.unavailable = unavailable
+        self.longest_unavailable_stretch_s = longest_unavailable_stretch_s
+        self.refusals_by_reason = refusals_by_reason
+        self.truncated = truncated
+
+    @property
+    def total_observations(self) -> int:
+        return self.available + self.unavailable
+
+    @property
+    def uptime_pct(self) -> float | None:
+        if self.total_observations == 0:
+            return None
+        return 100.0 * self.available / self.total_observations
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "window_days": self.window_days,
+            "since": self.since,
+            "until": self.until,
+            "gh_calls": self.gh_calls,
+            "ci_fetches": self.ci_fetches,
+            "total_observations": self.total_observations,
+            "available": self.available,
+            "unavailable": self.unavailable,
+            "uptime_pct": self.uptime_pct,
+            "longest_unavailable_stretch_s": self.longest_unavailable_stretch_s,
+            "refusals_by_reason": dict(self.refusals_by_reason),
+            "truncated": self.truncated,
+        }
+
+
+# Safety cap on how many audit rows a single report will page through --
+# bounds worst case cost the same way `coord.audit.query_audit_log`'s own
+# MAX_LIMIT bounds a single page; a window with more observations than this
+# reports `truncated=True` rather than paging forever.
+_MAX_REPORT_ROWS = 20_000
+
+
+def availability_report(
+    *, window_days: float = 30.0, now: float | None = None,
+) -> AvailabilityReport:
+    """Summarize forge/CI availability over the trailing *window_days*.
+
+    Read-only; queries the local ``audit_log`` via
+    :func:`coord.audit.query_audit_log`, paginating until the window is
+    exhausted or :data:`_MAX_REPORT_ROWS` is hit (``truncated=True`` in the
+    latter case, reported rather than hidden).
+    """
+    now = now if now is not None else time.time()
+    since = now - window_days * 86400.0
+
+    entries: list[dict[str, Any]] = []
+    cursor: str | None = None
+    truncated = False
+    while True:
+        page = query_audit_log(
+            since=since, until=now, category=CATEGORY,
+            limit=_AUDIT_MAX_LIMIT, cursor=cursor,
+        )
+        entries.extend(page["entries"])
+        if len(entries) >= _MAX_REPORT_ROWS:
+            truncated = bool(page["has_more"])
+            break
+        if not page["has_more"]:
+            break
+        cursor = page["next_cursor"]
+
+    observations = [
+        e for e in entries if e["event_type"] in (EVENT_GH_CALL, EVENT_CI_CHECK_FETCH)
+    ]
+    # query_audit_log returns newest-first; availability math wants
+    # chronological order so "contiguous" means "contiguous in time".
+    observations.sort(key=lambda e: (e["ts"], e["id"]))
+
+    gh_calls = sum(1 for e in observations if e["event_type"] == EVENT_GH_CALL)
+    ci_fetches = sum(1 for e in observations if e["event_type"] == EVENT_CI_CHECK_FETCH)
+
+    available = 0
+    unavailable = 0
+    longest_stretch = 0.0
+    run_start_ts: float | None = None
+    run_end_ts: float | None = None
+    for e in observations:
+        details = e.get("details") or {}
+        outcome = details.get("outcome")
+        duration_s = details.get("duration_s") or 0.0
+        is_available = outcome in _AVAILABLE_OUTCOMES
+        if is_available:
+            available += 1
+            if run_start_ts is not None:
+                longest_stretch = max(longest_stretch, (run_end_ts or run_start_ts) - run_start_ts)
+            run_start_ts = None
+            run_end_ts = None
+        else:
+            unavailable += 1
+            if run_start_ts is None:
+                run_start_ts = e["ts"]
+            run_end_ts = e["ts"] + duration_s
+    if run_start_ts is not None:
+        longest_stretch = max(longest_stretch, (run_end_ts or run_start_ts) - run_start_ts)
+
+    refusals_by_reason: dict[str, int] = {}
+    for e in entries:
+        if e["event_type"] != EVENT_MERGE_GATE_REFUSAL:
+            continue
+        reason = (e.get("details") or {}).get("reason", "unknown")
+        refusals_by_reason[reason] = refusals_by_reason.get(reason, 0) + 1
+
+    return AvailabilityReport(
+        window_days=window_days,
+        since=since,
+        until=now,
+        gh_calls=gh_calls,
+        ci_fetches=ci_fetches,
+        available=available,
+        unavailable=unavailable,
+        longest_unavailable_stretch_s=longest_stretch,
+        refusals_by_reason=refusals_by_reason,
+        truncated=truncated,
+    )
+
+
+def _format_duration(seconds: float) -> str:
+    if seconds <= 0:
+        return "0s"
+    minutes, secs = divmod(int(seconds), 60)
+    hours, minutes = divmod(minutes, 60)
+    days, hours = divmod(hours, 24)
+    parts = []
+    if days:
+        parts.append(f"{days}d")
+    if hours:
+        parts.append(f"{hours}h")
+    if minutes:
+        parts.append(f"{minutes}m")
+    if not parts:
+        parts.append(f"{secs}s")
+    return " ".join(parts)
+
+
+def format_report_lines(report: AvailabilityReport) -> list[str]:
+    """Human-readable report lines for ``coord diagnose --forge-availability``."""
+    lines: list[str] = []
+    uptime = report.uptime_pct
+    if uptime is None:
+        lines.append(
+            f"no forge/CI observations in the trailing {report.window_days:.0f}d "
+            "(nothing has called `gh` or read CI checks yet in this window)"
+        )
+    else:
+        lines.append(
+            f"uptime: {uptime:.2f}% ({report.available}/{report.total_observations} "
+            f"observations available) over the trailing {report.window_days:.0f}d"
+        )
+        lines.append(
+            f"observations: {report.gh_calls} gh call(s), {report.ci_fetches} CI check-fetch(es)"
+        )
+        lines.append(
+            f"longest unavailable stretch: {_format_duration(report.longest_unavailable_stretch_s)}"
+        )
+    if report.refusals_by_reason:
+        lines.append("merge-gate refusals by reason:")
+        for reason in sorted(report.refusals_by_reason):
+            lines.append(f"  {reason}: {report.refusals_by_reason[reason]}")
+    else:
+        lines.append("merge-gate refusals by reason: none")
+    if report.truncated:
+        lines.append(
+            f"⚠ truncated at {_MAX_REPORT_ROWS} rows -- narrow --window-days for exact figures"
+        )
+    return lines
+
+
+def summary_line(report: AvailabilityReport) -> str:
+    """Machine-parseable trailer line, same family as ``GRAPH_HEALTH:``."""
+    uptime = report.uptime_pct
+    uptime_str = f"{uptime:.2f}" if uptime is not None else "n/a"
+    refusals_total = sum(report.refusals_by_reason.values())
+    return (
+        f"FORGE_AVAILABILITY: window_days={report.window_days:.0f} "
+        f"observations={report.total_observations} uptime_pct={uptime_str} "
+        f"longest_outage_s={report.longest_unavailable_stretch_s:.0f} "
+        f"refusals_total={refusals_total} truncated={report.truncated}"
+    )