code-coordinator 0.5.301__tar.gz → 0.5.302__tar.gz

{code_coordinator-0.5.301 → code_coordinator-0.5.302}/PKG-INFO

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

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

@@ -248,6 +248,7 @@ coord/health/checks/timer_active.py
 coord/health/checks/toolchain.py
 coord/health/checks/unit_drift.py
 coord/health/checks/unit_enablement.py
+coord/health/checks/wedged_drive_queue.py
 coord/health/checks/worktrees.py
 coord/notifier/__init__.py
 coord/notifier/baseline.py
@@ -601,6 +602,7 @@ tests/test_health_timer_active.py
 tests/test_health_toolchain.py
 tests/test_health_unit_drift.py
 tests/test_health_unit_enablement.py
+tests/test_health_wedged_drive_queue.py
 tests/test_hooks.py
 tests/test_human_attended_437.py
 tests/test_init.py

{code_coordinator-0.5.301 → code_coordinator-0.5.302}/code_coordinator.egg-info/scm_file_list.json

@@ -165,6 +165,7 @@
     "coord/health/checks/toolchain.py",
     "coord/health/checks/unit_drift.py",
     "coord/health/checks/unit_enablement.py",
+    "coord/health/checks/wedged_drive_queue.py",
     "coord/health/checks/worktrees.py",
     "coord/health/cli.py",
     "coord/health/context.py",
@@ -627,6 +628,7 @@
     "tests/test_health_toolchain.py",
     "tests/test_health_unit_drift.py",
     "tests/test_health_unit_enablement.py",
+    "tests/test_health_wedged_drive_queue.py",
     "tests/test_hooks.py",
     "tests/test_human_attended_437.py",
     "tests/test_init.py",

{code_coordinator-0.5.301 → code_coordinator-0.5.302}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.301",
+  "tag": "0.5.302",
   "distance": 0,
-  "node": "g26f7e1b979b278db2f5c5a9a510debee5bb45a0a",
+  "node": "g4db839a79669e9ada2d3461267662cb4cefd6e52",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-30"

{code_coordinator-0.5.301 → code_coordinator-0.5.302}/coord/commands/drive_queue.py

@@ -72,6 +72,7 @@ from coord.drive_queue import (
     TickPlan,
     add_preflight_notice,
     build_board_view,
+    detect_unreachable_waits,
     diagnose_blocked_after,
     effective_max_fix_rounds,
     entries_from_rows,
@@ -87,6 +88,7 @@ from coord.drive_queue import (
     pending_probe_targets,
     plan_tick,
     render_plan,
+    unreachable_wait_alert,
     validate_enqueue,
 )
 from coord.overlap_predict import (
@@ -1523,6 +1525,30 @@ def _queue_alert() -> dict | None:
     return get_drive_escalation(QUEUE_ALERT_REPO, QUEUE_ALERT_ISSUE)
 
 
+def _unreachable_wait_alert_dict(rows: list[Mapping[str, Any]]) -> dict | None:
+    """#2944's synthetic queue-level alert, or ``None`` when nothing qualifies.
+
+    Computed fresh from the CURRENT queue rows on every call — deliberately
+    independent of :func:`_queue_alert`'s per-tick escalation record, which a
+    busy queue overwrites (and clears — see the tick's own ``else:
+    _clear_queue_alert()`` branch) every single tick it finds *something*
+    else to launch. A wedged entry with `attempts=0` sits in `blocked`/
+    `parked` for as long as it likes regardless of what else the queue is
+    doing, so its visibility must not depend on a tick ever having nothing
+    better to report — see :func:`coord.drive_queue.detect_unreachable_waits`
+    for the predicate and the #2900/#2907 incident this closes.
+    """
+    waits = detect_unreachable_waits(entries_from_rows(rows))
+    if not waits:
+        return None
+    synthetic = unreachable_wait_alert(waits)
+    return {
+        "reason": synthetic.reason,
+        "gate_readings": " | ".join(synthetic.details),
+        "proposed_command": synthetic.command,
+    }
+
+
 @drive_queue_group.command("status")
 @click.option("--json", "output_json", is_flag=True, default=False, help="Emit counts + alert as JSON.")
 @_CONFIG_OPTION
@@ -1532,7 +1558,13 @@ def drive_queue_status(output_json: bool, config_path: Path) -> None:
 
     rows = list_drive_queue()
     counts = _counts(rows)
-    alert = _queue_alert()
+    # #2944: a tick-raised alert (a HELD gate, "nothing eligible to launch")
+    # takes priority when one exists — it is fresher and, on a busy queue,
+    # `_unreachable_wait_alert_dict` would silently win-and-hide it every
+    # time a real, actionable alert IS present. Only when the tick has
+    # nothing to say (the common, dangerous case a queue with free slots
+    # sits in for hours) does the guaranteed-false-wait check get to speak.
+    alert = _queue_alert() or _unreachable_wait_alert_dict(rows)
     held = fired_holds(entries_from_rows(rows))
     # #2587: read directly from the marker file, not from the last tick's
     # `TickPlan` — `status` may run between ticks (or on a machine that never

{code_coordinator-0.5.301 → code_coordinator-0.5.302}/coord/drive_queue.py

@@ -2260,6 +2260,129 @@ def is_unsatisfiable_prereq_reason(text: str | None) -> bool:
     return _is_unsatisfiable_prereq_reason(text)
 
 
+# ── #2944: the guaranteed-false wait ─────────────────────────────────────────
+#
+# An entry with `attempts == 0` has never been dispatched: no `coord drive`
+# ever ran for it, so it has no branch, no PR, and no merge-queue row — and
+# never can have one, because nothing was ever built. A `blocked` or `parked`
+# entry in that state is not waiting on a gate that MIGHT clear; it is
+# waiting on a gate that structurally cannot exist. Whatever swept this row
+# last (#2230's merge-gate probe, #2935's after= graph, anything future)
+# cannot ever answer "yes" for it — the only exit is an operator's `remove` +
+# `add`.
+#
+# Deliberately independent of #2935/#2230: those fix (or will fix) individual
+# sweeps so they stop MISTAKING this shape for a real probe target. This
+# predicate does not care which sweep produced the block, or whether one
+# exists at all — it is the backstop that makes the NEXT undiscovered
+# instance of "a sweep declines to guess and therefore never terminates"
+# visible, instead of silent for another 32 hours (claude-coordinator#2900/
+# #2907: 207 and 186 deferrals, 0 attempts, ~10h and 22.7h blocked
+# respectively, `alert: (none)` the entire time — see #2944).
+#
+# `min_deferrals` is grace, not evidence: `deferrals` on a `blocked`/`parked`
+# row is whatever it had accumulated before the transition (subsequent ticks
+# do not bump it further — neither `_reconcile_blocked` nor
+# `_reconcile_blocked_unreadable` touches `deferrals`), so a fresh entry that
+# races straight from `waiting` to `blocked` on its very first tick reads
+# `deferrals=0` here regardless of how long it then sits. ~5 ticks (~15
+# minutes at the fleet's ~3-minute cadence) is enough that a row flagged here
+# has genuinely been sitting, not merely landed there this instant.
+UNREACHABLE_WAIT_MIN_DEFERRALS = 5
+
+
+@dataclass(frozen=True)
+class UnreachableWait:
+    """One queue entry stuck in the #2944 guaranteed-false wait.
+
+    See :func:`detect_unreachable_waits` for the predicate. Carries just
+    enough for a caller to build an operator-facing message without
+    re-deriving anything: the key names the entry, `deferrals` is the
+    evidence a genuine transient wouldn't have, and `last_reason` is
+    whatever the last sweep to touch this row recorded — useful context,
+    never re-interpreted here.
+    """
+
+    key: str
+    state: str
+    deferrals: int
+    last_reason: str
+
+
+def detect_unreachable_waits(
+    entries: Iterable[QueueEntry],
+    *,
+    min_deferrals: int = UNREACHABLE_WAIT_MIN_DEFERRALS,
+) -> list[UnreachableWait]:
+    """Entries sitting in the #2944 guaranteed-false wait.
+
+    ``state in (blocked, parked) AND attempts == 0 AND deferrals >
+    min_deferrals`` — see the module comment above this function for why
+    that combination can never resolve itself. Pure and cheap (a predicate
+    over already-loaded rows, no clock, no I/O), so the same function backs
+    both `coord drive-queue status`'s `alert:` line
+    (`coord.commands.drive_queue._queue_alert`) and the `coord doctor` WARN
+    (`coord.health.checks.wedged_drive_queue`) — one definition of "wedged",
+    not two that could drift apart.
+
+    An entry with ``attempts > 0`` is excluded unconditionally, however long
+    it has sat: it WAS dispatched at least once, so it has (or had) a real
+    branch/PR/merge-queue row for a sweep to have a genuine opinion about —
+    that is a legitimate wait, not an unreachable one.
+    """
+    return [
+        UnreachableWait(
+            key=e.key, state=e.state, deferrals=e.deferrals, last_reason=e.last_reason
+        )
+        for e in entries
+        if e.state in (STATE_BLOCKED, STATE_PARKED)
+        and e.attempts == 0
+        and e.deferrals > min_deferrals
+    ]
+
+
+def unreachable_wait_alert(waits: Sequence[UnreachableWait]) -> QueueAlert:
+    """The queue-level record #2944's predicate raises, in :func:`_hold_alert`'s
+    shape — a message naming the entry (or entries), the deferral count that
+    is the evidence, and the ONE remedy that actually clears it.
+
+    ``add`` alone does not clear ``blocked`` (the queue list already
+    documents this as a footgun elsewhere) — only ``remove`` then ``add``
+    does, so that is the command surfaced here rather than the generic
+    ``coord drive-queue list`` other alerts fall back on; naming the wrong
+    remedy on a state this non-obvious defeats the point of alerting at all.
+    Named INLINE in ``reason`` (not only in ``command``, which
+    ``drive-queue status``'s plain-text rendering never echoes — only its
+    ``gate_readings``/``details`` lines are printed) so the remedy is visible
+    wherever this alert's ``reason`` is, not just to a caller that also reads
+    the structured field.
+    """
+    names = ", ".join(
+        f"{w.key} ({w.state}, {w.deferrals} deferrals)" for w in waits[:5]
+    )
+    more = ", ..." if len(waits) > 5 else ""
+    plural = len(waits) != 1
+    return QueueAlert(
+        reason=(
+            f"{len(waits)} queue entr{'ies' if plural else 'y'} stuck in a "
+            "guaranteed-false wait — never dispatched (attempts=0) yet "
+            f"blocked/parked past {UNREACHABLE_WAIT_MIN_DEFERRALS} deferrals; "
+            f"no sweep can ever clear this on its own: {names}{more}. Fix: "
+            "coord drive-queue remove <repo> <issue> && "
+            "coord drive-queue add <repo> <issue> for each entry named above."
+        ),
+        details=tuple(
+            f"{w.key}: {w.state}, {w.deferrals} deferrals, "
+            f"last_reason={w.last_reason!r}"
+            for w in waits
+        ),
+        command=(
+            "coord drive-queue remove <repo> <issue> && "
+            "coord drive-queue add <repo> <issue> — for each entry named above"
+        ),
+    )
+
+
 def _reconcile_blocked_after(
     entry: QueueEntry,
     board: BoardView,

code_coordinator-0.5.302/coord/health/checks/wedged_drive_queue.py

@@ -0,0 +1,124 @@
+"""Drive-queue entries stuck in a guaranteed-false wait (#2944).
+
+``coord drive-queue status``'s ``alert:`` line is a per-tick record — a busy
+queue with free capacity elsewhere clears it every tick that finds
+*something* to launch (see ``coord.commands.drive_queue._run_tick``'s own
+``else: _clear_queue_alert()`` branch), even while an unrelated entry sits
+wedged for hours. That is exactly what happened to claude-coordinator#2900
+and #2907 on 2026-08-29: both sat ``blocked``, ``attempts=0``, 207 and 186
+deferrals, ~10h and 22.7h respectively — and ``alert: (none)`` read clean the
+entire time, because the rest of the queue kept launching fine.
+
+An entry with ``attempts == 0`` has never been dispatched — no branch, no
+PR, no merge-queue row ever existed for it, and none ever can, because
+nothing was ever built. A ``blocked``/``parked`` entry in that state is not
+waiting on a gate that MIGHT clear; it is waiting on a gate that structurally
+cannot exist. ``coord.drive_queue.detect_unreachable_waits`` is the one
+predicate for that shape (also what backs the ``status`` alert line itself,
+so this check and that line can never say different things) — this probe
+just re-derives it, live, from ``drive_queue`` state every time ``coord
+doctor`` runs, independent of whatever the last tick happened to report.
+
+This is deliberately independent of #2935 (which fixes the specific sweep
+that produced the #2900/#2907 incident) and #2230 (the sweep's origin): both
+are about *why* a row gets wedged this way; this check is about the row
+being wedged *at all*, whatever sweep — present or future — produced it.
+
+WARN, not CRIT: the fix costs an operator ~10 seconds (``coord drive-queue
+remove`` + ``add``) once they know, and this check exists to make sure they
+know — it is not itself an outage.
+
+``cost=COST_NETWORK``, not ``COST_CHEAP``: ``coord.state.list_drive_queue``
+routes to the daemon over HTTP whenever ``board_service`` is set, which is
+the common case on a thin-client fleet machine (same situation
+``release_cordon.py`` documents for its own board-state read) — so this is a
+real network call on most of the fleet, not a local DB read, and must be
+skippable by ``--no-network``/timer runs and the automatic per-agent health
+poll exactly like the other network-costed checks.
+"""
+
+from __future__ import annotations
+
+from coord.health.models import CheckResult, HealthContext, Severity
+from coord.health.registry import COST_NETWORK, check
+
+
+@check(
+    id="wedged_drive_queue",
+    scope="machine",
+    title="wedged drive-queue entries",
+    order=23,
+    cost=COST_NETWORK,
+    description=(
+        "Drive-queue rows in `coord.drive_queue`'s #2944 guaranteed-false "
+        "wait: `blocked`/`parked`, `attempts == 0` (never dispatched — no "
+        "branch, no PR, no merge-queue row ever existed or ever can), "
+        "sitting past a few ticks of grace. Reads via `coord.state."
+        "list_drive_queue`, which — per its own docstring — routes to the "
+        "daemon over HTTP when `board_service` is set (the common case on a "
+        "thin-client fleet machine, see `release_cordon.py`) and only reads "
+        "the local DB directly otherwise; `cost=network` so `--no-network`/"
+        "timer runs and the automatic per-agent health poll skip it exactly "
+        "like the other network-costed checks, same precedent as "
+        "`release_cordon`."
+    ),
+)
+def probe_wedged_drive_queue(ctx: HealthContext) -> CheckResult:
+    del ctx  # unused: this check reads local queue state directly, not config
+    from coord.drive_queue import (  # noqa: PLC0415
+        detect_unreachable_waits,
+        entries_from_rows,
+    )
+    from coord.state import list_drive_queue  # noqa: PLC0415
+
+    try:
+        rows = list_drive_queue()
+        waits = detect_unreachable_waits(entries_from_rows(rows))
+    except Exception as exc:  # noqa: BLE001 — a probe must never raise
+        return CheckResult(
+            check_id="wedged_drive_queue",
+            scope="machine",
+            severity=Severity.UNKNOWN,
+            headroom=f"could not read the drive queue: {exc}",
+            error=str(exc),
+        )
+
+    if not waits:
+        return CheckResult(
+            check_id="wedged_drive_queue",
+            scope="machine",
+            severity=Severity.OK,
+            headroom="0 wedged drive-queue entries",
+        )
+
+    sample = ", ".join(
+        f"{w.key} ({w.state}, {w.deferrals} deferrals)" for w in waits[:5]
+    )
+    return CheckResult(
+        check_id="wedged_drive_queue",
+        scope="machine",
+        severity=Severity.WARN,
+        headroom=(
+            f"{len(waits)} wedged drive-queue entr"
+            f"{'y' if len(waits) == 1 else 'ies'}"
+        ),
+        detail=(
+            f"e.g. {sample}" + (", ..." if len(waits) > 5 else "")
+            + " — never dispatched (attempts=0), cannot clear on its own; "
+            "fix: coord drive-queue remove <repo> <issue> && "
+            "coord drive-queue add <repo> <issue>"
+        ),
+        threshold="warn when any entry is blocked/parked, attempts=0, past a few ticks of grace",
+        values={
+            "count": len(waits),
+            "entries": [
+                {
+                    "key": w.key,
+                    "state": w.state,
+                    "deferrals": w.deferrals,
+                    "last_reason": w.last_reason,
+                }
+                for w in waits
+            ],
+        },
+    )

{code_coordinator-0.5.301 → code_coordinator-0.5.302}/tests/test_cli_drive_queue.py

@@ -3613,6 +3613,83 @@ def test_status_on_an_empty_queue_says_so(cli):
     assert "alert: (none)" in result.output
 
 
+# ── #2944: `status`'s `alert:` line for a guaranteed-false wait ─────────────
+#
+# claude-coordinator#2900/#2907: an entry with `attempts=0` sat `blocked` for
+# 10h/22.7h with `status` reading `alert: (none)` the whole time — because
+# the per-tick alert this line otherwise shows only fires when a tick has
+# NOTHING to launch anywhere, and a busy queue kept launching other entries
+# fine. These drive the real CLI end to end with no tick at all (the alert
+# must be visible from `status` alone, not conditional on ever running one),
+# manipulating only the tick-owned columns a real tick would eventually
+# write, via the same seam `update_drive_queue_entry` uses.
+
+
+def test_status_alert_reports_a_wedged_never_dispatched_blocked_entry(cli):
+    cli("add", REPO, "2900")
+    state._update_drive_queue_entry_local(
+        REPO, 2900, state="blocked", attempts=0, deferrals=207,
+        last_reason="exhausted 2/2 attempts",
+    )
+
+    result = cli("status")
+    assert result.exit_code == 0, result.output
+    assert "alert: (none)" not in result.output
+    assert f"{REPO}#2900" in result.output
+    assert "207 deferrals" in result.output
+    assert "coord drive-queue remove" in result.output
+    assert "coord drive-queue add" in result.output
+
+
+def test_status_alert_json_also_carries_the_wedged_entry(cli):
+    cli("add", REPO, "2900")
+    state._update_drive_queue_entry_local(
+        REPO, 2900, state="blocked", attempts=0, deferrals=207,
+    )
+
+    result = cli("status", "--json")
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["alert"] is not None
+    assert f"{REPO}#2900" in payload["alert"]["reason"]
+    # Same key a tick-raised escalation uses (coord.state's `drive_escalations`
+    # shape — see tests/test_cli_drive_queue.py's other `proposed_command`
+    # assertions) so a JSON consumer of `alert` has one shape regardless of
+    # which of the two sources produced it (#2096).
+    assert "coord drive-queue remove" in payload["alert"]["proposed_command"]
+    assert "coord drive-queue add" in payload["alert"]["proposed_command"]
+    assert "command" not in payload["alert"]
+
+
+def test_status_alert_does_not_trip_for_a_fresh_transient_block(cli):
+    """Below the grace threshold (deferrals), a `blocked attempts=0` entry
+    reads exactly like it did before #2944 — a real alert here on the FIRST
+    tick an entry lands in `blocked` at all would be a false positive, not a
+    signal."""
+    cli("add", REPO, "2901")
+    state._update_drive_queue_entry_local(
+        REPO, 2901, state="blocked", attempts=0, deferrals=2,
+    )
+
+    result = cli("status")
+    assert result.exit_code == 0, result.output
+    assert "alert: (none)" in result.output
+
+
+def test_status_alert_does_not_trip_for_a_real_merge_gate_wait(cli):
+    """`attempts > 0` means the entry WAS dispatched — a long `blocked` wait
+    is a legitimate wait on a real merge gate, never this alert's business."""
+    cli("add", REPO, "2902")
+    state._update_drive_queue_entry_local(
+        REPO, 2902, state="blocked", attempts=2, deferrals=500,
+        last_reason="merge gate still shut",
+    )
+
+    result = cli("status")
+    assert result.exit_code == 0, result.output
+    assert "alert: (none)" in result.output
+
+
 # ── deploy gates (#1757) ─────────────────────────────────────────────────────
 #
 # The acceptance bar for `--hold-after`.  `merged != live`: a queue that

{code_coordinator-0.5.301 → code_coordinator-0.5.302}/tests/test_drive_queue.py

@@ -27,18 +27,21 @@ from coord.drive_queue import (
     HOLD_SCOPE_ENTRY,
     HOLD_SCOPE_FLEET,
     PARK_STALE_SECONDS,
-    ProbeResult,
     STATE_BLOCKED,
     STATE_DONE,
     STATE_FAILED,
+    STATE_PARKED,
     STATE_RUNNING,
     STATE_WAITING,
+    UNREACHABLE_WAIT_MIN_DEFERRALS,
     BoardView,
     IssueFacts,
+    ProbeResult,
     QueueEntry,
     QueueError,
     add_preflight_notice,
     build_board_view,
+    detect_unreachable_waits,
     entries_from_rows,
     entry_key,
     find_cycle,
@@ -47,6 +50,7 @@ from coord.drive_queue import (
     parse_key,
     plan_tick,
     render_plan,
+    unreachable_wait_alert,
     validate_enqueue,
 )
 from coord.models import MERGE_LANDED_MARKER
@@ -5131,3 +5135,80 @@ def test_a_running_entrys_ordinary_death_gets_no_zero_commit_note():
 def test_is_empty_branch_death_reason_matches_the_drive_advisory_text():
     assert is_empty_branch_death_reason(_EMPTY_BRANCH_REASON) is True
     assert is_empty_branch_death_reason(None) is False
+
+
+# ── #2944: the guaranteed-false wait — `state ∈ {blocked, parked}`, ─────────
+# `attempts == 0`, past the grace window. See claude-coordinator#2900/#2907:
+# both sat this way for 10h/22.7h with `coord drive-queue status` reading
+# `alert: (none)` the entire time, because nothing was ever launched for
+# them, so no sweep — #2230's merge-gate probe included — could ever have
+# anything positive to report.
+
+
+def test_detect_unreachable_waits_flags_a_never_dispatched_blocked_entry():
+    stuck = entry(
+        2900,
+        state=STATE_BLOCKED,
+        attempts=0,
+        deferrals=207,
+        last_reason="exhausted 2/2 attempts",
+    )
+    waits = detect_unreachable_waits([stuck])
+    assert [w.key for w in waits] == [entry_key(REPO, 2900)]
+    assert waits[0].deferrals == 207
+    assert waits[0].state == STATE_BLOCKED
+
+
+def test_detect_unreachable_waits_flags_a_never_dispatched_parked_entry():
+    # `parked` realistically implies `attempts > 0` (a park is only ever set
+    # after a real merge attempt), but the predicate is defined over the
+    # state alone — see the module docstring on why this checks the SHAPE,
+    # not the mechanism that is known to produce it today.
+    stuck = entry(2907, state=STATE_PARKED, attempts=0, deferrals=186)
+    waits = detect_unreachable_waits([stuck])
+    assert [w.key for w in waits] == [entry_key(REPO, 2907)]
+
+
+def test_detect_unreachable_waits_does_not_trip_below_the_grace_threshold():
+    """A genuinely transient block — freshly blocked, few deferrals — must
+    not trip: that would false-positive on the very first tick a `waiting`
+    entry lands in `blocked` at all."""
+    fresh = entry(1, state=STATE_BLOCKED, attempts=0, deferrals=0)
+    at_threshold = entry(
+        2, state=STATE_BLOCKED, attempts=0, deferrals=UNREACHABLE_WAIT_MIN_DEFERRALS
+    )
+    assert detect_unreachable_waits([fresh, at_threshold]) == []
+    just_past = entry(
+        3,
+        state=STATE_BLOCKED,
+        attempts=0,
+        deferrals=UNREACHABLE_WAIT_MIN_DEFERRALS + 1,
+    )
+    assert [w.key for w in detect_unreachable_waits([just_past])] == [
+        entry_key(REPO, 3)
+    ]
+
+
+def test_detect_unreachable_waits_does_not_trip_for_a_real_attempt():
+    """`attempts > 0` means the entry WAS dispatched at least once — it has
+    (or had) a real branch/PR/merge-queue row, so a long `blocked` wait is a
+    legitimate wait on a real gate, not an unreachable one."""
+    real_attempt = entry(4, state=STATE_BLOCKED, attempts=1, deferrals=500)
+    assert detect_unreachable_waits([real_attempt]) == []
+
+
+def test_detect_unreachable_waits_ignores_waiting_and_running_states():
+    waiting = entry(5, state=STATE_WAITING, attempts=0, deferrals=500)
+    running = entry(6, state=STATE_RUNNING, attempts=0, deferrals=500)
+    assert detect_unreachable_waits([waiting, running]) == []
+
+
+def test_unreachable_wait_alert_names_the_entry_deferrals_and_remedy():
+    waits = detect_unreachable_waits(
+        [entry(2900, state=STATE_BLOCKED, attempts=0, deferrals=207)]
+    )
+    alert = unreachable_wait_alert(waits)
+    assert f"{REPO}#2900" in alert.reason
+    assert "207 deferrals" in alert.reason
+    assert "coord drive-queue remove" in alert.command
+    assert "coord drive-queue add" in alert.command