code-coordinator 0.5.329__tar.gz → 0.5.330__tar.gz

{code_coordinator-0.5.329 → code_coordinator-0.5.330}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.329",
+  "tag": "0.5.330",
   "distance": 0,
-  "node": "g620161040c983239a8258b25aa0e4e1fc5cf3c8a",
+  "node": "g1b5009cd9bd233460972d0e1bfca11135eb4058b",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-31"

{code_coordinator-0.5.329 → code_coordinator-0.5.330}/coord/commands/drive_queue.py

@@ -80,9 +80,12 @@ from coord.drive_queue import (
     find_cycle,
     fired_holds,
     is_dispatch_failure_reason,
+    is_merge_gate_block_reason,
     is_permanent_block_reason,
     is_pre_dispatch_block_reason,
     is_unsatisfiable_prereq_reason,
+    merge_gate_remedy_command,
+    merge_plan_inspect_command,
     parse_after_spec,
     parse_key,
     pending_probe_targets,
@@ -4526,6 +4529,30 @@ def _requeue_command(entry: QueueEntry | None, key: str) -> str:
     )
 
 
+def _blocked_escalation_command(entry: QueueEntry | None, key: str, reason: str) -> str:
+    """The command a `blocked`/`oscillating` escalation should propose
+    (#3016) — `_requeue_command` ONLY for a genuinely never-dispatched entry;
+    a gate-specific remedy (or the safe read-only inspect fallback) whenever
+    *reason* already names a merge-gate block.
+
+    `_requeue_command` is right exactly once: nothing was ever dispatched
+    for this row (or every dispatch attempt died before an assignment
+    existed), so there is nothing left to lose by dropping and re-adding it.
+    But `is_merge_gate_block_reason` names the other shape — Work/Test/
+    Review already completed and it is the MERGE stage that is stuck — where
+    the same requeue would discard that completed cycle instead of fixing
+    the one gate actually blocking it. `merge_gate_remedy_command` is the
+    one place that maps a merge-gate reason to its safe one-line fix (or, if
+    none is known blind, the inspect command); this only decides WHICH of
+    the two families applies.
+    """
+    if is_merge_gate_block_reason(reason):
+        parsed = parse_key(key)
+        if parsed is not None:
+            return merge_gate_remedy_command(reason, parsed[0], parsed[1])
+    return _requeue_command(entry, key)
+
+
 @drive_queue_group.command("tick")
 @click.option(
     "--max-parallel",
@@ -5071,7 +5098,7 @@ def drive_queue_tick(
                     f"{entry.position if entry else '?'} | after="
                     f"{','.join(entry.after) if entry and entry.after else '(none)'}"
                 ),
-                command=_requeue_command(entry, item.key),
+                command=_blocked_escalation_command(entry, item.key, item.reason),
             )
 
         # #2230: an entry #2230's sweep would have resumed, but has already
@@ -5098,7 +5125,7 @@ def drive_queue_tick(
                     f"/{MAX_BLOCKED_RESUMES} | position="
                     f"{entry.position if entry else '?'}"
                 ),
-                command=_requeue_command(entry, item.key),
+                command=_blocked_escalation_command(entry, item.key, item.reason),
             )
 
         # #2806: a `blocked` entry #2230's sweep targeted this tick, but whose
@@ -5117,6 +5144,14 @@ def drive_queue_tick(
             if parsed is None:
                 continue
             entry = by_key.get(item.key)
+            # #3016: NEVER the `remove && add` requeue here — `item.reason`
+            # already says "the next tick re-probes rather than guessing"
+            # (#2806); a destructive requeue directly contradicts that, and
+            # would additionally discard a completed Work/Test/Review cycle
+            # for no reason connected to what actually failed (a probe, not
+            # a gate). The read-only inspect command is the only thing safe
+            # to propose when the tick itself does not yet know what shape
+            # this block is.
             _escalate(
                 parsed[0],
                 parsed[1],
@@ -5125,7 +5160,7 @@ def drive_queue_tick(
                     f"queue_state=blocked | gate_reading=unreadable | "
                     f"position={entry.position if entry else '?'}"
                 ),
-                command=_requeue_command(entry, item.key),
+                command=merge_plan_inspect_command(parsed[0]),
             )
 
         if plan.alert is not None:

{code_coordinator-0.5.329 → code_coordinator-0.5.330}/coord/drive_queue.py

@@ -94,6 +94,7 @@ from coord.gate_a import is_gate_a_refusal_reason
 from coord.github_ops import is_throttle_skip_reason, parse_throttle_skip_until
 from coord.issues_sync_status import STALENESS_WARN_SECONDS as ISSUE_CACHE_STALE_CEILING_S
 from coord.merge_queue import (
+    CI_STALE_PREFIX,
     PLAN_READY,
     ci_rollup_all_clear,
     is_ci_flaky_reason,
@@ -2746,6 +2747,74 @@ def _is_merge_gate_block_reason(reason: str | None) -> bool:
     return "merge_status=" in lowered
 
 
+def merge_plan_inspect_command(repo: str) -> str:
+    """The read-only ``coord merge --plan`` fallback (#3016) — safe to
+    propose whenever no specific, blind-runnable remedy is known, because it
+    never mutates anything. Used both as :func:`merge_gate_remedy_command`'s
+    own fallback and directly by callers escalating a #2806 ``gate_unreadable``
+    outcome, whose reason text already says "the next tick re-probes" — the
+    destructive `remove && add` requeue would directly contradict that.
+    """
+    return f"coord merge --plan --repo {repo}"
+
+
+def merge_gate_remedy_command(reason: str | None, repo: str, issue: int) -> str:
+    """The gate-specific one-line fix for a `_is_merge_gate_block_reason`
+    block (#3016) — never the blanket ``drive-queue remove && add`` requeue
+    a synthetic escalation writer would otherwise reach for by default.
+
+    A requeue is not merely useless for a merge-gate block, it is actively
+    destructive: it discards a completed Work/Test/Review cycle to re-run it
+    from scratch, when the real fix is a single, targeted merge-lane command
+    — exactly the misdirection `_is_merge_gate_block_reason`'s own docstring
+    already names two live escalations (claude-coordinator#2405, coord-web#2)
+    as having produced, and #2424 only fixed on the prose (``reason``) side,
+    leaving this — the field a one-click "Run proposed fix" menu actually
+    executes — untouched.
+
+    Only the CI-stale / stale-but-passed-smoke shape has a remedy that is
+    both KNOWN and SAFE to run blind: ``coord merge --revalidate --only
+    <repo>#<issue>``, the exact command :func:`coord.merge_queue.
+    ci_stale_reason`'s own prose already tells the operator to run (matched
+    textually here — via :data:`coord.merge_queue.CI_STALE_PREFIX` and
+    :func:`is_stale_smoke_reason` — rather than re-derived, so the two can
+    never diverge on what "CI stale" means).
+
+    Every other shape this matches — red CI (``checks failed``), a
+    review/smoke gate divergence (``review_required —``/``smoke_required
+    —``), an opaque terminal ``merge_status=`` — has no single command that
+    is always both correct and safe to run without a human first reading
+    the actual gate state (fixing a named CI check, recovering or re-running
+    a review, deciding a UAT verdict). Guessing wrong there is worse than
+    not guessing: the menu this feeds runs the command on one click. So
+    every one of those falls back to the read-only inspect command instead
+    — see #3016's design note ("a wrong 'Recommended' is worse than no
+    recommendation").
+
+    Callers are expected to gate on :func:`_is_merge_gate_block_reason`
+    first; called on a reason that ISN'T a merge-gate block at all, this
+    still returns the safe inspect fallback rather than raising — there is
+    no reason this text-matching helper needs to enforce that precondition
+    itself when a wrong answer here is never destructive.
+    """
+    if reason and (
+        CI_STALE_PREFIX.lower() in reason.lower() or is_stale_smoke_reason(reason)
+    ):
+        return f"coord merge --revalidate --only {entry_key(repo, issue)}"
+    return merge_plan_inspect_command(repo)
+
+
+def is_merge_gate_block_reason(reason: str | None) -> bool:
+    """Public alias for :func:`_is_merge_gate_block_reason` (#3016).
+
+    Same convention as ``is_empty_branch_death_reason``/
+    ``is_unsatisfiable_prereq_reason``: the classifier is shared with the
+    synthetic escalation writers in ``coord.commands.drive_queue``, so it
+    gets a non-underscored name rather than a second copy of the text match.
+    """
+    return _is_merge_gate_block_reason(reason)
+
+
 def _is_empty_branch_death_reason(reason: str | None) -> bool:
     """#2363: does *reason* name the "claimed success, wrote nothing"
     signature — an acceptance-author or plain work session that exited

{code_coordinator-0.5.329 → code_coordinator-0.5.330}/tests/test_cli_drive_queue.py

@@ -1987,6 +1987,78 @@ def test_a_dead_drives_own_exit_reason_reaches_the_queue_row(
     assert state._get_drive_escalation_local(REPO, 1762) is not None
 
 
+def test_exhausted_ci_stale_escalation_proposes_revalidate_not_a_requeue(
+    cli, seed, launches, coord_db, config_file
+):
+    """#3016 regression fixture — the exact claude-coordinator#2983 shape
+    (2026-08-31), rendered end-to-end through the real `coord drive-queue
+    tick` -> escalation write -> `coord escalate list` path: a merge-gate
+    death whose OWN reason already names `coord merge --revalidate` as the
+    fix must not have the escalation's `proposed_command` — the ONE field a
+    one-click "Run proposed fix" menu actually runs — propose the blanket
+    `drive-queue remove && add` requeue instead. #2424 already fixed the
+    parallel misdirection in the `reason` prose; this pins the field that
+    executes.
+    """
+    from coord.audit import record_audit
+
+    seed(issues={2983: "open"})
+    cli("add", REPO, "2983")
+    cli("tick")
+
+    def _own_reason(n: int) -> str:
+        return (
+            f"drive exited for {REPO}#2983 (exit_code=1): merge attempted "
+            f"3 times without landing.\n"
+            "   Last board state: status='PENDING' reason='CI stale: checks "
+            "predate the current base (...); auto-rerun budget exhausted "
+            "(2/2) — re-run CI (`coord merge --revalidate`) before merging'"
+            f" (attempt {n})"
+        )
+
+    launched_at = queued(2983)["launched_at"]
+    _backdate(2983, DRIVE_STARTUP_GRACE_SECONDS + 60)
+    record_audit(
+        tier="business", category="drive", event_type="drive_exited",
+        actor="drive", summary=_own_reason(1), repo=REPO, issue=2983,
+        ts=launched_at + 5,
+    )
+    cli("tick")
+
+    _backdate_reason(coord_db, 2983, DRIVE_STARTUP_GRACE_SECONDS + 60)
+    relaunch = cli("tick")
+    assert relaunch.exit_code == 0, relaunch.output
+    assert queued(2983)["state"] == "running"
+
+    launched_at = queued(2983)["launched_at"]
+    _backdate(2983, DRIVE_STARTUP_GRACE_SECONDS + 60)
+    record_audit(
+        tier="business", category="drive", event_type="drive_exited",
+        actor="drive", summary=_own_reason(2), repo=REPO, issue=2983,
+        ts=launched_at + 5,
+    )
+    second_retry = cli("tick")
+    assert second_retry.exit_code == 0, second_retry.output
+
+    entry = queued(2983)
+    assert entry["state"] == "blocked"
+
+    listing = CliRunner().invoke(
+        main, ["escalate", "list", "--config", str(config_file)]
+    )
+    assert listing.exit_code == 0, listing.output
+    assert f"{REPO} #2983" in listing.output
+    assert "coord merge --revalidate" in listing.output
+    assert f"--only {REPO}#2983" in listing.output
+    assert "drive-queue remove" not in listing.output
+    assert "drive-queue add" not in listing.output
+
+    escalation = state._get_drive_escalation_local(REPO, 2983)
+    assert escalation is not None
+    proposed = escalation["proposed_command"]
+    assert proposed == f"coord merge --revalidate --only {REPO}#2983"
+
+
 def test_a_permanent_dispatch_refusal_blocks_on_the_first_tick_no_attempt_spent(
     cli, seed, launches,
 ):

{code_coordinator-0.5.329 → code_coordinator-0.5.330}/tests/test_drive_queue.py

@@ -46,6 +46,9 @@ from coord.drive_queue import (
     entry_key,
     find_cycle,
     is_empty_branch_death_reason,
+    is_merge_gate_block_reason,
+    merge_gate_remedy_command,
+    merge_plan_inspect_command,
     parse_after_spec,
     parse_key,
     plan_tick,
@@ -5468,3 +5471,82 @@ def test_detect_unreachable_waits_reproduces_the_ms5_incident_shape():
         assert dep.key not in alert.reason
     assert "8 dependent entries" in alert.reason
     assert "self-heal" in alert.reason
+
+
+# ── #3016: the escalation-time remedy for a merge-gate block must be the ──
+# gate-specific fix, never the blanket `drive-queue remove && add` requeue —
+# a requeue discards a completed Work/Test/Review cycle instead of fixing
+# the one gate actually stuck. `merge_gate_remedy_command` is the mapping;
+# `is_merge_gate_block_reason` (already exercised elsewhere via #2424) is
+# what a caller gates on before reaching for it.
+
+
+def test_merge_gate_remedy_command_is_the_2983_regression_fixture():
+    """The exact claude-coordinator#2983 shape (2026-08-31): a `merge
+    attempted N times without landing` death whose OWN reason already names
+    `coord merge --revalidate` as the fix must map to a scoped revalidate
+    command, never a requeue."""
+    reason = (
+        "drive exited (exit_code=1): merge attempted 3 times without "
+        "landing.\n   Last board state: status='PENDING' reason='CI stale: "
+        "checks predate the current base (...); auto-rerun budget exhausted "
+        "(2/2) — re-run CI (`coord merge --revalidate`) before merging'"
+    )
+    assert is_merge_gate_block_reason(reason) is True
+    command = merge_gate_remedy_command(reason, REPO, 2983)
+    assert command == f"coord merge --revalidate --only {REPO}#2983"
+    assert "drive-queue remove" not in command
+    assert "drive-queue add" not in command
+
+
+def test_merge_gate_remedy_command_handles_a_stale_smoke_verdict():
+    """The #1479 staleness race — `is_stale_smoke_reason` matches even
+    without the `CI stale:` prefix at all — same remedy, same reasoning."""
+    reason = "smoke test verdict is stale: recorded against base abc123, base is now def456"
+    assert is_merge_gate_block_reason(reason) is True
+    command = merge_gate_remedy_command(reason, REPO, 1650)
+    assert command == f"coord merge --revalidate --only {REPO}#1650"
+
+
+def test_merge_gate_remedy_command_falls_back_to_inspect_for_red_ci():
+    """`checks failed` (red CI) has no safe one-line auto-fix — the correct
+    remedy is "fix the named check", which is not a command this can hand
+    an operator to run blind. Falls back to the read-only inspect command
+    rather than a requeue or a guess."""
+    reason = "checks failed: build (exit 1)"
+    assert is_merge_gate_block_reason(reason) is True
+    command = merge_gate_remedy_command(reason, REPO, 1650)
+    assert command == merge_plan_inspect_command(REPO)
+    assert "revalidate" not in command
+    assert "drive-queue remove" not in command
+
+
+def test_merge_gate_remedy_command_falls_back_to_inspect_for_review_required():
+    reason = (
+        "review_required — coord merge's own gate reports 'review missing', "
+        "but this driver's OWN view already shows review_verdict='approved'"
+    )
+    assert is_merge_gate_block_reason(reason) is True
+    assert merge_gate_remedy_command(reason, REPO, 1650) == merge_plan_inspect_command(REPO)
+
+
+def test_merge_gate_remedy_command_falls_back_to_inspect_for_smoke_required():
+    reason = "smoke_required — coord merge's own gate reports 'no verdict'"
+    assert is_merge_gate_block_reason(reason) is True
+    assert merge_gate_remedy_command(reason, REPO, 1650) == merge_plan_inspect_command(REPO)
+
+
+def test_merge_gate_remedy_command_falls_back_to_inspect_for_opaque_merge_status():
+    reason = "merge_status=NEEDS_ATTENTION — no number of retries changes this"
+    assert is_merge_gate_block_reason(reason) is True
+    assert merge_gate_remedy_command(reason, REPO, 1650) == merge_plan_inspect_command(REPO)
+
+
+def test_merge_gate_remedy_command_is_the_safe_inspect_fallback_for_none_and_non_block_reasons():
+    """Never raises — called on a reason that isn't a merge-gate block at
+    all (or is missing entirely), it still returns the safe, read-only
+    fallback rather than asserting a precondition on its caller."""
+    assert merge_gate_remedy_command(None, REPO, 1650) == merge_plan_inspect_command(REPO)
+    ordinary = "no candidate machine available for claude-coordinator#1650"
+    assert is_merge_gate_block_reason(ordinary) is False
+    assert merge_gate_remedy_command(ordinary, REPO, 1650) == merge_plan_inspect_command(REPO)