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

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

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

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

{code_coordinator-0.5.755 → 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.755 → code_coordinator-0.5.757}/coord/dispatch.py

@@ -592,6 +592,12 @@ that hosts it.
 # half (parse, file through the issue-tracker seam, link, block the queue row
 # `after=` it). The example deliberately uses `<placeholders>`: the parser
 # rejects them, so a log that echoes this briefing never files a fake gap.
+# #3977: the body MUST name a real inline-code symbol (not `<placeholder>`,
+# not a backtick-quoted sentence or shell command — `_named_symbols` only
+# recognises a single identifier path) — a marker with none can't be checked
+# against the upstream repo before filing (`_verify_gap`), so it goes out
+# unverified and unqueued, costing a human a confirmation round-trip that
+# naming the symbol up front would have skipped.
 UPSTREAM_GAP_BRIEFING_NOTE = """
 
 ## Cross-repo gaps — `BLOCKED_ON_UPSTREAM` (#3676)
@@ -608,11 +614,17 @@ the lines directly below it (a blank line ends the body):
 where this repo would call it>
 
 `<repo>` is the upstream repo's coordinator name or its `owner/name` GitHub \
-slug. The coordinator files the upstream issue for you, links it to this \
-one, and holds this issue's drive-queue row until it lands — you never need \
-the issue number. Still commit and push whatever is genuinely done; if the \
-gap leaves this issue unresolved, also declare `ISSUE_RESOLUTION: partial — \
-blocked on upstream (BLOCKED_ON_UPSTREAM above)`.
+slug. The body MUST name at least one inline-code symbol for the missing \
+API — a bare symbol (`` `Foo::bar` ``) is clearest, and a path-prefixed or \
+call-decorated span (`` `a/b.rs::Foo::bar(Baz)` ``) is also recognised — \
+the coordinator greps the upstream repo's own default branch for it before \
+filing, so a marker with no checkable symbol is filed unverified and held \
+unqueued until a human confirms it (#3977). The coordinator files the upstream \
+issue for you, links it to this one, and holds this issue's drive-queue \
+row until it lands — you never need the issue number. Still commit and \
+push whatever is genuinely done; if the gap leaves this issue unresolved, \
+also declare `ISSUE_RESOLUTION: partial — blocked on upstream \
+(BLOCKED_ON_UPSTREAM above)`.
 """
 
 # #3711: appended to every `type="work"` briefing, alongside

{code_coordinator-0.5.755 → code_coordinator-0.5.757}/coord/drive_queue.py

@@ -123,6 +123,7 @@ from coord.models import (
     is_needs_decomposition_reason,
     is_policy_refusal_reason,
     is_premise_refusal_reason,
+    is_upstream_gap_park_reason,
     parse_issue_resolution,
 )
 from coord.worker_events import classify_zero_commit_outcome
@@ -8760,6 +8761,21 @@ def plan_tick(
         # (`coord drive-queue remove`).
         if is_needs_decomposition_reason(entry.last_reason):
             continue
+        # #3977: an upstream-gap park (`coord.upstream_gaps._park_queue_row`)
+        # has the SAME "no external verdict to poll for" shape as the three
+        # checks just above — a release landing or a coordinator confirming
+        # a dedup/unverified gap leaves no trace this tick can read, so this
+        # never resumes itself either. Without this check the row would read
+        # exactly like a cleared CI gate (`facts.merge_ci_pending` is False —
+        # this row was never in the merge queue) and fall straight into the
+        # #1891 default below, flipping back to `waiting`, resetting
+        # `attempts`, and relaunching a worker straight into re-emitting the
+        # identical marker — the park/relaunch bounce #2234's comment above
+        # exists to prevent, replayed here for a park written outside this
+        # module. Stays parked until a human clears it by hand (`coord
+        # drive-queue remove`).
+        if is_upstream_gap_park_reason(entry.last_reason):
+            continue
         # #2977: a throttle-skip park (`github_ops.is_throttle_skip_reason`)
         # carries its OWN known wall-clock expiry (`until=<epoch>`, embedded
         # by `github_ops.format_throttle_skip_reason` at park time) — unlike

{code_coordinator-0.5.755 → code_coordinator-0.5.757}/coord/github_ops.py

@@ -3661,13 +3661,43 @@ def create_issue(
     labels: list[str] | None = None,
     milestone: str | None = None,
 ) -> dict:
+    """Create an issue via ``gh issue create``. Returns ``{"number", "url"}``.
+
+    ``gh`` hard-fails the create when a requested label does not exist in
+    *repo*, so a label-not-found failure auto-creates every requested label
+    and retries the create once — the same recovery
+    :func:`change_issue_labels` performs on its add path, and what lets a
+    caller pass a policy label (e.g.
+    `coord.board_doctor.STRANDED_PREREQ_OPT_OUT_LABEL`) without every
+    target repo having been provisioned with it first. Only label-not-found
+    errors trigger it: :func:`_is_label_not_found` screens out auth,
+    network and rate-limit failures, which propagate untouched so a create
+    is never retried against a forge that may have accepted the first one.
+    A retry that still reports label-not-found raises :class:`GhNotFound`.
+    """
     args = ["issue", "create", "--repo", repo, "--title", title, "--body", body]
     if labels:
         for label in labels:
             args.extend(["--label", label])
     if milestone:
         args.extend(["--milestone", milestone])
-    raw = _gh(*args, caller="github_ops.create_issue")
+    try:
+        raw = _gh(*args, caller="github_ops.create_issue")
+    except RuntimeError as exc:
+        if not (labels and _is_label_not_found(exc)):
+            raise
+        for label in labels:
+            try:
+                _gh("label", "create", label, "--repo", repo,
+                    caller="github_ops.create_issue")
+            except RuntimeError:
+                pass  # idempotent: label may already exist (concurrent create)
+        try:
+            raw = _gh(*args, caller="github_ops.create_issue")
+        except RuntimeError as retry_exc:
+            if _is_label_not_found(retry_exc):
+                raise GhNotFound(str(retry_exc)) from retry_exc
+            raise
     url = raw.strip()
     number = int(url.rstrip("/").rsplit("/", 1)[-1])
     return {"number": number, "url": url}

{code_coordinator-0.5.755 → code_coordinator-0.5.757}/coord/models.py

@@ -1142,6 +1142,39 @@ def is_needs_decomposition_reason(text: str | None) -> bool:
     return bool(text) and NEEDS_DECOMPOSITION_MARKER in text
 
 
+# #3977: the machine-readable tag `coord.upstream_gaps._park_queue_row`
+# embeds in a downstream drive-queue row's `last_reason` when it parks the
+# row directly — no upstream issue, no `after=` edge: a symbol confirmed on
+# the upstream default branch (unreleased, not missing) or a dedup match
+# that closed within the recent-close window. Same SIBLING shape as
+# `POLICY_REFUSAL_MARKER`/`PREMISE_REFUSAL_MARKER`/`NEEDS_DECOMPOSITION_
+# MARKER` above: nothing on the board signals a release landing or a
+# coordinator's confirmation, so there is no external verdict to poll for.
+#
+# Text-marker matching (not a dedicated exit code), same rationale as the
+# three markers above: `coord/drive_queue.py`'s parked pre-pass recognises
+# this straight out of the row's own `last_reason` and leaves the row
+# parked rather than falling through to the CI-park "resume" default, which
+# would otherwise flip it back to `waiting` on the very next tick and
+# relaunch a worker straight into re-emitting the identical marker.
+UPSTREAM_GAP_PARK_MARKER = "[parked-on-upstream-gap #3977]"
+
+
+def is_upstream_gap_park_reason(text: str | None) -> bool:
+    """Whether *text* is a #3977 upstream-gap park reason.
+
+    Like a policy/premise refusal or a needs-decomposition park, this has
+    no external verdict that can arrive and clear it on its own — a
+    release landing, or a coordinator confirming a dedup/unverified gap,
+    leaves no trace on the board that this module (or anything else) polls
+    for — so nothing auto-resumes an entry parked for this reason. An
+    operator clears it by hand once the release lands / the pin is bumped,
+    or once the gap is confirmed, the same way they clear a `blocked` entry
+    (`coord drive-queue remove` + `add` for a fresh row).
+    """
+    return bool(text) and UPSTREAM_GAP_PARK_MARKER in text
+
+
 # #2850: the machine-readable tag `coord.drive.decide` embeds in its
 # `_succeed()` message when the "terminal: merged" branch's own LIVE check
 # (`MergeVerifier.verify_merged`) confirms the issue has genuinely landed —

{code_coordinator-0.5.755 → 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,