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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.310
+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.310 → 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.310
+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.310 → code_coordinator-0.5.311}/coord/drive_queue.py

@@ -2302,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(
@@ -2317,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``
@@ -2357,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)"
         ),
     )
 

{code_coordinator-0.5.310 → 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.310 → code_coordinator-0.5.311}/tests/test_cli_drive_queue.py

@@ -3690,6 +3690,49 @@ def test_status_alert_does_not_trip_for_a_real_merge_gate_wait(cli):
     assert "alert: (none)" in result.output
 
 
+# ── #2978: a wedged root with dependents chained behind it — the alert must
+# name the root only, not the dependents, and the fix is remove+add on the
+# root alone. This is the exact claude-coordinator#2978 ms-5 incident: an
+# `attempts > 0` root that exhausted its budget on #2273 dispatch-layer
+# deaths (never got as far as creating an assignment), with eight dependents
+# blocked behind it on an unsatisfiable `after=` — a shape #2756's
+# `_reconcile_blocked_after` self-heals on its own the moment the root
+# clears, so it must never be named here either.
+
+
+def test_status_alert_names_the_root_only_not_the_chained_dependents(cli):
+    cli("add", REPO, "161")
+    state._update_drive_queue_entry_local(
+        REPO, 161, state="blocked", attempts=2, deferrals=1,
+        last_reason=(
+            "drive session died without landing the work (2/2 attempts) — "
+            "giving up — no assignment was ever created for this run "
+            "(#2273): likely an infrastructure/dispatch-layer failure, not "
+            "a code defect"
+        ),
+    )
+    root_key = f"{REPO}#161"
+    for issue in range(162, 170):
+        cli("add", REPO, str(issue), "--after", "161")
+        state._update_drive_queue_entry_local(
+            REPO, issue, state="blocked", attempts=0, deferrals=40,
+            last_reason=(
+                f"pre-req {root_key} is queued but blocked — it will never "
+                "satisfy"
+            ),
+        )
+
+    result = cli("status")
+    assert result.exit_code == 0, result.output
+    assert "alert: (none)" not in result.output
+    assert root_key in result.output
+    for issue in range(162, 170):
+        assert f"{REPO}#{issue}" not in result.output
+    assert "coord drive-queue remove" in result.output
+    assert "coord drive-queue add" in result.output
+    assert "self-heal" in result.output
+
+
 # ── deploy gates (#1757) ─────────────────────────────────────────────────────
 #
 # The acceptance bar for `--hold-after`.  `merged != live`: a queue that

{code_coordinator-0.5.310 → code_coordinator-0.5.311}/tests/test_drive_queue.py

@@ -5371,3 +5371,100 @@ def test_unreachable_wait_alert_names_the_entry_deferrals_and_remedy():
     assert "207 deferrals" in alert.reason
     assert "coord drive-queue remove" in alert.command
     assert "coord drive-queue add" in alert.command
+
+
+# ── #2978: root-only, and the #2273-exhausted root is no longer excluded ────
+#
+# #2944's alert got today's ms-5 incident exactly backwards: it named eight
+# dependents that needed nothing (each blocked on an unsatisfiable `after=`
+# pre-req — #2756's to self-heal) and omitted the one entry — the root,
+# `attempts > 0` — that actually needed an operator. These tests pin both
+# halves of the fix plus the exact incident shape as a regression.
+
+_DISPATCH_FAILURE_REASON = (
+    "drive session died without landing the work (2/2 attempts) — giving up "
+    "— no assignment was ever created for this run (#2273): likely an "
+    "infrastructure/dispatch-layer failure, not a code defect"
+)
+
+
+def test_detect_unreachable_waits_excludes_an_unsatisfiable_after_block():
+    """#2756 owns this shape (`_reconcile_blocked_after` self-heals it the
+    moment the named pre-req clears) — it must never also be a #2944
+    target, no matter how many deferrals it has accumulated."""
+    dep_key = entry_key(REPO, 161)
+    dependent = entry(
+        162,
+        state=STATE_BLOCKED,
+        attempts=0,
+        deferrals=40,
+        after=(dep_key,),
+        last_reason=f"pre-req {dep_key} is queued but blocked — it will never satisfy",
+    )
+    assert detect_unreachable_waits([dependent]) == []
+
+
+def test_detect_unreachable_waits_flags_an_exhausted_dispatch_layer_root():
+    """#2978: an entry that exhausted its attempts without #2273's dispatch
+    layer ever producing a board-visible assignment IS the #2944 shape —
+    `attempts > 0` alone must no longer exclude it."""
+    root = entry(
+        161,
+        state=STATE_BLOCKED,
+        attempts=2,
+        deferrals=1,
+        last_reason=_DISPATCH_FAILURE_REASON,
+    )
+    waits = detect_unreachable_waits([root])
+    assert [w.key for w in waits] == [entry_key(REPO, 161)]
+
+
+def test_detect_unreachable_waits_still_ignores_a_real_dispatched_attempt():
+    """An ordinary `blocked` entry with `attempts > 0` and a last_reason that
+    does NOT carry #2273's dispatch-failure marker is still excluded — it
+    was dispatched, has (or had) a real branch/PR, and is a legitimate wait,
+    not an unreachable one."""
+    real_attempt = entry(
+        4, state=STATE_BLOCKED, attempts=1, deferrals=500, last_reason="CI red"
+    )
+    assert detect_unreachable_waits([real_attempt]) == []
+
+
+def test_detect_unreachable_waits_reproduces_the_ms5_incident_shape():
+    """The exact claude-coordinator#2978 incident: one root `blocked
+    attempts=2` with a #2273 dispatch-layer death, and eight dependents
+    chained behind it via `after=`, each blocked with the frozen
+    unsatisfiable-pre-req caption. The alert must name the root only — none
+    of the eight dependents, and the root's `dependents` count must be 8 so
+    the rendered alert can tell the operator they self-heal."""
+    root_key = entry_key(REPO, 161)
+    root = entry(
+        161,
+        state=STATE_BLOCKED,
+        attempts=2,
+        deferrals=1,
+        last_reason=_DISPATCH_FAILURE_REASON,
+    )
+    dependents = [
+        entry(
+            issue,
+            state=STATE_BLOCKED,
+            attempts=0,
+            deferrals=40,
+            after=(root_key,),
+            last_reason=f"pre-req {root_key} is queued but blocked — it will never satisfy",
+        )
+        for issue in range(162, 170)
+    ]
+    assert len(dependents) == 8
+
+    waits = detect_unreachable_waits([root, *dependents])
+    assert [w.key for w in waits] == [root_key]
+    assert waits[0].dependents == 8
+
+    alert = unreachable_wait_alert(waits)
+    assert root_key in alert.reason
+    for dep in dependents:
+        assert dep.key not in alert.reason
+    assert "8 dependent entries" in alert.reason
+    assert "self-heal" in alert.reason

{code_coordinator-0.5.310 → code_coordinator-0.5.311}/tests/test_health_wedged_drive_queue.py

@@ -98,6 +98,55 @@ def test_ok_when_blocked_with_real_attempts_spent(monkeypatch) -> None:
     assert result.severity == Severity.OK
 
 
+_DISPATCH_FAILURE_REASON = (
+    "drive session died without landing the work (2/2 attempts) — giving up "
+    "— no assignment was ever created for this run (#2273): likely an "
+    "infrastructure/dispatch-layer failure, not a code defect"
+)
+
+
+def test_warn_for_an_exhausted_dispatch_layer_root_despite_attempts_spent(
+    monkeypatch,
+) -> None:
+    """#2978: `attempts > 0` no longer buys an unconditional pass — an entry
+    that exhausted its retry budget without #2273's dispatch layer ever
+    producing an assignment has the identical "no branch/PR for a sweep to
+    act on" shape as the original attempts=0 case."""
+    monkeypatch.setattr(
+        "coord.state.list_drive_queue",
+        lambda: [
+            _row(161, state="blocked", attempts=2, deferrals=1, last_reason=_DISPATCH_FAILURE_REASON)
+        ],
+    )
+    result = probe_wedged_drive_queue(_health_ctx())
+    assert result.severity == Severity.WARN
+    assert "claude-coordinator#161" in result.detail
+
+
+def test_ok_for_a_dependent_blocked_on_an_unsatisfiable_after_prereq(
+    monkeypatch,
+) -> None:
+    """#2978: a dependent chained behind a blocked root — `_reconcile_
+    blocked_after`'s to self-heal (#2756) — must never warn here, no matter
+    how many deferrals it has piled up."""
+    root_key = "claude-coordinator#161"
+    monkeypatch.setattr(
+        "coord.state.list_drive_queue",
+        lambda: [
+            _row(
+                162,
+                state="blocked",
+                attempts=0,
+                deferrals=40,
+                after_json=f'["{root_key}"]',
+                last_reason=f"pre-req {root_key} is queued but blocked — it will never satisfy",
+            )
+        ],
+    )
+    result = probe_wedged_drive_queue(_health_ctx())
+    assert result.severity == Severity.OK
+
+
 def test_unknown_when_the_queue_read_raises(monkeypatch) -> None:
     def _boom():
         raise RuntimeError("db is locked")

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

@@ -1,8 +0,0 @@
-{
-  "tag": "0.5.310",
-  "distance": 0,
-  "node": "ga706a8d9e5cc804e73c38968328d2a67cd807eca",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-08-30"
-}