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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.301
+Version: 0.5.303
 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.303}/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.303}/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.303}/code_coordinator.egg-info/scm_version.json

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

{code_coordinator-0.5.301 → code_coordinator-0.5.303}/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.303}/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.303/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.303}/coord/prereqs.py

@@ -278,6 +278,102 @@ def _probe_playwright_browsers(prereq: Prereq, _timeout: float) -> ToolProbe:
     )
 
 
+# --- `windows` capability: the msvc cross-target lives per-toolchain (#2952) --
+#
+# dell64's Windows toolchain is a WSL-side cross-compile: `rustup target add
+# x86_64-pc-windows-msvc` plus `cargo install cargo-xwin` (for the MSVC
+# CRT/SDK cargo-xwin downloads and caches). `cargo-xwin` is an ordinary
+# binary probe, same shape as `cargo`/`opencode` below. The target is not —
+# `rustup target list --installed` is scoped to whichever toolchain is
+# *active*, and quadraui pins a specific one in `rust-toolchain.toml`
+# (`1.97.1` at the time of writing). Adding the target only to the default
+# toolchain leaves the pinned one without it, and a probe that only checked
+# the default would report MET while quadraui's own build still fails —
+# laundering an unbacked claim into a verified one, which is worse than no
+# probe at all. So this asserts the target against EVERY installed
+# toolchain and names the offending one in `what_breaks` when it's missing
+# from any of them.
+WINDOWS_MSVC_TARGET = "x86_64-pc-windows-msvc"
+
+
+def _rustup_toolchains(timeout: float) -> list[str]:
+    """Names of every installed rustup toolchain (`rustup toolchain list`).
+
+    Returns `[]` if `rustup` itself is missing or the call fails — the
+    caller treats that as "cannot confirm the target is installed" rather
+    than raising.
+    """
+    if shutil.which("rustup") is None:
+        return []
+    try:
+        result = subprocess.run(
+            ["rustup", "toolchain", "list"],
+            capture_output=True, text=True, timeout=timeout,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return []
+    if result.returncode != 0:
+        return []
+    toolchains = []
+    for line in (result.stdout or "").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        # `rustup toolchain list` suffixes the active one with "(default)"
+        # (and possibly "(override)") — strip it, `--toolchain` wants the
+        # bare name.
+        toolchains.append(line.split()[0])
+    return toolchains
+
+
+def _toolchain_has_target(toolchain: str, target: str, timeout: float) -> bool:
+    try:
+        result = subprocess.run(
+            ["rustup", "target", "list", "--installed", "--toolchain", toolchain],
+            capture_output=True, text=True, timeout=timeout,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    if result.returncode != 0:
+        return False
+    installed = {line.strip() for line in (result.stdout or "").splitlines() if line.strip()}
+    return target in installed
+
+
+def _probe_windows_msvc_target(prereq: Prereq, timeout: float) -> ToolProbe:
+    """`custom_probe` backing the `windows` capability's cross-target check
+    (#2952). See the module comment above `WINDOWS_MSVC_TARGET` for why this
+    cannot be a plain binary probe."""
+    toolchains = _rustup_toolchains(timeout)
+    if not toolchains:
+        return ToolProbe(
+            tool=prereq.tool, capability=prereq.capability, found=False,
+            version=None, min_version=prereq.min_version, meets_floor=None,
+            what_breaks=(
+                "rustup reports no installed toolchains (or rustup itself "
+                f"is missing on PATH) — {prereq.what_breaks}"
+            ),
+        )
+    missing = [
+        tc for tc in toolchains
+        if not _toolchain_has_target(tc, WINDOWS_MSVC_TARGET, timeout)
+    ]
+    if missing:
+        return ToolProbe(
+            tool=prereq.tool, capability=prereq.capability, found=False,
+            version=None, min_version=prereq.min_version, meets_floor=None,
+            what_breaks=(
+                f"{WINDOWS_MSVC_TARGET} missing from toolchain(s) "
+                f"{', '.join(missing)} — {prereq.what_breaks}"
+            ),
+        )
+    return ToolProbe(
+        tool=prereq.tool, capability=prereq.capability, found=True,
+        version=", ".join(sorted(toolchains)), min_version=prereq.min_version,
+        meets_floor=None, what_breaks=prereq.what_breaks,
+    )
+
+
 # Required on every machine, no matter its declared capabilities — coord
 # itself doesn't function without these.
 BASELINE_PREREQS: tuple[Prereq, ...] = (
@@ -378,6 +474,33 @@ CAPABILITY_PREREQS: tuple[Prereq, ...] = (
         ),
         custom_probe=_probe_opencode,
     ),
+    # #2952: backs the `windows` capability — dell64's WSL-side cross-compile
+    # to `x86_64-pc-windows-msvc` via cargo-xwin, routing quadraui's
+    # `src/win/` (and vimcode's equivalent) Win-GUI work. Two independent
+    # things can silently regress in that one home directory: the
+    # `cargo-xwin` binary (`~/.cargo/bin`) and the rustup target (see
+    # `_probe_windows_msvc_target` above for why that one needs its own
+    # custom probe rather than a plain binary check).
+    Prereq(
+        tool="cargo-xwin", binary="cargo-xwin", version_args=("--version",),
+        version_re=r"(\d+\.\d+\.\d+\S*)", min_version=None, capability="windows",
+        what_breaks=(
+            "quadraui's `--target x86_64-pc-windows-msvc` cross-compile "
+            "cannot link against the MSVC CRT/SDK — `cargo install "
+            "cargo-xwin`"
+        ),
+    ),
+    Prereq(
+        tool="windows-msvc-target", binary="", version_args=(), version_re="",
+        min_version=None, capability="windows",
+        what_breaks=(
+            f"`rustup target add {WINDOWS_MSVC_TARGET}` is missing from an "
+            "installed toolchain — quadraui pins one in rust-toolchain.toml, "
+            "so add the target to it explicitly, not just the default "
+            "toolchain (#2952)"
+        ),
+        custom_probe=_probe_windows_msvc_target,
+    ),
 )
 
 ALL_PREREQS: tuple[Prereq, ...] = BASELINE_PREREQS + CAPABILITY_PREREQS

{code_coordinator-0.5.301 → code_coordinator-0.5.303}/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