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

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

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

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

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

{code_coordinator-0.5.452 → code_coordinator-0.5.453}/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.453}/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.453}/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.453}/coord/serve_app.py

@@ -5821,14 +5821,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 +6056,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 +6109,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 +6166,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 +6649,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 +6657,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 +6706,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).

{code_coordinator-0.5.452 → code_coordinator-0.5.453}/coord/sql.py

@@ -1195,6 +1195,42 @@ def sqlite_integrity_check(conn: Any) -> str:
     return str(rows[0][0]) if rows else "<no output>"
 
 
+def sqlite_data_version(conn: Any) -> str:
+    """SQLite's ``PRAGMA data_version`` for *conn*, as an opaque string.
+
+    The value changes whenever **another** connection commits to the same
+    database file, which makes it a cheap "has anything been written since I
+    last looked?" signal — see :meth:`coord.dao.SqliteStore.change_token`,
+    its only caller, which backs the ``/board`` read path's write-driven
+    cache invalidation (#3294).
+
+    Two properties the caller depends on, both SQLite's, not this helper's:
+    the value is **relative to the connection that reads it** (a freshly
+    opened connection always reports the same baseline no matter how many
+    commits preceded it, and only starts advancing once *it* has observed a
+    change), so the caller must reuse one long-lived connection; and it does
+    **not** move for this connection's own writes. See
+    https://sqlite.org/pragma.html#pragma_data_version.
+
+    Lives here for the same reason :func:`sqlite_journal_mode`,
+    :func:`sqlite_wal_checkpoint_truncate` and :func:`sqlite_integrity_check`
+    do: ``PRAGMA`` is SQLite-only statement text with no Postgres equivalent
+    to translate to, and this module is the one place in the tree allowed to
+    spell one (enforced by ``tests/test_sql_dialect.py::
+    test_no_sqlite_only_construct_in_statement_text_outside_db_and_seam``).
+    SQLite-only: callers must already know *conn* is a SQLite connection —
+    this helper does not dialect-guard, matching the rest of that family.
+
+    An empty result (which real SQLite never produces, but a stubbed
+    connection in a test can) degrades to ``"0"``. That is a *constant*, so a
+    caller comparing two such tokens sees "unchanged" — callers that cannot
+    tolerate a false "unchanged" must treat an exception here as "assume
+    changed", which is what ``change_token``'s caller does.
+    """
+    row = execute(conn, "PRAGMA data_version").fetchone()
+    return str(row[0]) if row is not None else "0"
+
+
 def driver_error(conn: Any) -> type[BaseException]:
     """The DB-API ``Error`` base class *conn*'s driver raises (#2766).
 

{code_coordinator-0.5.452 → code_coordinator-0.5.453}/tests/test_board_read_path.py

@@ -186,6 +186,70 @@ def test_board_version_bumps_when_content_changes(
         assert r3.headers["etag"] != r1.headers["etag"]
 
 
+# ── #3294: the cache rebuilds on a write, not on a clock ─────────────────────
+
+
+def test_board_rebuild_trigger_is_a_write_not_the_ttl_clock(
+    detail_db: Path, valid_config_path: Path, monkeypatch
+) -> None:
+    """#3294 acceptance: two ``/board`` requests with NO intervening write
+    must produce exactly one ``board_projection()`` build, and a write
+    between them must force a second — asserted on a build counter, never on
+    timing (the issue's own words: "Timing-based assertions will be flaky —
+    count builds").
+
+    The write here is a RAW external SQLite commit — not a POST to
+    ``/board``, which already busted the cache explicitly and always did.
+    This is the case #3294 actually exists for: the drive-queue timer and a
+    concurrent ``coord notify`` write the DB directly, with no daemon POST
+    anywhere in the picture. Before #3294 a write from either of those
+    sources was invisible to the ``/board`` cache until its TTL (1.5 s by
+    default, pre-fix) happened to expire on its own. This test pins the
+    safety-TTL to a deliberately generous 60 s specifically so the *only*
+    thing that can explain the second build is the change-token check
+    noticing the external write — a TTL-only cache would still be showing
+    the stale, pre-write board at that point.
+    """
+    call_count = 0
+    original_projection = SqliteStore.board_projection
+
+    def counting_projection(self):  # noqa: ANN001
+        nonlocal call_count
+        call_count += 1
+        return original_projection(self)
+
+    monkeypatch.setattr(SqliteStore, "board_projection", counting_projection)
+    monkeypatch.setenv("COORD_BOARD_CACHE_TTL", "60")  # generous safety ceiling
+
+    cfg = load_config(valid_config_path)
+    app = build_app(SqliteStore(detail_db), cfg)
+    with TestClient(app) as cli:
+        r1 = cli.get("/board")
+        assert r1.status_code == 200
+        assert call_count == 1
+
+        r2 = cli.get("/board")
+        assert r2.status_code == 200
+        assert call_count == 1, "no write happened — must still be exactly one build"
+
+        # A write from OUTSIDE the daemon entirely: no POST /board, no
+        # `_bust_board_cache()` call — the drive-queue-timer / `coord notify`
+        # shape the issue names.
+        conn = sqlite3.connect(str(detail_db))
+        conn.execute(
+            "UPDATE assignments SET status='failed' WHERE assignment_id='work1'"
+        )
+        conn.commit()
+        conn.close()
+
+        r3 = cli.get("/board")
+        assert r3.status_code == 200
+        assert call_count == 2, (
+            "an external write must trigger a rebuild via the change token, "
+            "well before the 60s safety TTL elapses"
+        )
+
+
 def test_board_digest_projection_masks_only_the_named_volatile_fields() -> None:
     """#3293 unit-level check on ``_board_digest_projection`` itself: the
     three named culprits (``audit_recent_count``, ``issues[*].synced_at``,
@@ -420,12 +484,22 @@ def test_stale_concurrent_rebuild_is_never_published(
 
     monkeypatch.setenv("COORD_BOARD_CACHE_TTL", "1000")  # cache once published
 
+    # #3294: `_build()` is faked below (it never touches the real store), so
+    # pin `store.change_token()` to a fixed value too — otherwise the
+    # handler's real (unmocked) freshness check would compare the fake
+    # build's canned token against the REAL store's live `PRAGMA
+    # data_version` and never see a match, breaking the cache-hit path this
+    # test relies on for its final 304. Irrelevant to what this test
+    # actually exercises (out-of-order publish, not change detection).
+    store = SqliteStore(detail_db)
+    monkeypatch.setattr(store, "change_token", lambda: "fixed-token")
+
     # Deterministic out-of-order completion: the first request's build
     # carries a NEWER snapshot stamp than the second's (as if the second
     # started earlier but finished later).
     results = iter([
-        (100.0, {"round_number": 1, "marker": "NEW"}),
-        (50.0, {"round_number": 1, "marker": "STALE"}),
+        (100.0, "fixed-token", {"round_number": 1, "marker": "NEW"}),
+        (50.0, "fixed-token", {"round_number": 1, "marker": "STALE"}),
     ])
 
     async def _fake_run_in_threadpool(fn, *args):  # noqa: ANN001, ARG001
@@ -434,7 +508,7 @@ def test_stale_concurrent_rebuild_is_never_published(
     monkeypatch.setattr(sc, "run_in_threadpool", _fake_run_in_threadpool)
 
     cfg = load_config(valid_config_path)
-    app = build_app(SqliteStore(detail_db), cfg)
+    app = build_app(store, cfg)
     with TestClient(app) as cli:
         r1 = cli.get("/board")
         assert r1.json()["marker"] == "NEW"

{code_coordinator-0.5.452 → code_coordinator-0.5.453}/tests/test_sql_dialect.py

@@ -542,6 +542,64 @@ def test_sqlite_integrity_check_degrades_to_a_placeholder_on_an_empty_result(mon
     assert sql.sqlite_integrity_check(object()) == "<no output>"
 
 
+# ── change detection: sqlite_data_version (#3294) ────────────────────────
+#
+# The /board read path's write-driven cache invalidation calls this instead
+# of spelling `PRAGMA data_version` in coord/dao.py, where the SQLite-only
+# statement-text ratchet below would (correctly) reject it.
+
+
+def test_sqlite_data_version_advances_when_another_connection_commits(tmp_path):
+    """The property #3294's cache depends on: the token MOVES on somebody
+    else's commit, and holds still when nobody writes.
+
+    Both halves matter and neither implies the other — a helper that returned
+    a fresh constant every call would pass "it changed" while making the
+    cache useless, and one that returned a hardcoded constant would pass "it
+    held still" while making the cache serve stale boards forever. Driven
+    through two real connections on a file DB because that *is* the semantics
+    under test: `PRAGMA data_version` only reports commits made by a
+    connection other than the reader's own.
+    """
+    db = tmp_path / "dv.db"
+    writer = sqlite3.connect(str(db))
+    reader = sqlite3.connect(str(db))
+    try:
+        writer.execute("CREATE TABLE t (id INTEGER PRIMARY KEY)")
+        writer.commit()
+
+        before = sql.sqlite_data_version(reader)
+        assert sql.sqlite_data_version(reader) == before, (
+            "no write happened between these two reads — the token must not move"
+        )
+
+        writer.execute("INSERT INTO t (id) VALUES (1)")
+        writer.commit()
+
+        assert sql.sqlite_data_version(reader) != before, (
+            "another connection committed — the token must move, or the "
+            "/board cache can never notice an external write"
+        )
+    finally:
+        reader.close()
+        writer.close()
+
+
+def test_sqlite_data_version_degrades_to_a_constant_on_an_empty_result(monkeypatch):
+    """Real SQLite always answers with a row, but a stub (or a connection in
+    an exotic state) might not. Degrade to a constant rather than raising:
+    ``change_token``'s caller treats an exception as "assume changed", and an
+    IndexError escaping here would turn a missing PRAGMA row into a permanent
+    rebuild-on-every-request."""
+
+    class _Cursor:
+        def fetchone(self):
+            return None
+
+    monkeypatch.setattr(sql, "execute", lambda conn, statement, params=(): _Cursor())
+    assert sql.sqlite_data_version(object()) == "0"
+
+
 # ── row factory ──────────────────────────────────────────────────────────