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

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

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

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

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

{code_coordinator-0.5.756 → code_coordinator-0.5.757}/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.757}/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.757}/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.757}/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."""
 

{code_coordinator-0.5.756 → code_coordinator-0.5.757}/tests/test_queue_diagnose.py

@@ -416,3 +416,78 @@ def test_no_work_assignment_at_all_cannot_tell_not_confirmed_fresh(monkeypatch):
 
     assert review_stale is None
     assert test_stale is None
+
+
+# ── #3979: a terminal park must never read as a PR-shaped cause ─────────────
+
+
+def test_a_needs_decomposition_park_classifies_as_its_own_cause_not_no_pr():
+    """A row the tick's own parked pre-pass already treats as terminal
+    (`coord.models.NEEDS_DECOMPOSITION_MARKER` in `last_reason`) has, by
+    design, no PR — `_rule_no_pr` would otherwise claim it, and
+    `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."""
+    from coord.models import NEEDS_DECOMPOSITION_MARKER
+
+    got = qd.diagnose(
+        entry(
+            10,
+            last_reason=f"{NEEDS_DECOMPOSITION_MARKER} split into A and B",
+        ),
+        live(pr_number=None, pr_state="none", mergeable=None, checks=None),
+    )
+    assert got.cause == qd.CAUSE_NEEDS_DECOMPOSITION
+    assert got.cause != qd.CAUSE_NO_PR
+    assert got.confidence == qd.CONFIDENCE_HIGH
+
+
+def test_a_premise_refusal_park_classifies_as_its_own_cause_not_no_pr():
+    from coord.models import PREMISE_REFUSAL_MARKER
+
+    got = qd.diagnose(
+        entry(11, last_reason=f"{PREMISE_REFUSAL_MARKER} missing prereq"),
+        live(pr_number=None, pr_state="none", mergeable=None, checks=None),
+    )
+    assert got.cause == qd.CAUSE_PREMISE_REFUSAL
+    assert got.cause != qd.CAUSE_NO_PR
+
+
+def test_an_upstream_gap_park_classifies_as_its_own_cause_not_no_pr():
+    from coord.models import UPSTREAM_GAP_PARK_MARKER
+
+    got = qd.diagnose(
+        entry(12, last_reason=f"{UPSTREAM_GAP_PARK_MARKER} unreleased symbol"),
+        live(pr_number=None, pr_state="none", mergeable=None, checks=None),
+    )
+    assert got.cause == qd.CAUSE_UPSTREAM_GAP_PARK
+    assert got.cause != qd.CAUSE_NO_PR
+
+
+def test_a_genuine_no_pr_stall_with_no_marker_still_classifies_no_pr():
+    """Regression: a row with no terminal-park marker at all must still
+    reach the ordinary `CAUSE_NO_PR` reading — the new rule must never
+    fire on prose that merely happens to be stalled with no PR."""
+    got = qd.diagnose(
+        entry(13, last_reason="blocked: CI red, 2/2 attempts"),
+        live(pr_number=None, pr_state="none", mergeable=None, checks=None),
+    )
+    assert got.cause == qd.CAUSE_NO_PR
+
+
+def test_needs_decomposition_is_not_auto_or_investigate_eligible():
+    """#3979's whole point: the new cause must never land on the
+    auto-dispatch or investigate tier — `coord.board_doctor_policy.
+    policy_tier_of` must read it as alert-only, the same place an
+    unregistered cause already lands."""
+    from coord import board_doctor_policy as bdp
+    from coord.board_doctor import TIER_ALERT
+
+    for cause in (
+        qd.CAUSE_NEEDS_DECOMPOSITION,
+        qd.CAUSE_PREMISE_REFUSAL,
+        qd.CAUSE_UPSTREAM_GAP_PARK,
+    ):
+        assert cause not in bdp.ALLOWLIST
+        assert cause not in bdp.INVESTIGATE_CAUSES
+        assert bdp.policy_tier_of(cause) == TIER_ALERT