code-coordinator 0.5.293__tar.gz → 0.5.294__tar.gz

{code_coordinator-0.5.293 → code_coordinator-0.5.294}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.293",
+  "tag": "0.5.294",
   "distance": 0,
-  "node": "g80ec18827638d21151ef2fd58d9374377758ba0b",
+  "node": "gad3ed43a4b2310f6ef6968a7676f11e2deaca61f",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-29"

{code_coordinator-0.5.293 → code_coordinator-0.5.294}/coord/client.py

@@ -474,6 +474,62 @@ def post_pause(
     return post_record(svc, "/pause", {"machine": machine, "action": action}, timeout=timeout)
 
 
+def fetch_github_backoff(
+    svc: ServiceConfig, *, timeout: float = _DEFAULT_TIMEOUT
+) -> dict | None:
+    """GET /github-backoff → the daemon's shared GitHub rate-limit backoff
+    state, or ``None`` when there isn't an active one (#2934).
+
+    The read side of the fleet-wide half of #2809: a 403 recorded by ANY
+    machine's `coord.github_throttle.record()` lands here, so every other
+    machine's next `coord.github_throttle.consult()` — the seam every `gh`
+    call funnels through — sees it before making its own call, rather than
+    only ever learning about its own host's hits. Raises ``httpx.HTTPError``
+    on transport/HTTP failure — `coord.github_throttle.consult()` catches
+    that itself and falls back to the local per-host file (this module stays
+    strict, same posture as `fetch_paused_machines`, so a caller that DOES
+    want to distinguish "confirmed none" from "couldn't ask" still can).
+
+    Returns the raw ``{until, reason, status, request_id, retry_after_s,
+    recorded_at}`` mapping (or ``None``) rather than a `Backoff` — parsing
+    that shape is `coord.github_throttle`'s job, the same division client.py
+    keeps for `fetch_cordons`/`fetch_quiet_hours` above.
+    """
+    resp = httpx.get(f"{svc.url}/github-backoff", headers=_headers(svc), timeout=timeout)
+    resp.raise_for_status()
+    data = resp.json()
+    backoff = data.get("backoff") if isinstance(data, dict) else None
+    return dict(backoff) if isinstance(backoff, dict) else None
+
+
+def post_github_backoff(
+    svc: ServiceConfig,
+    *,
+    reason: str,
+    status: int | None,
+    request_id: str | None,
+    retry_after_s: float | None,
+    timeout: float = _WRITE_TIMEOUT,
+) -> dict:
+    """POST /github-backoff {reason, status, request_id, retry_after_s} —
+    publish a rate-limit hit to the daemon's shared backoff state (#2934).
+
+    Raises ``httpx.HTTPError`` on transport/HTTP failure —
+    `coord.github_throttle.record()` catches that itself and falls back to
+    writing this host's own local file, the same fail-soft posture the
+    module's docstring requires of every public function here: a caller
+    that just got a 403 must never fail a *second* way because publishing it
+    fleet-wide didn't work.
+    """
+    payload = {
+        "reason": reason,
+        "status": status,
+        "request_id": request_id,
+        "retry_after_s": retry_after_s,
+    }
+    return post_record(svc, "/github-backoff", payload, timeout=timeout)
+
+
 def fetch_remote_config(svc: ServiceConfig, *, timeout: float = _DEFAULT_TIMEOUT) -> Path:
     """GET /config, cache it to ``~/.coord/coordinator.remote.yml``, return the path.
 

{code_coordinator-0.5.293 → code_coordinator-0.5.294}/coord/github_throttle.py

@@ -1,4 +1,4 @@
-"""Shared, per-machine GitHub request backoff state (#2809).
+"""Shared, fleet-wide GitHub request backoff state (#2809, #2934).
 
 **The problem.** GitHub's *secondary* (abuse-detection) rate limiter fires on
 request *rate and concurrency*, not cumulative volume — it does not show up
@@ -29,20 +29,39 @@ only decays when request volume drops), and every wait applies jitter so
 pollers that all observed the same 403 don't all wake up and retry in
 lockstep.
 
-**Scope: per-machine, not per-fleet.** The fleet spans multiple machines
-sharing one GitHub token/user, so a *complete* fix routes this through the
-board daemon (the one process every machine already talks to — see
-``coord.machine_pause`` for the daemon-aware pattern this module deliberately
-does NOT yet follow). That is a larger, separable change; this module closes
-the same-host half of #2809 (the incident's own two concrete examples —
-``claude-coordinator#2782``/``#2802`` — were polling from the same host) and
-leaves cross-machine coordination as a documented follow-up rather than
-silently claiming to solve it.
+**Scope: fleet-wide, not just per-machine (#2934).** GitHub's secondary
+limiter is keyed on the *user*, not the host — #2809's own captured 403 reads
+``API rate limit exceeded for user ID 3506413`` — so four individually
+well-behaved machines sharing one token still sum to a rate that trips it,
+each backing off in isolation while the other three keep calling. That is
+exactly the synchronized-poll pattern that keeps a secondary limit tripped
+instead of letting it decay, and it is why the two full days after #2809
+alone went live (36, 48 trips) read at or above its own pre-fix baseline
+(15, 43, 30).
+
+:func:`record` and :func:`consult` — the two functions :func:`coord.
+github_ops._gh` actually calls — now route through the board daemon (the one
+process every machine already talks to) when one is configured, following
+the daemon-aware pattern ``coord.machine_pause`` established: a hit recorded
+on one host is published once to the daemon's local file, and every other
+host's very next ``consult()`` sees it over that same HTTP seam, rather than
+each host only ever learning about its own 403s. :func:`local_record` /
+:func:`local_consult` (and :func:`current` / :func:`clear`, which stay
+local-only — nothing outside tests reads them) are the original same-host
+primitives from #2809, now the fallback :func:`record`/:func:`consult` use
+whenever no board service is configured (solo use, or the daemon's own
+in-process calls — it has no ``board_service`` configured for itself, so its
+own ``gh`` calls read/write the very file its ``/github-backoff`` endpoint
+serves, with no extra hop) **and** whenever the daemon IS configured but
+unreachable: a transport failure on either the read or the write side
+degrades to the per-host file rather than to "no damping" or a raised
+exception — see both functions' docstrings.
 
 **Best-effort, unconditionally.** Every public function here can fail (a
-missing/unwritable state dir, a corrupt file) without ever raising into or
-delaying a caller beyond the bound it already asked for — damping must never
-become a new way to break `gh` access, only a way to reduce it.
+missing/unwritable state dir, a corrupt file, an unreachable daemon) without
+ever raising into or delaying a caller beyond the bound it already asked
+for — damping must never become a new way to break `gh` access, only a way
+to reduce it.
 """
 
 from __future__ import annotations
@@ -127,6 +146,26 @@ def _jitter(seconds: float) -> float:
     return max(0.0, seconds + random.uniform(-spread, spread))
 
 
+def _backoff_from_mapping(data: dict) -> Backoff | None:
+    """Parse one ``{until, reason, status, request_id, retry_after_s,
+    recorded_at}`` mapping into a :class:`Backoff`, or ``None`` if it isn't
+    one — shared by :func:`_read` (the on-disk JSON) and :func:`consult`
+    (the daemon's ``GET /github-backoff`` JSON body), so the two shapes can
+    never quietly drift apart.
+    """
+    until = data.get("until")
+    if not isinstance(until, (int, float)):
+        return None
+    return Backoff(
+        until=float(until),
+        reason=data.get("reason") or "rate_limit",
+        status=data.get("status"),
+        request_id=data.get("request_id"),
+        retry_after_s=data.get("retry_after_s"),
+        recorded_at=float(data.get("recorded_at") or 0.0),
+    )
+
+
 def _read(path: Path | None = None) -> Backoff | None:
     path = path if path is not None else _state_path()
     try:
@@ -139,17 +178,17 @@ def _read(path: Path | None = None) -> Backoff | None:
         return None
     if not isinstance(data, dict):
         return None
-    until = data.get("until")
-    if not isinstance(until, (int, float)):
-        return None
-    return Backoff(
-        until=float(until),
-        reason=data.get("reason") or "rate_limit",
-        status=data.get("status"),
-        request_id=data.get("request_id"),
-        retry_after_s=data.get("retry_after_s"),
-        recorded_at=float(data.get("recorded_at") or 0.0),
-    )
+    return _backoff_from_mapping(data)
+
+
+def _resolve_service():  # -> coord.client.ServiceConfig | None
+    """Same seam ``coord.machine_pause._resolve_service`` uses: ``None`` for
+    solo/local use and for the daemon's own in-process calls (it never
+    configures a board service for itself), a ``ServiceConfig`` for a thin
+    client."""
+    from coord.board_service import resolve  # noqa: PLC0415
+
+    return resolve()
 
 
 def record(
@@ -160,7 +199,54 @@ def record(
     retry_after_s: float | None,
     now: float | None = None,
 ) -> None:
-    """Record a rate-limit hit as the shared backoff-until timestamp.
+    """Record a rate-limit hit as the shared, fleet-wide backoff-until
+    timestamp (#2934).
+
+    Daemon-first: when a board service is configured, POSTs the hit to the
+    daemon's ``/github-backoff`` endpoint (:func:`coord.client.
+    post_github_backoff`), which records it into *that host's* local file —
+    the same file every other machine's next :func:`consult` reads. Falls
+    back to :func:`local_record` — this host's own file — both when no board
+    service is configured (solo use, or the daemon's own in-process calls)
+    and when one is configured but the POST fails for any reason (network,
+    timeout, an older daemon with no ``/github-backoff`` route): a caller who
+    just got a 403 must never fail a *second* way, over the network, because
+    publishing it fleet-wide didn't work. ``now`` is only honoured on the
+    local fallback path — the daemon's own clock governs its file.
+    """
+    svc = _resolve_service()
+    if svc is not None:
+        try:
+            from coord.client import post_github_backoff  # noqa: PLC0415
+
+            post_github_backoff(
+                svc, reason=reason, status=status, request_id=request_id,
+                retry_after_s=retry_after_s,
+            )
+            return
+        except Exception as exc:  # noqa: BLE001 -- fall back to the local file
+            _log.debug("github_throttle: daemon record failed, falling back to local: %s", exc)
+    local_record(
+        reason=reason, status=status, request_id=request_id,
+        retry_after_s=retry_after_s, now=now,
+    )
+
+
+def local_record(
+    *,
+    reason: str,
+    status: int | None,
+    request_id: str | None,
+    retry_after_s: float | None,
+    now: float | None = None,
+) -> None:
+    """Record a rate-limit hit into THIS HOST's own backoff file (#2809).
+
+    The same-host primitive :func:`record` above falls back to when no
+    board service is configured or the daemon is unreachable — see its
+    docstring. Also what the daemon's own ``POST /github-backoff`` handler
+    calls, since that endpoint runs *inside* the daemon and this file IS the
+    shared state a fleet-wide caller is asking to read.
 
     Best-effort (never raises): a caller who just got a 403 must never fail
     a *second* way because bookkeeping about the first one broke.
@@ -233,8 +319,30 @@ def clear() -> None:
         pass
 
 
+def _consult_from(b: Backoff | None, *, now: float) -> tuple[float, Backoff | None]:
+    """Shared sleep/skip computation for both :func:`local_consult` (reading
+    the on-disk *b*) and :func:`consult` (reading a daemon-fetched *b*) — one
+    place decides the jitter and the :data:`MAX_PRECALL_SLEEP_S` cap,
+    regardless of where *b* came from."""
+    if b is None:
+        return 0.0, None
+    remaining = b.until - now
+    return _jitter(min(remaining, MAX_PRECALL_SLEEP_S)), b
+
+
 def consult(*, now: float | None = None) -> tuple[float, Backoff | None]:
-    """``(sleep_s, backoff)`` for a caller about to issue a `gh` call.
+    """``(sleep_s, backoff)`` for a caller about to issue a `gh` call
+    (#2934: fleet-wide).
+
+    Daemon-first: when a board service is configured, GETs the shared
+    backoff from the daemon's ``/github-backoff`` endpoint
+    (:func:`coord.client.fetch_github_backoff`) — so a 403 recorded by
+    *another* machine's :func:`record` is honoured here, on this machine's
+    very next call, without this host having tripped anything itself. Falls
+    back to :func:`local_consult` — this host's own file — both when no
+    board service is configured (solo use, or the daemon's own in-process
+    calls) and when one is configured but the GET fails for any reason:
+    never raises, never silently drops damping to zero.
 
     ``backoff`` is the active :class:`Backoff`, or ``None`` when there isn't
     one (``sleep_s`` is then always ``0.0``). ``sleep_s`` is the jittered
@@ -245,11 +353,33 @@ def consult(*, now: float | None = None) -> tuple[float, Backoff | None]:
     docstring.
 
     Never calls `time.sleep` itself, so this stays a pure, cheaply-testable
-    read — the actual wait/skip decision belongs to the caller.
+    read — the actual wait/skip decision belongs to the caller. The daemon
+    round trip is the one exception to "cheap": a caller on the hot path of
+    every `gh` invocation pays one small HTTP GET per call when a board
+    service is configured, same cost class as every other daemon-routed read
+    in this package.
     """
     now = now if now is not None else time.time()
-    b = current(now=now)
-    if b is None:
-        return 0.0, None
-    remaining = b.until - now
-    return _jitter(min(remaining, MAX_PRECALL_SLEEP_S)), b
+    svc = _resolve_service()
+    if svc is not None:
+        try:
+            from coord.client import fetch_github_backoff  # noqa: PLC0415
+
+            raw = fetch_github_backoff(svc)
+        except Exception as exc:  # noqa: BLE001 -- fall back to the local file
+            _log.debug("github_throttle: daemon consult failed, falling back to local: %s", exc)
+        else:
+            b = _backoff_from_mapping(raw) if isinstance(raw, dict) else None
+            return _consult_from(b, now=now)
+    return local_consult(now=now)
+
+
+def local_consult(*, now: float | None = None) -> tuple[float, Backoff | None]:
+    """``(sleep_s, backoff)`` from THIS HOST's own backoff file (#2809).
+
+    The same-host primitive :func:`consult` above falls back to when no
+    board service is configured or the daemon is unreachable — see its
+    docstring for the shape of the return value.
+    """
+    now = now if now is not None else time.time()
+    return _consult_from(current(now=now), now=now)

{code_coordinator-0.5.293 → code_coordinator-0.5.294}/coord/serve_app.py

@@ -4510,6 +4510,49 @@ def openapi_spec() -> dict:
                 },
             },
         },
+        "/github-backoff": {
+            "get": {
+                "summary": (
+                    "#2934: the daemon's own view of the shared GitHub "
+                    "secondary-rate-limit backoff — the state every "
+                    "machine's `coord.github_throttle.consult()` reads "
+                    "before its next `gh` call, fleet-wide rather than "
+                    "per-host."
+                ),
+                "responses": {
+                    "200": {"description": "OK"},
+                },
+            },
+            "post": {
+                "summary": (
+                    "#2934: record a rate-limit hit into the daemon's "
+                    "shared backoff store, so every OTHER machine's next "
+                    "`gh` call honours it too, not just the host that "
+                    "observed the 403."
+                ),
+                "requestBody": {
+                    "required": True,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "type": "object",
+                                "properties": {
+                                    "reason": {"type": "string"},
+                                    "status": {"type": "integer", "nullable": True},
+                                    "request_id": {"type": "string", "nullable": True},
+                                    "retry_after_s": {"type": "number", "nullable": True},
+                                },
+                                "required": ["reason"],
+                            }
+                        }
+                    },
+                },
+                "responses": {
+                    "200": {"description": "OK"},
+                    "400": {"description": "Missing field: reason"},
+                },
+            },
+        },
         "/issue-comments": {
             "get": {
                 "summary": "#873: read an issue's captured comments (oldest-first) from the durable mirror",
@@ -7730,6 +7773,47 @@ def build_app(store: CoordStore, config: Config, *, token: str | None = None) ->
         else:
             return JSONResponse({"error": f"unknown action: {action!r}"}, status_code=400)
 
+    async def get_github_backoff(request: Request) -> Response:  # noqa: ARG001
+        # #2934: the daemon's own view of the shared GitHub rate-limit
+        # backoff — ALWAYS the local-only file (coord.github_throttle.
+        # current()), never routed back out over HTTP, for the same reason
+        # get_pause() above never routes: this endpoint runs *inside* the
+        # daemon, the one host whose file a fleet-wide `consult()` call is
+        # actually asking about, and whose own `gh` calls already read that
+        # exact file directly with no HTTP round trip of their own.
+        from coord.github_throttle import current  # noqa: PLC0415
+
+        b = current()
+        return JSONResponse({"backoff": b._asdict() if b is not None else None})
+
+    async def post_github_backoff(request: Request) -> Response:
+        # #2934: record a rate-limit hit into the daemon's shared backoff
+        # file — the fleet-wide half of #2809. See get_github_backoff()
+        # above for why this always uses the local-only writer: one host
+        # publishes the hit once, here, and every OTHER host's next
+        # `consult()` GETs it back via get_github_backoff() above.
+        from coord.github_throttle import current, local_record  # noqa: PLC0415
+
+        body = await _read_json(request)
+        if body is None:
+            return JSONResponse({"error": "invalid JSON body"}, status_code=400)
+        reason = body.get("reason")
+        if not reason or not isinstance(reason, str):
+            return JSONResponse({"error": "missing field: reason"}, status_code=400)
+        status = body.get("status")
+        request_id = body.get("request_id")
+        retry_after_s = body.get("retry_after_s")
+        local_record(
+            reason=reason,
+            status=status if isinstance(status, int) else None,
+            request_id=request_id if isinstance(request_id, str) else None,
+            retry_after_s=(
+                float(retry_after_s) if isinstance(retry_after_s, (int, float)) else None
+            ),
+        )
+        b = current()
+        return JSONResponse({"backoff": b._asdict() if b is not None else None})
+
     async def get_issue_comments(request: Request) -> Response:
         # #873: read an issue's captured comments (oldest-first) from the
         # durable mirror.
@@ -9668,6 +9752,8 @@ def build_app(store: CoordStore, config: Config, *, token: str | None = None) ->
         Route("/drive-queue", post_drive_queue, methods=["POST"]),
         Route("/pause", get_pause, methods=["GET"]),
         Route("/pause", post_pause, methods=["POST"]),
+        Route("/github-backoff", get_github_backoff, methods=["GET"]),
+        Route("/github-backoff", post_github_backoff, methods=["POST"]),
         Route("/issue-comments", get_issue_comments, methods=["GET"]),
         Route("/issue-comments", post_issue_comments, methods=["POST"]),
         Route("/merge", post_merge, methods=["POST"]),

{code_coordinator-0.5.293 → code_coordinator-0.5.294}/tests/test_github_throttle.py

@@ -1,5 +1,5 @@
 """Tests for coord.github_throttle (#2809: the shared per-machine GitHub
-rate-limit backoff state).
+rate-limit backoff state; #2934: made fleet-wide via the board daemon).
 
 Scope: the module is a small, best-effort, file-backed signal — record a
 hit, consult it before the next call, never shrink an active window, never
@@ -7,14 +7,27 @@ raise into a caller regardless of what the on-disk state looks like. The
 `tests/conftest.py` autouse `_no_real_github_backoff_store` fixture already
 redirects every test's `$COORD_GITHUB_BACKOFF_STATE` to a private tmp file,
 so these tests never touch the operator's real `~/.coord/github_backoff.json`.
+
+Every test above `TestDaemonRouting` runs with no board service configured
+(the default), so `record()`/`consult()` exercise exactly the same local-file
+code path their pre-#2934 counterparts — `local_record()`/`local_consult()` —
+always did; #2934 only added a daemon-first branch in front of it.
+`TestDaemonRouting` below is the unit-level coverage for THAT branch (mocking
+`coord.board_service.resolve()` and the `coord.client` transport functions,
+same pattern as `tests/test_machine_pause.py`'s `_remote()` helper); the full
+cross-process round trip through a real daemon app — one host's `record()`
+observed by another host's `consult()` — is covered separately in
+`tests/test_serve.py::test_github_backoff_recorded_on_one_host_is_honoured_by_another`.
 """
 
 from __future__ import annotations
 
 import json
 
+import httpx
 import pytest
 
+from coord import client as coord_client
 from coord import github_throttle
 
 
@@ -186,3 +199,132 @@ class TestStatePathOverride:
         assert data["request_id"] == "req-1"
         assert data["retry_after_s"] == 42.0
         assert data["until"] == pytest.approx(542.0)
+
+
+# ── #2934: daemon-aware routing ─────────────────────────────────────────────
+#
+# `record()`/`consult()` route through the board daemon when one is
+# configured (thin client), following the same daemon-aware pattern
+# `coord.machine_pause` established for pause/quiet-hours/cordons. These
+# tests cover the unit-level routing decision in isolation — see the module
+# docstring for where the real cross-process round trip lives.
+
+
+def _remote(monkeypatch, url: str = "http://daemon:7435") -> None:
+    """Make `coord.board_service.resolve()` (and therefore github_throttle's
+    daemon-aware functions) act as a thin client pointed at *url* — same
+    helper `tests/test_machine_pause.py` uses for the identical seam."""
+    monkeypatch.setattr(
+        coord_client, "resolve_board_service",
+        lambda *a, **k: coord_client.ServiceConfig(url=url),
+    )
+
+
+class TestDaemonRouting:
+    def test_record_posts_to_the_daemon_instead_of_the_local_file(
+        self, monkeypatch, tmp_path
+    ) -> None:
+        _remote(monkeypatch)
+        posted = {}
+
+        def _fake_post(svc, **kwargs):
+            posted["url"] = svc.url
+            posted.update(kwargs)
+            return {"backoff": None}
+
+        monkeypatch.setattr(coord_client, "post_github_backoff", _fake_post)
+
+        github_throttle.record(
+            reason="secondary_rate_limit", status=403,
+            request_id="req-1", retry_after_s=120.0,
+        )
+        assert posted == {
+            "url": "http://daemon:7435",
+            "reason": "secondary_rate_limit", "status": 403,
+            "request_id": "req-1", "retry_after_s": 120.0,
+        }
+        # Never fell through to the local file.
+        assert github_throttle.current() is None
+
+    def test_record_falls_back_to_the_local_file_when_the_daemon_is_unreachable(
+        self, monkeypatch
+    ) -> None:
+        _remote(monkeypatch)
+
+        def _raise(*_a, **_k):
+            raise httpx.ConnectError("refused")
+
+        monkeypatch.setattr(coord_client, "post_github_backoff", _raise)
+
+        # Must not raise -- record() is unconditionally best-effort, daemon
+        # routing included (module docstring: "damping must never become a
+        # new way to break `gh` access").
+        github_throttle.record(
+            reason="secondary_rate_limit", status=403,
+            request_id=None, retry_after_s=90.0, now=1000.0,
+        )
+        b = github_throttle.current(now=1000.0)
+        assert b is not None
+        assert b.until == pytest.approx(1090.0)
+
+    def test_consult_asks_the_daemon_when_remote(self, monkeypatch) -> None:
+        _remote(monkeypatch)
+        monkeypatch.setattr(
+            coord_client, "fetch_github_backoff",
+            lambda svc, **k: {
+                "until": 1120.0, "reason": "secondary_rate_limit", "status": 403,
+                "request_id": "remote-hit", "retry_after_s": 120.0, "recorded_at": 1000.0,
+            },
+        )
+        sleep_s, backoff = github_throttle.consult(now=1002.0)
+        assert backoff is not None
+        assert backoff.request_id == "remote-hit"
+        # 118s remaining, capped at MAX_PRECALL_SLEEP_S +/- jitter.
+        assert sleep_s <= github_throttle.MAX_PRECALL_SLEEP_S * 1.25
+        # Never touched the local file to answer this.
+        assert github_throttle.current() is None
+
+    def test_consult_reports_no_backoff_when_the_daemon_has_none(self, monkeypatch) -> None:
+        _remote(monkeypatch)
+        monkeypatch.setattr(coord_client, "fetch_github_backoff", lambda svc, **k: None)
+        sleep_s, backoff = github_throttle.consult(now=1000.0)
+        assert sleep_s == 0.0
+        assert backoff is None
+
+    def test_consult_falls_back_to_the_local_file_when_the_daemon_is_unreachable(
+        self, monkeypatch
+    ) -> None:
+        """The other three hosts must still honour their OWN last-known
+        local state when the shared daemon can't be reached -- never 'no
+        damping' just because the network blipped."""
+        _remote(monkeypatch)
+
+        def _raise(*_a, **_k):
+            raise httpx.ConnectError("refused")
+
+        monkeypatch.setattr(coord_client, "fetch_github_backoff", _raise)
+
+        # Seed the LOCAL file directly (bypassing record(), which would also
+        # try the daemon) to isolate consult()'s own fallback.
+        github_throttle.local_record(
+            reason="secondary_rate_limit", status=403,
+            request_id=None, retry_after_s=60.0, now=1000.0,
+        )
+        sleep_s, backoff = github_throttle.consult(now=1002.0)
+        assert backoff is not None
+        assert backoff.until == pytest.approx(1060.0)
+
+    def test_consult_treats_a_malformed_daemon_response_as_no_backoff(
+        self, monkeypatch
+    ) -> None:
+        """A successful GET carrying junk (not an exception) reads as 'no
+        backoff' -- same fail-open posture `_read()` already has for a
+        corrupt local file -- rather than falling back to the local file,
+        which the daemon DID successfully answer for."""
+        _remote(monkeypatch)
+        monkeypatch.setattr(
+            coord_client, "fetch_github_backoff", lambda svc, **k: {"not": "a backoff"},
+        )
+        sleep_s, backoff = github_throttle.consult(now=1000.0)
+        assert sleep_s == 0.0
+        assert backoff is None