code-coordinator 0.5.648__tar.gz → 0.5.650__tar.gz

{code_coordinator-0.5.648 → code_coordinator-0.5.650}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.648",
+  "tag": "0.5.650",
   "distance": 0,
-  "node": "g24bda09de37c4892fe2faaad63b17e81bfcba919",
+  "node": "gf6c0cf969776e35085b65dc340c118b19733079d",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-18"

{code_coordinator-0.5.648 → code_coordinator-0.5.650}/coord/commands/drive_queue.py

@@ -31,6 +31,7 @@ from __future__ import annotations
 
 import json as _json
 import logging
+import re
 import socket
 import subprocess
 import time
@@ -95,7 +96,9 @@ from coord.drive_queue import (
     is_fix_round_ceiling_blocked,
     is_merge_gate_block_reason,
     is_permanent_block_reason,
+    is_policy_refusal_reason,
     is_pre_dispatch_block_reason,
+    is_premise_refusal_reason,
     is_test_stage_routing_dead_end_reason,
     is_unsatisfiable_prereq_reason,
     merge_gate_remedy_command,
@@ -2304,6 +2307,36 @@ def drive_queue_remove(repo: str, issue: int, config_path: Path) -> None:
     )
 
 
+#: Shapes an un-filled-in ``--reason`` template takes: an angle-bracketed
+#: prompt (``<describe why the premise now holds>``) or a bare ellipsis
+#: (``"..."``) — the two forms this repo's own remediation strings use.
+_TEMPLATED_REASON_RE = re.compile(r"<[^<>]*>|^[.…\s]+$")
+
+
+def _is_templated_reason(reason: str) -> bool:
+    """True when *reason* is still a copy-pasted placeholder, not an assertion.
+
+    #3339's premise recheck is "a human's explicit, auditable assertion …
+    its mere presence — never inferred, never re-derived" (`coord/drive.py`'s
+    `decide()`), so the one thing `--reason` must never accept is the template
+    text out of a remediation string. Several surfaces print that chain with a
+    placeholder in it — `coord diagnose`'s `refused_premise` finding, the
+    premise park reason, and the `proposed_command` on the #3719 refusal-park
+    escalation, which `coord escalate run` executes blind with no confirmation
+    prompt. Rejecting the placeholder is what makes such a blind run exit
+    non-zero (so nothing is requeued and the escalation is not dismissed)
+    instead of recording a fabricated assertion and dispatching paid work at
+    a premise nobody rechecked.
+
+    The angle-bracket arm over-matches: a genuine reason that quotes a
+    bracketed URL (`PR <https://…> landed`) is rejected too. That is the
+    deliberate direction to err in — the rejection names the offending
+    string and shows a usable example, so the cost is one retyped sentence,
+    whereas the other direction records an assertion nobody made.
+    """
+    return bool(_TEMPLATED_REASON_RE.search(reason))
+
+
 @drive_queue_group.command("clear-refusal")
 @click.argument("repo")
 @click.argument("issue", type=int)
@@ -2336,6 +2369,13 @@ def drive_queue_clear_refusal(
     row that will actually tick. Re-scope the issue FIRST if the remaining
     work has changed — this command only unblocks dispatch, it does not
     touch the issue body.
+
+    `--reason` must be your own words. A still-templated placeholder — the
+    `<...>`/`"..."` text the remediation chains printed by `coord diagnose`,
+    the premise park reason and the #3719 refusal-park escalation all carry
+    — is rejected, so running one of those chains verbatim (including blind,
+    via `coord escalate run`) fails here rather than fabricating the
+    assertion and redispatching paid work at an unverified premise.
     """
     from coord.drive_state import WORK_LIKE  # noqa: PLC0415
     from coord.state import mark_premise_rechecked  # noqa: PLC0415
@@ -2343,6 +2383,16 @@ def drive_queue_clear_refusal(
     reason = reason.strip()
     if not reason:
         raise click.ClickException("--reason must not be empty")
+    if _is_templated_reason(reason):
+        raise click.ClickException(
+            f"--reason is still the placeholder text ({reason!r}) — it must be "
+            "your own assertion of why the premise now holds (e.g. "
+            '--reason "quadraui#971 landed, re-scoped to a pin move"). This '
+            "is recorded as a human's explicit, auditable claim that the "
+            "prerequisite exists now, and `coord drive` dispatches fresh "
+            "paid work off its mere presence, so it is never inferred and "
+            "never filled in from a template."
+        )
 
     aid, status, _machine = _latest_work_assignment(repo, issue)
     if not aid:
@@ -6759,7 +6809,15 @@ def _apply_writes(plan: TickPlan) -> None:
         update_drive_queue_entry(parsed[0], parsed[1], **updates)
 
 
-def _escalate(repo: str, issue: int, *, reason: str, gates: str, command: str) -> None:
+def _escalate(
+    repo: str,
+    issue: int,
+    *,
+    reason: str,
+    gates: str,
+    command: str,
+    assignment_id: str | None = None,
+) -> None:
     from coord.state import record_drive_escalation  # noqa: PLC0415
 
     record_drive_escalation(
@@ -6769,6 +6827,7 @@ def _escalate(repo: str, issue: int, *, reason: str, gates: str, command: str) -
         reason=reason,
         gate_readings=gates,
         proposed_command=command,
+        assignment_id=assignment_id,
     )
 
 
@@ -6801,6 +6860,77 @@ def _requeue_command(entry: QueueEntry | None, key: str) -> str:
     )
 
 
+def _refusal_park_escalation_command(
+    entry: QueueEntry | None,
+    key: str,
+    reason: str,
+    kind: str,
+    *,
+    config_path: Path | None = None,
+) -> str:
+    """The command a #3719 policy-/premise-refusal `parked` escalation
+    proposes.
+
+    Both causes need a human DECISION first — retarget the issue (policy,
+    #2234) or confirm the premise now holds (premise, #3164) — and neither
+    decision is itself expressible as a blind CLI command: retargeting means
+    rewriting the GitHub issue title by hand, and `clear-refusal` takes a
+    free-text `--reason` only a human can write. `reason` (passed through
+    verbatim as this escalation's own `reason=`) already states which
+    decision is needed and why, so this only has to supply the mechanical
+    half that runs once that decision is made.
+
+    A parked `refused_premise`/`refused_policy` row IS a completed
+    Work-stage assignment (that is what those statuses mean), so it gets
+    the mechanical half from `_blocked_escalation_command` — the same
+    function every other parked/blocked escalation uses — instead of a
+    bespoke requeue: #2377's open-PR check (never propose a blind requeue
+    when an out-of-band PR already exists for this entry) and #3539's
+    plain-`add` carve-out (a green PR missing only its recorded gates)
+    both apply here as they do for any other parked entry. One corner is
+    inherited from #3539's own design rather than chosen here: it reasons
+    from `state.work_aid` being unset, which for a refusal park it is not,
+    so on a premise refusal whose issue has acquired a green out-of-band PR
+    the plain `add` restarts the Work stage over that PR rather than
+    running only the missing stages forward.
+
+    For `kind == "premise"`, `coord drive`'s `decide()` reads the latest
+    work assignment's own `work_status` column directly — independent of
+    the drive-queue row or any PR — so ANY redispatch (the blind requeue
+    OR the #3539 plain `add`) dies on the same refusal again unless
+    `clear-refusal` first records that the premise now holds. Prepend
+    that step whenever the delegated command would actually redispatch
+    (still names `drive-queue add`); the inspect/merge-existing remedies
+    propose no redispatch at all, so they need no such prefix. The policy
+    case has no `clear-refusal` equivalent — #2234's refusal is cleared by
+    retargeting the GitHub issue by hand, which a redispatch neither needs
+    nor can bypass.
+
+    The `--reason` this emits is a PLACEHOLDER, and this field is executed
+    blind: `coord escalate run` shells the whole string out with no
+    confirmation prompt, and `coord/reports.py` offers it as the card's
+    "Recommended" option. That is safe only because
+    :func:`_is_templated_reason` makes `clear-refusal` reject the
+    placeholder, so a one-key run fails on the FIRST step — nothing is
+    requeued, no premise assertion is recorded, and `escalate run` reports
+    the failure instead of dismissing the escalation as resolved. Keep the
+    two in step: an edit here that produces a reason `clear-refusal` would
+    accept turns this into a blind command that fabricates the one value
+    #3339 says must never be inferred.
+    """
+    tail = _blocked_escalation_command(entry, key, reason, config_path=config_path)
+    if kind != "premise" or "drive-queue add" not in tail:
+        return tail
+    parsed = parse_key(key)
+    if parsed is None:
+        return tail
+    repo, issue = parsed
+    return (
+        f"coord drive-queue clear-refusal {repo} {issue} "
+        f'--reason "<describe why the premise now holds>" && {tail}'
+    )
+
+
 def _blocked_escalation_command(
     entry: QueueEntry | None,
     key: str,
@@ -7771,6 +7901,74 @@ def drive_queue_tick(
                 command=merge_plan_inspect_command(parsed[0]),
             )
 
+        # #3719: a `parked` entry whose park reason names a policy (#2234)
+        # or premise (#3164) refusal never resumes on its own — see
+        # `plan_tick`'s pre-pass above (`is_policy_refusal_reason`/
+        # `is_premise_refusal_reason` both just `continue`, leaving the
+        # entry parked rather than falling through to the CI-park auto-
+        # resume) — so without this it sits invisible until an operator
+        # happens to notice it in `coord drive-queue list`. Gate-A
+        # (#2063), throttle-skip (#2977), `merge_ci_pending` (#1891), and
+        # the issue-cache-stale (#2858) parks are deliberately NOT swept
+        # here: all four are documented, by the same pre-pass, to clear
+        # themselves with no human decision needed — exactly the
+        # auto-resolvable half #3719 says must NOT be escalated.
+        #
+        # This fires once: `plan.reconciles` only carries a `"parked"`
+        # entry for *this* key on the single tick `_reconcile_running`
+        # first parks it (a running entry hitting the refusal) — every
+        # later tick the entry stays parked, the pre-pass above `continue`s
+        # without emitting a `Reconcile` for it at all, so there is no
+        # repeat entry here to re-escalate on.
+        for item in plan.reconciles:
+            if item.outcome != "parked":
+                continue
+            if not (
+                is_policy_refusal_reason(item.reason)
+                or is_premise_refusal_reason(item.reason)
+            ):
+                continue
+            parsed = parse_key(item.key)
+            if parsed is None:
+                continue
+            entry = by_key.get(item.key)
+            kind = "premise" if is_premise_refusal_reason(item.reason) else "policy"
+            # Best-effort, matching `_record_checks_stale_escalation`'s own
+            # posture: the write above (`_apply_writes(plan)`) already
+            # landed, so a failure recording the escalation itself must not
+            # turn an otherwise-successful tick into a reported CLI failure.
+            # The stdout line is the floor, and here it is load-bearing: the
+            # sweep fires once per park, so a failure anywhere in this block
+            # (including inside `_refusal_park_escalation_command`, which
+            # reaches `gh` for #2377's open-PR check) loses this entry's ONLY
+            # escalation permanently — it must at least leave a trace.
+            try:
+                aid, _status, _machine = _latest_work_assignment(
+                    parsed[0], parsed[1]
+                )
+                _escalate(
+                    parsed[0],
+                    parsed[1],
+                    reason=item.reason,
+                    gates=(
+                        f"queue_state=parked | refusal={kind} | position="
+                        f"{entry.position if entry else '?'}"
+                    ),
+                    command=_refusal_park_escalation_command(
+                        entry,
+                        item.key,
+                        item.reason,
+                        kind,
+                        config_path=config_path,
+                    ),
+                    assignment_id=aid or None,
+                )
+            except Exception as exc:  # noqa: BLE001 — the stdout line is the floor
+                click.echo(
+                    f"  (could not record the {kind}-refusal park escalation "
+                    f"for {item.key}: {exc})"
+                )
+
         # #3695 review finding 1: `_apply_writes(plan)` above only ever
         # touches `_DRIVE_QUEUE_UPDATABLE` columns on the DRIVE QUEUE row
         # itself (`update_drive_queue_entry`) — it has no way to reach the

{code_coordinator-0.5.648 → code_coordinator-0.5.650}/coord/drive_queue.py

@@ -1376,6 +1376,16 @@ QUEUE_ALERT_REPO = "(drive-queue)"
 QUEUE_ALERT_ISSUE = 0
 QUEUE_ALERT_STAGE = "drive-queue"
 
+#: #3720: the sentinel ``QueueAlert.command`` value meaning "no one-key
+#: remedy exists — there is nothing for a human to run." The step-4 "nothing
+#: eligible to launch" alert below is the only `QueueAlert` that omits
+#: ``command``, so it is the only one that carries this value; the notifier
+#: (`coord/notifier/collect.py`'s `halted_drives`) matches on it to tell that
+#: routine, self-healing condition apart from a genuine hold/cordon/drift
+#: escalation (each of which names its own real fix) without a DB schema
+#: change — `coord drive-queue status` still reads the record unchanged.
+QUEUE_ALERT_NO_REMEDY_COMMAND = "coord drive-queue list"
+
 #: #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
@@ -2767,12 +2777,15 @@ class QueueAlert:
     ``command`` is the proposed fix written into the escalation record. It is
     carried here rather than derived in the shell so the alert's prose and its
     one-key remedy are decided together — a "HELD" alert whose command says
-    ``coord drive-queue list`` teaches the operator to ignore the field.
+    ``coord drive-queue list`` teaches the operator to ignore the field. Left
+    at its ``QUEUE_ALERT_NO_REMEDY_COMMAND`` default, it also doubles as the
+    signal the notifier uses to tell a routine, self-healing alert (nothing
+    names a real fix) apart from one that does.
     """
 
     reason: str
     details: tuple[str, ...] = ()
-    command: str = "coord drive-queue list"
+    command: str = QUEUE_ALERT_NO_REMEDY_COMMAND
 
 
 @dataclass(frozen=True)
@@ -8463,6 +8476,23 @@ def plan_tick(
     if launch is None and stalled:
         details = [f"{item.key}: {item.reason}" for item in deferrals]
         details += [f"{item.key}: BLOCKED — {item.reason}" for item in blocked]
+        # A tick where every stalled entry is a benign deferral has no
+        # one-key remedy — nothing is wedged, the fleet is just busy, and the
+        # next tick that finds capacity self-heals it — so `command` stays at
+        # `QueueAlert`'s `QUEUE_ALERT_NO_REMEDY_COMMAND` default, which is
+        # also the signal the notifier reads to treat the alert as routine.
+        # The moment even one entry is genuinely `blocked`, though, there IS
+        # a remedy (the same remove+add this module already surfaces for
+        # #2944's guaranteed-false waits), so the alert must carry it
+        # explicitly rather than let it fall through to the "nothing to do
+        # here" sentinel — a gate's failure must still be able to page.
+        command = QUEUE_ALERT_NO_REMEDY_COMMAND
+        if blocked:
+            command = (
+                "coord drive-queue remove <repo> <issue> && "
+                "coord drive-queue add <repo> <issue> — for each BLOCKED "
+                "entry named above"
+            )
         alert = QueueAlert(
             # "considered N" rather than "N waiting": some of those entries are
             # blocked by the time this line is written, and an alert that
@@ -8474,6 +8504,7 @@ def plan_tick(
                 f"{capacity - occupied} free slot(s)"
             ),
             details=tuple(details),
+            command=command,
         )
 
     return TickPlan(

{code_coordinator-0.5.648 → code_coordinator-0.5.650}/coord/notifier/collect.py

@@ -271,7 +271,25 @@ def halted_drives(*, notifier_state: NotifierState, now: float) -> list[HaltedDr
     A ``drive_escalations`` row is exactly the condition this feature
     exists for: the drive reached a decision it cannot make, exited, and
     nothing will tick that issue again until a human looks.
+
+    One queue-level row is the exception: `plan_tick`'s step 4 writes a
+    "nothing eligible to launch" record on an ordinary quiet tick whenever
+    every stalled entry is a benign deferral rather than an actual block —
+    self-healing (the next tick that finds something to launch clears it)
+    and carrying no real fix, which is exactly why its ``proposed_command``
+    is left at ``QUEUE_ALERT_NO_REMEDY_COMMAND`` instead of naming one (see
+    that constant). `coord drive-queue status` still shows it on request;
+    this function just stops it from becoming a push. A queue-level alert
+    that DOES carry a real ``proposed_command`` (because step 4 found at
+    least one genuinely blocked entry) is never a sentinel match here, so it
+    pages like any other halted drive.
     """
+    from coord.drive_queue import (  # noqa: PLC0415
+        QUEUE_ALERT_ISSUE,
+        QUEUE_ALERT_NO_REMEDY_COMMAND,
+        QUEUE_ALERT_REPO,
+    )
+
     try:
         from coord.state import list_drive_escalations  # noqa: PLC0415
 
@@ -288,6 +306,13 @@ def halted_drives(*, notifier_state: NotifierState, now: float) -> list[HaltedDr
             issue = int(record.get("issue_number"))
         except (TypeError, ValueError):
             continue
+        command = str(record.get("proposed_command") or "").strip()
+        if (
+            repo == QUEUE_ALERT_REPO
+            and issue == QUEUE_ALERT_ISSUE
+            and command == QUEUE_ALERT_NO_REMEDY_COMMAND
+        ):
+            continue
         stage = str(record.get("stage") or "").strip()
         reason = str(record.get("reason") or "").strip()
         out.append(
@@ -296,6 +321,7 @@ def halted_drives(*, notifier_state: NotifierState, now: float) -> list[HaltedDr
                 issue=issue,
                 reason=f"{stage + ': ' if stage else ''}{reason}".strip(),
                 urgent=urgent_key(repo, issue) in urgent,
+                proposed_command=command or None,
             )
         )
     return out

{code_coordinator-0.5.648 → code_coordinator-0.5.650}/coord/notifier/predicate.py

@@ -124,6 +124,7 @@ class HaltedDrive:
     reason: str = ""
     exit_code: int | None = None
     urgent: bool = False
+    proposed_command: str | None = None
 
 
 @dataclass(frozen=True)
@@ -361,20 +362,25 @@ def _parked_event(gate: ParkedGate, snapshot: PipelineSnapshot) -> NotifyEvent:
 
 def _halted_event(drive: HaltedDrive, snapshot: PipelineSnapshot) -> NotifyEvent:
     where = f"{drive.repo}#{drive.issue}"
+    command = (drive.proposed_command or "").strip() or None
+    body = f"The drive reached a terminal state and will not tick again. {drive.reason.strip()}".strip()
+    if command:
+        body = f"{body} Fix: {command}"
     return NotifyEvent(
         subject=f"drive:{where}",
         condition=CONDITION_DRIVE_HALTED,
         title=f"{where} — {CONDITION_LABELS[CONDITION_DRIVE_HALTED]}",
-        body=(
-            f"The drive reached a terminal state and will not tick again. "
-            f"{drive.reason.strip()}".strip()
-        ),
+        body=body,
         created_at=snapshot.now,
         repo=drive.repo,
         issue=drive.issue,
         urgent=drive.urgent,
         link=deep_link(snapshot.web_base_url, drive.repo, drive.issue),
-        detail={"reason": drive.reason, "exit_code": drive.exit_code},
+        detail={
+            "reason": drive.reason,
+            "exit_code": drive.exit_code,
+            "proposed_command": command,
+        },
     )