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

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

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.756",
+  "tag": "0.5.758",
   "distance": 0,
-  "node": "g6554d6ff10c266cf881ccdd2d5940ba15260475a",
+  "node": "g8f42c93d4e44ab72667aba0b52cb6a7b0631535b",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-11-11"

{code_coordinator-0.5.756 → code_coordinator-0.5.758}/coord/agent.py

@@ -4521,6 +4521,22 @@ only re-propose the same split. Omit the marker entirely for every other \
 or a false/unmet premise that is NOT "already done") — those still read \
 off your prose exactly as before.
 
+With `needs-decomposition`, also put the split in your final message as \
+this block (one `## Child N:` per proposed issue, each with its own \
+`## Files` list); the coordinator files the children and supersedes this \
+issue automatically when it is well-formed:
+
+  SIZE_TRIAGE_VERDICT: split
+  ## Child 1: <title>
+  <one paragraph of scope>
+
+  ## Files
+  - path/a.py
+
+  ## Child 2: <title>
+  ...
+  END_SIZE_TRIAGE
+
 Progress reporting:
 - After each significant step (first build, test run, approach change), \
 output a status line in exactly this format:

{code_coordinator-0.5.756 → code_coordinator-0.5.758}/coord/board_doctor_policy.py

@@ -2856,14 +2856,39 @@ def _diagnosis_options(
     return tuple(options)
 
 
+def _most_recent_leg_aid(repo_name: str, issue_number: int) -> str | None:
+    """The ``assignment_id`` of the most recently dispatched leg against
+    *repo_name*#*issue_number*, or ``None`` on no match or a read failure.
+
+    Reads `coord.state.load_dispatched`, the SAME dispatched-ledger read
+    `coord log`/`coord sessions`/`coord status` already use (#2096) rather
+    than a second history source — its own docstring guarantees the result
+    is sorted oldest-first, so the last match is the most recent leg. Only
+    used to make a board-doctor alert's suggested ``coord log <aid>``
+    concrete; a missing or unreadable ledger must never block the alert
+    itself, so this fails open to ``None`` rather than raising.
+    """
+    from coord.state import load_dispatched  # noqa: PLC0415
+
+    try:
+        matches = [
+            d
+            for d in load_dispatched()
+            if d.get("repo_name") == repo_name and d.get("issue_number") == issue_number
+            and d.get("assignment_id")
+        ]
+    except Exception:  # noqa: BLE001 — best-effort enrichment only
+        return None
+    return str(matches[-1]["assignment_id"]) if matches else None
+
+
 def _alert_resolution(row: StuckRow, repo_name: str, issue_number: int) -> tuple[str, str]:
     """``(reason_suffix, proposed_command)`` for *row*'s cause (#3761's C4).
 
     Every alert-only cause gets a one-line, ready-to-run operator command
     rather than a self-executing fix — the whole point of this tier is that
     recovery needs a human decision. ``"coord status"`` is the fallback for
-    causes with no single-command remedy; the two causes below each have
-    one:
+    causes with no single-command remedy; the causes below each have one:
 
     * ``queue_diagnose.CAUSE_GATE_BLOCKED`` on a **merge-queue** row — this
       cause is only ever minted there (`_MERGE_QUEUE_STUCK_CAUSE`) from the
@@ -2888,7 +2913,49 @@ def _alert_resolution(row: StuckRow, repo_name: str, issue_number: int) -> tuple
       is actually true rather than claiming a pause that doesn't exist;
       the command stays ``coord status`` — the streak clears on its own
       the next time the base goes green.
+    * #3979: :data:`queue_diagnose.CAUSE_NEEDS_DECOMPOSITION`/
+      :data:`queue_diagnose.CAUSE_PREMISE_REFUSAL`/
+      :data:`queue_diagnose.CAUSE_UPSTREAM_GAP_PARK` — a row the tick's
+      own parked pre-pass already treats as terminal (the worker/upstream
+      park that parked it wrote one of `coord.models`'
+      ``NEEDS_DECOMPOSITION_MARKER``/``PREMISE_REFUSAL_MARKER``/
+      ``UPSTREAM_GAP_PARK_MARKER`` into `last_reason`). There is no
+      single-command *fix* for any of the three — each needs an
+      operator judgment call (decompose, re-scope, or wait on a release)
+      — so unlike every other alert-only cause above the "command" here
+      is the read-only inspection step, never ``coord status``: the whole
+      point is naming the SPECIFIC action, not pointing at the generic
+      fleet view.
     """
+    if row.cause in (
+        queue_diagnose.CAUSE_NEEDS_DECOMPOSITION,
+        queue_diagnose.CAUSE_PREMISE_REFUSAL,
+        queue_diagnose.CAUSE_UPSTREAM_GAP_PARK,
+    ):
+        command = f"coord log {_most_recent_leg_aid(repo_name, issue_number) or '<aid>'}"
+        action = {
+            queue_diagnose.CAUSE_NEEDS_DECOMPOSITION: (
+                "decompose the issue into the sub-issues already proposed "
+                "on it (posted as a comment by the coordinator), then "
+                "`coord drive-queue remove` + `add` for the replacement(s)"
+            ),
+            queue_diagnose.CAUSE_PREMISE_REFUSAL: (
+                "re-scope or close the issue once the missing prerequisite "
+                "it named is confirmed, then `coord drive-queue clear-refusal` "
+                "and `remove` + `add` for a fresh row"
+            ),
+            queue_diagnose.CAUSE_UPSTREAM_GAP_PARK: (
+                "wait for the named release to land or the gap to be "
+                "confirmed, then `coord drive-queue remove` + `add` for a "
+                "fresh row"
+            ),
+        }[row.cause]
+        return (
+            f" — this row is parked terminal, not stuck; no fix-it leg or "
+            f"relaunch can resolve it — {action}; re-read its own evidence "
+            f"first with: `{command}`",
+            command,
+        )
     if row.cause == queue_diagnose.CAUSE_GATE_BLOCKED:
         if row.queue == "merge-queue":
             command = (

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

@@ -1319,9 +1319,13 @@ def file_and_queue_split_proposal(
     proposal: "SplitProposal",
     verification: "SplitVerification",
     repo: "Repo",
+    origin: str = "preflight size-triage review",
 ) -> int:
     """File *proposal*'s chunks as a real epic + children and queue them.
 
+    *origin* names what proposed the split; it is quoted in the epic body
+    and in the comment closing the superseded original.
+
     Called only after :func:`coord.preflight_size.verify_split_proposal` has
     returned ``ok=True`` for *verification* — this function trusts
     ``verification.work_order`` and ``verification.epic_body`` without
@@ -1365,9 +1369,8 @@ def file_and_queue_split_proposal(
 
     epic_body = (
         f"{proposal.rationale}\n\n"
-        f"Split from #{proposal.issue_number} by the preflight "
-        "size-triage review. Children are filed below and queued in "
-        "overlap order."
+        f"Split from #{proposal.issue_number} by the {origin}. Children "
+        "are filed below and queued in overlap order."
     )
     epic = github_ops.create_issue(
         repo.github,
@@ -1419,8 +1422,7 @@ def file_and_queue_split_proposal(
         proposal.issue_number,
         comment=(
             f"Superseded by #{epic_number} — split into "
-            f"{len(proposal.chunks)} child issue(s) per the size-triage "
-            "review."
+            f"{len(proposal.chunks)} child issue(s) per the {origin}."
         ),
         force=True,
     )
@@ -1438,6 +1440,105 @@ def file_and_queue_split_proposal(
     return epic_number
 
 
+#: The ``origin`` text :func:`auto_split_needs_decomposition` passes to
+#: :func:`file_and_queue_split_proposal`.
+NEEDS_DECOMPOSITION_SPLIT_ORIGIN = "work leg's needs-decomposition split proposal"
+
+
+def auto_split_needs_decomposition(
+    final_message: str | None,
+    *,
+    config: "Config",
+    repo_name: str,
+    issue_number: int,
+) -> int | None:
+    """File the split a ``needs-decomposition`` work leg proposed, if it
+    proposed one in the machine-readable size-triage format.
+
+    *final_message* is the worker's own final message. The worker states its
+    split as a ``SIZE_TRIAGE_VERDICT: split`` / ``## Child N:`` /
+    ``## Files`` / ``END_SIZE_TRIAGE`` block — the same wire format the
+    size-triage agent uses, parsed by :func:`parse_size_triage_response` —
+    and the split then goes through the identical
+    :func:`coord.preflight_size.verify_split_proposal` gate and
+    :func:`file_and_queue_split_proposal` filer a size-triage SPLIT verdict
+    does: an epic plus chained children are filed and queued, and the
+    original is closed as superseded. The original's own (parked) drive-
+    queue row is then removed, since the issue it tracks is closed.
+
+    Returns the new epic's issue number, or ``None`` when nothing was filed:
+    the repo has not opted into the preflight decomposition guard
+    (:meth:`coord.config.Config.preflight_guard_enabled` — the same opt-in
+    that governs every other automatic split), the message carries no
+    complete split block (prose-only proposals stay with the coordinator,
+    exactly as before), the original issue is already closed (a replayed
+    transition, or someone already decomposed it), or the proposal fails the
+    verification gate — a broken epic is never filed. A failure *inside*
+    the filer propagates: by then real issues exist on GitHub.
+    """
+    text = final_message or ""
+    if not _SIZE_TRIAGE_VERDICT_RE.search(text):
+        return None
+    repo = config.repo(repo_name)
+    if repo is None or not config.preflight_guard_enabled(repo_name):
+        return None
+
+    from coord import github_ops
+    from coord.preflight_size import verify_split_proposal
+
+    issue_data = github_ops.get_issue(repo.github, issue_number)
+    if str(issue_data.get("state") or "").upper() == "CLOSED":
+        return None
+    issue_title = issue_data.get("title") or f"issue #{issue_number}"
+
+    try:
+        proposal = parse_size_triage_response(
+            text,
+            repo_name=repo_name,
+            issue_number=issue_number,
+            issue_title=issue_title,
+        )
+    except SizeTriageError as exc:
+        _log.info(
+            "auto_split_needs_decomposition: %s#%s split block unparseable: %s",
+            repo_name, issue_number, exc,
+        )
+        return None
+    if proposal is None:
+        return None
+    proposal.rationale = (
+        "a work leg concluded this issue needs decomposition and proposed "
+        "this split"
+    )
+
+    verification = verify_split_proposal(proposal)
+    if not verification.ok:
+        _log.info(
+            "auto_split_needs_decomposition: %s#%s split rejected: %s",
+            repo_name, issue_number, verification.reason,
+        )
+        return None
+
+    epic_number = file_and_queue_split_proposal(
+        proposal=proposal,
+        verification=verification,
+        repo=repo,
+        origin=NEEDS_DECOMPOSITION_SPLIT_ORIGIN,
+    )
+
+    from coord.state import dequeue_drive_queue
+
+    try:
+        dequeue_drive_queue(repo_name, issue_number, operator=False)
+    except Exception as exc:  # noqa: BLE001
+        _log.warning(
+            "auto_split_needs_decomposition: filed epic #%s but could not "
+            "dequeue superseded %s#%s: %s",
+            epic_number, repo_name, issue_number, exc,
+        )
+    return epic_number
+
+
 def dispatch_size_triage_review(
     *,
     repo_cfg: "Repo",

{code_coordinator-0.5.756 → code_coordinator-0.5.758}/coord/notify.py

@@ -2364,6 +2364,55 @@ def _capture_upstream_gaps(transition: Transition, entry: dict, record: dict) ->
         )
 
 
+def _capture_needs_decomposition_split(
+    transition: Transition, entry: dict, record: dict
+) -> None:
+    """File the split a ``needs-decomposition`` work leg proposed in the
+    machine-readable size-triage block — see
+    :func:`coord.decomposition_chat.auto_split_needs_decomposition`.
+
+    Reads the worker's final message from the row's
+    ``needs_decomposition_reason`` first, falling back to the final message
+    in the worker log. Best-effort: any failure is logged and the issue
+    stays parked for the coordinator, the same as a prose-only proposal.
+    """
+    from coord.decomposition_chat import (  # noqa: PLC0415
+        SIZE_TRIAGE_END_MARKER,
+        auto_split_needs_decomposition,
+    )
+
+    if (record.get("type") or "work") != "work" or not transition.issue_number:
+        return
+    try:
+        text = entry.get("needs_decomposition_reason") or ""
+        if SIZE_TRIAGE_END_MARKER not in text:
+            from coord.upstream_gaps import (  # noqa: PLC0415
+                final_message_from_log_text,
+            )
+
+            text = final_message_from_log_text(_worker_log_text(transition, entry))
+        if SIZE_TRIAGE_END_MARKER not in text:
+            return
+        from coord.config import load as _load_config  # noqa: PLC0415
+
+        epic_number = auto_split_needs_decomposition(
+            text,
+            config=_load_config(),
+            repo_name=transition.repo_name,
+            issue_number=transition.issue_number,
+        )
+        if epic_number is not None:
+            log.info(
+                "_capture_needs_decomposition_split: %s#%s split into epic #%s",
+                transition.repo_name, transition.issue_number, epic_number,
+            )
+    except Exception as exc:  # noqa: BLE001
+        log.warning(
+            "_capture_needs_decomposition_split: failed for %s: %s",
+            transition.assignment_id, exc,
+        )
+
+
 def _capture_smoke_tests(transition: Transition, entry: dict) -> None:
     """#252: parse the worker's SMOKE_TESTS block and persist it on the row.
 
@@ -4966,6 +5015,9 @@ def post_transition(transition: Transition, record: dict, entry: dict) -> None:
             transition.event,
             branch=entry.get("branch"),
         )
+        # Runs after `mark_notified` so a split that files issues and then
+        # fails partway can never be replayed into a duplicate epic.
+        _capture_needs_decomposition_split(transition, entry, record)
     else:
         # #1605/#1797: carry the agent's own diagnostic (a usage-limit kill,
         # a terminal API-error classification, or an auth-shaped push

{code_coordinator-0.5.756 → code_coordinator-0.5.758}/coord/queue_diagnose.py

@@ -60,6 +60,11 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Protocol
 
 from coord.drive_queue import QueueEntry, is_unreachable_wait_shape
+from coord.models import (
+    is_needs_decomposition_reason,
+    is_premise_refusal_reason,
+    is_upstream_gap_park_reason,
+)
 
 if TYPE_CHECKING:
     from coord.gates import GateReport
@@ -68,11 +73,14 @@ _log = logging.getLogger(__name__)
 
 __all__ = [
     "CAUSE_INTEGRATION_RED",
+    "CAUSE_NEEDS_DECOMPOSITION",
     "CAUSE_NEVER_DISPATCHED",
+    "CAUSE_PREMISE_REFUSAL",
     "CAUSE_PROSE",
     "CAUSE_REVIEW_STALE",
     "CAUSE_TEST_STALE",
     "CAUSE_UNKNOWN",
+    "CAUSE_UPSTREAM_GAP_PARK",
     "CONFIDENCE_HIGH",
     "CONFIDENCE_LOW",
     "CONFIDENCE_MEDIUM",
@@ -115,6 +123,37 @@ __all__ = [
 # what Phase 2's scoping would count.  Keep them stable: a renamed slug
 # silently splits a bucket in the corpus.
 
+#: #3979: a row the tick's own parked pre-pass (`coord.drive_queue`'s
+#: parked branch inside its main loop) ALREADY recognises as terminal from
+#: `entry.last_reason` carrying `coord.models.NEEDS_DECOMPOSITION_MARKER`
+#: (`coord.models.is_needs_decomposition_reason`) — a worker leg concluded
+#: the issue itself needs splitting and pushed 0 commits by design, so
+#: there is, and never will be, a PR. Checked FIRST in `_RULES`, strictly
+#: ahead of every PR-shaped rule (`_rule_pr_merged`/`_rule_no_pr`/etc.):
+#: without that ordering a parked needs-decomposition row reads
+#: byte-for-byte like `CAUSE_NO_PR` — which IS investigate-eligible — and
+#: board-doctor's sweep dispatches a fix-it leg that re-reports the
+#: identical split proposal (#3979's incident: two legs, zero commits,
+#: then a `coord status` alert that never mentions decomposition at all).
+#: Never auto-dispatch-eligible and never on the investigate tier — see
+#: `coord.board_doctor_policy`'s module docstring: nothing on the board
+#: signals when decomposition has happened, so there is no external
+#: verdict a fix-it leg or an auto-action could ever observe.
+CAUSE_NEEDS_DECOMPOSITION = "needs-decomposition"
+#: #3979 audit of the sibling terminal park `coord.drive_queue`'s parked
+#: pre-pass already skips (`coord.models.is_premise_refusal_reason`): the
+#: same "no PR, no external verdict, never auto-dispatch" shape as
+#: :data:`CAUSE_NEEDS_DECOMPOSITION` above, for a worker that found a named
+#: prerequisite missing rather than the issue needing a split. Checked
+#: immediately after it, same ordering rationale.
+CAUSE_PREMISE_REFUSAL = "premise-refusal"
+#: #3979 audit of the other sibling terminal park
+#: (`coord.models.is_upstream_gap_park_reason`, written by
+#: `coord.upstream_gaps._park_queue_row` rather than a worker exit): the
+#: same shape again — no PR, no external verdict, never auto-dispatch —
+#: for a row parked on a confirmed upstream gap (unreleased symbol, or a
+#: recent-close dedup).
+CAUSE_UPSTREAM_GAP_PARK = "upstream-gap-park"
 CAUSE_PR_MERGED = "pr-merged"
 CAUSE_PR_CLOSED = "pr-closed"
 CAUSE_MERGE_CONFLICT = "merge-conflict"
@@ -195,6 +234,9 @@ CAUSE_TEST_STALE = "test-stale"
 CAUSE_UNKNOWN = "unknown"
 
 CAUSE_PROSE: dict[str, str] = {
+    CAUSE_NEEDS_DECOMPOSITION: "a worker leg already concluded the issue needs splitting and parked the row by design (#3931) — not fixable by any fix-it leg or relaunch; decompose the issue into the proposed sub-issues and clear the row by hand",
+    CAUSE_PREMISE_REFUSAL: "a worker leg already concluded a named prerequisite is missing and parked the row by design (#3164) — not fixable by any fix-it leg or relaunch; re-scope or close the issue once the prerequisite is confirmed, then clear the row by hand",
+    CAUSE_UPSTREAM_GAP_PARK: "the row is parked on a confirmed upstream gap (#3977) — not fixable by any fix-it leg or relaunch; clear the row by hand once the release lands or the gap is confirmed",
     CAUSE_PR_MERGED: "the PR merged while the entry sat stalled, so whatever the queue said had outlived its subject",
     CAUSE_PR_CLOSED: "the PR was closed while the entry sat stalled, so the queue is waiting on work that no longer exists",
     CAUSE_MERGE_CONFLICT: "GitHub reports the PR as conflicting; the branch needs a rebase before anything else can be true",
@@ -587,6 +629,46 @@ def _stated_still_supported(family: str, live: LiveState) -> bool | None:
 # probes, never average them.
 
 
+def _rule_terminal_park(entry: QueueEntry, live: LiveState) -> tuple[str, str, str] | None:
+    """#3979: classify a row the tick's own parked pre-pass already treats
+    as terminal, straight off ``entry.last_reason`` — never off any live
+    probe. Checked FIRST in :data:`_RULES`, strictly ahead of every
+    PR-shaped rule below: a terminal park has, by construction, no PR (the
+    worker that parked it pushed 0 commits), so :func:`_rule_no_pr` would
+    otherwise claim every one of these, and :data:`CAUSE_NO_PR` IS
+    investigate-eligible — which is exactly the #3979 incident, a fix-it
+    leg relaunched against a row nothing can fix by relaunching.
+
+    The three predicates this reads
+    (``coord.models.is_needs_decomposition_reason``/
+    ``is_premise_refusal_reason``/``is_upstream_gap_park_reason``) are the
+    SAME ones ``coord.drive_queue``'s own parked pre-pass already trusts
+    to leave these rows parked rather than resuming them (#2096: one
+    question, one answer) — this can never answer "terminal" for a row
+    that tick would itself flip back to ``waiting``.
+    """
+    reason = entry.last_reason
+    if is_needs_decomposition_reason(reason):
+        return (
+            CAUSE_NEEDS_DECOMPOSITION,
+            CONFIDENCE_HIGH,
+            f"last_reason: needs-decomposition park (#3931) — {reason}",
+        )
+    if is_premise_refusal_reason(reason):
+        return (
+            CAUSE_PREMISE_REFUSAL,
+            CONFIDENCE_HIGH,
+            f"last_reason: premise-refusal park (#3164) — {reason}",
+        )
+    if is_upstream_gap_park_reason(reason):
+        return (
+            CAUSE_UPSTREAM_GAP_PARK,
+            CONFIDENCE_HIGH,
+            f"last_reason: upstream-gap park (#3977) — {reason}",
+        )
+    return None
+
+
 def _rule_pr_merged(entry: QueueEntry, live: LiveState) -> tuple[str, str, str] | None:
     if live.pr_state == "MERGED":
         return CAUSE_PR_MERGED, CONFIDENCE_HIGH, _pr_line(live)
@@ -752,6 +834,10 @@ def _rule_agent_unreachable(
 
 
 _RULES = (
+    # #3979: a terminal park's marker in `entry.last_reason` wins outright,
+    # strictly before every PR-shaped rule below — see
+    # `_rule_terminal_park`'s own docstring for why the ordering matters.
+    _rule_terminal_park,
     _rule_pr_merged,
     _rule_pr_closed,
     _rule_conflict,

{code_coordinator-0.5.756 → code_coordinator-0.5.758}/tests/test_board_doctor.py

@@ -2358,6 +2358,86 @@ class TestNeverDispatchedRowReachesTheSweep:
         assert alert.count == 0
 
 
+class TestNeedsDecompositionRowNeverReDispatches:
+    """#3979: a row the tick's own parked pre-pass already treats as
+    terminal (a `WORK_OUTCOME: needs-decomposition` worker exit, parked by
+    `coord.models.NEEDS_DECOMPOSITION_MARKER`) must classify as its own
+    cause — never `queue_diagnose.CAUSE_NO_PR`, which IS investigate-
+    eligible — and the sweep must take no auto-dispatch action for it,
+    in a dry run or a real one.
+
+    Same end-to-end shape as `TestNeverDispatchedRowReachesTheSweep` above:
+    `queue_diagnose.run_pass` -> `coord.board_doctor.drive_queue_rows` ->
+    `sweep`, with the real `policy_tier_of` — load-bearing evidence the
+    row is actually routed to the alert tier, not a tautology.
+    """
+
+    def _rows(self) -> list:
+        from coord.drive_queue import STATE_PARKED
+        from coord.models import NEEDS_DECOMPOSITION_MARKER
+        from coord.queue_diagnose import LiveState
+
+        entry = QueueEntry(
+            repo="acme/widgets",
+            issue=3979,
+            state=STATE_PARKED,
+            attempts=1,
+            last_reason=(
+                f"{NEEDS_DECOMPOSITION_MARKER} split into: (1) the API "
+                "surface, (2) the CLI wiring"
+            ),
+        )
+        episode = {
+            "key": entry.key,
+            "state": STATE_PARKED,
+            "diagnoses": 0,
+            "diagnosed_cause": "",
+        }
+
+        class _NoPrProbe:
+            def probe(self, entry_):
+                return LiveState(pr_number=None, pr_state="none")
+
+        diagnoses = queue_diagnose.run_pass([entry], [episode], probe=_NoPrProbe())
+        return drive_queue_rows(diagnoses)
+
+    def test_classifies_as_needs_decomposition_not_no_pr(self) -> None:
+        [row] = self._rows()
+        assert row.cause == queue_diagnose.CAUSE_NEEDS_DECOMPOSITION
+        assert row.cause != queue_diagnose.CAUSE_NO_PR
+
+    def test_dry_run_sweep_dispatches_nothing(self) -> None:
+        from coord.board_doctor_policy import policy_tier_of
+
+        rows = self._rows()
+        auto = _Recorder()
+        alert = _Recorder()
+        sweep(
+            rows,
+            tier_of=policy_tier_of,
+            auto_dispatchers={queue_diagnose.CAUSE_NEEDS_DECOMPOSITION: auto},
+            alert_dispatcher=alert,
+            dry_run=True,
+        )
+        assert auto.count == 0
+        assert alert.count == 0
+
+    def test_real_sweep_alerts_but_never_auto_dispatches(self) -> None:
+        from coord.board_doctor_policy import policy_tier_of
+
+        rows = self._rows()
+        auto = _Recorder()
+        alert = _Recorder()
+        sweep(
+            rows,
+            tier_of=policy_tier_of,
+            auto_dispatchers={queue_diagnose.CAUSE_NEEDS_DECOMPOSITION: auto},
+            alert_dispatcher=alert,
+        )
+        assert auto.count == 0
+        assert alert.count == 1
+
+
 class TestParseNoProgressMinutes:
     """#3888 review: `no_progress_minutes` validates the same way its
     sibling `followthrough_cap` already does — tested here since

{code_coordinator-0.5.756 → code_coordinator-0.5.758}/tests/test_board_doctor_policy.py

@@ -164,6 +164,13 @@ class TestPolicyTierOf:
             queue_diagnose.CAUSE_NOTHING_BLOCKING,
             queue_diagnose.CAUSE_CI_GREEN,
             CAUSE_BASELINE_RED,
+            # #3979: a terminal park has no external verdict to resume it,
+            # so it must never auto-dispatch or compete for the shared
+            # investigate-tier budget — see TestAlertResolutionTerminalPark
+            # below for the alert text itself.
+            queue_diagnose.CAUSE_NEEDS_DECOMPOSITION,
+            queue_diagnose.CAUSE_PREMISE_REFUSAL,
+            queue_diagnose.CAUSE_UPSTREAM_GAP_PARK,
         ):
             assert cause not in ALLOWLIST
             assert cause not in INVESTIGATE_CAUSES
@@ -772,6 +779,46 @@ class TestEscalationAlertDispatcher:
         assert "redesign" in reason
 
 
+class TestTerminalParkAlert:
+    """#3979: a row the sweep classifies as a terminal park (needs-
+    decomposition/premise-refusal/upstream-gap) must alert with the real
+    action named, never the generic ``coord status`` fallback — and must
+    never auto-dispatch or escalate to the investigate tier."""
+
+    @pytest.mark.parametrize(
+        ("cause", "expected_fragment"),
+        [
+            (queue_diagnose.CAUSE_NEEDS_DECOMPOSITION, "decompose"),
+            (queue_diagnose.CAUSE_PREMISE_REFUSAL, "re-scope"),
+            (queue_diagnose.CAUSE_UPSTREAM_GAP_PARK, "release"),
+        ],
+    )
+    def test_alert_names_the_real_action_not_coord_status(
+        self, cause: str, expected_fragment: str,
+    ) -> None:
+        row = _row(f"acme/widgets#{hash(cause) % 1000}", cause)
+
+        assert escalation_alert_dispatcher(row) is True
+
+        repo, issue = board_doctor_policy._parse_row_key(row.key)
+        escalation = state.get_drive_escalation(repo, issue)
+        assert escalation is not None
+        assert escalation["proposed_command"] != "coord status"
+        assert escalation["proposed_command"].startswith("coord log ")
+        assert expected_fragment in escalation["reason"]
+        assert "parked terminal" in escalation["reason"]
+
+    def test_sweep_takes_no_dispatch_action_for_a_needs_decomposition_row(
+        self,
+    ) -> None:
+        # Not in ALLOWLIST/INVESTIGATE_CAUSES -> policy_tier_of reads
+        # TIER_ALERT, so `coord.board_doctor.sweep` routes it through the
+        # alert dispatcher, never a fix-it leg or a mechanical requeue.
+        assert queue_diagnose.CAUSE_NEEDS_DECOMPOSITION not in ALLOWLIST
+        assert queue_diagnose.CAUSE_NEEDS_DECOMPOSITION not in INVESTIGATE_CAUSES
+        assert policy_tier_of(queue_diagnose.CAUSE_NEEDS_DECOMPOSITION) == TIER_ALERT
+
+
 class TestClassifyEnvProbeOutput:
     """The text classifier behind the baseline-red env diagnosis."""