cctally 1.94.1 → 1.95.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.95.0] - 2026-08-09
+
+### Changed
+- The test gate refuses to report green while verifying less than it claims. `bin/cctally-test-all` now admits the harness estate from a committed manifest (`tests/authoritative-test-manifest.json`) instead of a two-name list, so a harness that lost its executable bit, went missing, or appeared unexpectedly fails the run instead of quietly leaving the bundle. It also reads each harness's exit status rather than only the counters it printed, requires an audited minimum case count per harness, asserts the runner's capabilities before starting, and refuses a run carrying a golden-regeneration variable (#529).
+- A red run now says which kind of red it was. Every run emits a versioned outcome object whose `failureClass` is `product` (tests genuinely failed), `infrastructure` (the run could not start or the machinery broke), or `incomplete` (the run finished without verifying what it claimed), with every contributing reason retained. The exit band is `0` pass, `1` product failure, `2` usage error, `3` infrastructure or incomplete (#529).
+
+### Fixed
+- `stats.db` now uses SQLite rollback journaling (`DELETE` / `FULL`) instead of WAL. The disposable index no longer depends on live `-wal`/`-shm` generations or checkpoints; corrupt-family replacement requires a cold second drain and preserves the complete main/rollback-journal family before publishing the rebuilt index. Existing WAL installs rebuild once at epoch 1010 and refuse with restart guidance while an older dashboard or process still holds the legacy family. `cctally db checkpoint --db stats` is retired with exit 2; cache and conversations remain WAL-backed (#538).
+- Codex Guardian approval-review usage is now priced through its canonical `gpt-5.5` model instead of the generic `gpt-5` unknown-model fallback. Retained `codex-auto-review` rows no longer trigger a false pricing-coverage advisory, fast-tier reports use the canonical 2.5x multiplier, and genuinely unknown identifiers still warn and remain actionable (#535).
+- Differently pinned worktrees can now share the default remote test workdir. Each agentmem revision has its own selected executable, so provisioning one tree no longer replaces or rejects the other tree's pin and takes the runner fleet out of service (#519).
+- Codex share artifacts now disclose provider availability consistently across all nine dashboard panels. Current-week, trend, daily, monthly, weekly, and sessions exports were deriving availability only from their row count, so a real partial or empty provider state could leave both the rendered artifact and its drift indicator unchanged (#533).
+- Corrupt `stats.db` recovery no longer starves behind continuous hook traffic. The first detector now elects one durable background owner before waiting for maintenance, other callers return promptly and coalesce onto it, and that owner captures forensics and rebuilds after readers drain instead of every caller timing out before recovery is admitted (#530).
+- Escape now closes the share modal after you have clicked into the live preview. The preview is a sandboxed frame, so a key pressed inside it belonged to a different document and never reached the shortcut that closes the modal — the only way out was to tab back out of the frame first. It works from the composer's combined preview too, and it still closes one layer at a time: a section's actions first, then the composer, then the dialog beneath it (#503).
+- The share preview frame is no longer announced to a screen reader as "Report preview (decorative)". It was fully exposed to assistive technology while its only name told you not to bother with it — on the one control the documentation tells you to review before sharing. It now names the panel and template it is showing (#503).
+- Manage presets is now a real dialog. It claimed to be one but rendered as a plain block at the bottom of the share modal: Tab walked straight out of it into the template gallery behind, and closing it left focus nowhere, because it tried to return focus to a menu item that had already disappeared. It now covers the screen, keeps Tab inside itself, fits a phone without sideways scrolling, and returns focus to the presets button you opened it from (#503).
+- Escape inside a composer section's actions menu no longer closes the whole composer and discards your unsaved title, theme and format edits. It closes just the menu and puts focus back on the button that opened it; press it again to close the composer. Opening one section's actions also closes any other section's, which previously could all be open at once. The menu no longer describes itself to screen readers as a menu it never behaved like — both actions remain reachable by Tab exactly as before (#503).
+- Share checkboxes and radio buttons are 44 pixels tall in a narrow browser window, not only on a touch device. The touch sizing keyed on the pointer type rather than the width, so a narrow desktop window got none of it. The `Anon on export` label — the privacy control — was also rendering at 12 pixels on a phone despite a rule meant to set it to 16, which is the threshold below which iOS zooms the page when you tap a control (#503).
+- The share preview on a phone now shows the report instead of its frontmatter. It was capped at 128 pixels, which left about four lines once the privacy notice had taken its share, and the source label was printed twice inside that space. The cap is now proportional to the visible screen, and it shrinks correctly when the on-screen keyboard is up rather than being pushed off the bottom (#503).
+- Gallery text no longer appears to bleed through the pinned preview on a phone. Two separate causes: a 12-pixel band above the preview where scrolling content passed through a gap, and a bottom edge where the preview and the tile beneath it were the same colour with the same hairline border, so two half-cut lines of text read as one overlapping line. The preview now has a visible boundary and sits flush against the top of the scroll area (#503).
+- Rotating a phone or resizing the window with the share modal open no longer resets the preview. The two layouts rendered separate previews, so crossing the breakpoint threw away the rendered report and its privacy answer, blanked the preview for about a second, and briefly showed the wrong statement about whether your export contains real project names. There is now one preview, positioned by layout at both sizes (#503).
+- The keyboard shortcuts in the share documentation now name the gestures that work. Every passage that advertised a bare `S` or `B` has been rewritten; both shortcuts have always required Shift, and an unshifted `s` opens Settings instead. Several passages also told you to click a panel to focus it, which does not focus it — it opens the panel's own modal, which then blocks the shortcut — and two quoted a help message the application has never shown. The correct gesture is to Tab to one of the panel's actions and press Shift+S, which appeared nowhere. The share icon's own tooltip said `Share (S)` and now says `Share (Shift+S)` (#503).
+
+## [1.94.2] - 2026-08-08
+
+### Fixed
+- Release validation's segment-elision oracle no longer flakes when two equivalent rebuilds cross a one-second boundary: it still compares the complete migration set, but ignores each rebuild's wall-clock migration timestamp.
+
 ## [1.94.1] - 2026-08-08
 
 ### Fixed

package/bin/_cctally_core.py

@@ -321,14 +321,6 @@ OAUTH_BACKOFF_CAP_SECONDS = 3600.0
 _init_paths_from_env()
 
 
-# stats.db WAL cap (#297). Bounds the persistent WAL file so a resetting
-# checkpoint truncates it back down instead of leaving it at its high-water
-# size. stats.db writes are small (its -wal was observed at 0 bytes even under
-# the contention that bloated cache.db to multi-GB), so a tighter 16 MB cap is
-# ample. See docs/superpowers/specs/2026-07-13-cache-db-wal-hardening-design.md.
-STATS_WAL_SIZE_LIMIT_BYTES = 16 * 1024 * 1024  # 16777216
-
-
 # === stats.db epoch-rebuild versioning (DB journal redesign §7.1/§8) ==
 #
 # stats.db is no longer a versioned migration target — it is a DISPOSABLE index
@@ -393,7 +385,12 @@ STATS_WAL_SIZE_LIMIT_BYTES = 16 * 1024 * 1024  # 16777216
 # before any schema work, so an `add_column_if_missing` would never run on an
 # upgraded install and the column would simply never appear. The registry stays
 # frozen at 13 and an epoch mismatch resolves by rebuild.
-STATS_INDEX_EPOCH = 1009
+# 1009 -> 1010 (#538 Task A): retire WAL for the disposable stats index. Every
+# stats connection now uses DELETE/FULL rollback journaling, structurally
+# removing the shared-memory WAL page map implicated by the retained corruption
+# bundles. The one-time rebuild is the mode transition; no stats migration is
+# added and cache/conversations remain WAL/NORMAL.
+STATS_INDEX_EPOCH = 1010
 LEGACY_STATS_HEAD = 13
 
 #: #496 S1 F1. A NEW branch, for a state that cannot occur before the
@@ -773,8 +770,8 @@ def ensure_dirs() -> None:
 #   bin/_cctally_store.py    _heal_flock_blocking, reached through
 #                            _acquire_stats_maintenance_reentrant by the epoch
 #                            resolver
-#   bin/_cctally_store.py    _acquire_stats_maintenance_for_heal, the corruption
-#                            heal's ownership-first BOUNDED acquire (#496 S3)
+#   bin/_cctally_store.py    detached corruption-heal worker maintenance acquire
+#                            (the detector itself never acquires it; #530)
 #   bin/_cctally_db.py       cmd_db_rebuild, _acquire_db_admin_writer_flocks
 #                            (db skip / db unskip), _cmd_db_repair_exclusive,
 #                            _vacuum_one_db
@@ -1647,11 +1644,12 @@ def open_db(*, _target_path=None) -> sqlite3.Connection:
     # #453: probe the live index before the maintenance-shared opener. During
     # a large detached rebuild that opener can wait for its bounded 5-second
     # guard; a statusline arriving mid-replay would otherwise pay that delay
-    # (and can reach more than one stats opener in a single render). The raw
-    # probe is read-only and deliberately recognizes only a readable,
-    # post-legacy wrong epoch. Missing/unreadable/legacy indexes retain their
-    # established guarded-open paths. The post-open epoch gate below remains a
-    # race-closing defense if the version changes after this probe.
+    # (and can reach more than one stats opener in a single render). The probe
+    # reads only the fixed user_version field in the main-file header; it never
+    # opens SQLite or bypasses the maintenance opener fence. Missing, invalid-
+    # header and legacy indexes retain their established guarded-open paths.
+    # The post-open epoch gate below remains a race-closing defense if the
+    # version changes after this probe.
     if (
         _target_path is None
         and _cctally_store.stats_epoch_enabled()
@@ -1682,18 +1680,16 @@ def open_db(*, _target_path=None) -> sqlite3.Connection:
     # (corruption that only surfaces mid-DDL stays a raw error; the probe
     # catches the common case).
     try:
-        # §6.1 PRAGMA policy via the shared table (stats: WAL / NORMAL /
+        # §6.1 PRAGMA policy via the shared table (stats: DELETE / FULL /
         # busy_timeout 15000 / journal_size_limit 16 MiB / auto_vacuum unset).
         # #297: busy_timeout 15000 lets a writer wait out a slow-but-normal sync
-        # (>5 s) instead of erroring "database is locked"; it does NOT absorb
-        # SQLITE_BUSY_SNAPSHOT (defended by BEGIN IMMEDIATE / write-first at the
-        # write sites, cctally-dev#87). journal_size_limit bounds the persistent
-        # WAL. The corruption probe (SELECT 1) stays here inside the narrow
+        # (>5 s) instead of erroring "database is locked". The corruption probe
+        # (SELECT 1) stays here inside the narrow
         # StatsDbCorruptError boundary.
         _cctally_store.apply_policy(conn, "stats")
         conn.execute("SELECT 1").fetchone()
-        # §9.2 (#496 S6 F23). AFTER `apply_policy`, because that is what sets
-        # journal_mode=WAL and so what can materialize the sidecars.
+        # §9.2 (#496 S6 F23). AFTER `apply_policy`, so any rollback journal
+        # materialized during the transition is included in family hardening.
         _cctally_store._harden_stats_family(db_path)
     except sqlite3.DatabaseError as exc:
         try:
@@ -1714,7 +1710,15 @@ def open_db(*, _target_path=None) -> sqlite3.Connection:
         # it — all of which fall through to the original guided
         # StatsDbCorruptError so the manual path still applies.
         heal = getattr(_cctally_store, "HEAL_HOOK", None)
-        if _target_path is None and heal is not None and heal("stats", exc):
+        heal_enabled = (
+            os.environ.get("CCTALLY_TEST_DISABLE_STATS_AUTO_HEAL") != "1"
+        )
+        if (
+            _target_path is None
+            and heal is not None
+            and heal_enabled
+            and heal("stats", exc)
+        ):
             # #386: the post-heal retry is an opener too. The heal released the
             # maintenance lock before returning, so another maintenance path can
             # legitimately own the family by now.

package/bin/_cctally_dashboard_share.py

@@ -1763,9 +1763,15 @@ def _build_codex_source_share_snapshot(ls, *, state, panel: str,
         display_tz_label=display_tz,
     )
     codex_module = sys.modules["cctally"]._load_sibling("_cctally_codex")
+    # The canonical CLI adapter derives availability from its row count, but
+    # this source-aware path has an authoritative provider state. Project the
+    # normalized state after adapting the rows so all nine panels carry the
+    # same source chrome and built-snapshot digest signal (#533).
     return replace(
         codex_module._build_codex_share_snapshot(command, view, normalized_rows),
         template_id=template_id,
+        availability=availability,
+        availability_reason=reason,
     )
 
 

package/bin/_cctally_db.py

@@ -373,10 +373,11 @@ class StatsHealDeferred(StatsRebuildDeferred):
     quarantine and rebuild while the caller waited (#496 S3 §6). The caller
     degrades where it already degrades; it never blocks on the rebuild.
 
-    ``heal_id`` correlates this signal with the durable heal event the hook
-    recorded at detection, and ``forensics_path`` is the absolute bundle the
-    user was told about. Both are attributes rather than message text so a
-    consumer can use them without parsing.
+    ``heal_id`` correlates this signal with the durable admitted occurrence.
+    ``forensics_path`` is optional: since #530 the fresh worker captures and
+    persists that bundle after maintenance drains, so the detector normally
+    raises before a path exists. Both remain attributes rather than parsed
+    message text.
     """
 
     def __init__(
@@ -1042,7 +1043,7 @@ def write_corruption_forensics(
                 "truncated": False,
             },
         }
-    for suffix in ("", "-wal", "-shm"):
+    for suffix in ("", "-journal", "-wal", "-shm"):
         p = pathlib.Path(str(db_path) + suffix)
         try:
             st = p.stat()
@@ -1276,6 +1277,7 @@ def _load_pending_quarantine(db_path: pathlib.Path) -> "dict[str, Any] | None":
             isinstance(name, str)
             and name in {
                 db_path.name,
+                f"{db_path.name}-journal",
                 f"{db_path.name}-wal",
                 f"{db_path.name}-shm",
             }
@@ -1363,6 +1365,7 @@ def _quarantine_db_family_strict(
         members = [
             candidate.name
             for candidate in (
+                pathlib.Path(f"{db_path}-journal"),
                 pathlib.Path(f"{db_path}-wal"),
                 pathlib.Path(f"{db_path}-shm"),
                 db_path,
@@ -1448,7 +1451,7 @@ def quarantine_db_family(
     strict: bool = False,
     context: "QuarantineContext | None" = None,
 ) -> pathlib.Path:
-    """Move a damaged DB + its ``-wal``/``-shm`` sidecars into a single
+    """Move a damaged DB and its SQLite journals into a single
     timestamped incident directory under ``quarantine/`` with a manifest (spec
     §6.3). NEVER deletes evidence — three renames under the caller's exclusion
     locks, not pretending to be one atomic op. ``0o700`` dir / ``0o600`` files.
@@ -1475,7 +1478,7 @@ def quarantine_db_family(
         except OSError:
             pass
     moved: list = []
-    for suffix in ("", "-wal", "-shm"):
+    for suffix in ("", "-journal", "-wal", "-shm"):
         src = pathlib.Path(str(db_path) + suffix)
         if not src.exists():
             continue
@@ -9415,10 +9418,10 @@ def _release_repair_marker(path: pathlib.Path, claim: RepairMarkerClaim) -> None
 
 
 def _db_family_open_pids(path: pathlib.Path) -> "set[int] | None":
-    """Return processes with main/WAL/SHM open; None means unverifiable."""
+    """Return processes with any SQLite family member open; None if unknown."""
     family = [
         pathlib.Path(str(path) + suffix)
-        for suffix in ("", "-wal", "-shm")
+        for suffix in ("", "-journal", "-wal", "-shm")
         if pathlib.Path(str(path) + suffix).exists()
     ]
     if not family:
@@ -9478,7 +9481,7 @@ def _unique_sibling_path(path: pathlib.Path) -> pathlib.Path:
     def family_exists(candidate: pathlib.Path) -> bool:
         return any(
             pathlib.Path(str(candidate) + suffix).exists()
-            for suffix in ("", "-wal", "-shm")
+            for suffix in ("", "-journal", "-wal", "-shm")
         )
 
     if not family_exists(path):
@@ -9510,9 +9513,9 @@ def _copy_db_family(
     source: pathlib.Path,
     destination: pathlib.Path,
     *,
-    suffixes: "tuple[str, ...]" = ("", "-wal", "-shm"),
+    suffixes: "tuple[str, ...]" = ("", "-journal", "-wal", "-shm"),
 ) -> None:
-    """Copy main/WAL/SHM bytes while the caller holds SQLite's writer lock."""
+    """Copy main and journal bytes while the caller owns the family."""
     for suffix in suffixes:
         src = pathlib.Path(str(source) + suffix)
         if not src.exists():
@@ -9523,6 +9526,53 @@ def _copy_db_family(
         _fsync_file(dst)
 
 
+def _reserve_post_drain_evidence_path(
+    backup: pathlib.Path, suffix: str
+) -> pathlib.Path:
+    """Reserve a unique sibling without ever overwriting retained evidence."""
+    for number in range(1, 10_000):
+        infix = ".post-drain" if number == 1 else f".post-drain-{number}"
+        candidate = pathlib.Path(f"{backup}{infix}{suffix}")
+        try:
+            fd = os.open(
+                candidate,
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+                0o600,
+            )
+        except FileExistsError:
+            continue
+        os.close(fd)
+        return candidate
+    raise OSError(f"could not allocate post-drain evidence beside {backup}")
+
+
+def _preserve_post_drain_sidecars(
+    source: pathlib.Path, backup: pathlib.Path
+) -> "tuple[pathlib.Path, ...]":
+    """Move late sidecars aside without changing the classified backup."""
+    moved = []
+    for suffix in ("-journal", "-wal", "-shm"):
+        member = pathlib.Path(str(source) + suffix)
+        if not member.exists():
+            continue
+        destination = _reserve_post_drain_evidence_path(backup, suffix)
+        try:
+            # The O_EXCL reservation owns this pathname, so replace cannot
+            # destroy pre-existing user or pre-checkpoint evidence.
+            os.replace(member, destination)
+        except OSError:
+            try:
+                os.unlink(destination)
+            except OSError:
+                pass
+            raise
+        os.chmod(destination, 0o600)
+        _fsync_file(destination)
+        _fsync_directory(destination.parent)
+        moved.append(destination)
+    return tuple(moved)
+
+
 #: The classification sidecar's own schema version, matching the incident
 #: `classification.json` the correlator writes.
 _BACKUP_CLASSIFICATION_SCHEMA_VERSION = 1
@@ -9554,7 +9604,7 @@ def _write_backup_classification_sidecar(
     safe direction.
     """
     members = []
-    for suffix in ("", "-wal", "-shm"):
+    for suffix in ("", "-journal", "-wal", "-shm"):
         member = pathlib.Path(str(stem) + suffix)
         try:
             info = member.stat()
@@ -9680,7 +9730,23 @@ def _repair_preflight_and_copy(
     *,
     timeout_ms: int,
 ) -> "tuple[int, dict[str, int | None], int | None, sqlite3.Connection | None, str]":
-    """Preserve forensic bytes, drain WAL, and return a held writer guard."""
+    """Preserve bytes, drain only proven-coherent legacy WAL, and hold writer."""
+    import _lib_stats_wal
+
+    wal_evidence = _lib_stats_wal.inspect_wal_index_family(path)
+    wal_verdict = wal_evidence.get("verdict")
+    if _lib_stats_wal.is_incoherent_wal_index(wal_evidence):
+        return (
+            3, {}, None, None,
+            "incoherent legacy WAL family; refusing to open or checkpoint it",
+        )
+    if wal_verdict not in {"coherent", "wal_absent", "wal_empty"}:
+        return (
+            3, {}, None, None,
+            "could not prove the legacy WAL family coherent "
+            f"({wal_verdict or 'unknown'}); refusing repair",
+        )
+    checkpoint_legacy_wal = wal_verdict == "coherent"
     conn = sqlite3.connect(
         f"file:{path}?mode=rw", uri=True, timeout=max(timeout_ms, 0) / 1000
     )
@@ -9717,20 +9783,23 @@ def _repair_preflight_and_copy(
         _write_backup_classification_sidecar(backup)
         conn.rollback()
 
-        try:
-            checkpoint = conn.execute("PRAGMA wal_checkpoint(TRUNCATE)").fetchone()
-        except sqlite3.DatabaseError as exc:
-            conn.close()
-            return 3, {}, None, None, f"WAL checkpoint failed: {exc}"
-        wal_path = pathlib.Path(str(path) + "-wal")
-        wal_bytes = wal_path.stat().st_size if wal_path.exists() else 0
-        if checkpoint is None or int(checkpoint[0]) != 0 or wal_bytes != 0:
-            conn.close()
-            return 3, {}, None, None, "WAL could not be fully checkpointed"
+        if checkpoint_legacy_wal:
+            try:
+                checkpoint = conn.execute(
+                    "PRAGMA wal_checkpoint(TRUNCATE)"
+                ).fetchone()
+            except sqlite3.DatabaseError as exc:
+                conn.close()
+                return 3, {}, None, None, f"WAL checkpoint failed: {exc}"
+            wal_path = pathlib.Path(str(path) + "-wal")
+            wal_bytes = wal_path.stat().st_size if wal_path.exists() else 0
+            if checkpoint is None or int(checkpoint[0]) != 0 or wal_bytes != 0:
+                conn.close()
+                return 3, {}, None, None, "WAL could not be fully checkpointed"
 
-        # Hold this one write exclusion continuously through .recover and the
-        # main-file replace. Since the WAL is empty, replacement failure leaves
-        # the old main file coherent and no committed frames can be lost.
+        # Hold this write exclusion through source capture and `.recover`.
+        # Final replacement releases it only to perform the mandatory second
+        # whole-family drain under the repair marker + maintenance fence.
         try:
             conn.execute("BEGIN IMMEDIATE")
         except sqlite3.DatabaseError as exc:
@@ -10047,18 +10116,34 @@ def _cmd_db_repair_under_retention(
         try:
             os.chmod(recovered_path, 0o600)
             _fsync_file(recovered_path)
-            # WAL is already fully checkpointed and this same guard has blocked
-            # every writer since capture. Replace the coherent main file first;
-            # a failed replace therefore leaves the old coherent main + empty
-            # sidecars intact. New cctally opens remain blocked by the marker.
-            os.replace(recovered_path, path)
-            _fsync_directory(path.parent)
+            # Release our own SQLite handle before the destructive-edge drain.
+            # The repair marker and maintenance-exclusive hold still fence every
+            # normal cctally opener. A second whole-family scan closes the gap
+            # between the admission scan and this physical replacement.
             close_guard()
-            for suffix in ("-wal", "-shm"):
-                try:
-                    pathlib.Path(str(path) + suffix).unlink()
-                except FileNotFoundError:
-                    pass
+            open_pids = _db_family_open_pids(path)
+            if open_pids is None:
+                eprint(
+                    "cctally: final stats.db repair declined: the second cold "
+                    "drain could not verify open handles. Nothing was moved."
+                )
+                return 3
+            if open_pids:
+                eprint(
+                    "cctally: final stats.db repair declined after a new reader "
+                    "appeared in process(es) "
+                    + ", ".join(str(pid) for pid in sorted(open_pids))
+                    + ". Stop the dashboard and older cctally processes, then "
+                    "retry; nothing was moved."
+                )
+                return 3
+
+            # The old family was copied, fsync'd, and classified before
+            # recovery. Preserve any later survivors under unique post-drain
+            # names; overwriting the exact pre-checkpoint members would destroy
+            # evidence and make their inode/size classification stale.
+            _preserve_post_drain_sidecars(path, backup)
+            os.replace(recovered_path, path)
             _fsync_directory(path.parent)
         except OSError as exc:
             close_guard()
@@ -10128,11 +10213,11 @@ def cmd_db_backup(args: argparse.Namespace) -> int:
             prefix=f".{output.name}.tmp-", dir=output.parent
         ) as scratch_raw:
             temp_path = pathlib.Path(scratch_raw) / output.name
-            # #386: `db backup --db stats` holds this handle across the entire
-            # `source.backup(destination)` loop — a long-lived READ TRANSACTION,
-            # which Stage 1 measured as the only thing that pins the stats WAL —
-            # so it participates in the replacement protocol. The `mode=ro` open
-            # is preserved verbatim through the `connect` seam.
+            # #386/#538: `db backup --db stats` holds this handle across the
+            # entire `source.backup(destination)` loop. In rollback mode that is
+            # a long-lived reader, so it participates in the replacement
+            # protocol. The `mode=ro` open is preserved verbatim through the
+            # `connect` seam.
             def _backup_source_connect(_p, _timeout_ms=timeout_ms):
                 return sqlite3.connect(
                     f"file:{_p}?mode=ro", uri=True,
@@ -10183,8 +10268,7 @@ def cmd_db_backup(args: argparse.Namespace) -> int:
 
 
 def cmd_db_checkpoint(args: argparse.Namespace) -> int:
-    """Fast, non-destructive WAL drain (TRUNCATE checkpoint) for cache.db /
-    stats.db (#297).
+    """Fast, non-destructive WAL drain (TRUNCATE checkpoint) for cache.db.
 
     Opens a RAW existing-file-only connection — NOT open_cache_db()/open_db(),
     which apply schema, run the migration dispatcher, can DELETE Codex rows on a
@@ -10200,17 +10284,29 @@ def cmd_db_checkpoint(args: argparse.Namespace) -> int:
     was not fully truncated through the timeout — an actionable "something is
     still holding it" signal.
     """
-    import _cctally_cache
     from _lib_json_envelope import stamp_schema_version
 
     which = args.db  # "cache" | "stats"
-    if which == "cache":
-        path, label = _cctally_core.CACHE_DB_PATH, "cache.db"
-    else:
-        path, label = _cctally_core.DB_PATH, "stats.db"
+    as_json = bool(getattr(args, "json", False))
+    if which == "stats":
+        reason = (
+            "stats.db uses rollback journaling; no WAL checkpoint is applicable"
+        )
+        if as_json:
+            print(json.dumps(stamp_schema_version({
+                "db": "stats.db",
+                "status": "notApplicable",
+                "reason": reason,
+            }, version=1)))
+        else:
+            eprint(f"cctally: {reason}.")
+        return 2
+
+    import _cctally_cache
+
+    path, label = _cctally_core.CACHE_DB_PATH, "cache.db"
     timeout = int(getattr(args, "busy_timeout_ms", None)
                   or _cctally_cache.CHECKPOINT_CMD_BUSY_TIMEOUT_MS)
-    as_json = bool(getattr(args, "json", False))
 
     # Absent file → nothing to drain; a missing re-derivable cache is not an
     # error (mirrors cmd_db_recover / cmd_db_unskip). Do NOT connect — mode=rw
@@ -10227,20 +10323,10 @@ def cmd_db_checkpoint(args: argparse.Namespace) -> int:
 
     from _lib_cache_writer_lock import acquire_ordered_flocks
 
-    # #386: the stats leg previously took NO advisory lock — the flock branch was
-    # gated `if which == "cache"` — while running a real
-    # `wal_checkpoint(TRUNCATE)` against the live family. Maintenance SHARED is
-    # the right strength: a checkpoint is not a physical replacement, it just
-    # must not overlap one.
-    lock_plan = {
-        "cache": [
-            (_cctally_core.CACHE_LOCK_MAINTENANCE_PATH, fcntl.LOCK_SH),
-            (_cctally_core.CACHE_LOCK_PATH, fcntl.LOCK_EX),
-        ],
-        "stats": [
-            (_cctally_core.STATS_LOCK_MAINTENANCE_PATH, fcntl.LOCK_SH),
-        ],
-    }[which]
+    lock_plan = [
+        (_cctally_core.CACHE_LOCK_MAINTENANCE_PATH, fcntl.LOCK_SH),
+        (_cctally_core.CACHE_LOCK_PATH, fcntl.LOCK_EX),
+    ]
 
     held: list[int] = []
     try:
@@ -10286,7 +10372,7 @@ def cmd_db_checkpoint(args: argparse.Namespace) -> int:
 
 # VACUUM writes a full fresh copy of the database into a temporary file and then
 # swaps it in, so it transiently needs roughly the DB's own size on top of the
-# existing file, plus room for the drained WAL. A short busy_timeout keeps a
+# existing file, plus room for any WAL on WAL-backed stores. A short busy_timeout keeps a
 # contended VACUUM from hanging (F13).
 _VACUUM_BUSY_TIMEOUT_MS = 250
 
@@ -10313,7 +10399,7 @@ def _vacuum_required_free_bytes(path) -> int:
 
 
 def _run_vacuum_exclusive(path, label: str) -> int:
-    """Checkpoint + VACUUM ``path`` under a real SQLite EXCLUSIVE lock (F13).
+    """VACUUM ``path`` under EXCLUSIVE; checkpoint WAL-backed stores first.
 
     ``locking_mode=EXCLUSIVE`` + a short ``busy_timeout`` make a concurrent
     reader/writer FAIL PROMPTLY (no TOCTOU gap — the exclusion is the DB's own
@@ -10326,7 +10412,8 @@ def _run_vacuum_exclusive(path, label: str) -> int:
         before = conn.execute("PRAGMA page_count").fetchone()[0]
         try:
             conn.execute("PRAGMA locking_mode=EXCLUSIVE")
-            conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+            if label != "stats.db":
+                conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
             conn.execute("VACUUM")
         except sqlite3.OperationalError as exc:
             if "lock" in str(exc).lower() or "busy" in str(exc).lower():
@@ -10424,6 +10511,17 @@ def _vacuum_one_db(path, label: str, provider_locked: bool) -> int:
                         )
                         return 3
                     held.append(fh)
+            if stats_store:
+                import _cctally_store
+
+                if _cctally_store._stats_legacy_wal_family_present(path):
+                    eprint(
+                        "cctally: stats.db VACUUM declined: the index still uses "
+                        "legacy WAL. Stop and restart older cctally processes, "
+                        "then run a normal command to complete the epoch rebuild "
+                        "before retrying VACUUM."
+                    )
+                    return 3
             return _run_vacuum_exclusive(path, label)
         finally:
             for fh in held: