code-coordinator 0.5.532__tar.gz → 0.5.534__tar.gz

{code_coordinator-0.5.532 → code_coordinator-0.5.534}/PKG-INFO

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.532
+Version: 0.5.534
 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.534/code_coordinator.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.5.534",
+  "distance": 0,
+  "node": "ga57e6a4b749192d9ac4e31c24b5ad4b9fa5a2e13",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-30"
+}

{code_coordinator-0.5.532 → code_coordinator-0.5.534}/coord/client.py

@@ -763,18 +763,44 @@ def fetch_drive_escalations(
     return entries if isinstance(entries, list) else []
 
 
-def fetch_drive_queue(
+@dataclass(frozen=True)
+class DriveQueueRead:
+    """Result of one drive-queue read attempt (#2992).
+
+    Distinguishes "the daemon could not be read" from "the daemon answered
+    and the queue is genuinely empty" — a distinction :func:`fetch_drive_queue`
+    itself collapses on purpose (see its docstring), because most callers only
+    want best-effort rows. ``coord drive-queue list`` is the one caller that
+    must NOT collapse it: reporting "queue is empty" for a daemon that never
+    actually answered is exactly the false "nothing to see here" #2992 was
+    filed over.
+
+    ``ok=True`` — the daemon answered; ``entries`` is the real list, ``[]``
+    included for a genuinely drained queue.
+    ``ok=False`` — the read failed (network error, non-2xx, malformed JSON);
+    ``entries`` is always ``[]`` here too (never meaningful) and ``error``
+    carries a short human-readable reason.
+    """
+
+    ok: bool
+    entries: list[dict]
+    error: str | None = None
+
+
+def fetch_drive_queue_result(
     svc: ServiceConfig,
     repo_name: str | None = None,
     *,
     timeout: float = _DEFAULT_TIMEOUT,
-) -> list[dict]:
-    """GET the drive queue in run order, optionally filtered to one repo (#1753).
-
-    ``[]`` on ANY failure (404 from a daemon predating this route, network
-    error, bad JSON, or a genuinely empty queue) — fail-soft, mirrors
-    :func:`fetch_drive_escalations`. ``after_json`` arrives already decoded to
-    a list; this helper does not re-parse it.
+) -> DriveQueueRead:
+    """GET the drive queue — same request as :func:`fetch_drive_queue` — but
+    returning a :class:`DriveQueueRead` that keeps "could not read" and
+    "read fine, zero rows" apart (#2992).
+
+    This is the one place that decides what counts as a successful
+    drive-queue read; :func:`fetch_drive_queue` is now a thin fail-soft
+    wrapper around it, so there is exactly one answer to "did this read
+    succeed" rather than two implementations that could drift apart.
     """
     try:
         params = {"repo_name": repo_name} if repo_name else {}
@@ -786,10 +812,42 @@ def fetch_drive_queue(
         )
         resp.raise_for_status()
         data = resp.json()
-    except Exception:  # noqa: BLE001
-        return []
+    except httpx.HTTPStatusError as exc:
+        status = exc.response.status_code if exc.response is not None else "?"
+        return DriveQueueRead(
+            ok=False, entries=[], error=f"HTTP {status} from {svc.url}/drive-queue"
+        )
+    except Exception as exc:  # noqa: BLE001 — transport/JSON failure; reported, not swallowed
+        return DriveQueueRead(ok=False, entries=[], error=f"{type(exc).__name__}: {exc}")
     entries = data.get("entries") if isinstance(data, dict) else None
-    return entries if isinstance(entries, list) else []
+    if not isinstance(entries, list):
+        return DriveQueueRead(
+            ok=False, entries=[], error="malformed response (no 'entries' list)"
+        )
+    return DriveQueueRead(ok=True, entries=entries)
+
+
+def fetch_drive_queue(
+    svc: ServiceConfig,
+    repo_name: str | None = None,
+    *,
+    timeout: float = _DEFAULT_TIMEOUT,
+) -> list[dict]:
+    """GET the drive queue in run order, optionally filtered to one repo (#1753).
+
+    ``[]`` on ANY failure (404 from a daemon predating this route, network
+    error, bad JSON, or a genuinely empty queue) — fail-soft, mirrors
+    :func:`fetch_drive_escalations`. ``after_json`` arrives already decoded to
+    a list; this helper does not re-parse it.
+
+    Deliberately still collapses "failed" and "genuinely empty" to the same
+    ``[]`` — most callers (``coord.state.list_drive_queue``'s daemon route,
+    the auto-loop tick) only want best-effort rows and must keep degrading
+    quietly. A caller that needs to tell the two apart — ``coord
+    drive-queue list`` (#2992) — should call :func:`fetch_drive_queue_result`
+    instead, of which this is now a thin wrapper.
+    """
+    return fetch_drive_queue_result(svc, repo_name, timeout=timeout).entries
 
 
 def fetch_leg_counts(

{code_coordinator-0.5.532 → code_coordinator-0.5.534}/coord/commands/drive_queue.py

@@ -132,6 +132,7 @@ from coord.overlap_predict import (
 )
 
 if TYPE_CHECKING:  # pragma: no cover — typing only
+    from coord.client import DriveQueueRead
     from coord.config import Config
     from coord.merge_queue import QueuedMerge
 
@@ -1460,15 +1461,64 @@ def _board_for_list_diagnosis() -> BoardView | None:
         return None
 
 
+def _drive_queue_list_read(
+    repo: str | None,
+) -> tuple[list[dict], DriveQueueRead | None, str | None]:
+    """Fetch the rows `list` renders, distinguishing "daemon unreachable"
+    from "genuinely empty" on a thin client (#2992).
+
+    Returns ``(rows, failure, service_url)`` — ``failure`` is ``None`` on a
+    successful read (rows may still be ``[]``, a genuinely drained queue)
+    and a :class:`coord.client.DriveQueueRead` with ``ok=False`` when the
+    daemon could not be read at all; ``service_url`` names the daemon the
+    failed read targeted (``None`` in host mode). Host mode (no
+    ``board_service`` configured) has no daemon to fail against, so it
+    always reads the local DB and never returns a failure here — out of
+    scope per #2992's own issue body (``coord/state.py``'s local-DB
+    fallback is a separate seam).
+    """
+    from coord.client import fetch_drive_queue_result, resolve_board_service  # noqa: PLC0415
+    from coord.state import list_drive_queue  # noqa: PLC0415
+
+    svc = resolve_board_service()
+    if svc is None:
+        return list_drive_queue(repo), None, None
+    result = fetch_drive_queue_result(svc, repo)
+    if not result.ok:
+        return [], result, svc.url
+    return result.entries, None, svc.url
+
+
+def _drive_queue_list_failure_text(service_url: str, error: str | None) -> str:
+    """The `list` failure line — must read as unmistakably NOT "empty"
+    (#2992's acceptance bar: never contains the words "queue is empty")."""
+    return (
+        f"(drive queue UNREADABLE — could not reach board daemon at "
+        f"{service_url}: {error})"
+    )
+
+
+def _drive_queue_list_failure_json(service_url: str, error: str | None) -> str:
+    """The `--json` failure payload — never a bare `[]` a caller could
+    mistake for zero entries (#2992)."""
+    return _json.dumps({"error": error, "service_url": service_url, "ok": False})
+
+
 @drive_queue_group.command("list")
 @click.option("--repo", "repo", default=None, help="Restrict to one repo (default: every repo).")
 @click.option("--json", "output_json", is_flag=True, default=False, help="Emit the raw rows as JSON.")
 @_CONFIG_OPTION
 def drive_queue_list(repo: str | None, output_json: bool, config_path: Path) -> None:
     """Show the queue in run order."""
-    from coord.state import list_drive_queue  # noqa: PLC0415
+    rows, failure, service_url = _drive_queue_list_read(repo)
+    if failure is not None:
+        import sys as _sys  # noqa: PLC0415
 
-    rows = list_drive_queue(repo)
+        if output_json:
+            click.echo(_drive_queue_list_failure_json(service_url, failure.error))
+        else:
+            click.echo(_drive_queue_list_failure_text(service_url, failure.error))
+        _sys.exit(1)
     if output_json:
         click.echo(_json.dumps(rows))
         return

{code_coordinator-0.5.532 → code_coordinator-0.5.534}/coord/drive.py

@@ -1387,7 +1387,9 @@ def _decide_acceptance_author(
         # cites), so the thing being waited for could not happen even with
         # `merge.auto_drain` on.
         return replace(
-            _decide_acceptance_landing(state, oracle, opts, counters, machine),
+            _decide_acceptance_landing(
+                state, oracle, opts, counters, machine, verifier
+            ),
             warnings=(
                 f"ACCEPTANCE: JIT slice {aid} is ADVISORY with commits present "
                 "— proceeding per --accept-advisory (#1357)",
@@ -1460,7 +1462,9 @@ def _decide_acceptance_author(
         # Authoring finished and the branch carries commits: hand over to the
         # landing driver, which observes the daemon-driven Test/Review stages
         # and performs the one step the daemon will not (#2079 — the merge).
-        return _decide_acceptance_landing(state, oracle, opts, counters, machine)
+        return _decide_acceptance_landing(
+            state, oracle, opts, counters, machine, verifier
+        )
 
     # "" / running: still authoring — nothing to drive yet.
     return _wait(
@@ -1476,6 +1480,7 @@ def _decide_acceptance_landing(
     opts: DriveOptions,
     counters: DriveCounters,
     machine: str,
+    verifier: MergeVerifier,
 ) -> Action:
     """Land the authored JIT acceptance slice (#2079).
 
@@ -1673,7 +1678,7 @@ def _decide_acceptance_landing(
         merge_aid=state.acceptance_merge_aid,
         merge_pr_url=state.acceptance_merge_pr_url,
     )
-    action = _decide_merge(shadow, opts, counters.slice_budget())
+    action = _decide_merge(shadow, opts, counters.slice_budget(), verifier)
     return replace(
         action,
         label=_acceptance_label(action.label),
@@ -1779,6 +1784,8 @@ class MergeVerifier(Protocol):
         self, state: IssueState
     ) -> EpicChecklistSnapshot | None: ...
 
+    def github_backoff_active(self) -> bool: ...
+
 
 def _remote_matches_repo(remote_url: str, repo_github: str) -> bool:
     """Loosely compare a ``git remote get-url origin`` URL against the
@@ -1991,6 +1998,26 @@ class GitMergeVerifier:
 
         return github_ops.get_branch_sha(state.repo_github, state.work_branch)
 
+    def github_backoff_active(self) -> bool:
+        """True when GitHub's shared, fleet-wide rate-limit backoff
+        (:mod:`coord.github_throttle`, #2809/#2934) is currently in force.
+
+        #3479: the ONE thing :func:`_decide_merge`'s ``"unknown_head"`` arm
+        must check before spending a live ``coord merge --only`` re-check —
+        see that arm's own docstring for the latched-reason bug this
+        guards against. Routed through :func:`coord.github_throttle.
+        consult` (not the same-host-only :func:`~coord.github_throttle.
+        current`) so this honours a backoff another machine recorded via
+        the daemon, exactly like the shared funnel every live ``gh`` call
+        already consults before it ever reaches GitHub — re-probing INTO a
+        window another host just tripped is precisely the synchronized-
+        hammering #2809 exists to prevent.
+        """
+        from coord import github_throttle  # noqa: PLC0415
+
+        _sleep_s, backoff = github_throttle.consult()
+        return backoff is not None
+
     def epic_checklist_snapshot(
         self, state: IssueState
     ) -> EpicChecklistSnapshot | None:
@@ -2913,7 +2940,7 @@ def decide(
             warnings=warnings,
         )
 
-    merge = _decide_merge(state, opts, counters)
+    merge = _decide_merge(state, opts, counters, verifier)
     return replace(merge, warnings=warnings + merge.warnings)
 
 
@@ -4275,7 +4302,10 @@ def _park_uat_fixup_dispatch_failure(
 
 
 def _decide_merge(
-    state: IssueState, opts: DriveOptions, counters: DriveCounters
+    state: IssueState,
+    opts: DriveOptions,
+    counters: DriveCounters,
+    verifier: MergeVerifier,
 ) -> Action:
     """The MERGE stage.
 
@@ -4335,13 +4365,55 @@ def _decide_merge(
     # confirmed. No retry or fix this driver can take changes GitHub's
     # answer; wait, exactly like the CI-unreadable case below, and never
     # spend a merge attempt re-observing the identical unreadable probe.
+    #
+    # #3479: this used to be a BARE `_wait()` for as long as this reason
+    # stayed on the board — nothing here ever re-probed, so a `merge_reason`
+    # from an outage that had already cleared just kept getting re-read
+    # forever (quadraui#1083: 309 consecutive polls over 2.5h reprinting the
+    # identical "branch head unknown" line while GitHub was fully healthy
+    # the whole time — `gh auth status` OK, rate limit 5000/5000 — because
+    # the REAL block, a failing required CI check, was a few lines further
+    # down in `_decide_merge` and this arm returned before ever reaching
+    # it). "Branch head unknown" means "wait until the probe recovers", so
+    # this now actually re-probes: once the shared GitHub backoff
+    # (:mod:`coord.github_throttle`, #2809/#2934 — the SAME funnel every
+    # live `gh` call already consults) is no longer active, dispatch the
+    # identical budget-exempt real `coord merge --only <aid>` re-check the
+    # CI-unreadable arm below uses, instead of re-reading a value nothing
+    # here ever refreshes. That live attempt re-evaluates every gate,
+    # including CI, so a resolved outage reaches the SAME `checks_failed` →
+    # `coord.commands.merge._dispatch_ci_fixes` path a human running the
+    # identical command by hand already does — the quadraui#1083 recovery.
+    #
+    # While the backoff IS active, this still just waits, WITHOUT touching
+    # `verifier`/GitHub at all — #2809's whole point is that hammering
+    # GitHub during a backoff window only prolongs it, so no probe (real or
+    # otherwise) is issued while one is in force.
     if _merge_gate_kind(gate_reason) == "unknown_head":
-        return _wait(
-            label=(
-                "MERGE: branch head unknown — GitHub read failed (rate "
-                "limit, auth, or network); waiting, not retrying (#2704): "
-                f"{gate_reason}"
+        if verifier.github_backoff_active():
+            return _wait(
+                label=(
+                    "MERGE: branch head unknown — GitHub backoff active "
+                    "(#2809); waiting, not probing (#2704/#3479): "
+                    f"{gate_reason}"
+                )
             )
+        aid = state.merge_aid or state.work_aid
+        return Action(
+            kind=RUN,
+            label=(
+                "MERGE: branch head unknown — GitHub backoff clear, "
+                "re-checking for real instead of re-reading the latched "
+                f"reason (#2704/#3479): {gate_reason}"
+            ),
+            command=("merge", "--only", aid, "--method", opts.merge_method),
+            on_error="warn",
+            error_message=(
+                "coord merge returned non-zero (or the merge lock timed "
+                "out) while re-checking an unknown branch head — "
+                "re-checking next poll"
+            ),
+            serialize_merge=True,
         )
     # #2947 (follow-up to #2687): the UAT gate is a human-attended block — no
     # `coord merge` retry can clear it, only an operator or a customer

{code_coordinator-0.5.532 → code_coordinator-0.5.534}/tests/test_client.py

@@ -204,3 +204,125 @@ class TestFetchBoardPayloadConditionalGet:
         cc.reset_board_payload_cache()
 
         assert cc._board_payload_cache == {}
+
+
+class TestFetchDriveQueueResult:
+    """#2992: a daemon read failure must be distinguishable from a
+    genuinely empty queue — ``fetch_drive_queue_result`` is the function
+    that carries that distinction; ``fetch_drive_queue`` stays a fail-soft
+    wrapper around it for callers that don't want it (unchanged contract).
+    """
+
+    def test_populated_queue_is_ok_with_the_real_rows(self, monkeypatch) -> None:
+        rows = [{"repo_name": "cc", "issue_number": 1}, {"repo_name": "cc", "issue_number": 2}]
+
+        def fake_get(url, *, headers=None, params=None, **kw):
+            return _FakeResponse(json_body={"entries": rows})
+
+        monkeypatch.setattr(cc.httpx, "get", fake_get)
+
+        result = cc.fetch_drive_queue_result(_svc())
+
+        assert result.ok is True
+        assert result.entries == rows
+        assert result.error is None
+
+    def test_genuinely_empty_queue_is_ok_with_zero_rows(self, monkeypatch) -> None:
+        def fake_get(url, *, headers=None, params=None, **kw):
+            return _FakeResponse(json_body={"entries": []})
+
+        monkeypatch.setattr(cc.httpx, "get", fake_get)
+
+        result = cc.fetch_drive_queue_result(_svc())
+
+        assert result.ok is True
+        assert result.entries == []
+        assert result.error is None
+
+    def test_transport_error_is_not_ok_and_names_the_reason(self, monkeypatch) -> None:
+        def fake_get(url, *, headers=None, params=None, **kw):
+            raise httpx.ConnectError("connection refused")
+
+        monkeypatch.setattr(cc.httpx, "get", fake_get)
+
+        result = cc.fetch_drive_queue_result(_svc())
+
+        assert result.ok is False
+        assert result.entries == []
+        assert result.error is not None
+        assert "refused" in result.error or "ConnectError" in result.error
+
+    def test_5xx_is_not_ok_and_names_the_status(self, monkeypatch) -> None:
+        def fake_get(url, *, headers=None, params=None, **kw):
+            return _FakeResponse(status_code=503)
+
+        monkeypatch.setattr(cc.httpx, "get", fake_get)
+
+        result = cc.fetch_drive_queue_result(_svc())
+
+        assert result.ok is False
+        assert result.entries == []
+        assert "503" in result.error
+
+    def test_malformed_json_is_not_ok(self, monkeypatch) -> None:
+        def fake_get(url, *, headers=None, params=None, **kw):
+            return _FakeResponse(json_body={"not_entries_at_all": True})
+
+        monkeypatch.setattr(cc.httpx, "get", fake_get)
+
+        result = cc.fetch_drive_queue_result(_svc())
+
+        assert result.ok is False
+        assert result.entries == []
+        assert result.error
+
+    def test_the_three_shapes_are_mutually_distinguishable(self, monkeypatch) -> None:
+        """Empty / transport-error / populated must never collapse to the
+        same result — the whole point of #2992."""
+
+        def get_for(shape: str):
+            def fake_get(url, *, headers=None, params=None, **kw):
+                if shape == "populated":
+                    return _FakeResponse(json_body={"entries": [{"issue_number": 1}]})
+                if shape == "empty":
+                    return _FakeResponse(json_body={"entries": []})
+                raise httpx.ConnectError("refused")
+
+            return fake_get
+
+        monkeypatch.setattr(cc.httpx, "get", get_for("populated"))
+        populated = cc.fetch_drive_queue_result(_svc())
+        monkeypatch.setattr(cc.httpx, "get", get_for("empty"))
+        empty = cc.fetch_drive_queue_result(_svc())
+        monkeypatch.setattr(cc.httpx, "get", get_for("error"))
+        errored = cc.fetch_drive_queue_result(_svc())
+
+        assert (populated.ok, empty.ok, errored.ok) == (True, True, False)
+        assert populated.entries != empty.entries
+        assert errored.error is not None
+        assert populated.error is None
+        assert empty.error is None
+
+    def test_fetch_drive_queue_stays_fail_soft_to_empty_list_on_failure(
+        self, monkeypatch
+    ) -> None:
+        """The pre-existing, unchanged contract: `fetch_drive_queue` itself
+        never raises and never exposes the failure — only
+        `fetch_drive_queue_result` does."""
+
+        def fake_get(url, *, headers=None, params=None, **kw):
+            raise httpx.ConnectError("refused")
+
+        monkeypatch.setattr(cc.httpx, "get", fake_get)
+
+        assert cc.fetch_drive_queue(_svc()) == []
+
+    def test_fetch_drive_queue_returns_the_real_rows_on_success(self, monkeypatch) -> None:
+        rows = [{"repo_name": "cc", "issue_number": 7}]
+
+        def fake_get(url, *, headers=None, params=None, **kw):
+            return _FakeResponse(json_body={"entries": rows})
+
+        monkeypatch.setattr(cc.httpx, "get", fake_get)
+
+        assert cc.fetch_drive_queue(_svc()) == rows