code-coordinator 0.5.309__tar.gz → 0.5.311__tar.gz

{code_coordinator-0.5.309 → code_coordinator-0.5.311}/PKG-INFO

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.309
+Version: 0.5.311
 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.311/code_coordinator.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.5.311",
+  "distance": 0,
+  "node": "g8003167b7c6ac292c1b0e3a06e71cc4dd08761b2",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-08-31"
+}

{code_coordinator-0.5.309 → code_coordinator-0.5.311}/coord/commands/dispatch.py

@@ -1172,6 +1172,28 @@ def assign(
     # Fetch the issue title from GitHub
     try:
         issue_data = github_ops.get_issue(repo_cfg.github, issue)
+    except github_ops.GhRateLimitError as e:
+        if e.from_cache:
+            # #2977: `_gh`'s pre-call guard refused this WITHOUT ever making
+            # a network call — a shared rate-limit backoff
+            # (`coord.github_throttle`) was already known active. That is
+            # categorically different from a real failure: nothing about
+            # this dispatch attempt was wrong, and the exact moment it would
+            # succeed is already known. Exit `EX_TEMPFAIL` (not the generic
+            # `1` below) and embed that moment in the message itself — see
+            # `github_ops.format_throttle_skip_reason` — so
+            # `coord/drive_queue.py`'s tick can park this launch without
+            # spending one of its two attempts, instead of treating a
+            # skipped call as indistinguishable from a genuine dispatch
+            # failure (the `coord-portal#161` incident this closes).
+            click.echo(
+                f"error: could not fetch issue #{issue}: "
+                f"{github_ops.format_throttle_skip_reason(e)}",
+                err=True,
+            )
+            sys.exit(github_ops.EX_TEMPFAIL)
+        click.echo(f"error: could not fetch issue #{issue}: {e}", err=True)
+        sys.exit(1)
     except RuntimeError as e:
         click.echo(f"error: could not fetch issue #{issue}: {e}", err=True)
         sys.exit(1)

{code_coordinator-0.5.309 → code_coordinator-0.5.311}/coord/drive_queue.py

@@ -91,6 +91,7 @@ from typing import Any, Iterable, Mapping, Sequence
 
 from coord.drive_state import TERMINAL_STATUSES, WORK_LIKE
 from coord.gate_a import is_gate_a_refusal_reason
+from coord.github_ops import is_throttle_skip_reason, parse_throttle_skip_until
 from coord.issues_sync_status import STALENESS_WARN_SECONDS as ISSUE_CACHE_STALE_CEILING_S
 from coord.merge_queue import (
     PLAN_READY,
@@ -2301,12 +2302,20 @@ class UnreachableWait:
     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.
+
+    `dependents` (#2978) is the count of OTHER queue entries whose `after=`
+    names this one — computed against the full entry set the caller passed
+    to :func:`detect_unreachable_waits`, not just the flagged subset, so it
+    is accurate even though those dependents themselves never appear in the
+    result (see the predicate's own docstring for why). `0` for an entry
+    nothing is chained behind.
     """
 
     key: str
     state: str
     deferrals: int
     last_reason: str
+    dependents: int = 0
 
 
 def detect_unreachable_waits(
@@ -2316,35 +2325,73 @@ def detect_unreachable_waits(
 ) -> 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.
+    Two independent shapes, either of which qualifies a `blocked`/`parked`
+    entry — both provably have no branch/PR/merge-queue row for any sweep to
+    ever form an opinion about, which is the actual invariant this predicate
+    is checking, not "attempts == 0" as a proxy for it (#2978 found the proxy
+    wrong for the second shape):
+
+    * ``attempts == 0`` and ``deferrals > min_deferrals`` — never dispatched
+      at all. The original #2944 shape.
+    * ``attempts > 0``, ``state == blocked``, and the entry's own
+      `last_reason` carries #2273's "no assignment was ever created for this
+      run" marker (:func:`_is_dispatch_failure_reason`) — every dispatch
+      attempt died before `coord assign` produced a board-visible row, and
+      the entry has now exhausted its retry budget (the only way to reach
+      `blocked` with that reason: see `_reconcile_running`'s `exhausted`
+      branch). Exhaustion is its own grace period — there is no next attempt
+      left to wait out — so `min_deferrals` is not applied here.
+
+    A `blocked`/`parked` entry whose `last_reason` is instead one of
+    `_resolve_prereqs`'s unsatisfiable-`after=` verdict shapes
+    (:func:`_is_unsatisfiable_prereq_reason`) is excluded UNCONDITIONALLY,
+    regardless of attempts/deferrals — #2978: that shape is
+    :func:`_reconcile_blocked_after`'s to resolve (#2362, widened #2756),
+    not an operator's, and flagging it here directly contradicts that
+    function's own documented behaviour. This is what keeps a chain's
+    dependents (each blocked with "pre-req X is queued but blocked — it will
+    never satisfy") out of the result entirely, leaving only the root that
+    actually needs a human.
+
+    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.
     """
-    return [
-        UnreachableWait(
-            key=e.key, state=e.state, deferrals=e.deferrals, last_reason=e.last_reason
+    entries = list(entries)
+    dependents_of: dict[str, int] = {}
+    for e in entries:
+        for dep in e.after:
+            dependents_of[dep] = dependents_of.get(dep, 0) + 1
+
+    waits: list[UnreachableWait] = []
+    for e in entries:
+        if e.state not in (STATE_BLOCKED, STATE_PARKED):
+            continue
+        if _is_unsatisfiable_prereq_reason(e.last_reason):
+            continue
+        if e.attempts == 0:
+            if e.deferrals <= min_deferrals:
+                continue
+        elif not (e.state == STATE_BLOCKED and _is_dispatch_failure_reason(e.last_reason)):
+            continue
+        waits.append(
+            UnreachableWait(
+                key=e.key,
+                state=e.state,
+                deferrals=e.deferrals,
+                last_reason=e.last_reason,
+                dependents=dependents_of.get(e.key, 0),
+            )
         )
-        for e in entries
-        if e.state in (STATE_BLOCKED, STATE_PARKED)
-        and e.attempts == 0
-        and e.deferrals > min_deferrals
-    ]
+    return waits
 
 
 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.
+    shape — a message naming the entry (or entries), the evidence that
+    qualified it, 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``
@@ -2356,29 +2403,52 @@ def unreachable_wait_alert(waits: Sequence[UnreachableWait]) -> QueueAlert:
     ``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.
+
+    #2978: each name also carries its `dependents` count when non-zero — the
+    entries chained behind a flagged root never appear in `waits` (see
+    `detect_unreachable_waits`), so without this an operator has no way to
+    know a fix to the one row named here will also resolve N others they
+    never see mentioned. Explicitly says those dependents need no remedy of
+    their own, since #2944's original wording ("for each entry named above")
+    read, on a real incident, as an instruction to `remove`+`add` entries
+    that were never named — but easy to mis-generalize to "the dependents
+    too" by an operator who does not already know #2756 self-heals them.
     """
-    names = ", ".join(
-        f"{w.key} ({w.state}, {w.deferrals} deferrals)" for w in waits[:5]
-    )
+    def _name(w: UnreachableWait) -> str:
+        base = f"{w.key} ({w.state}, {w.deferrals} deferrals)"
+        if w.dependents:
+            plural = "ies" if w.dependents != 1 else "y"
+            base += (
+                f" — {w.dependents} dependent entr{plural} chained behind it "
+                "will self-heal automatically once this clears (#2756), no "
+                "remedy needed on them"
+            )
+        return base
+
+    names = ", ".join(_name(w) 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; "
+            "guaranteed-false wait — blocked/parked with no branch/PR/"
+            "merge-queue row any sweep could ever act on (never dispatched, "
+            "or every dispatch attempt died before creating an assignment); "
             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."
+            "coord drive-queue add <repo> <issue> for each ROOT entry named "
+            "above — never on a dependent chained behind one."
         ),
         details=tuple(
             f"{w.key}: {w.state}, {w.deferrals} deferrals, "
-            f"last_reason={w.last_reason!r}"
+            f"dependents={w.dependents}, 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"
+            "coord drive-queue add <repo> <issue> — for each ROOT entry "
+            "named above; any dependents chained behind it self-heal on "
+            "their own (#2756)"
         ),
     )
 
@@ -3425,6 +3495,42 @@ def _reconcile_running(
             None,
         )
 
+    # #2977: `coord assign` exited because `_gh`'s pre-call guard found a
+    # shared GitHub rate-limit backoff already active and skipped the call
+    # entirely (`GhRateLimitError(from_cache=True)`) — no `gh` call was ever
+    # attempted for this launch. That is neither a permanent refusal (the
+    # `is_policy_refusal_reason`/`is_gate_a_refusal_reason` shapes above —
+    # nothing about the ISSUE was rejected) nor a genuine dispatch failure
+    # (the generic `_dispatch_produced_nothing` note below, which would
+    # spend an attempt): it is a fleet-wide, known-duration condition this
+    # entry had nothing to do with. Parks WITHOUT spending an attempt
+    # (`Reconcile.updates` carries no `attempts` key, same as every other
+    # park above) — the wall-clock `until=` timestamp
+    # `github_ops.format_throttle_skip_reason` embedded in `own_reason` is
+    # what lets `plan_tick`'s parked-entry sweep resume it the moment the
+    # backoff clears, with no live re-check and no operator action, unlike
+    # the gate_a/policy parks just above which need one.
+    if own_reason and is_throttle_skip_reason(own_reason):
+        reason = (
+            f"{own_reason} — parking without spending an attempt; the queue "
+            "resumes it automatically once the backoff clears, no operator "
+            "needed (#2977)"
+        )
+        return (
+            Reconcile(
+                entry.key,
+                "parked",
+                reason,
+                occupies=False,
+                updates={
+                    "state": STATE_PARKED,
+                    "last_reason": reason,
+                    "session_name": None,
+                },
+            ),
+            None,
+        )
+
     permanent: tuple[str, str] | None = None
     if own_reason and (exit_refused or {}).get(entry.key):
         permanent = (
@@ -5008,6 +5114,59 @@ def plan_tick(
         # clears it (`coord drive-queue remove`, same as `blocked`).
         if is_policy_refusal_reason(entry.last_reason):
             continue
+        # #2977: a throttle-skip park (`github_ops.is_throttle_skip_reason`)
+        # carries its OWN known wall-clock expiry (`until=<epoch>`, embedded
+        # by `github_ops.format_throttle_skip_reason` at park time) — unlike
+        # the CI-park default below, which needs a live re-check because it
+        # has no way to know in advance when checks will report, this park
+        # can resume on a plain clock comparison, no I/O at all. `now is
+        # None` (a pure-logic caller with no clock) degrades to "never
+        # resume this tick", same posture #1794's grace window uses for the
+        # same input. An unparseable `until` (should not happen for text
+        # this module itself wrote) or a wait that has run well past
+        # `PARK_STALE_SECONDS` — far longer than any real backoff
+        # (`coord.github_throttle.MAX_BACKOFF_S` is 900s) — resumes anyway
+        # rather than parking indefinitely on a reading nothing can refresh,
+        # the same finite-wait guarantee #2158 already gives the CI park.
+        if is_throttle_skip_reason(entry.last_reason):
+            if now is None:
+                continue
+            until = parse_throttle_skip_until(entry.last_reason)
+            age = now - entry.reason_at if entry.reason_at is not None else None
+            cleared = until is not None and now >= until
+            stale = until is None or (age is not None and age > PARK_STALE_SECONDS)
+            if not cleared and not stale:
+                continue
+            reason = (
+                (
+                    f"the GitHub rate-limit backoff that parked {entry.key} "
+                    "has cleared — resuming without spending an attempt "
+                    "(#2977)"
+                )
+                if cleared
+                else (
+                    f"{entry.last_reason} — this throttle-skip park has run "
+                    f"{PARK_STALE_SECONDS / 60:.0f}m+ with no refreshable "
+                    "expiry left to trust — resuming rather than parking "
+                    "indefinitely (#2977)"
+                )
+            )
+            reconciles.append(
+                Reconcile(
+                    entry.key,
+                    "resumed",
+                    reason,
+                    occupies=False,
+                    updates={
+                        "state": STATE_WAITING,
+                        "attempts": 0,
+                        "last_reason": reason,
+                    },
+                )
+            )
+            states[entry.key] = STATE_WAITING
+            effective_attempts[entry.key] = 0
+            continue
         if park_expired is not None:
             # Deliberately does NOT claim CI has reported — nothing here knows
             # that. It says only that the reading this park rests on has no

{code_coordinator-0.5.309 → code_coordinator-0.5.311}/coord/github_ops.py

@@ -100,6 +100,108 @@ class GhRateLimitError(GhTransientError):
         self.from_cache = from_cache
 
 
+# ── #2977: coord-assign-side signal for a throttle-SKIPPED gh call ─────────
+#
+# `_gh`'s pre-call guard above raises `GhRateLimitError(from_cache=True)`
+# WITHOUT ever making a network call, whenever a shared backoff
+# (:mod:`coord.github_throttle`) is already known active — see that raise's
+# own comment. Before this, that distinction was lost the moment it crossed
+# the `coord assign` subprocess boundary: the caller (`coord/drive.py`)
+# just saw a bare non-zero exit and folded it into the same generic "drive
+# died" bucket as a real infrastructure failure, so `coord/drive_queue.py`'s
+# tick spent one of the entry's two launch attempts on a call that never
+# even reached GitHub (the 2026-08-30 `coord-portal#161` incident this
+# closes — see the issue for the full trace).
+#
+# `EX_TEMPFAIL` is the conventional (sysexits.h) code for "temporary
+# failure, retry later" — used by :mod:`coord.commands.dispatch`'s `assign`
+# command to give this ONE failure shape a distinct exit status. That is
+# necessary but not sufficient for `coord/drive_queue.py`'s pure tick logic
+# to act on: the exit code alone carries no expiry, and by the time a
+# `drive_exited` audit row is read back the file that raised the original
+# `GhRateLimitError` is long gone, so there is nothing left to re-consult.
+# `format_throttle_skip_reason` instead embeds everything the tick needs —
+# the marker, and an absolute `until=<epoch>` wall-clock timestamp — directly
+# in the human-readable reason text that already survives the subprocess
+# boundary unmodified (`coord.drive.Driver._spawn` captures the child's
+# stdout+stderr verbatim into `_last_run_output`, which flows straight into
+# the `drive_exited` audit summary `coord/commands/drive_queue.py`'s
+# `_fetch_exit_reasons` reads back as `own_reason` — no protocol change
+# needed on that path at all). `is_throttle_skip_reason`/
+# `parse_throttle_skip_until` are `coord/drive_queue.py`'s read side: pure
+# text parsing, no I/O, so `_reconcile_running`'s park (and its wall-clock
+# resume, no live re-check needed) stay exactly as pure as every other
+# branch in that module.
+THROTTLE_SKIP_MARKER = "[gh-throttle-skipped #2977]"
+
+#: The conventional sysexits.h "temporary failure, please try again" code —
+#: distinct from every other exit status `coord assign` uses (see
+#: `coord.drive.EXIT_DISPATCH_REFUSED`/`EXIT_DEAD_END` for the other two
+#: exit codes a downstream reader must be able to tell apart from "died").
+EX_TEMPFAIL = 75
+
+_THROTTLE_SKIP_UNTIL_RE = re.compile(r"until=([0-9]+(?:\.[0-9]+)?)")
+
+
+def format_throttle_skip_reason(exc: GhRateLimitError, *, now: float | None = None) -> str:
+    """Canonical, parseable text for a ``coord assign`` refusal caused by a
+    throttle-SKIPPED ``gh`` call (``exc.from_cache`` — see
+    :class:`GhRateLimitError`'s docstring).  Wraps ``str(exc)`` (already
+    carries the reason/status/request-id `_gh` recovered) with
+    :data:`THROTTLE_SKIP_MARKER` and an absolute ``until=`` epoch timestamp
+    that :func:`parse_throttle_skip_until` recovers later, with no clock of
+    its own and no access to :mod:`coord.github_throttle` needed.
+
+    ``exc.retry_after_s`` is "seconds remaining AT THE MOMENT ``_gh`` raised"
+    — a value that goes stale the instant it's read back, which is exactly
+    why an absolute timestamp is embedded here (computed once, at the one
+    point in this whole path that has both a fresh clock and the exception)
+    rather than a duration re-derived downstream. Falls back to
+    :data:`coord.github_throttle.DEFAULT_BACKOFF_S` when ``retry_after_s``
+    is ``None`` (the pre-call guard's own fallback wording already reads
+    "GitHub's guidance" in that case, so this mirrors it rather than
+    inventing a shorter window with no evidence behind it).
+    """
+    now = now if now is not None else time.time()
+    retry_after = (
+        exc.retry_after_s if exc.retry_after_s is not None else github_throttle.DEFAULT_BACKOFF_S
+    )
+    until = now + max(0.0, retry_after)
+    return (
+        f"{THROTTLE_SKIP_MARKER} {exc} — no gh call was made for this launch "
+        f"attempt, so it should not spend one (#2977); until={until:.3f}"
+    )
+
+
+def is_throttle_skip_reason(text: str | None) -> bool:
+    """``True`` when *text* is (or contains) a :func:`format_throttle_skip_reason`
+    result — the same marker-based convention as
+    ``coord.models.is_policy_refusal_reason``/``coord.gate_a.
+    is_gate_a_refusal_reason``, so ``coord/drive_queue.py`` can recognise this
+    park from plain reason text with no I/O.
+    """
+    return bool(text) and THROTTLE_SKIP_MARKER in text
+
+
+def parse_throttle_skip_until(text: str | None) -> float | None:
+    """The absolute epoch ``until=`` timestamp embedded by
+    :func:`format_throttle_skip_reason`, or ``None`` when *text* doesn't
+    carry the marker at all, or carries it without a parseable timestamp
+    (defensive — should not happen for text this module itself wrote, but a
+    hand-edited row or a future format change must degrade to "unknown",
+    never a wrong resume time).
+    """
+    if not is_throttle_skip_reason(text):
+        return None
+    m = _THROTTLE_SKIP_UNTIL_RE.search(text)
+    if not m:
+        return None
+    try:
+        return float(m.group(1))
+    except ValueError:
+        return None
+
+
 class GhTooOldForJsonChecks(GhError):
     """Raised when the installed ``gh`` doesn't support ``gh pr checks --json``
     *at all* (#1564 Addendum 2), as opposed to supporting ``--json`` but

{code_coordinator-0.5.309 → code_coordinator-0.5.311}/coord/health/checks/wedged_drive_queue.py

@@ -19,6 +19,15 @@ 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.
 
+#2978: the predicate also flags an ``attempts > 0`` entry that exhausted its
+retry budget without ever getting a #2273 dispatch-layer death past `coord
+assign` (same "no branch/PR ever existed" invariant, just reached a
+different way) — and excludes an entry blocked solely on an unsatisfiable
+``after=`` pre-req, since that one is ``_reconcile_blocked_after``'s to
+self-heal (#2362/#2756), not an operator's. See
+``coord.drive_queue.detect_unreachable_waits`` for the exact predicate; this
+probe does not duplicate it, only renders its result.
+
 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
@@ -51,16 +60,19 @@ from coord.health.registry import COST_NETWORK, check
     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`."
+        "wait: `blocked`/`parked` with no branch/PR/merge-queue row any "
+        "sweep could ever act on — either `attempts == 0` (never dispatched) "
+        "past a few ticks of grace, or `attempts > 0` with an exhausted "
+        "#2273 dispatch-layer death (#2978). Excludes an entry blocked "
+        "solely on an unsatisfiable `after=` pre-req — that one is "
+        "`_reconcile_blocked_after`'s to self-heal (#2756), not an "
+        "operator's. 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:
@@ -92,7 +104,10 @@ def probe_wedged_drive_queue(ctx: HealthContext) -> CheckResult:
         )
 
     sample = ", ".join(
-        f"{w.key} ({w.state}, {w.deferrals} deferrals)" for w in waits[:5]
+        f"{w.key} ({w.state}, {w.deferrals} deferrals"
+        + (f", {w.dependents} dependents self-heal (#2756)" if w.dependents else "")
+        + ")"
+        for w in waits[:5]
     )
     return CheckResult(
         check_id="wedged_drive_queue",
@@ -104,11 +119,17 @@ def probe_wedged_drive_queue(ctx: HealthContext) -> CheckResult:
         ),
         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>"
+            + " — no branch/PR/merge-queue row any sweep could ever act on "
+            "(never dispatched, or every dispatch attempt died before "
+            "creating an assignment); cannot clear on its own. fix (root "
+            "only — any dependents self-heal, #2756): coord drive-queue "
+            "remove <repo> <issue> && coord drive-queue add <repo> <issue>"
+        ),
+        threshold=(
+            "warn when any entry is blocked/parked with no branch/PR a sweep "
+            "could ever act on: attempts=0 past a few ticks of grace, or "
+            "attempts>0 with an exhausted #2273 dispatch-layer death"
         ),
-        threshold="warn when any entry is blocked/parked, attempts=0, past a few ticks of grace",
         values={
             "count": len(waits),
             "entries": [
@@ -116,6 +137,7 @@ def probe_wedged_drive_queue(ctx: HealthContext) -> CheckResult:
                     "key": w.key,
                     "state": w.state,
                     "deferrals": w.deferrals,
+                    "dependents": w.dependents,
                     "last_reason": w.last_reason,
                 }
                 for w in waits

{code_coordinator-0.5.309 → code_coordinator-0.5.311}/tests/test_cli_assign.py

@@ -495,6 +495,68 @@ class TestAssignDispatch:
         assert result.exit_code == 1
         assert "could not fetch issue" in result.output
 
+    def test_issue_fetch_throttle_skip_exits_distinctly(
+        self, config_file: Path, coord_dir: Path
+    ) -> None:
+        """#2977: a `GhRateLimitError(from_cache=True)` — `_gh`'s pre-call
+        guard skipped this `gh issue view` call WITHOUT making a network
+        call because a shared rate-limit backoff was already known active
+        — is a categorically different failure from an ordinary fetch error
+        (the generic `RuntimeError` case just above, still exit `1`). It
+        must exit `github_ops.EX_TEMPFAIL`, and the printed message must
+        carry `THROTTLE_SKIP_MARKER` plus an absolute `until=` timestamp, so
+        `coord drive-queue`'s tick (`coord/drive_queue.py`'s
+        `is_throttle_skip_reason`/`parse_throttle_skip_until`) can park this
+        launch without spending one of its two attempts instead of treating
+        it like a genuine dispatch failure (the `coord-portal#161`
+        incident)."""
+        from coord.github_ops import EX_TEMPFAIL, GhRateLimitError, THROTTLE_SKIP_MARKER
+
+        with patch(
+            "coord.github_ops.get_issue",
+            side_effect=GhRateLimitError(
+                "gh issue view 999 --repo acme/api --json ... skipped: GitHub "
+                "secondary_rate_limit backoff active for 59s more "
+                "(status=403, request_id=abc123)",
+                status_code=403, request_id="abc123", retry_after_s=59.0,
+                secondary=True, from_cache=True,
+            ),
+        ):
+            result = CliRunner().invoke(
+                main,
+                ["assign", "laptop", "api", "999", "--config", str(config_file)],
+            )
+        assert result.exit_code == EX_TEMPFAIL
+        assert result.exit_code != 1
+        assert "could not fetch issue" in result.output
+        assert THROTTLE_SKIP_MARKER in result.output
+        assert "until=" in result.output
+
+    def test_issue_fetch_real_rate_limit_hit_keeps_the_generic_exit(
+        self, config_file: Path, coord_dir: Path
+    ) -> None:
+        """The counterpart: a `GhRateLimitError` from an ACTUAL network call
+        (`from_cache=False`) is a genuine observation, not a skip — it must
+        keep exiting the generic `1` the `RuntimeError` case above does, not
+        `EX_TEMPFAIL`, so it is never mistaken for the zero-attempt-cost
+        skip class this issue fixes."""
+        from coord.github_ops import GhRateLimitError
+
+        with patch(
+            "coord.github_ops.get_issue",
+            side_effect=GhRateLimitError(
+                "gh issue view 999 --repo acme/api --json ... failed: API "
+                "rate limit exceeded",
+                status_code=403, retry_after_s=60.0, from_cache=False,
+            ),
+        ):
+            result = CliRunner().invoke(
+                main,
+                ["assign", "laptop", "api", "999", "--config", str(config_file)],
+            )
+        assert result.exit_code == 1
+        assert "could not fetch issue" in result.output
+
     def test_briefing_post_failure_is_nonfatal(
         self, config_file: Path, coord_dir: Path
     ) -> None: