code-coordinator 0.5.452__tar.gz → 0.5.454__tar.gz

{code_coordinator-0.5.452 → code_coordinator-0.5.454}/PKG-INFO

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.452
+Version: 0.5.454
 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.452 → code_coordinator-0.5.454}/code_coordinator.egg-info/SOURCES.txt

@@ -657,6 +657,7 @@ tests/test_health_unit_drift.py
 tests/test_health_unit_enablement.py
 tests/test_health_wedged_drive_queue.py
 tests/test_hooks.py
+tests/test_housekeeping.py
 tests/test_human_attended_437.py
 tests/test_init.py
 tests/test_install_agent_venv_2911.py

{code_coordinator-0.5.452 → code_coordinator-0.5.454}/code_coordinator.egg-info/scm_file_list.json

@@ -683,6 +683,7 @@
     "tests/test_health_unit_enablement.py",
     "tests/test_health_wedged_drive_queue.py",
     "tests/test_hooks.py",
+    "tests/test_housekeeping.py",
     "tests/test_human_attended_437.py",
     "tests/test_init.py",
     "tests/test_install_agent_venv_2911.py",

{code_coordinator-0.5.452 → code_coordinator-0.5.454}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.452",
+  "tag": "0.5.454",
   "distance": 0,
-  "node": "g69efb323ff5ace2c8783a4e3eb8deb0b37b5aff0",
+  "node": "ga4a99bfd3ea79dd343b5828974ef637592ae4897",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-11"

{code_coordinator-0.5.452 → code_coordinator-0.5.454}/coord/dao.py

@@ -78,6 +78,7 @@ from __future__ import annotations
 import json
 import os
 import sqlite3
+import threading
 import time
 from contextlib import closing
 from pathlib import Path
@@ -186,6 +187,9 @@ class CoordStore(Protocol):
     def get_assignment(self, assignment_id: str) -> dict | None: ...
     def get_issue(self, repo_name: str, number: int) -> dict | None: ...
 
+    # ── change detection (#3294) ────────────────────────────────────────────
+    def change_token(self) -> str: ...
+
 
 def compute_board_keep_ids(
     assignment_index: list[dict],
@@ -305,10 +309,28 @@ class SqliteStore:
     pooling under real load) and never migrates the DB. ``board_projection``
     opens a single connection so the whole payload is one consistent
     snapshot.
+
+    ``change_token()`` (#3294) is the one exception to "fresh connection per
+    call": ``PRAGMA data_version`` is relative to the connection that reads
+    it — a brand-new SQLite connection always reports the same baseline
+    value no matter how many *other* connections have committed writes
+    before it opened, and only starts advancing once IT has observed a
+    change. So the cheap "did anything write?" signal only works against a
+    connection this store keeps open across calls; see ``_change_conn``
+    below and ``change_token``'s docstring.
     """
 
     def __init__(self, db_path: Path | str | None = None) -> None:
         self._path = Path(db_path) if db_path is not None else DB_PATH
+        # #3294: lazily-opened, kept-open connection dedicated to
+        # `change_token()` — see the class docstring for why this one
+        # connection is the exception to "fresh connection per call".
+        # Guarded by `_change_lock` because it is shared between the event
+        # loop thread (the /board handler's initial freshness check) and a
+        # threadpool worker (the same handler's rebuild leader) — see
+        # coord.serve_app's board().
+        self._change_conn: Any = None
+        self._change_lock = threading.Lock()
 
     # ── connection ────────────────────────────────────────────────────────────
     def _connect(self) -> Any:
@@ -576,3 +598,77 @@ class SqliteStore:
                 # retention cap; `after_json` arrives decoded as a real list.
                 "drive_queue": self._table(conn, "drive_queue", order="position"),
             }
+
+    # ── change detection (#3294) ────────────────────────────────────────────
+    def _open_change_conn(self) -> Any:
+        conn = sql.connect(
+            backend=sql.DIALECT_SQLITE,
+            sqlite_path=self._path,
+            read_only=True,
+            check_same_thread=False,
+        )
+        sql.apply_row_factory(conn)
+        sql.apply_connection_setup(conn, read_only=True)
+        return conn
+
+    def change_token(self) -> str:
+        """A cheap, opaque "has anything been written since I last asked?" token.
+
+        Backs the ``/board`` read path's cache invalidation in
+        ``coord.serve_app`` (the board() handler's cache block): a 1.5 s TTL
+        forced a full board rebuild on essentially every poll even when
+        nothing had changed, because pollers run at 5 s and always missed the
+        window. This token replaces "younger than N seconds" with "no write
+        since this build" as the PRIMARY trigger -- the TTL survives only as
+        a safety upper bound (see serve_app.py) in case this token's source
+        ever misses a write path.
+
+        SQLite: :func:`coord.sql.sqlite_data_version` (``PRAGMA
+        data_version``, spelled in the dialect seam rather than here --
+        ``PRAGMA`` is SQLite-only statement text and ``coord/sql.py`` is the
+        one module allowed to name one, #2782/#1948), which changes whenever
+        ANY connection -- not just this process's own POSTs, but the
+        drive-queue timer and a concurrent ``coord notify`` writing locally
+        too -- commits to the database file. **Unlike every other read in
+        this class, this is NOT a fresh connection per call**: ``data_version``
+        is relative to the connection that reads it, and a brand-new
+        connection always reports the same baseline value regardless of how
+        many other connections committed before it opened -- it only starts
+        advancing once it has personally observed a change. So this method
+        reuses one connection (``_change_conn``, opened lazily, guarded by
+        ``_change_lock`` since it's shared between the event loop thread and
+        a threadpool worker -- see ``coord.serve_app.board()``) across every
+        call for the life of this ``SqliteStore``. See
+        https://sqlite.org/pragma.html#pragma_data_version. A failure (e.g.
+        the connection went stale) reopens once and, failing that, propagates
+        -- callers must treat any exception here as "assume changed, rebuild"
+        rather than crash the read path over a cache optimization.
+
+        Postgres (#827's in-flight lane): TODO(#3294-pg) -- ``data_version``
+        has no Postgres equivalent. A ``board_revision`` sequence bumped at
+        each write choke point (the ``_*_local()`` family in
+        ``coord/state.py``) or a ``LISTEN``/``NOTIFY`` channel are the two
+        candidates the issue names; until one lands, this returns a constant
+        so two calls always compare equal and the cache degrades to
+        "TTL-only" -- exactly today's (pre-#3294) behaviour -- rather than
+        silently caching forever or rebuilding on every request.
+        """
+        target = db_mod._resolve_store_target()
+        if target.backend == sql.DIALECT_POSTGRES:
+            return "pg-change-token-unimplemented"  # TODO(#3294-pg)
+        with self._change_lock:
+            if self._change_conn is None:
+                self._change_conn = self._open_change_conn()
+            try:
+                return sql.sqlite_data_version(self._change_conn)
+            except Exception:  # noqa: BLE001 — reopen-once fallback, see below
+                # Stale/broken connection (e.g. the underlying file was
+                # replaced out from under us) — reopen once. A repeat
+                # failure propagates to the caller, which treats it as
+                # "assume changed" rather than serving a false cache hit.
+                try:
+                    self._change_conn.close()
+                except Exception:  # noqa: BLE001 — already broken, best effort
+                    pass
+                self._change_conn = self._open_change_conn()
+                return sql.sqlite_data_version(self._change_conn)

{code_coordinator-0.5.452 → code_coordinator-0.5.454}/coord/health/checks/fleet_board.py

@@ -7,6 +7,16 @@ Like the other fleet checks in this package, the daemon's ``/board`` handler
 (``coord.serve_app``) is the thing that actually measures its own latency and
 serialized body size on each rebuild; this probe only judges the numbers it's
 handed.
+
+#3294 added a third, advisory-only number: how many rebuilds actually
+*published* in the last 60s (``board_builds_per_minute`` on ``daemon_host``,
+tracked by ``FleetHealthRefresher.record_board_stats``). The ``/board`` cache
+used to rebuild on a fixed 1.5s TTL regardless of whether anything had
+written — pollers run at 5s, so that meant a rebuild on nearly every poll.
+The cache's primary trigger is now "a write happened" (``dao.CoordStore.
+change_token``); this field is what makes that claim measurable rather than
+assumed. Never affects severity — a burst of real writes legitimately drives
+it up.
 """
 
 from __future__ import annotations
@@ -41,6 +51,13 @@ def probe_board_latency(ctx: HealthContext) -> CheckResult:
     dh = ctx.fleet.daemon_host or {}
     latency_ms = dh.get("board_latency_ms")
     payload_bytes = dh.get("board_payload_bytes")
+    # #3294: how many /board REBUILDS (not requests) published in the last
+    # 60s — the direct measurement of whether the write-triggered cache
+    # (dao.CoordStore.change_token, replacing the old 1.5s TTL) is actually
+    # cutting rebuilds, rather than an assumption. Advisory only: absent on
+    # an older daemon that hasn't published a build yet, and never affects
+    # severity below — a burst of real writes legitimately drives this up.
+    builds_per_minute = dh.get("board_builds_per_minute")
 
     if latency_ms is None and payload_bytes is None:
         return CheckResult(
@@ -72,6 +89,8 @@ def probe_board_latency(ctx: HealthContext) -> CheckResult:
         parts.append(f"{latency_ms:.0f}ms")
     if payload_bytes is not None:
         parts.append(human_bytes(payload_bytes))
+    if builds_per_minute is not None:
+        parts.append(f"{builds_per_minute} build/min")
     headroom = " / ".join(parts) if parts else "no data"
     if severity is not Severity.OK:
         headroom += f" ({', '.join(reasons)})"
@@ -85,5 +104,9 @@ def probe_board_latency(ctx: HealthContext) -> CheckResult:
             f"warn at {human_bytes(_PAYLOAD_WARN_BYTES)}/{_LATENCY_WARN_MS:.0f}ms, "
             f"crit at {human_bytes(_PAYLOAD_CRIT_BYTES)}/{_LATENCY_CRIT_MS:.0f}ms"
         ),
-        values={"latency_ms": latency_ms, "payload_bytes": payload_bytes},
+        values={
+            "latency_ms": latency_ms,
+            "payload_bytes": payload_bytes,
+            "builds_per_minute": builds_per_minute,
+        },
     )

{code_coordinator-0.5.452 → code_coordinator-0.5.454}/coord/health/fleet_snapshot.py

@@ -39,6 +39,7 @@ import json
 import logging
 import os
 import time
+from collections import deque
 from dataclasses import dataclass, field
 from pathlib import Path
 
@@ -276,6 +277,13 @@ class FleetHealthRefresher:
         # than fabricating a 0.
         self._board_latency_ms: float | None = None
         self._board_payload_bytes: int | None = None
+        # #3294: one timestamp per PUBLISHED /board build (never per request
+        # — a cache hit or a 304 doesn't rebuild, so it doesn't append here).
+        # This is the daemon-side, directly-measured answer to "did #3294's
+        # write-triggered cache actually cut rebuilds?", rather than an
+        # assumption — see `_builds_per_minute` and `probe_board_latency`
+        # (coord/health/checks/fleet_board.py).
+        self._board_build_timestamps: deque[float] = deque()
 
     def snapshot(self) -> FleetHealthSnapshot:
         return self._snapshot
@@ -284,12 +292,31 @@ class FleetHealthRefresher:
         """Called by the /board handler after each publish (#1630/#1597).
 
         Deliberately NOT I/O and NOT gated on the tick cadence — recording a
-        float+int is free, and the alternative (recomputing board latency
-        independently from this refresher) would mean building a whole
-        second board just to measure it, defeating the point of the check.
+        float+int (+ one timestamp, #3294) is free, and the alternative
+        (recomputing board latency independently from this refresher) would
+        mean building a whole second board just to measure it, defeating the
+        point of the check.
         """
         self._board_latency_ms = latency_ms
         self._board_payload_bytes = payload_bytes
+        self._board_build_timestamps.append(time.time())
+        self._prune_build_timestamps()
+
+    def _prune_build_timestamps(self, now: float | None = None) -> None:
+        """Drop build timestamps older than 60s — #3294's rolling window."""
+        cutoff = (now if now is not None else time.time()) - 60.0
+        timestamps = self._board_build_timestamps
+        while timestamps and timestamps[0] < cutoff:
+            timestamps.popleft()
+
+    def _builds_per_minute(self, now: float) -> int:
+        """#3294: how many /board REBUILDS (not requests) published in the
+        last 60s — the direct measurement backing the write-triggered
+        cache's whole premise ("rebuilds should track writes, not a 5s poll
+        clock"). Read by `refresh()` below into ``daemon_host`` for
+        ``fleet_board_latency`` (coord/health/checks/fleet_board.py)."""
+        self._prune_build_timestamps(now)
+        return len(self._board_build_timestamps)
 
     def refresh(self, config) -> FleetHealthSnapshot:  # noqa: ANN001 — coord.config.Config
         from coord import network, state  # noqa: PLC0415
@@ -376,6 +403,7 @@ class FleetHealthRefresher:
         daemon_host["phantom_running"] = self._phantom_running_rows(machines)
         daemon_host["board_latency_ms"] = self._board_latency_ms
         daemon_host["board_payload_bytes"] = self._board_payload_bytes
+        daemon_host["board_builds_per_minute"] = self._builds_per_minute(now)
         # #2858: per-repo issues-sync staleness — a small local JSON read
         # (coord.issues_sync_status), same "daemon-host-local fact" shape as
         # the two lines above. `coord.health.checks.issues_sync_staleness`

{code_coordinator-0.5.452 → code_coordinator-0.5.454}/coord/housekeeping.py

@@ -41,6 +41,30 @@ is wired in too, reclaiming ``~/.coord/confirm-worktrees/`` entries that
 outlived ``confirm_branch``'s own per-run cleanup. That is disk hygiene, not
 DB archiving, but reusing this sweep's cadence beats inventing a second timer
 for a second maintenance job.
+
+#3296: the same sweep also archives two tables #1107/#762 never reached —
+both ~800 KB of every ``/board`` poll with no retention policy at all, per a
+live-fleet sample that found 1,114 ``drive_queue`` rows all ``state=done``
+and 13 of 14 ``plans`` rows belonging to assignments no longer on the board:
+
+* terminal ``drive_queue`` rows (:data:`coord.drive_queue.TERMINAL_QUEUE_STATES`
+  — the same "is this queue entry terminal" answer the tick processor itself
+  uses, not a second definition) older than the retention window ->
+  ``drive_queue_archive``. Age is read off the row's own last-touched
+  timestamp (``reason_at`` if the row was ever updated post-launch, else
+  ``launched_at``, else ``enqueued_at``) — the same fallback chain
+  ``merge_queue``'s ``last_attempt or enqueued_at`` uses just below.
+* ``plans`` rows whose ``assignment_id`` no longer appears in the live
+  ``assignments`` table (i.e. that assignment has itself already been
+  archived — by this sweep or an earlier one) -> ``plans_archive``. A plan
+  can only orphan once its assignment ages out, which already implies it is
+  past the retention window, so no separate cutoff is needed for ``plans``.
+
+Both move via the same ``_move_rows``/``_ensure_archive_mirror`` machinery
+above — move-not-delete, dumb-mirror archive tables — so ``GET
+/drive-queue?state=...`` can still retrieve archived history (see
+``coord.serve_app``) and nothing is ever unreachable, only un-shipped by
+default from the live table / board projection.
 """
 
 from __future__ import annotations
@@ -71,6 +95,10 @@ _NOTIFICATIONS_ARCHIVE = "notifications_archive"
 _MERGE_QUEUE = "merge_queue"
 _MERGE_QUEUE_ARCHIVE = "merge_queue_archive"
 _MERGE_QUEUE_MERGED_STATE = "merged"
+_DRIVE_QUEUE = "drive_queue"
+_DRIVE_QUEUE_ARCHIVE = "drive_queue_archive"
+_PLANS = "plans"
+_PLANS_ARCHIVE = "plans_archive"
 _BATCH = 400  # keep IN(...) clauses well under SQLite's 999-variable limit
 
 
@@ -148,20 +176,27 @@ def _move_rows(
 
 def sweep(*, dry_run: bool = False, now: float | None = None) -> dict:
     """Archive stale terminal assignments + their notifications + merged
-    merge_queue entries, and reclaim leaked confirm-worktree directories.
+    merge_queue entries + terminal drive_queue rows + orphaned plans, and
+    reclaim leaked confirm-worktree directories.
 
     Returns ``{"archived_assignments": N, "archived_notifications": M,
-    "archived_merge_queue": K, "removed_confirm_worktrees": W, "dry_run": bool,
-    "retention_days": D}``. ``archived_*``/``removed_confirm_worktrees`` are
-    the counts that were (or, for ``dry_run``, would be) moved/deleted.  A
-    no-op returns zeros.
+    "archived_merge_queue": K, "archived_drive_queue": Q, "archived_plans": P,
+    "removed_confirm_worktrees": W, "dry_run": bool, "retention_days": D}``.
+    ``archived_*``/``removed_confirm_worktrees`` are the counts that were (or,
+    for ``dry_run``, would be) moved/deleted.  A no-op returns zeros.
 
     Conservative by construction: nothing active, recent (within the archive
     window), queued-for-merge, latest-of-an-open-issue, or review-linked to any
     such row is ever moved. Merge queue entries are archived only once they
     are in the terminal ``MERGED`` state (#1107 Part 3) — non-terminal /
     conflicted entries are left for ``prune_stale_queue_entries`` or manual
-    ``coord merge --drop``.
+    ``coord merge --drop``. Drive-queue entries are archived only once they
+    are in a :data:`coord.drive_queue.TERMINAL_QUEUE_STATES` state AND older
+    than the retention window (#3296) — a fresh ``done``/``blocked``/
+    ``failed`` row stays put until it ages out, same as everything else this
+    sweep touches. ``plans`` rows follow their assignment: once an
+    assignment_id no longer appears in the live ``assignments`` table, its
+    plan is orphaned and moves too.
 
     #2974: ``removed_confirm_worktrees`` is independent of the DB-archiving
     ``cutoff``/``retention_days`` above (it has its own, much shorter,
@@ -179,6 +214,8 @@ def sweep(*, dry_run: bool = False, now: float | None = None) -> dict:
         "archived_assignments": 0,
         "archived_notifications": 0,
         "archived_merge_queue": 0,
+        "archived_drive_queue": 0,
+        "archived_plans": 0,
         "removed_confirm_worktrees": len(swept_worktrees["removed"]),
         "dry_run": dry_run,
         "retention_days": _archive_retention_days(),
@@ -240,10 +277,47 @@ def sweep(*, dry_run: bool = False, now: float | None = None) -> dict:
         )
     ]
 
+    # #3296: terminal drive_queue rows past the retention window. Reuses
+    # `coord.drive_queue.TERMINAL_QUEUE_STATES` — the same "is this queue
+    # entry terminal" the tick processor itself answers — rather than a
+    # second, driftable definition here.
+    from coord.drive_queue import TERMINAL_QUEUE_STATES  # noqa: PLC0415
+
+    dq_rows = sql.execute(
+        conn,
+        "SELECT id, state, reason_at, launched_at, enqueued_at "  # noqa: S608
+        f"FROM {_DRIVE_QUEUE}",
+    ).fetchall()
+    dq_candidates = [
+        r["id"]
+        for r in dq_rows
+        if (r["state"] or "").lower() in TERMINAL_QUEUE_STATES
+        and (r["reason_at"] or r["launched_at"] or r["enqueued_at"] or 0) < cutoff
+    ]
+
+    # #3296: `plans` rows whose assignment is no longer in the live
+    # `assignments` table — orphaned either by the archiving just computed
+    # above, or by an earlier sweep (run before this feature existed, hence
+    # the live fleet's 13-of-14-orphaned sample). No separate cutoff: a plan
+    # can only orphan once its assignment ages out, which already implies
+    # it's past the retention window.
+    live_assignment_ids = {r["assignment_id"] for r in index} - candidate_set
+    plan_candidates = [
+        r["assignment_id"]
+        for r in sql.execute(
+            conn, f"SELECT assignment_id FROM {_PLANS}"  # noqa: S608
+        ).fetchall()
+        if r["assignment_id"] and r["assignment_id"] not in live_assignment_ids
+    ]
+
     result["archived_assignments"] = len(candidates)
     result["archived_notifications"] = len(notif_ids)
     result["archived_merge_queue"] = len(mq_merged_ids)
-    if dry_run or (not candidates and not notif_ids and not mq_merged_ids):
+    result["archived_drive_queue"] = len(dq_candidates)
+    result["archived_plans"] = len(plan_candidates)
+    if dry_run or not (
+        candidates or notif_ids or mq_merged_ids or dq_candidates or plan_candidates
+    ):
         return result
 
     with conn:
@@ -259,4 +333,8 @@ def sweep(*, dry_run: bool = False, now: float | None = None) -> dict:
             _move_rows(
                 conn, _MERGE_QUEUE, _MERGE_QUEUE_ARCHIVE, "assignment_id", mq_merged_ids
             )
+        if dq_candidates:
+            _move_rows(conn, _DRIVE_QUEUE, _DRIVE_QUEUE_ARCHIVE, "id", dq_candidates)
+        if plan_candidates:
+            _move_rows(conn, _PLANS, _PLANS_ARCHIVE, "assignment_id", plan_candidates)
     return result

{code_coordinator-0.5.452 → code_coordinator-0.5.454}/coord/serve_app.py

@@ -4800,7 +4800,11 @@ def openapi_spec() -> dict:
                 "summary": (
                     "#1753: read the operator-declared `coord drive` work "
                     "queue in run order. Filter by repo_name (+ optional "
-                    "issue_number); omit both to list the whole queue."
+                    "issue_number); omit both to list the whole queue. "
+                    "#3296: an explicit `state` also pulls in matching rows "
+                    "`coord.housekeeping.sweep()` has since archived, so "
+                    "terminal history stays reachable after it ages out of "
+                    "the live table."
                 ),
                 "parameters": [
                     {
@@ -4811,6 +4815,16 @@ def openapi_spec() -> dict:
                         "name": "issue_number", "in": "query", "required": False,
                         "schema": {"type": "integer"},
                     },
+                    {
+                        "name": "state", "in": "query", "required": False,
+                        "schema": {"type": "string"},
+                        "description": (
+                            "#3296: filter by drive_queue.state (e.g. "
+                            "'done'/'blocked'/'failed'). When given, also "
+                            "reads drive_queue_archive so archived rows "
+                            "matching this state are still returned."
+                        ),
+                    },
                 ],
                 "responses": {
                     "200": {"description": "OK"},
@@ -5821,14 +5835,30 @@ def build_app(
 
     _machine_metrics_sampler = machine_metrics_sampler or MachineMetricsSampler()
 
-    # Short-TTL cache for the computed /board projection so burst polls from the
-    # TUI don't each pay the full board_projection + merge-plan + stage-projection
+    # Cache for the computed /board projection so burst polls from the TUI
+    # don't each pay the full board_projection + merge-plan + stage-projection
     # recomputation (~465-issue load measured in the issue). Keyed to nothing
-    # (one board per daemon instance). TTL controlled by COORD_BOARD_CACHE_TTL
-    # (default 1.5 s). Busted immediately on board-mutating POSTs so a user
-    # action is visible on the very next poll without waiting out the TTL.
+    # (one board per daemon instance).
+    #
+    # #3294: the cache's PRIMARY invalidation trigger is "has anything
+    # written since this build?" (``store.change_token()``, ``dao.CoordStore``
+    # protocol — SQLite: ``PRAGMA data_version``), not a fixed clock. A 1.5 s
+    # TTL forced a full rebuild on essentially every poll, because pollers
+    # run at 5 s and always missed the window — and the rebuild (the
+    # ``fleet_board_latency`` check's own 0.65-0.8 s measurement) is what
+    # actually held the GIL, not the wire cost the ETag already covers.
+    # ``COORD_BOARD_CACHE_TTL`` (default below) survives only as a SAFETY
+    # UPPER BOUND — a rebuild is forced past that age regardless of the
+    # change token, in case the token's source ever misses a write path —
+    # not as the primary trigger. Busted immediately on board-mutating POSTs
+    # (``_bust_board_cache``, unchanged by #3294) so a user action is visible
+    # on the very next poll without waiting on either signal.
     _board_cache: dict | None = None
     _board_cache_at: float = 0.0
+    # #3294: the ``store.change_token()`` value as of ``_board_cache``'s
+    # build. A poll is served from cache only when the CURRENT token still
+    # equals this one — i.e. nothing has written since.
+    _board_cache_token: str | None = None
     # #1597 Part 2: the fully-rendered JSON bytes for the currently-cached
     # build, shared verbatim by every response that serves ``_board_cache``
     # (a fresh build's own responses, every single-flight follower, and
@@ -6040,18 +6070,35 @@ def build_app(
         # config reloads prompt.
         _refresh_config()
 
-        # Part 2 (cache): serve a cached projection if it's still within the TTL.
-        # Burst polls (TUI polls every ~2 s) hit the cache; the real computation
-        # only runs once per TTL window.  Cache is busted immediately by the
-        # board-mutating POST handlers below so user actions are visible on the
-        # very next poll without waiting out the TTL.
+        # Part 2 (cache): serve the cached projection when nothing has
+        # written since it was built (#3294). Burst polls (TUI polls every
+        # ~2 s) hit the cache; the real computation only runs when a write
+        # actually happened. Cache is also busted immediately by the
+        # board-mutating POST handlers below so user actions are visible on
+        # the very next poll without waiting on either signal.
         import time as _time  # noqa: PLC0415
-        _ttl = float(os.getenv("COORD_BOARD_CACHE_TTL", "1.5"))
+        # Safety upper bound only (#3294) — see the comment on
+        # `_board_cache_token` above. Raised from the pre-#3294 1.5 s default
+        # now that the change-token check is the primary trigger.
+        _safety_ttl = float(os.getenv("COORD_BOARD_CACHE_TTL", "30"))
         _now = _time.monotonic()
         nonlocal _board_cache, _board_cache_at, _board_cache_built_at, _board_body
-        nonlocal _board_inflight
+        nonlocal _board_cache_token, _board_inflight
         _client_etag = request.headers.get("if-none-match")
 
+        # #3294: cheap "did anything write?" probe — see
+        # `dao.CoordStore.change_token`'s docstring. Run inline (not
+        # threadpooled) like `_refresh_config()`'s stat() just above: a
+        # single PRAGMA on an already-open connection, not I/O of the shape
+        # #1336 invariant 1 guards against. A failure here must never crash
+        # the read path over a cache optimization — treat it as "assume
+        # changed" (a sentinel that can never equal a real cached token) so
+        # the worst case is an extra rebuild, never a wedged/stale cache.
+        try:
+            _current_token: str | None = store.change_token()
+        except Exception:  # noqa: BLE001 — fail toward rebuilding, not crashing
+            _current_token = None
+
         def _respond(result: dict, etag: str | None, body: bytes | None) -> Response:
             if _client_etag and etag and _client_etag == etag:
                 # STILL identical to what the client holds — spare the wire
@@ -6076,7 +6123,18 @@ def build_app(
             _cached_etag = _board_etag
             _cached_at = _board_cache_at
             _cached_body = _board_body
-        if _cached is not None and (_now - _cached_at) < _ttl:
+            _cached_token = _board_cache_token
+        # #3294: fresh iff nothing wrote since this build (token still
+        # matches) AND we're inside the safety-TTL ceiling. `_cached_token
+        # is not None` rules out a `None == None` false match when either
+        # side came from a failed change_token() read (see above).
+        _fresh = (
+            _cached is not None
+            and _cached_token is not None
+            and _cached_token == _current_token
+            and (_now - _cached_at) < _safety_ttl
+        )
+        if _fresh:
             return _respond(_cached, _cached_etag, _cached_body)
 
         # #1597 Part 1: single-flight the rebuild.  On a cache miss, at most
@@ -6122,12 +6180,24 @@ def build_app(
         # concurrent request calls _refresh_config() while _build() is running.
         _cfg = config
 
-        def _build() -> tuple[float, dict]:
+        def _build() -> tuple[float, str | None, dict]:
             # Snapshot-order stamp: captured immediately before the DB read so
             # the publish step below can reject a build whose snapshot is
             # older than the one already cached (concurrent rebuilds can
             # finish out of order).
             _built_at = _time.monotonic()
+            # #3294: the change token AS OF this build's snapshot moment —
+            # published alongside the cache below so the *next* request's
+            # freshness check compares against "what had (or hadn't) written
+            # by the time THIS build started", not some later moment.
+            # `None` (never a real token — see `_current_token` above) if the
+            # read itself fails; that means the published cache below can
+            # never look "fresh" to a later poll, which is the safe direction
+            # to fail in.
+            try:
+                _built_token = store.change_token()
+            except Exception:  # noqa: BLE001 — see `_current_token` above
+                _built_token = None
             # ── board projection ──────────────────────────────────────────────
             try:
                 projection = store.board_projection()
@@ -6593,7 +6663,7 @@ def build_app(
             from coord.board_wire import bound_board_payload as _bound  # noqa: PLC0415
 
             _bound(projection)
-            return _built_at, projection
+            return _built_at, _built_token, projection
 
         # This coroutine is the single-flight leader: it alone runs _build(),
         # then fans its outcome out to every waiter (itself plus every
@@ -6601,7 +6671,7 @@ def build_app(
         # of the acceptance test, and why a failed build must reach every
         # waiter rather than wedging the followers.
         try:
-            built_at, result = await run_in_threadpool(_build)
+            built_at, built_token, result = await run_in_threadpool(_build)
         except _BoardReadError as e:
             _board_inflight = None  # clear FIRST: a retry must build fresh,
             # never see a "done" future and think it must wait on this one.
@@ -6650,7 +6720,9 @@ def build_app(
                     _board_body = body
                     _board_cache_at = _time.monotonic()
                     _board_cache_built_at = built_at
-                    # #1630: feed this build's own latency + wire size to the
+                    _board_cache_token = built_token  # #3294
+                    # #1630/#3294: feed this build's own latency + wire size
+                    # (+ the fact that a build happened at all) to the
                     # fleet-health snapshot's board-latency check — read back
                     # on the health-poll tick's own cadence, never recomputed
                     # inline (see FleetHealthRefresher.record_board_stats).
@@ -8687,9 +8759,16 @@ def build_app(
         # filters to that repo; `repo_name` + `issue_number` narrows to the (at
         # most one) entry for that issue; neither given lists the whole queue
         # (hand-sized by definition — one row per issue an operator queued).
+        #
+        # #3296: `?state=` additionally reads `drive_queue_archive` — the
+        # live table alone would silently lose a terminal entry the moment
+        # `coord.housekeeping.sweep()` ages it out, making archived history
+        # unreachable rather than merely un-shipped-by-default from the
+        # unfiltered list.
         from coord import state  # noqa: PLC0415
 
         repo_name = request.query_params.get("repo_name")
+        state_filter = request.query_params.get("state")
         raw_issue = request.query_params.get("issue_number")
         issue_number = None
         if raw_issue is not None:
@@ -8702,9 +8781,21 @@ def build_app(
         try:
             if repo_name and issue_number is not None:
                 entry = state._get_drive_queue_entry_local(repo_name, issue_number)
+                if entry is None and state_filter:
+                    entry = state._get_drive_queue_archive_entry_local(
+                        repo_name, issue_number
+                    )
+                if (
+                    entry is not None
+                    and state_filter
+                    and entry.get("state") != state_filter
+                ):
+                    entry = None
                 entries = [entry] if entry else []
             else:
-                entries = state._list_drive_queue_local(repo_name)
+                entries = state._list_drive_queue_local(
+                    repo_name, state=state_filter
+                )
         except Exception as e:  # noqa: BLE001
             return JSONResponse(
                 {"error": "drive-queue read failed", "detail": str(e)},