code-coordinator 0.5.97__tar.gz → 0.5.99__tar.gz

{code_coordinator-0.5.97 → code_coordinator-0.5.99}/PKG-INFO

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

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

@@ -109,6 +109,7 @@ coord/portal_sync.py
 coord/pr_body_lint.py
 coord/prereqs.py
 coord/progress.py
+coord/queue_diagnose.py
 coord/reconcile.py
 coord/refine_chat.py
 coord/release_cordon.py
@@ -674,6 +675,7 @@ tests/test_reap_stale_interactive_tick.py
 tests/test_reconcile_branch.py
 tests/test_reconcile_completions.py
 tests/test_reconcile_merges.py
+tests/test_reconcile_no_agent_record.py
 tests/test_reconcile_usage_limit_done.py
 tests/test_refine_chat.py
 tests/test_release_cordon_2101.py

{code_coordinator-0.5.97 → code_coordinator-0.5.99}/code_coordinator.egg-info/scm_file_list.json

@@ -290,6 +290,7 @@
     "coord/providers/claude.py",
     "coord/providers/claude_pty.py",
     "coord/providers/opencode.py",
+    "coord/queue_diagnose.py",
     "coord/reconcile.py",
     "coord/refine_chat.py",
     "coord/release_cordon.py",
@@ -704,6 +705,7 @@
     "tests/test_reconcile_branch.py",
     "tests/test_reconcile_completions.py",
     "tests/test_reconcile_merges.py",
+    "tests/test_reconcile_no_agent_record.py",
     "tests/test_reconcile_usage_limit_done.py",
     "tests/test_refine_chat.py",
     "tests/test_release_cordon_2101.py",

{code_coordinator-0.5.97 → code_coordinator-0.5.99}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.97",
+  "tag": "0.5.99",
   "distance": 0,
-  "node": "g2c2fb9bb30187ab30ecfca32a852de69332b37e9",
+  "node": "g8a04998d3cc3d58b70436288c2ee857a647fde7d",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-15"

{code_coordinator-0.5.97 → code_coordinator-0.5.99}/coord/block_log.py

@@ -16,12 +16,24 @@ So this module records, for every entry that reaches ``blocked`` or
   Phase-0 read on its *true* cause — and
 * whether a **human had to act** to get it out.
 
-**What this is emphatically NOT.**  It does not diagnose.  It runs no ``gh``
-call, re-derives no gate, and consults no live state that the tick has not
-already fetched for its own purposes.  Phase 1's read-only diagnostician is a
-separate, later thing whose scope this log exists to *decide*; building it now
-would be guessing at failure modes that #2230/#2229/#2231/#2234 have just
-stopped producing.
+**What the RECORDER is emphatically NOT.**  The writer above does not
+diagnose.  It runs no ``gh`` call, re-derives no gate, and consults no live
+state that the tick has not already fetched for its own purposes.
+
+**Phase 1 (#2276) fills the column Phase 0 cannot.**  ``true_cause`` is empty
+on every ``enter`` record — at that instant nobody knows it — and on ``exit``
+it is derived from *the release the queue itself performed*, which is still
+the queue talking about itself.  #2235's finding is that the queue is wrong
+about this five times out of seven.  So :mod:`coord.queue_diagnose` re-derives
+the cause from live state and appends a third record shape here,
+:data:`EVENT_DIAGNOSIS`, which :func:`episodes` folds onto the open episode as
+its ``true_cause``.  That module owns the *deriving*; this one owns the
+*record*, the pairing, and the honesty accounting — how often the derived
+cause later agreed with how the episode actually resolved
+(:func:`agreement_for`), reported as a rate rather than assumed
+(:func:`summarize`).  A diagnostician that is confidently wrong is worse than
+one that abstains, which is why ``unknown`` is counted separately from
+``disagreed`` and never folded into it.
 
 **Recording must never change a decision.**  Every public entry point here is
 best-effort and swallows its own exceptions (:func:`record`), for the same
@@ -65,10 +77,17 @@ from coord.drive_queue import (
 _log = logging.getLogger(__name__)
 
 __all__ = [
+    "AGREEMENT_ABSTAINED",
+    "AGREEMENT_AGREED",
+    "AGREEMENT_DISAGREED",
+    "AGREEMENT_UNDECIDED",
+    "EVENT_DIAGNOSIS",
     "EVENT_ENTER",
     "EVENT_RESOLVE",
     "STALL_STATES",
+    "agreement_for",
     "block_log_path",
+    "diagnosis_event",
     "enter_event",
     "episodes",
     "operator_resolution_event",
@@ -86,6 +105,13 @@ STALL_STATES: frozenset[str] = frozenset({STATE_BLOCKED, STATE_PARKED})
 
 EVENT_ENTER = "enter"
 EVENT_RESOLVE = "resolve"
+#: #2276 Phase 1.  A read-only re-derivation of an OPEN episode's cause, from
+#: live state rather than from the queue's own stated reason.  Appended to the
+#: same file rather than a new store for the same reason `enter`/`resolve` are
+#: two records and not one mutated row: the writer stays an O(1) append with
+#: no read-modify-write race, and a later diagnosis that contradicts an earlier
+#: one stays visible instead of overwriting it.
+EVENT_DIAGNOSIS = "diagnosis"
 
 # Rotate at 4 MiB — comfortably more than two weeks at this fleet's rate
 # (single-digit stalls a night, ~400 bytes a record), and small enough that
@@ -444,6 +470,109 @@ def operator_resolution_event(
     return record
 
 
+# ── #2276 Phase 1: the diagnosis record, and scoring it ──────────────────────
+
+
+def diagnosis_event(
+    *,
+    key: str,
+    state: str,
+    stated_reason: str,
+    true_cause: str,
+    cause: str,
+    confidence: str,
+    evidence: Sequence[str] = (),
+    contradicts_stated: bool = False,
+    trigger: str = "",
+    host: str = "",
+    now: float | None = None,
+) -> dict[str, Any]:
+    """A ``diagnosis`` record for one still-open stall.
+
+    Deliberately NOT a ``resolve``: the entry is still stalled, and a record
+    that closed the episode would make an observation look like an outcome —
+    which is the exact conflation (*a stated reason read as a cause*) this
+    whole plan exists to undo.  :func:`episodes` folds it onto the open
+    episode instead, so ``coord drive-queue block-log`` shows a populated
+    ``true_cause`` where it previously showed ``(unresolved)`` while the
+    episode itself stays open.
+
+    ``human_acted`` is absent on purpose rather than ``False``: Phase 1 acts on
+    nothing and knows nothing about what a human did, and a ``False`` here
+    would be counted by :func:`summarize` as an auto-release that never
+    happened.
+
+    Every argument is a plain scalar so this module needs no import from
+    :mod:`coord.queue_diagnose` — the recorder must not depend on the thing it
+    records.
+    """
+    return {
+        "event": EVENT_DIAGNOSIS,
+        "ts": time.time() if now is None else now,
+        "key": key,
+        "state": state,
+        # VERBATIM, same contract as `_enter_record`: the comparison between
+        # this and `true_cause` below IS the deliverable.
+        "stated_reason": stated_reason,
+        "true_cause": true_cause,
+        "cause": cause,
+        "confidence": confidence,
+        "evidence": [str(line) for line in evidence],
+        "contradicts_stated": bool(contradicts_stated),
+        "trigger": trigger,
+        "host": host,
+        "source": "diagnostician",
+    }
+
+
+AGREEMENT_AGREED = "agreed"
+AGREEMENT_DISAGREED = "disagreed"
+#: The diagnosis said ``unknown``.  A first-class verdict with NO penalty:
+#: #2276 is explicit that a diagnostician which abstains is better than one
+#: that guesses, so this is counted apart from `disagreed` and kept out of the
+#: disagreement rate's denominator entirely.
+AGREEMENT_ABSTAINED = "abstained"
+#: The RESOLUTION is the unknown one.  `operator-intervened` says in as many
+#: words that what the human fixed is not recorded, so scoring a diagnosis
+#: against it would be scoring it against noise.
+AGREEMENT_UNDECIDED = "undecided"
+
+#: ``resolve``-side cause slug -> the diagnosis causes that agree with it.
+#: Keyed on the slug before the first " — ", the same split
+#: :func:`summarize` buckets on.  A resolution absent from this table is
+#: undecidable, not a disagreement — see :data:`AGREEMENT_UNDECIDED`.
+_AGREEING_CAUSES: dict[str, frozenset[str]] = {
+    "already-landed": frozenset({"pr-merged", "pr-closed"}),
+    "gate-cleared-after-giveup": frozenset(
+        {"nothing-blocking", "ci-green", "ci-pending"}
+    ),
+    "ci-reported": frozenset({"nothing-blocking", "ci-green", "ci-pending"}),
+    "unrefreshable-reading": frozenset({"nothing-blocking", "ci-green", "no-pr"}),
+}
+
+
+def agreement_for(diagnosed_cause: str, resolution_cause: str) -> str:
+    """Did Phase 1's derived cause match how the episode actually ended?
+
+    #2235's stated route to Phase 2 is *"run it read-only and check whether
+    its diagnosis matches what the human actually did"*, so this comparison
+    is a deliverable, not a follow-up.  It is deliberately conservative in
+    both directions: an unrecognised resolution scores ``undecided`` rather
+    than being counted as a win, and an ``unknown`` diagnosis scores
+    ``abstained`` rather than being counted as a loss.
+    """
+    diagnosed = str(diagnosed_cause or "").split(" — ")[0]
+    resolved = str(resolution_cause or "").split(" — ")[0]
+    if not diagnosed:
+        return ""
+    if diagnosed == "unknown":
+        return AGREEMENT_ABSTAINED
+    agreeing = _AGREEING_CAUSES.get(resolved)
+    if agreeing is None:
+        return AGREEMENT_UNDECIDED
+    return AGREEMENT_AGREED if diagnosed in agreeing else AGREEMENT_DISAGREED
+
+
 # ── persistence (best-effort, never raises) ──────────────────────────────────
 
 
@@ -543,6 +672,17 @@ def episodes(events: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
     A ``resolve`` with no preceding ``enter`` (the log started mid-stall) is
     dropped rather than synthesised: an episode whose stated reason is
     unknown cannot answer the one question this log exists to answer.
+
+    A ``diagnosis`` (#2276 Phase 1) folds onto the open episode: it fills
+    ``true_cause`` — the column Phase 0 leaves empty and ``summarize`` buckets
+    as ``(unresolved)`` — without closing the episode, because the entry is
+    still stalled.  A diagnosis for a key with no open episode is dropped for
+    the same reason an orphan ``resolve`` is: there is nothing to attach it
+    to, and inventing the episode would fabricate a stated reason to compare
+    against.  Once the episode resolves, ``true_cause`` reverts to the
+    resolution's own account of what happened and the derived one is kept
+    beside it as ``diagnosed_cause``, so ``agreement`` scores two independent
+    claims rather than one claim against itself.
     """
     open_by_key: dict[str, dict[str, Any]] = {}
     out: list[dict[str, Any]] = []
@@ -571,21 +711,54 @@ def episodes(events: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
                 "human_acted": None,
                 "resolved_at": None,
                 "stalled_seconds": None,
+                # #2276 Phase 1.  `diagnoses` is what `needs_diagnosis` spends
+                # against the attempt budget, so it has to survive a restart —
+                # which it does, being recounted from the log every read
+                # rather than held in memory.
+                "diagnoses": 0,
+                "diagnosed_cause": "",
+                "diagnosis_confidence": "",
+                "diagnosis_evidence": [],
+                "diagnosis_contradicts_stated": False,
+                "agreement": "",
             }
+        elif kind == EVENT_DIAGNOSIS:
+            episode = open_by_key.get(key)
+            if episode is None:
+                continue
+            cause = str(event.get("cause") or "")
+            episode.update(
+                {
+                    "diagnoses": int(episode.get("diagnoses") or 0) + 1,
+                    "diagnosed_cause": cause,
+                    "diagnosis_confidence": str(event.get("confidence") or ""),
+                    "diagnosis_evidence": list(event.get("evidence") or []),
+                    "diagnosis_contradicts_stated": bool(
+                        event.get("contradicts_stated")
+                    ),
+                    # The whole point of the column: an OPEN episode now has a
+                    # cause where it used to have "".
+                    "true_cause": str(event.get("true_cause") or ""),
+                }
+            )
         elif kind == EVENT_RESOLVE:
             episode = open_by_key.pop(key, None)
             if episode is None:
                 continue
             resolved_at = float(event.get("ts") or 0.0)
+            resolution_cause = str(event.get("true_cause") or "")
             episode.update(
                 {
                     "resolved": True,
                     "resolution": event.get("resolution", ""),
-                    "true_cause": event.get("true_cause", ""),
+                    "true_cause": resolution_cause,
                     "human_acted": bool(event.get("human_acted")),
                     "resolved_at": resolved_at,
                     "stalled_seconds": max(0.0, resolved_at - episode["entered_at"]),
                     "source": event.get("source", ""),
+                    "agreement": agreement_for(
+                        str(episode.get("diagnosed_cause") or ""), resolution_cause
+                    ),
                 }
             )
             out.append(episode)
@@ -608,6 +781,17 @@ def summarize(items: Sequence[Mapping[str, Any]]) -> dict[str, Any]:
     than once.  The issue's framing — *a repeat is a bug report, not a
     success* — needs that count visible from day one, or the trend line has
     nothing to be checked against.
+
+    ``diagnosis`` is #2276's own success criterion, and it is reported as a
+    measurement rather than an assertion.  ``disagreement_rate`` is
+    ``disagreed / (agreed + disagreed)`` and is ``None`` — not ``0.0`` — when
+    nothing scorable has resolved yet, because a rate of zero out of zero
+    reads as a perfect record.  ``abstained`` sits outside that fraction
+    entirely: #2276 makes ``unknown`` a first-class verdict with no penalty,
+    and putting it in the denominator would penalise it.  ``contradicted``
+    counts the episodes where the live evidence positively ruled the queue's
+    stated reason out — the five-of-seven number, finally measured instead of
+    reconstructed by hand.
     """
     by_state: dict[str, int] = {}
     by_cause: dict[str, int] = {}
@@ -615,7 +799,17 @@ def summarize(items: Sequence[Mapping[str, Any]]) -> dict[str, Any]:
     human = 0
     auto = 0
     still_open = 0
+    diagnosed = 0
+    contradicted = 0
+    agreement_counts: dict[str, int] = {}
     for item in items:
+        if item.get("diagnosed_cause"):
+            diagnosed += 1
+            if item.get("diagnosis_contradicts_stated"):
+                contradicted += 1
+            verdict = str(item.get("agreement") or "")
+            if verdict:
+                agreement_counts[verdict] = agreement_counts.get(verdict, 0) + 1
         state = str(item.get("state") or "?")
         by_state[state] = by_state.get(state, 0) + 1
         if not item.get("resolved"):
@@ -639,6 +833,9 @@ def summarize(items: Sequence[Mapping[str, Any]]) -> dict[str, Any]:
         for (repo, stated), count in sorted(seen_pairs.items())
         if count > 1
     }
+    agreed = agreement_counts.get(AGREEMENT_AGREED, 0)
+    disagreed = agreement_counts.get(AGREEMENT_DISAGREED, 0)
+    scored = agreed + disagreed
     return {
         "episodes": len(items),
         "by_state": by_state,
@@ -647,4 +844,13 @@ def summarize(items: Sequence[Mapping[str, Any]]) -> dict[str, Any]:
         "auto_released": auto,
         "open": still_open,
         "repeat_causes": repeats,
+        "diagnosis": {
+            "diagnosed": diagnosed,
+            "contradicted_stated_reason": contradicted,
+            "agreed": agreed,
+            "disagreed": disagreed,
+            "abstained": agreement_counts.get(AGREEMENT_ABSTAINED, 0),
+            "undecided": agreement_counts.get(AGREEMENT_UNDECIDED, 0),
+            "disagreement_rate": (disagreed / scored) if scored else None,
+        },
     }

{code_coordinator-0.5.97 → code_coordinator-0.5.99}/coord/commands/drive_queue.py

@@ -928,7 +928,26 @@ def _episode_line(item: Mapping[str, Any]) -> str:
     if len(stated) > 90:
         stated = stated[:87] + "..."
     if not item.get("resolved"):
-        return f"{key:<28} {state:<8} STILL STALLED  stated: {stated}"
+        line = f"{key:<28} {state:<8} STILL STALLED  stated: {stated}"
+        # #2276 Phase 1.  An open episode used to have nothing in the `cause`
+        # column at all — `summarize` bucketed it as `(unresolved)`. When the
+        # diagnostician has been round, it does, and the CONTRADICTS marker is
+        # what makes #2235's five-of-seven finding legible at a glance instead
+        # of requiring the reader to hold both strings in their head.
+        cause = " ".join(str(item.get("true_cause") or "").split())
+        if cause:
+            flag = (
+                "  ← CONTRADICTS the stated reason"
+                if item.get("diagnosis_contradicts_stated")
+                else ""
+            )
+            confidence = str(item.get("diagnosis_confidence") or "?")
+            line += (
+                f"\n{'':<28} {'':<8}               cause:  {cause}"
+                f"\n{'':<28} {'':<8}               "
+                f"(diagnosed, confidence {confidence}){flag}"
+            )
+        return line
     mark = "HUMAN" if item.get("human_acted") else "auto "
     held = item.get("stalled_seconds")
     age = _age_str(float(held)) if held is not None else "?"
@@ -962,10 +981,15 @@ def drive_queue_block_log(output_json: bool, days: float, config_path: Path) ->
     how often did a human have to act?" is answered from two weeks of evidence
     rather than from one morning's triage.
 
-    Nothing here diagnoses. `cause` is derived from the release the queue
-    itself performed (a #2230 gate-clear, a #1891 CI resume, an operator's
-    `remove`), never from a live re-check — that is Phase 1, and its scope is
-    supposed to be decided BY this data, not assumed ahead of it.
+    This command itself does not diagnose — it renders what other passes
+    recorded. For a *resolved* episode, `cause` is still derived from the
+    release the queue itself performed (a #2230 gate-clear, a #1891 CI
+    resume, an operator's `remove`), never from a live re-check. For a
+    still-open episode, `cause` may instead be a Phase 1 (#2276) live
+    re-check's verdict — `coord drive-queue diagnose` or the notifier tick's
+    `diagnose_pass` recorded it as a `diagnosis` event, and `_episode_line`
+    renders it with a `(diagnosed, confidence ...)` tag so it reads distinct
+    from a resolution-derived cause.
 
     Read the two summary numbers together: `human_acted` is the count #2235
     wants to see fall, but a queue that stops needing interventions by leaving
@@ -1014,6 +1038,225 @@ def drive_queue_block_log(output_json: bool, days: float, config_path: Path) ->
             stats["repeat_causes"].items(), key=lambda kv: (-kv[1], kv[0])
         ):
             click.echo(f"  {count}× {label}")
+    for line in _diagnosis_summary_lines(stats.get("diagnosis") or {}):
+        click.echo(line)
+
+
+def _diagnosis_summary_lines(diag: Mapping[str, Any]) -> list[str]:
+    """#2276's success criterion, rendered as a measurement.
+
+    The disagreement rate is printed as ``(not yet measurable)`` rather than
+    ``0%`` until something scorable has resolved, because #2276 is explicit
+    that the number must be *measured, not assumed* — and "0% wrong out of
+    nothing" is the most flattering way there is to assume it.
+    """
+    if not diag.get("diagnosed"):
+        return []
+    lines = [
+        f"diagnosed {diag['diagnosed']} stall(s) — "
+        f"{diag.get('contradicted_stated_reason', 0)} contradicted the stated reason"
+    ]
+    rate = diag.get("disagreement_rate")
+    scored = f"{diag.get('agreed', 0)} agreed · {diag.get('disagreed', 0)} disagreed"
+    tail = (
+        f"{rate * 100:.0f}% disagreement"
+        if rate is not None
+        else "disagreement rate: (not yet measurable — nothing scorable has resolved)"
+    )
+    lines.append(f"  vs. how they actually resolved: {scored} — {tail}")
+    lines.append(
+        f"  {diag.get('abstained', 0)} abstained (said unknown, which is not a "
+        f"failure) · {diag.get('undecided', 0)} unscorable"
+    )
+    return lines
+
+
+# ── diagnose (#2276 Phase 1) ─────────────────────────────────────────────────
+
+
+def _diagnosis_lines(diagnosis: Any) -> list[str]:
+    """One diagnosis, rendered.  ``stated`` and ``cause`` adjacent, as ever."""
+    flag = " ← CONTRADICTS the stated reason" if diagnosis.contradicts_stated else ""
+    trigger = f"  (triggered by: {diagnosis.trigger})" if diagnosis.trigger else ""
+    lines = [
+        f"{diagnosis.key} [{diagnosis.state}]{trigger}",
+        f"  stated: {' '.join((diagnosis.stated_reason or '(none)').split())}",
+        f"  cause:  {diagnosis.cause} (confidence {diagnosis.confidence}){flag}",
+    ]
+    if diagnosis.abstained:
+        lines.append(
+            "          unknown is a verdict, not a failure — the evidence "
+            "below was too thin to name a cause"
+        )
+    lines.append("  evidence:")
+    lines.extend(f"    - {line}" for line in diagnosis.evidence)
+    return lines
+
+
+@drive_queue_group.command("diagnose")
+@click.option("--json", "output_json", is_flag=True, default=False, help="Emit diagnoses as JSON.")
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Derive and print, but do not append the diagnosis to the block log.",
+)
+@_CONFIG_OPTION
+def drive_queue_diagnose(output_json: bool, dry_run: bool, config_path: Path) -> None:
+    """Re-derive the REAL blocker of every still-stalled entry (#2276 Phase 1).
+
+    Read-only. It runs no `coord merge`, dispatches nothing, and writes nothing
+    to the board or the queue — its single output is a `diagnosis` record in
+    the Phase-0 block log, which no decision path reads.
+
+    The queue's stated reason is an INPUT TO BE CONTRADICTED, never a starting
+    hypothesis: #2235 found that five of seven overnight stalls named a symptom
+    rather than a cause, so this asks GitHub, the live gate report and the
+    agent's /health what is actually true right now, and only then checks
+    whether the evidence still supports what the queue said.
+
+    `unknown` is a first-class verdict. Thin evidence gets an abstention, not a
+    guess — a confidently wrong cause is worse than no cause, because #2268's
+    Phase 2 would inherit the confidence.
+
+    It runs here, and in `coord serve`'s notifier tick, rather than as a
+    dispatched worker: a diagnosis needs `gh`, and `gh` is denied to workers
+    (#1483). The trigger in the daemon is #1632's own stall detector — there is
+    deliberately no second definition of "stalled" anywhere in this path.
+
+    That notifier-tick trigger only fires when `notifications.enabled` is
+    true (`coord.notifier.service._tick` returns before `diagnose_pass` runs
+    otherwise) — notifications are off by default in this repo, so on a
+    fleet that has not turned them on, THIS command is the only live entry
+    point into Phase 1.
+    """
+    from coord import block_log, queue_diagnose  # noqa: PLC0415
+    from coord.board_service import is_remote  # noqa: PLC0415
+    from coord.commands._common import _load_config  # noqa: PLC0415
+
+    # #615/#906 guard: everything this command reads — the Phase-0 block log,
+    # the queue rows, the board handed to GhLiveProbe — lives on the daemon
+    # host, and the probes need `gh` (denied to workers, #1483). On a thin
+    # client all three reads would be silently empty, so the "diagnosis"
+    # would be a confident report about a queue that isn't there. Fail loud
+    # instead (the exact #615 failure mode this audit exists to prevent).
+    if is_remote():
+        raise click.ClickException(
+            "drive-queue diagnose reads the daemon host's block log, queue "
+            "and board directly — run it there (a board_service-configured "
+            "thin client would diagnose an empty queue)."
+        )
+
+    from coord.drive import list_drive_sessions  # noqa: PLC0415
+    from coord.health.aggregate import local_fleet_health_block  # noqa: PLC0415
+    from coord.state import build_board, list_drive_queue  # noqa: PLC0415
+
+    config = _load_config(config_path)
+    episodes = [
+        ep for ep in block_log.episodes(block_log.read_events()) if not ep.get("resolved")
+    ]
+    entries = entries_from_rows(list_drive_queue())
+    # #2276 review: without these two, `GhLiveProbe._health()` short-circuits
+    # to `(None, None, [])` for every entry — `agent_reachable` and
+    # `agent_has_session` are permanently unknown, which makes `dead-leg` and
+    # `agent-unreachable` structurally unreachable verdicts from this command.
+    # Same local-DB read `coord status` uses in host mode (status.py's own
+    # `local_fleet_health_block` call) — no fresh /health round trip, just
+    # the last tick's reported state; and the same `list_drive_sessions()`
+    # this file already calls elsewhere (`_fetch_board_view`) for live tmux
+    # session names.
+    fleet_health = local_fleet_health_block([m.name for m in config.machines])
+    live_sessions = frozenset(
+        str(row["session_name"])
+        for row in list_drive_sessions()
+        if row.get("session_name")
+    )
+    probe = queue_diagnose.GhLiveProbe(
+        config=config,
+        board=build_board(),
+        fleet_health=fleet_health,
+        live_sessions=live_sessions,
+        # #1870: that `list_drive_sessions()` above is a LOCAL tmux read, so
+        # the probe has to know whose tmux it is. Without this an entry some
+        # OTHER machine launched reads as "session absent" here and lands a
+        # high-confidence `dead-leg` on a session that is very much alive —
+        # the same trap `_reconcile_running` already sidesteps.
+        local_host=_local_host_id(),
+    )
+    # `keys=None` — an operator asking directly wants every open episode
+    # looked at, not just the ones the notifier happens to have raised this
+    # minute. `limit=None` for the same reason, and because the per-pass cap
+    # exists to protect `coord serve`'s 30 s tick, which this is not on: a cap
+    # here would silently diagnose four of ten and print "4 diagnosed", which
+    # reads as "that was all of them". The per-episode budget still applies,
+    # so this cannot become a way to spend `gh` calls in a loop.
+    diagnoses = queue_diagnose.run_pass(
+        entries, episodes, probe=probe, keys=None, limit=None
+    )
+
+    if diagnoses and not dry_run:
+        _record_block_log(
+            [
+                block_log.diagnosis_event(
+                    key=d.key,
+                    state=d.state,
+                    stated_reason=d.stated_reason,
+                    true_cause=d.true_cause,
+                    cause=d.cause,
+                    confidence=d.confidence,
+                    evidence=d.evidence,
+                    contradicts_stated=d.contradicts_stated,
+                    trigger=d.trigger,
+                    host=_local_host_id(),
+                )
+                for d in diagnoses
+            ]
+        )
+
+    if output_json:
+        click.echo(
+            _json.dumps(
+                {
+                    "recorded": bool(diagnoses) and not dry_run,
+                    "diagnoses": [
+                        {
+                            "key": d.key,
+                            "state": d.state,
+                            "stated_reason": d.stated_reason,
+                            "cause": d.cause,
+                            "true_cause": d.true_cause,
+                            "confidence": d.confidence,
+                            "evidence": list(d.evidence),
+                            "contradicts_stated": d.contradicts_stated,
+                            "trigger": d.trigger,
+                        }
+                        for d in diagnoses
+                    ],
+                }
+            )
+        )
+        return
+
+    if not diagnoses:
+        click.echo(
+            "nothing to diagnose: no open stall episode is both unexplained and "
+            "still within its diagnosis budget"
+        )
+        return
+    for diagnosis in diagnoses:
+        for line in _diagnosis_lines(diagnosis):
+            click.echo(line)
+        click.echo("")
+    contradicted = sum(1 for d in diagnoses if d.contradicts_stated)
+    abstained = sum(1 for d in diagnoses if d.abstained)
+    click.echo(
+        f"{len(diagnoses)} diagnosed — {contradicted} contradicted the stated "
+        f"reason · {abstained} abstained (unknown)"
+    )
+    click.echo(
+        "nothing was mutated; read the outcome later with "
+        "`coord drive-queue block-log`"
+    )
 
 
 # ── overlap-report (#2247) ───────────────────────────────────────────────────