code-coordinator 0.5.172__tar.gz → 0.5.173__tar.gz

{code_coordinator-0.5.172 → code_coordinator-0.5.173}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.172",
+  "tag": "0.5.173",
   "distance": 0,
-  "node": "gbab69913bc39627dc11bb77bed4e0e8c37519e6e",
+  "node": "g3e3dcca5954ea1c1094878c1f81ed18e515e641f",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-19"

{code_coordinator-0.5.172 → code_coordinator-0.5.173}/coord/drive.py

@@ -114,6 +114,7 @@ from coord.failure_class import (
     plan_usage_limit_resume,
 )
 from coord.models import DELIVERABLE_ANALYSIS_LABEL, POLICY_REFUSAL_MARKER
+from coord.self_health import self_freshness
 from coord.usage_limits import PlanLimits, evaluate_usage_gate, get_plan_limits
 # Lost in the #1584-onto-#1590 rebase: _decide_review() calls this, but the
 # import lived in a hunk #1590 rewrote, so the merge came out textually clean
@@ -181,6 +182,20 @@ EXIT_DISPATCH_REFUSED = 5
 # vimcode#635 for the two live incidents (140 minutes and ~25 minutes of a
 # held queue slot, respectively, producing nothing).
 EXIT_DEAD_END = 6
+# #2443: a deliberate SELF-HEAL exit, not a failure — the drive loop noticed
+# it was stuck repeating the identical WAIT reason (see `_SELF_HEAL_WAIT_
+# STREAK`) while its OWN on-disk `coord` install had moved since this
+# session started. Python never reloads an already-imported module, so a
+# fix landing mid-run is otherwise invisible to a live session for as long
+# as `--deadline` allows — the claude-coordinator#2286 incident this closes
+# polled one unfetchable path every ~60s for 2+ hours after the fix was
+# already on disk. Distinct from EXIT_DISPATCH_REFUSED/EXIT_DEAD_END on
+# purpose: this condition is NOT permanent — relaunching is exactly the fix
+# — so it must fall through `coord.drive_queue._reconcile_running`'s
+# ordinary `retry` branch rather than either of those two `blocked`
+# branches, which is why nothing in drive_queue.py needs to special-case
+# this code at all.
+EXIT_SELF_STALE = 7
 
 
 class DriveError(Exception):
@@ -218,6 +233,31 @@ _CAPTURED_OUTPUT_LIMIT = 4000
 # never *tightened* for the environmental case.
 _ENVIRONMENTAL_WORK_RETRY_BUDGET = 5
 
+# #2443: how many CONSECUTIVE polls of the IDENTICAL `Action.label` to
+# tolerate before `Driver._loop` checks whether its own on-disk `coord`
+# install has moved since this session started. Below this, a same-label
+# repeat is indistinguishable from an ordinary slow-but-progressing wait (a
+# 10-20 minute test, a slow CI check) and checking would just be wasted
+# subprocess calls; at/above it, the check itself is a single local `git
+# rev-parse HEAD` (no network — see `coord.self_health.self_freshness
+# (fetch=False)`), cheap enough to run on every remaining poll of the
+# streak. At the default `--poll` of 60s this is ~10 minutes — fast enough
+# to matter against a multi-hour `--deadline`, slow enough that a routine
+# wait is never mistaken for the stuck case this exists to catch.
+_SELF_HEAL_WAIT_STREAK = 10
+
+
+def _current_self_head() -> str | None:
+    """Real default for `Driver.self_head_probe` (#2443): THIS process's own
+    on-disk `coord` install's current HEAD, or ``None`` when it can't be
+    determined (not a git checkout, unreadable HEAD — see
+    :func:`coord.self_health.self_freshness`). ``fetch=False``: this only
+    needs to notice code that has ALREADY landed locally (e.g. a prior `git
+    pull`), never reaches the network, and therefore never blocks the poll
+    loop on a slow/unreachable origin.
+    """
+    return self_freshness(fetch=False).head_sha
+
 
 def _bounded_tail(text: str, limit: int = _CAPTURED_OUTPUT_LIMIT) -> str:
     """*text*, or its last *limit* characters if longer — the tail, because
@@ -3685,8 +3725,19 @@ class Driver:
     # real `claude -p "/usage"` subprocess — mirrors *verifier*/*oracle_gate*
     # above. Defaults to the real (cached, ~60s) probe.
     usage_prober: Callable[[], PlanLimits] = get_plan_limits
+    # #2443: injected so tests can script a fake on-disk HEAD sequence
+    # without a real git checkout — same shape as *usage_prober* above.
+    # Defaults to the real, local-only (`fetch=False`) probe.
+    self_head_probe: Callable[[], str | None] = _current_self_head
 
     _run_log: Path | None = field(default=None, init=False, repr=False)
+    # #2443: this session's own on-disk `coord` HEAD, captured once by
+    # `_loop()` right as the poll loop begins — the baseline every later
+    # `_self_heal_drift_message` check compares against. `None` when it
+    # could not be determined (not a git checkout, unreadable HEAD), which
+    # keeps the self-heal check permanently a no-op for this run rather than
+    # ever comparing against a placeholder.
+    _start_head_sha: str | None = field(default=None, init=False, repr=False)
     # #1499: the terminating Action's own message, captured by `_loop()` right
     # before it returns — `run()` folds this into the `drive_exited` audit
     # summary/details so a non-exceptional terminal exit (e.g. `decide()`
@@ -3818,6 +3869,36 @@ class Driver:
         finally:
             lock.release()
 
+    # ── self-heal (#2443) ──────────────────────────────────────────────
+    def _self_heal_drift_message(self, label: str, streak: int) -> str | None:
+        """Has THIS process's own on-disk ``coord`` install moved since this
+        drive session started? ``None`` when it hasn't — or when freshness
+        can't be determined at all, which must never be misread as drift —
+        the overwhelmingly common case, so the caller just keeps waiting
+        exactly as before.
+
+        Only ever consulted once *label* (a WAIT ``Action``'s own reason)
+        has repeated *streak* times in a row (``_loop``'s
+        ``_SELF_HEAL_WAIT_STREAK`` gate) — this is specifically the #2286
+        shape: ``_decide_acceptance_author``'s "could not verify commits
+        (git fetch failed), retrying" arm returned the IDENTICAL label every
+        ~60s for 2+ hours after the fix that would have resolved it had
+        already landed on disk, because Python never reloads an
+        already-imported module. A stale in-memory `coord/drive.py` has no
+        way to notice that on its own — this is the bounded check that lets
+        it notice anyway.
+        """
+        current = self.self_head_probe()
+        if not current or not self._start_head_sha or current == self._start_head_sha:
+            return None
+        return (
+            "code changed underneath this session — on-disk coord moved "
+            f"from {self._start_head_sha[:8]} to {current[:8]} while stuck "
+            f"repeating the same wait {streak}x: {label!r}. Exiting "
+            "(EXIT_SELF_STALE) so coord drive-queue relaunches with "
+            f"current code instead of continuing to wait on stale logic (#2443)."
+        )
+
     def _post_escalation_comment(self, state: IssueState, message: str) -> None:
         """#1526: durably surface an escalation's reason onto the issue
         itself, not just this run's tmux pane and the ``coord escalate``
@@ -4061,6 +4142,15 @@ class Driver:
         # nudge) while guaranteeing a stalled stage is never more than one
         # `stall_secs` window away from a fresh check.
         last_nudge: float | None = None
+        # #2443: this session's own on-disk `coord` HEAD, captured once,
+        # right as the poll loop begins — see `_self_heal_drift_message`.
+        self._start_head_sha = self.self_head_probe()
+        # A distinct object (never equal to any real `Action.label`, empty
+        # string included) so the very first WAIT of the run always starts
+        # its streak at 1 rather than accidentally matching an unset
+        # sentinel.
+        last_wait_label: object = object()
+        same_wait_streak = 0
 
         while True:
             now = self.clock()
@@ -4155,6 +4245,36 @@ class Driver:
             for warning in action.warnings:
                 self.warn(warning)
 
+            # #2443: self-heal — see `_self_heal_drift_message`. Tracked off
+            # the Action's own `label`, NOT `fingerprint` above: a WAIT can
+            # (and, in the #2286 shape, does) repeat the identical reason
+            # poll after poll while the board fingerprint itself is static
+            # for the same underlying reason, so this is really the same
+            # signal — but keying directly on what the loop is ABOUT TO DO
+            # keeps this correct even for a WAIT arm whose label happens to
+            # be static text unrelated to fingerprint (e.g. "TEST: in
+            # progress on a capability-matched machine") without needing to
+            # reason about the two staying in lockstep. A non-WAIT action
+            # (RUN or EXIT) always resets the streak: dispatching something
+            # is progress by definition.
+            if action.kind == WAIT:
+                if action.label == last_wait_label:
+                    same_wait_streak += 1
+                else:
+                    last_wait_label = action.label
+                    same_wait_streak = 1
+                if same_wait_streak >= _SELF_HEAL_WAIT_STREAK:
+                    drift = self._self_heal_drift_message(
+                        action.label, same_wait_streak
+                    )
+                    if drift:
+                        self._last_exit_message = drift
+                        self.warn(drift)
+                        return EXIT_SELF_STALE
+            else:
+                last_wait_label = object()
+                same_wait_streak = 0
+
             if action.is_exit:
                 # #1499: capture the exit reason for the audit boundary before
                 # anything below can fail — the escalation write is explicitly

{code_coordinator-0.5.172 → code_coordinator-0.5.173}/docs/OPERATING_GOTCHAS.md

@@ -44,6 +44,23 @@ doc's guess) and reports STALE with a commit count when it hasn't been pulled
 since a `coord/**` fix merged — the checkable gate for this row, the same way
 `coord diagnose --graph` is the checkable gate for graphify freshness.
 
+**#2443: a LIVE `coord drive` session now self-heals mid-run too.** #2436
+above only helps *before* a new launch — it says nothing about a session
+that was already running, with the OLD code loaded into memory, when the fix
+landed. Python never reloads an already-imported module, so a stale live
+session has no way to notice a fix on its own. `coord/drive.py`'s poll loop
+now watches its own `WAIT` actions: once the identical wait reason repeats
+`_SELF_HEAL_WAIT_STREAK` (10) polls in a row, it compares its own on-disk
+`coord` HEAD (captured once, at session start) against the current one
+(`coord.self_health.self_freshness(fetch=False)` — a local `git rev-parse
+HEAD`, no network). If the checkout moved underneath it, the session exits
+`EXIT_SELF_STALE` — a clean, non-permanent exit `coord drive-queue`'s
+ordinary retry/relaunch path picks straight back up under the current code —
+instead of continuing to poll dead logic for the rest of `--deadline`. This
+is the actual fix for the incident #2436 diagnosed after the fact: a live
+session on dellserver polled one unfetchable path every ~60s for 2+ hours
+after the #2319/#2320 fix that would have resolved it was already on disk.
+
 Not academic. #1394 (worker strands uncommitted work, then cleanup destroys it)
 sat merged-but-undeployed, and the very next dispatch — #1402 — hit the
 identical bug: **$3.44 and 10 minutes lost to something already fixed on

{code_coordinator-0.5.172 → code_coordinator-0.5.173}/tests/test_drive.py

@@ -39,6 +39,7 @@ from coord.drive import (
     EXIT_DISPATCH_REFUSED,
     EXIT_ESCALATED,
     EXIT_OK,
+    EXIT_SELF_STALE,
     EXIT_TERMINAL_FAILURE,
     EXIT_USAGE,
     RUN,
@@ -4664,7 +4665,7 @@ def driver_factory(tmp_path, monkeypatch, capsys):
 
     def make(
         payloads, *, opts=None, verifier=None, config=None, oracle_gate=None,
-        usage_prober=None, ticks=200,
+        usage_prober=None, self_head_probe=None, ticks=200,
     ):
         clock = {"t": 0.0}
         recorded: list[list[str]] = []
@@ -4688,6 +4689,16 @@ def driver_factory(tmp_path, monkeypatch, capsys):
             # probe at all), which the gate always treats as "proceed,
             # silently". Tests exercising the gate itself pass their own.
             usage_prober=usage_prober or (lambda: PlanLimits(status="unknown")),
+            # #2443: default to a stub reporting a constant, never-moving
+            # HEAD — same "opt in only the test that needs it" posture as
+            # *usage_prober* above. Without this, every driver test would
+            # exercise the REAL probe (a handful of local `git` reads
+            # against this actual checkout, routed through `fake_run` above
+            # since `coord.self_health` imports the same `subprocess`
+            # module object) — harmless, but tying every other test's
+            # behaviour to this repo's own git state is exactly the kind of
+            # incidental coupling worth avoiding.
+            self_head_probe=self_head_probe or (lambda: "unchanging-sha"),
             sleeper=lambda secs: clock.__setitem__("t", clock["t"] + secs),
             clock=lambda: clock["t"],
         )
@@ -5322,6 +5333,66 @@ def test_driver_returns_the_deadline_code_when_time_runs_out(driver_factory, cap
     assert "deadline" in capsys.readouterr().err
 
 
+def test_driver_self_heals_when_code_moves_underneath_a_stuck_wait(
+    driver_factory, capsys,
+):
+    """#2443: the claude-coordinator#2286 shape end to end. `_decide_
+    advisory`'s "could not verify branch commits (git fetch failed),
+    retrying" WAIT (#2426) repeats byte-for-byte every poll as long as
+    nothing about the underlying condition changes — exactly what a stuck
+    `git fetch` looks like, and exactly what a session running STALE
+    in-memory `coord/drive.py` code can never resolve on its own (Python
+    never reloads an already-imported module). If this session's own
+    on-disk checkout moves while it is stuck in that loop, it must self-exit
+    (`EXIT_SELF_STALE`) instead of polling the same dead logic to
+    `--deadline` — the recovery is `coord drive-queue` relaunching fresh,
+    not this process outliving its own bug fix."""
+    calls = {"n": 0}
+
+    def probe():
+        calls["n"] += 1
+        # Call 1 is `_loop`'s own start-of-run baseline capture. Every call
+        # after that is a self-heal re-check, made only once the WAIT
+        # streak crosses the threshold — return a DIFFERENT sha from the
+        # second call onward to simulate a fix landing mid-run.
+        return "aaaaaaaaaaaa" if calls["n"] == 1 else "bbbbbbbbbbbb"
+
+    driver = driver_factory(
+        [board(status="advisory", branch="issue-1392-x")],
+        opts=DriveOptions(machine="precision", poll=1.0, deadline_mins=60.0),
+        verifier=FakeVerifier(has_commits=None),
+        self_head_probe=probe,
+    )
+    assert driver.run() == EXIT_SELF_STALE
+    err = capsys.readouterr().err
+    assert "code changed underneath this session" in err
+    assert "aaaaaaaa" in err  # the recorded start sha, truncated to 8 chars
+    assert "bbbbbbbb" in err  # the recorded moved-to sha, truncated
+    # It genuinely waited out the streak threshold instead of firing on the
+    # very first repeat of the label — the start capture plus AT LEAST one
+    # re-check, never on call 1 alone.
+    assert calls["n"] >= 2
+
+
+def test_driver_keeps_waiting_when_the_same_wait_repeats_but_code_has_not_moved(
+    driver_factory, capsys,
+):
+    """The other half of #2443: an identical WAIT label repeating is not, on
+    its own, grounds to self-exit — only a MOVED on-disk HEAD is. The
+    ordinary, overwhelmingly common case (the underlying condition just
+    genuinely has not resolved yet) must keep polling exactly as before,
+    all the way to `--deadline` — this must never fire for a
+    slow-but-progressing wait."""
+    driver = driver_factory(
+        [board(status="advisory", branch="issue-1392-x")],
+        opts=DriveOptions(machine="precision", poll=1.0, deadline_mins=0.2),
+        verifier=FakeVerifier(has_commits=None),
+        self_head_probe=lambda: "unchanging-sha",
+    )
+    assert driver.run() == EXIT_DEADLINE
+    assert "deadline" in capsys.readouterr().err
+
+
 def test_driver_tolerates_a_transport_blip_mid_loop_and_retries(driver_factory, capsys):
     """A daemon blip must be a retry next poll, never a traceback."""
     driver = driver_factory([board(status="merged")])