code-coordinator 0.5.758__tar.gz → 0.5.760__tar.gz

{code_coordinator-0.5.758 → code_coordinator-0.5.760}/PKG-INFO

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

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

@@ -0,0 +1,8 @@
+{
+  "tag": "0.5.760",
+  "distance": 0,
+  "node": "g110342595fbe069c4cb87b136ae89c3e3656fc3a",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-11-12"
+}

{code_coordinator-0.5.758 → code_coordinator-0.5.760}/coord/commands/drive_queue.py

@@ -93,6 +93,8 @@ from coord.drive_queue import (
     find_cycle,
     fired_holds,
     flag_shadows_config_warning,
+    format_coarse_duration,
+    is_benign_queue_alert_command,
     is_dispatch_failure_reason,
     is_fix_round_ceiling_blocked,
     is_merge_gate_block_reason,
@@ -2069,15 +2071,12 @@ def _reason_age_suffix(entry: QueueEntry, now: float) -> str:
     return f" ({_age_str(max(0.0, now - entry.reason_at))} ago)"
 
 
-def _age_str(delta_seconds: float) -> str:
-    """``42s`` / ``3h`` / ``5d`` — coarse, single-unit, matches #2133's ask."""
-    if delta_seconds < 60:
-        return f"{int(delta_seconds)}s"
-    if delta_seconds < 3600:
-        return f"{int(delta_seconds // 60)}m"
-    if delta_seconds < 86400:
-        return f"{int(delta_seconds // 3600)}h"
-    return f"{int(delta_seconds // 86400)}d"
+# #3983: `coord.drive_queue.format_coarse_duration` — imported under this
+# module's own pre-existing name so every call site below (and the
+# `describe_unreachable_wait`-driven alert text) renders "how long has this
+# held" with the identical single-unit shape, never a second formatter that
+# could drift from it.
+_age_str = format_coarse_duration
 
 
 def _hold_lines(entry: QueueEntry) -> list[str]:
@@ -2566,7 +2565,7 @@ def _unreachable_wait_alert_dict(rows: list[Mapping[str, Any]]) -> dict | None:
     waits = detect_unreachable_waits(entries_from_rows(rows))
     if not waits:
         return None
-    synthetic = unreachable_wait_alert(waits)
+    synthetic = unreachable_wait_alert(waits, now=time.time())
     return {
         "reason": synthetic.reason,
         "gate_readings": " | ".join(synthetic.details),
@@ -2583,13 +2582,32 @@ def drive_queue_status(output_json: bool, config_path: Path) -> None:
 
     rows = list_drive_queue()
     counts = _counts(rows)
-    # #2944: a tick-raised alert (a HELD gate, "nothing eligible to launch")
+    # #2944: a tick-raised alert (a HELD gate, a real BLOCKED-entry remedy)
     # 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)
+    # time a real, actionable alert IS present.
+    #
+    # #3983: EXCEPT the one tick-raised shape that is itself a sentinel for
+    # "nothing is actually broken" — `QUEUE_ALERT_NO_REMEDY_COMMAND` (step
+    # 4's "nothing eligible to launch" write when every stalled entry is a
+    # benign deferral, never an actual block). The quadraui#2341 incident: a
+    # root parked `needs_decomposition` with 13 `waiting` dependents chained
+    # on it via `after=` never reaches `blocked` at all — `_resolve_prereqs`
+    # treats a `parked` pre-req as an ordinary unsatisfied deferral, not the
+    # unsatisfiable-and-escalate shape it gives a `blocked`/`failed` one — so
+    # EVERY tick re-wrote this exact no-remedy sentinel over the root's own
+    # #2944/#2978 finding, and `status` never got a chance to name it. Same
+    # benign-sentinel check `coord.notifier.collect.halted_drives` already
+    # uses to keep this shape out of the pager — one question ("is this
+    # tick-raised alert itself the thing, or just noise?"), one answer,
+    # shared by both callers.
+    tick_alert = _queue_alert()
+    if tick_alert is not None and not is_benign_queue_alert_command(
+        tick_alert.get("proposed_command")
+    ):
+        alert = tick_alert
+    else:
+        alert = _unreachable_wait_alert_dict(rows) or tick_alert
     # #3413: `alert["created_at"]` (present only for a tick-raised record —
     # `_unreachable_wait_alert_dict` is computed fresh on every call and
     # carries no timestamp of its own) now survives an unbroken same-reason

{code_coordinator-0.5.758 → code_coordinator-0.5.760}/coord/decomposition_chat.py

@@ -46,6 +46,7 @@ from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
     from coord.config import Config
+    from coord.milestone_order import WorkOrderNode
     from coord.models import Assignment, Board, Machine, Repo, SplitProposal
     from coord.preflight_size import SplitVerification
 
@@ -1314,6 +1315,98 @@ def parse_size_triage_response(
     )
 
 
+def _repoint_queued_dependents_at_split(
+    *,
+    repo_name: str,
+    original_issue: int,
+    epic_number: int,
+    remapped_nodes: tuple["WorkOrderNode", ...],
+    origin: str,
+) -> None:
+    """Re-point every queued entry whose ``after=`` names *original_issue*
+    onto the split's sink children (#3984).
+
+    Without this, ``drive_queue._resolve_prereqs``'s ``live_prereq_
+    terminal`` recovery (#2602/#2850) reads a prerequisite a live re-check
+    finds CLOSED as satisfied, whatever the reason it closed — so a
+    dependent chained on the original would read it as "done" the instant
+    :func:`file_and_queue_split_proposal` closes it as superseded, and
+    launch before any split child has merged (the quadraui#2341 incident:
+    13 rows would have launched against code the split hadn't landed yet).
+
+    Walks the WHOLE drive queue, not just *repo_name*'s — an ``after=`` key
+    is fully-qualified (``repo#N``) and a dependent can live in a different
+    repo than the original. Every matching row is rewritten with the SAME
+    write path ``coord drive-queue add`` itself uses
+    (:func:`coord.state.enqueue_drive_queue`), carrying forward every
+    OTHER operator-declared field on that row untouched, then confirmed
+    with a readback before moving to the next row — an unconfirmed rewrite
+    is not a rewrite, same discipline the child-queuing loop above already
+    applies. A row's ``last_reason`` also records why its edges changed, so
+    ``coord drive-queue list`` doesn't just show a different ``after=``
+    with no explanation.
+
+    Raises (never swallows) on the first row that doesn't read back the new
+    ``after=`` — propagating straight out of
+    :func:`file_and_queue_split_proposal`, which calls this BEFORE closing
+    the original, so a raise here always aborts before that close.
+    """
+    from coord.drive_queue import entry_key, rewrite_after_for_split, sink_children
+    from coord.state import (
+        enqueue_drive_queue,
+        get_drive_queue_entry,
+        list_drive_queue,
+        update_drive_queue_entry,
+    )
+
+    sink_issue_numbers = sink_children(remapped_nodes)
+    original_key = entry_key(repo_name, original_issue)
+    sink_keys = [entry_key(repo_name, n) for n in sink_issue_numbers]
+
+    for row in list_drive_queue():
+        current_after = [str(a) for a in (row.get("after_json") or [])]
+        if original_key not in current_after:
+            continue
+        dep_repo = str(row.get("repo_name") or "")
+        dep_issue = int(row.get("issue_number") or 0)
+        new_after = rewrite_after_for_split(current_after, original_key, sink_keys)
+
+        enqueue_drive_queue(
+            dep_repo,
+            dep_issue,
+            machine=row.get("machine") or None,
+            after=new_after,
+            hold_after=bool(row.get("hold_after")),
+            hold_reason=str(row.get("hold_reason") or ""),
+            resume_when=str(row.get("resume_when") or ""),
+            hold_scope=str(row.get("hold_scope") or "entry"),
+            max_fix_rounds=row.get("max_fix_rounds"),
+            no_acceptance=bool(row.get("no_acceptance")),
+            plan_destructive=bool(row.get("plan_destructive")),
+        )
+        update_drive_queue_entry(
+            dep_repo,
+            dep_issue,
+            last_reason=(
+                f"re-pointed off superseded {original_key} onto #{epic_number}'s "
+                f"split children ({', '.join(sink_keys)}) by the {origin}"
+            ),
+        )
+
+        confirmed = get_drive_queue_entry(dep_repo, dep_issue)
+        confirmed_after = (
+            [str(a) for a in (confirmed.get("after_json") or [])]
+            if confirmed is not None
+            else None
+        )
+        if confirmed is None or sorted(confirmed_after) != sorted(new_after):
+            raise RuntimeError(
+                f"filed epic #{epic_number} but re-pointing queued dependent "
+                f"{dep_repo}#{dep_issue} off superseded {original_key} did not "
+                f"read back the new after= list"
+            )
+
+
 def file_and_queue_split_proposal(
     *,
     proposal: "SplitProposal",
@@ -1339,8 +1432,13 @@ def file_and_queue_split_proposal(
     ``proposal.chunks`` order, remap the placeholder work order onto the
     real numbers and splice it into the epic body, queue each child
     (confirming every queue write with a readback — an unconfirmed queue
-    insert is not a queued child), then close the original issue pointing
-    at the new epic — forcing past the "open children" guard (the
+    insert is not a queued child), re-point every ALREADY-queued entry
+    whose ``after=`` names the original onto the split's sink children
+    (:func:`_repoint_queued_dependents_at_split`, #3984 — otherwise
+    ``drive_queue._resolve_prereqs``'s ``live_prereq_terminal`` recovery
+    reads the original's close as "pre-req satisfied" and launches every
+    dependent before any child has landed), then close the original issue
+    pointing at the new epic — forcing past the "open children" guard (the
     original's own body is exactly the shape expected to trip it once it
     already carries a ``## Sub-issues``/``## Work order`` block, e.g. from
     a prior triage pass) and confirming the close itself with a readback,
@@ -1410,6 +1508,19 @@ def file_and_queue_split_proposal(
                 "did not read back from the drive queue"
             )
 
+    # #3984: before closing the original, re-point every dependent ALREADY
+    # queued against it onto the split's children — a failure here raises
+    # and propagates straight out of this function, same as every other
+    # step above, so the original is never closed with a dependent still
+    # pointing at it.
+    _repoint_queued_dependents_at_split(
+        repo_name=repo.name,
+        original_issue=proposal.issue_number,
+        epic_number=epic_number,
+        remapped_nodes=remapped_nodes,
+        origin=origin,
+    )
+
     # `force=True`: the original being split is likely to already carry a
     # `## Sub-issues`/`## Work order` block of its own (e.g. a prior triage
     # pass), which would otherwise trip `close_issue()`'s open-children

{code_coordinator-0.5.758 → code_coordinator-0.5.760}/coord/drive_queue.py

@@ -114,7 +114,7 @@ from coord.merge_queue import (
     is_ci_unreadable_reason,
     is_stale_smoke_reason,
 )
-from coord.milestone_order import TRACKING_ISSUE_LABEL
+from coord.milestone_order import TRACKING_ISSUE_LABEL, WorkOrderNode
 from coord.models import (
     CLOSES_ISSUE_TYPES,
     EPIC_DECOMPOSE_TYPE,
@@ -1551,6 +1551,20 @@ QUEUE_ALERT_STAGE = "drive-queue"
 #: change — `coord drive-queue status` still reads the record unchanged.
 QUEUE_ALERT_NO_REMEDY_COMMAND = "coord drive-queue list"
 
+
+def is_benign_queue_alert_command(command: object) -> bool:
+    """Is *command* the :data:`QUEUE_ALERT_NO_REMEDY_COMMAND` sentinel?
+
+    One normalization (`str(...).strip()`), shared by `coord drive-queue
+    status` (`coord.commands.drive_queue._queue_alert`'s caller) and the
+    notifier (`coord.notifier.collect.halted_drives`) — before #3983 each
+    wrote its own comparison (one on the raw dict value, the other via
+    `str(...).strip()` plus its own repo/issue check), which happened to
+    agree only because neither had yet drifted; this is the one answer both
+    now ask the identical question of (#2096).
+    """
+    return str(command or "").strip() == QUEUE_ALERT_NO_REMEDY_COMMAND
+
 #: #3413: a DISPLAY hint only — production's `coord-drive-queue.timer` fires
 #: every 3 minutes (`OnUnitActiveSec=3min`, `deploy/coord-drive-queue.timer`),
 #: not a value this module reads from the deployed unit (there is no seam to
@@ -1636,6 +1650,51 @@ def parse_after_spec(raw: str | Iterable[str], default_repo: str) -> list[str]:
     return out
 
 
+def sink_children(nodes: Iterable[WorkOrderNode]) -> list[int]:
+    """The subset of a split's children nothing else in *nodes* depends on.
+
+    A split's own ``after=`` graph can fan out into more than one
+    independent chain (e.g. ``C1 -> C2`` alongside a parallel ``C3``) — this
+    is every chain's own tail, i.e. the split's full "everything landed"
+    frontier. :func:`coord.decomposition_chat.file_and_queue_split_proposal`
+    re-points a dependent chained on the SUPERSEDED original onto exactly
+    this set: a dependent re-pointed at only the last-filed child would
+    launch the moment that ONE chain lands, while a sibling chain is still
+    mid-flight (#3984).
+
+    Order follows *nodes*' own order, not issue-number order — filed issue
+    numbers need not increase in work-order position order.
+    """
+    nodes = list(nodes)
+    depended_on = {dep for node in nodes for dep in node.after}
+    return [node.issue_number for node in nodes if node.issue_number not in depended_on]
+
+
+def rewrite_after_for_split(
+    after: Sequence[str], original_key: str, sink_keys: Sequence[str]
+) -> list[str]:
+    """Drop *original_key* from *after* and append *sink_keys* in its place.
+
+    Every OTHER pre-req *after* already names (the ``X`` in ``after=O,X``)
+    is kept, untouched — a dependent chained on more than the superseded
+    original still waits on those too. De-duplicates, preserving
+    first-seen order, so a dependent that already names one of the sink
+    children (unusual, but not impossible) doesn't end up listing it
+    twice. Returns a list with the same keys and order as *after* — never
+    raises — when *original_key* isn't present; callers are expected to
+    check that themselves before deciding whether a rewrite happened.
+    """
+    kept = [key for key in after if key != original_key]
+    if len(kept) == len(after):
+        return kept
+    seen = set(kept)
+    for key in sink_keys:
+        if key not in seen:
+            seen.add(key)
+            kept.append(key)
+    return kept
+
+
 # ── the queue row ────────────────────────────────────────────────────────────
 
 
@@ -4196,6 +4255,16 @@ class UnreachableWait:
     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.
+
+    `cause` (#3983) is :func:`classify_unreachable_wait_cause`'s verdict —
+    one of :data:`UNREACHABLE_WAIT_CAUSE_NEEDS_DECOMPOSITION`/
+    `_PREMISE_REFUSAL`/`_UPSTREAM_GAP_PARK` for a terminal park, or
+    `_DISPATCH_FAILURE`/`_NEVER_DISPATCHED` for the two shapes
+    :func:`is_unreachable_wait_shape` itself distinguishes. `reason_at` is
+    `entry.reason_at` carried straight through — the wall-clock stamp of
+    when `last_reason` (hence this wait) was written, so a renderer can
+    show how long the row has sat this way instead of a bare, undated
+    reason (#2133's rule, applied here).
     """
 
     key: str
@@ -4203,6 +4272,8 @@ class UnreachableWait:
     deferrals: int
     last_reason: str
     dependents: int = 0
+    cause: str = ""
+    reason_at: float | None = None
 
 
 def is_unreachable_wait_shape(entry: QueueEntry) -> bool:
@@ -4273,6 +4344,135 @@ def is_unreachable_wait_shape(entry: QueueEntry) -> bool:
     return entry.state == STATE_BLOCKED and _is_dispatch_failure_reason(entry.last_reason)
 
 
+# #3983: the cause label `classify_unreachable_wait_cause` assigns a row
+# matching `is_unreachable_wait_shape`. The three terminal-park values are
+# the SAME strings `coord.queue_diagnose` names
+# `CAUSE_NEEDS_DECOMPOSITION`/`CAUSE_PREMISE_REFUSAL`/`CAUSE_UPSTREAM_GAP_PARK`
+# — deliberately not imported from there: `coord.queue_diagnose` imports
+# `QueueEntry`/`is_unreachable_wait_shape` FROM this module, so importing its
+# constants back here would cycle. Keeping the literal text identical is
+# what lets a reader compare `coord drive-queue status`'s alert and `coord
+# drive-queue diagnose`'s verdict for the same row without translating
+# between two vocabularies for the same finding (#2096).
+UNREACHABLE_WAIT_CAUSE_NEEDS_DECOMPOSITION = "needs-decomposition"
+UNREACHABLE_WAIT_CAUSE_PREMISE_REFUSAL = "premise-refusal"
+UNREACHABLE_WAIT_CAUSE_UPSTREAM_GAP_PARK = "upstream-gap-park"
+#: `attempts > 0`, exhausted the retry budget with no #2273 dispatch-layer
+#: assignment ever created — the second `is_unreachable_wait_shape` branch.
+UNREACHABLE_WAIT_CAUSE_DISPATCH_FAILURE = "dispatch-failure"
+#: `attempts == 0`, no terminal-park marker — the original #2944 shape:
+#: nothing has ever tried to dispatch this row at all.
+UNREACHABLE_WAIT_CAUSE_NEVER_DISPATCHED = "never-dispatched"
+
+#: The three causes a worker/park-writer already asserted are terminal —
+#: "no fix-it leg or relaunch can resolve this" is the row's OWN last_reason
+#: text, not a guess this module is making. See
+#: :func:`unreachable_wait_remedy_command` for why that rules out the
+#: blanket `remove && add` requeue for exactly these three.
+_UNREACHABLE_WAIT_TERMINAL_PARK_CAUSES = frozenset(
+    {
+        UNREACHABLE_WAIT_CAUSE_NEEDS_DECOMPOSITION,
+        UNREACHABLE_WAIT_CAUSE_PREMISE_REFUSAL,
+        UNREACHABLE_WAIT_CAUSE_UPSTREAM_GAP_PARK,
+    }
+)
+
+_UNREACHABLE_WAIT_CAUSE_LABEL: dict[str, str] = {
+    UNREACHABLE_WAIT_CAUSE_NEEDS_DECOMPOSITION: "needs-decomposition park (#3931)",
+    UNREACHABLE_WAIT_CAUSE_PREMISE_REFUSAL: "premise-refusal park (#3164)",
+    UNREACHABLE_WAIT_CAUSE_UPSTREAM_GAP_PARK: "upstream-gap park (#3977)",
+    UNREACHABLE_WAIT_CAUSE_DISPATCH_FAILURE: "exhausted dispatch-layer death (#2273)",
+    UNREACHABLE_WAIT_CAUSE_NEVER_DISPATCHED: "never dispatched",
+}
+
+#: The manual next-step for a cause no blind command can fix — embedded
+#: straight into :func:`describe_unreachable_wait` so the reason text stays
+#: self-contained even where :func:`unreachable_wait_remedy_command` can only
+#: offer a read-only fallback (#3983).
+_UNREACHABLE_WAIT_CAUSE_MANUAL_NOTE: dict[str, str] = {
+    UNREACHABLE_WAIT_CAUSE_NEEDS_DECOMPOSITION: (
+        "not fixable by any fix-it leg or relaunch — decompose the issue "
+        "into the proposed sub-issues and clear the row by hand"
+    ),
+    UNREACHABLE_WAIT_CAUSE_PREMISE_REFUSAL: (
+        "not fixable by a requeue alone — run `coord drive-queue "
+        "clear-refusal` once the missing prerequisite is confirmed, THEN "
+        "`coord drive-queue remove` + `add`"
+    ),
+    UNREACHABLE_WAIT_CAUSE_UPSTREAM_GAP_PARK: (
+        "not fixable by any fix-it leg or relaunch — clear the row by hand "
+        "once the release lands or the gap is confirmed"
+    ),
+}
+
+
+def classify_unreachable_wait_cause(entry: QueueEntry) -> str:
+    """Which `is_unreachable_wait_shape` branch explains *entry*'s wedge.
+
+    Read straight off `entry.last_reason` via the same marker predicates
+    `coord.drive_queue`'s own parked pre-pass and
+    `coord.queue_diagnose._rule_terminal_park` already trust for this text
+    — never a live probe, so this is exactly as cheap as the shape check
+    itself (#2096: one question, one answer, asked the same way everywhere).
+    Callers are expected to gate on :func:`is_unreachable_wait_shape` first;
+    called on a row that fails that shape, this still returns a value
+    rather than raising (the two dispatch-shaped labels degrade safely for
+    an unmatched row — see :func:`unreachable_wait_remedy_command`, which
+    treats an unrecognised cause the same as "never dispatched").
+    """
+    reason = entry.last_reason
+    if is_premise_refusal_reason(reason):
+        return UNREACHABLE_WAIT_CAUSE_PREMISE_REFUSAL
+    if is_needs_decomposition_reason(reason):
+        return UNREACHABLE_WAIT_CAUSE_NEEDS_DECOMPOSITION
+    if is_upstream_gap_park_reason(reason):
+        return UNREACHABLE_WAIT_CAUSE_UPSTREAM_GAP_PARK
+    if entry.attempts and _is_dispatch_failure_reason(reason):
+        return UNREACHABLE_WAIT_CAUSE_DISPATCH_FAILURE
+    return UNREACHABLE_WAIT_CAUSE_NEVER_DISPATCHED
+
+
+def unreachable_wait_remedy_command(w: UnreachableWait) -> str:
+    """The one-line fix for *w*, picked by `.cause` (#3983) — never the
+    blanket `coord drive-queue remove && add` requeue for a cause the row's
+    OWN last_reason already asserts no relaunch can resolve.
+
+    Mirrors :func:`merge_gate_remedy_command`'s #3016 rule for the same
+    reason: a wrong "run this" is worse than no recommendation, so a cause
+    with no blind-safe command falls back to the identical read-only
+    inspect pattern (`coord drive-queue list`, scoped to the entry's repo)
+    rather than ever proposing `remove`+`add` for a needs-decomposition,
+    premise-refusal or upstream-gap park — relaunching one of those just
+    re-runs the drive straight back into the identical park (the #3922
+    needs-decomposition incident this guards against).
+    """
+    parsed = parse_key(w.key)
+    repo, issue = parsed if parsed is not None else ("", 0)
+    if w.cause in _UNREACHABLE_WAIT_TERMINAL_PARK_CAUSES:
+        return f"coord drive-queue list --repo {repo}"
+    return (
+        f"coord drive-queue remove {repo} {issue} && "
+        f"coord drive-queue add {repo} {issue}"
+    )
+
+
+def format_coarse_duration(delta_seconds: float) -> str:
+    """``42s`` / ``3h`` / ``5d`` — coarse, single-unit (#2133's ask).
+
+    Shared by :func:`describe_unreachable_wait` and
+    `coord.commands.drive_queue`'s own age renderings (imported from here
+    rather than re-implemented) so "how long has this held" always reads
+    the same shape everywhere it is shown.
+    """
+    if delta_seconds < 60:
+        return f"{int(delta_seconds)}s"
+    if delta_seconds < 3600:
+        return f"{int(delta_seconds // 60)}m"
+    if delta_seconds < 86400:
+        return f"{int(delta_seconds // 3600)}h"
+    return f"{int(delta_seconds // 86400)}d"
+
+
 def is_unreachable_wait(
     entry: QueueEntry,
     *,
@@ -4327,21 +4527,74 @@ def detect_unreachable_waits(
                 deferrals=e.deferrals,
                 last_reason=e.last_reason,
                 dependents=dependents_of.get(e.key, 0),
+                cause=classify_unreachable_wait_cause(e),
+                reason_at=e.reason_at,
             )
         )
     return waits
 
 
-def unreachable_wait_alert(waits: Sequence[UnreachableWait]) -> QueueAlert:
+def describe_unreachable_wait(w: UnreachableWait, *, now: float | None = None) -> str:
+    """Render one :class:`UnreachableWait` — the entry, its cause (#3983),
+    how long it has sat this way, and (#2978) its dependent count when
+    non-zero, naming WHY those dependents need no remedy of their own (they
+    self-heal on #2756 the moment the root clears, so a reader must not
+    read this as "fix these too").
+
+    *now* is the caller's wall clock: omitted (the default), the age clause
+    is left out rather than guessed — the same degrade `_reason_age_suffix`
+    uses for a row with no `reason_at` at all. Every live caller has a
+    clock available (`time.time()` for the CLI/notifier, `ctx.now` for the
+    health probe) and is expected to pass it; only a clockless test exercises
+    the bare form.
+
+    One rendering, shared by :func:`unreachable_wait_alert` (the `coord
+    drive-queue status` `alert:` line), `coord doctor`'s WARN sample
+    (:mod:`coord.health.checks.wedged_drive_queue`) and (#3983)
+    :mod:`coord.notifier.collect`'s own per-root ``HaltedDrive`` reason —
+    so the CLI, the health probe and the pager phrase the identical finding
+    identically rather than drifting apart (#2096).
+    """
+    age = ""
+    if now is not None and w.reason_at is not None:
+        age = f", stuck {format_coarse_duration(max(0.0, now - w.reason_at))}"
+    cause_label = _UNREACHABLE_WAIT_CAUSE_LABEL.get(w.cause, w.cause or "unknown cause")
+    base = f"{w.key} ({w.state}, {cause_label}, {w.deferrals} deferrals{age})"
+    notes: list[str] = []
+    manual_note = _UNREACHABLE_WAIT_CAUSE_MANUAL_NOTE.get(w.cause)
+    if manual_note:
+        notes.append(manual_note)
+    if w.dependents:
+        plural = "y" if w.dependents == 1 else "ies"
+        notes.append(
+            f"{w.dependents} dependent entr{plural} chained behind it will "
+            "self-heal automatically once this clears (#2756), no remedy "
+            "needed on them"
+        )
+    if notes:
+        base += " — " + "; ".join(notes)
+    return base
+
+
+def unreachable_wait_alert(
+    waits: Sequence[UnreachableWait], *, now: float | None = None
+) -> QueueAlert:
     """The queue-level record #2944's predicate raises, in :func:`_hold_alert`'s
     shape — a message naming the entry (or entries), the evidence that
-    qualified it, and the ONE remedy that actually clears it.
+    qualified it, and the remedy that actually clears it.
+
+    #3983: the remedy is picked PER ENTRY by :func:`unreachable_wait_remedy_command`
+    — never the blanket ``remove`` + ``add`` for a needs-decomposition/
+    premise-refusal/upstream-gap park, each of which the row's own
+    last_reason already asserts no relaunch can resolve (see that
+    function's docstring). The top-level ``command`` field mirrors the
+    single entry's remedy when there is exactly one; with several entries
+    of possibly different causes there is no one command that is safe for
+    all of them, so it falls back to the same read-only ``coord
+    drive-queue list`` #3016's ``merge_gate_remedy_command`` falls back to
+    — the per-entry remedy is still named in ``details`` and inline in
+    ``reason`` via :func:`describe_unreachable_wait`.
 
-    ``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
@@ -4358,42 +4611,40 @@ def unreachable_wait_alert(waits: Sequence[UnreachableWait]) -> QueueAlert:
     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.
     """
-    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])
+    names = ", ".join(describe_unreachable_wait(w, now=now) for w in waits[:5])
     more = ", ..." if len(waits) > 5 else ""
     plural = len(waits) != 1
+    if len(waits) == 1:
+        command = unreachable_wait_remedy_command(waits[0])
+    elif waits and all(
+        w.cause not in _UNREACHABLE_WAIT_TERMINAL_PARK_CAUSES for w in waits
+    ):
+        command = (
+            "coord drive-queue remove <repo> <issue> && "
+            "coord drive-queue add <repo> <issue> — for each ROOT entry "
+            "named above; any dependents chained behind it self-heal on "
+            "their own (#2756)"
+        )
+    else:
+        command = "coord drive-queue list  # remedy differs per entry — see above"
     return QueueAlert(
         reason=(
             f"{len(waits)} queue entr{'ies' if plural else 'y'} stuck in a "
             "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 ROOT entry named "
-            "above — never on a dependent chained behind one."
+            f"no sweep can ever clear this on its own: {names}{more}. Fix "
+            "is named per entry above — a needs-decomposition/"
+            "premise-refusal/upstream-gap park is NEVER cleared by `remove`"
+            "+`add`, only an ordinary never-dispatched/dispatch-failure root is."
         ),
         details=tuple(
-            f"{w.key}: {w.state}, {w.deferrals} deferrals, "
-            f"dependents={w.dependents}, last_reason={w.last_reason!r}"
+            f"{w.key}: {w.state}, cause={w.cause}, {w.deferrals} deferrals, "
+            f"dependents={w.dependents}, last_reason={w.last_reason!r}, "
+            f"fix={unreachable_wait_remedy_command(w)}"
             for w in waits
         ),
-        command=(
-            "coord drive-queue remove <repo> <issue> && "
-            "coord drive-queue add <repo> <issue> — for each ROOT entry "
-            "named above; any dependents chained behind it self-heal on "
-            "their own (#2756)"
-        ),
+        command=command,
     )