cctally 1.92.3 → 1.93.0

package/CHANGELOG.md

@@ -5,12 +5,47 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-## [1.92.3] - 2026-08-06
+## [1.93.0] - 2026-08-07
+
+### Added
+- The dashboard's share modal now states, above the preview, what the export will contain. With "Anonymize project names on export" checked it reads "Preview shows real names. Export is anonymized."; unchecked it reads "Export will show real project names." On a report that contains no project names at all — Trend and Forecast, and any other report whose data has none — it instead reads "This export contains no project names.", which is true whichever way the checkbox is set. The line is always present and changes text rather than appearing and disappearing, so a screen reader announces the new state when you toggle the checkbox. The preview pane itself still always shows real names, which is what makes the line necessary: until now the checkbox changed nothing you could see (#503).
 
 ### Changed
-- `cctally db journal-repair` and `cctally db rederive` now read the journal once per pass instead of two to four times, which lowers their memory use and start-up time on large journals. Their output is unchanged (#496).
+- A share artifact that would disclose an identifier the documentation promises it will not is now **refused** rather than produced. The check runs over the finished document and looks for session ids and other canonical UUIDs, conversation identity keys, absolute paths and `~`/`$HOME` expansions, email addresses, source-root fingerprints, quota identity keys, and credential shapes. On the command line the refusal prints `cctally: refused to write a share artifact — share artifact would disclose: <what it found> (<the offending value>)` and exits 3, and no file is written; in the dashboard it surfaces as an export error. Naming the value matters because one known case has no way around it: if a project directory is itself named as a bare hexadecimal token or a UUID, showing real names in a report is refused, and the message tells you which directory to rename. This replaces redacting and continuing, which hid the underlying defect (#503).
+- Anonymized session charts now label each bar with its cost rank and project (`1 · project-1`) instead of the session id. The chart previously printed session ids in plain sight while anonymizing a field that was never rendered, so a `sessions` artifact could carry fifteen session ids and claim to be anonymized (#503).
+- Revealing project names now shows a disambiguated basename everywhere, on the dashboard as well as the command line. Two projects named `app` under different parents render as `app (work)` and `app (personal)` rather than collapsing into one indistinguishable label — and, once anonymized, into one `project-N` (#503).
+- A composed multi-panel document now uses one set of anonymous names across all of its sections, so `project-1` means the same project everywhere in the document. Previously each section was numbered on its own and the same name could denote different projects in different sections (#503).
+- When the dashboard refuses a share export, its log now records only what kind of identifier was found, not the identifier itself. Because the refusal message names the offending value so you can find it, that value — which may be an absolute path, a session id or an email address — was being written to the dashboard log as well, and a log is a plausible thing to paste into a bug report. The message shown on screen is unchanged, and none of this detail was ever sent to a browser (#503).
+- Rebuilding the stats index no longer re-reads the journal files whose contents cctally has already proved are in the cache. A rebuild reads every byte of the journal on every pass, and on a large install most of those bytes are Codex quota observations sitting in older files that never change and that contribute nothing new to the index. When the record described above says the cache has already caught up with one of those files, the rebuild now skips reading it and uses the counts it recorded the last time it read it. A file is skipped only when it is not the newest one, when what cctally recorded about it still matches the file on disk exactly — same size, same last complete line, same identity — when it contains no record type the index folds, and when the catch-up record covers it. Anything else, including a file that was still being written to when it was last read, is read normally, and the resulting index is identical either way. If the cache changes while the rebuild is running — an ordinary Codex session is enough — it reads the skipped files after all and replays them in the order they appear in the journal; if it cannot read one of them in full — including a file that ends earlier than cctally recorded, which reading it reports no error for — it still publishes the index but does not record the cache as caught up. `cctally db rebuild --db stats --json` reports which files were skipped and, for each one that was not, why (#496).
 
 ### Fixed
+- Keep the multi-account dashboard header on one desktop row when the live sync age changes between seconds and minutes, while preserving the intentional stacked layout on phone-width screens (#496).
+- The `anonymized:` field in exported Markdown now reports whether the export was anonymized, rather than being guessed from what the labels look like. A chart-only artifact such as the Sessions visual stamped `anonymized: false` onto an artifact that had in fact been anonymized, and a project genuinely named `project-1` was reported as anonymized when it was not (#503).
+- The dashboard's render and compose endpoints now anonymize when the request omits the anonymization field. `POST /api/share/render` previously defaulted that absent field to revealing real names, and the Projects panel's subtitle separately claimed "real projects" about contents that had been anonymized (#503).
+- Restore generated agent instruction validation and keep repository instruction chains within their enforced size budget (#515).
+- Prevent stats index corruption when an in-place rebuild overlaps an idle reader by leaving live WAL/SHM sidecars under SQLite's ownership; corruption recovery also preserves a mismatched WAL-index generation without checkpointing it into the main database (#514).
+
+## [1.92.3] - 2026-08-06
+
+### Changed
+- `cctally db journal-repair` and `cctally db rederive` now read the journal once per pass instead of two to four times, which lowers their memory use and start-up time on large journals. Their output is unchanged (#496).
+- The stats index now records what a rebuild worked out about correction batches, instead of throwing that away and working it out again on the next command. This upgrade rebuilds the stats index once. Nothing about the reports changes (#496).
+- Rebuilding the stats index no longer replays Codex quota history into a cache that already holds it. Until now every rebuild re-materialized every retained quota observation into `cache.db` while holding both cache write locks, which is why version 1.92.2 reported that lock being held for 23.0 seconds on a 1.7 GB journal, and why other commands could report `database is locked` during a rebuild. cctally now records how far the cache has already caught up with the journal and, when that record still describes the journal and cache in front of it, skips the replay and takes no cache write lock at all. Measured on a 300,000-line journal carrying 276,538 quota observations: a rebuild whose cache already holds those observations held the cache write locks for 5.2 seconds without the record and 0.0 seconds with it, and finished in 12.6 seconds instead of 17.8. Those are the two figures to compare, because both describe the same full cache. A first rebuild into an empty cache still pays 14.2 seconds of lock hold to insert the rows for the first time, and the record does not change that — it removes the repeated re-materialization on every rebuild afterwards, not the initial one. The saving also assumes nothing wrote to the journal or the Codex cache between the two rebuilds; any such write discards the record and the next rebuild replays. The record is deliberately narrow: it says only that everything in the journal has reached the cache, never that the cache is otherwise correct, and anything that deletes cached quota rows discards it — including the Codex cache-rebuild migration, which clears every cached Codex quota row and can be re-run through `cctally db skip` and `cctally db unskip` — so the next rebuild replays. A record written by a version of cctally that materialized journal records differently is discarded rather than carried forward, and the record never claims a journal position past the last record the pass actually read, so a journal file that was still being written to is never counted as caught up. A rebuild that has to replay still does, and `cctally db rebuild --db stats --json` now reports which of the two happened (#496).
+- A rebuild that does have to replay Codex quota history no longer holds the cache write locks for the whole replay. It now works in bounded pieces — each capped at 8 MB of journal bytes and 20,000 observations — and releases both locks between them, so a status line, a report or a Codex sync can write while a rebuild is running instead of waiting for it or reporting `database is locked`. Each piece is decoded only when its turn comes, so the memory saving version 1.92.2 delivered is unaffected. Because the locks are genuinely released, another process can now clear the Codex cache midway through a rebuild's replay; when that happens the rebuild notices and starts its replay again from the beginning rather than continuing over the gap, so it never records that the cache has caught up with the journal when it has not. Restarting is always safe, because replaying an observation that is already stored changes nothing. A rebuild will restart at most three times before reporting that its cache recovery is incomplete, so a process that keeps clearing the cache cannot keep a rebuild running indefinitely. A rebuild also restarts when the set of Codex source roots changes underneath it, which is the second signal that another process cleared the cache, and it reports its cache recovery as incomplete rather than complete whenever it finished the replay but could not record how far the cache had caught up (#496).
+- A rebuild whose Codex cache recovery could not finish no longer serves the partial quota picture that recovery would have completed. The stats index's quota view is worked out from the Codex cache, so a rebuild that could not finish restoring that cache publishes a quota view covering only part of your history. The rebuild still publishes, still exits 0 and still prints the same success line — refusing to publish would leave a corrupt index in place, which is worse — but it now records inside the published index that its quota view is incomplete, and every command that reads that view refuses to serve it until it has been reconciled rather than showing you an understated one. The next command you run finishes the interrupted cache recovery and rewrites the quota view before answering, so the refusal is normally invisible; when it cannot finish — another process is mid-ingest, say — it leaves the mark in place and tries again on the following command rather than clearing it. `cctally db rebuild --db stats --json` now reports the two outcomes as separate fields, `publication` and `cacheRecovery`, so a script cannot read one as the other (#496).
+- Reading a correction record no longer makes cctally read the whole journal. Until now, an ingest pass that met one re-read every journal file from the beginning to work out which corrections applied, on a 1.7 GB journal every time; a report or a dashboard refresh paid that cost only when it triggered an ingest. It now continues from what the last rebuild recorded and reads only the records it has not seen yet, and it loads only the stored rows that delta actually names rather than every one of them. The result is identical: the same corrections win, an incomplete or structurally invalid batch stays inert, and anything cctally cannot decide from the recorded state falls back to the full read rather than guessing. One case is handled explicitly instead of being carried forward: when a later record invalidates a correction batch that had already been applied, cctally rebuilds the index through exactly that record, so the problem is resolved once rather than being reported again on every following command. A pass that cannot use the recorded state — because another process held the database for a moment, say — now catches up on the next pass instead of leaving the shortcut switched off until the next full rebuild, and `cctally db rebuild --db stats --json` reports when it replaced an index that had fallen behind in that way. That catch-up is bounded: past a fixed number of journal bytes a pass falls back to the full read rather than re-reading a range that keeps growing, and the same JSON reports when it did. Recorded problems with a correction batch are also withdrawn when a later record resolves them, so `cctally doctor` no longer reports a problem, and no longer prints a `cctally db journal-repair` command for it, once the journal itself no longer shows one (#496).
+
+### Fixed
+- `cctally doctor` now reports when the stats index's quota view is marked incomplete, and names `cctally cache-sync` as the way to reconcile it. Only two things clear that mark — a reconciliation, which only `cctally cache-sync` and the dashboard perform, and a later rebuild whose cache recovery completed — so until now the mark could stay set indefinitely with every Codex quota surface showing empty or stale figures and nothing anywhere stating the cause or the remedy. The new report is read-only, never reconciles anything, and is a warning rather than a failure, because the index is valid and no data is lost (#496).
+- Every refusal to serve an incomplete quota view now names `cctally cache-sync` as the way to reconcile it, instead of saying only that the view is incomplete. In the terminal dashboard the refusal is also reported as its own cause rather than being folded into a generic database failure, which previously left the Codex source panel blank on a first run with nothing on screen explaining why (#496).
+- The web dashboard now shows that refusal too. Its status chip reads "quota view reconciling" and names `cctally cache-sync`, where before it read "server sync error" with no suggested action and the sentence naming the remedy reached only the server's log. The two dashboard endpoints that can meet the refusal — a quota cycle's detail and a quota block's detail — now answer with a distinct response naming the same command, instead of reporting a server failure or an unavailable feature for a view that is simply being rebuilt (#496).
+- A corrupt stats index is no longer reported as an incomplete quota view. The check that reads the incompleteness mark cannot read anything at all from a corrupt index, and it was treating that as its own case, which both stated the wrong cause and stopped the corruption ever reaching cctally's repair path. A corrupt index is now passed on to that path unchanged, and no quota figure is served either way (#496, #407).
+- Publishing a rebuilt stats index no longer deletes the write-ahead log files of the database other cctally processes still have open, which could make those processes read stale figures or fail outright. Deleting those files is outside what SQLite supports while any connection is open, and two things had to happen together before the damage showed: something had to write to the database after the deletion, and the affected process had to have read from it before. Measured on two test machines: when the later write came from the same process, the open connection failed with a disk I/O error, and when it came from a separate process, the open connection — and any connection opened afterwards — kept reporting the figures from before that write, with no error at all. Reports, the dashboard and the status line all keep connections open across a rebuild, so both outcomes were reachable in ordinary use. The deletion is gone. Those files are removed by SQLite itself when the last connection closes, so nothing accumulates; what remains straight after a rebuild is an emptied log (#516, #496).
+- The check that refuses to serve an incomplete quota view no longer treats a failure to read the incompleteness mark as proof the mark is clear. It previously ignored every database error while reading it, on the reasoning that any current index carries the mark's table; a connection can instead fail its reads for an unrelated reason, and was then told the quota view was complete when it was not. Only a genuinely absent table — an index predating the mark — is still read as complete, and absence is now established by looking the table up rather than by matching the wording of an error message; every other failure refuses the read. The separate decision to *attempt* a reconciliation still declines on any such failure, because a connection that cannot read the mark cannot safely start one either (#496).
+- Finishing an interrupted Codex cache recovery no longer makes an ordinary command read the whole journal. The mark a rebuild leaves when its cache recovery could not finish used to be acted on by every command that opened the stats index, including each status line render and each background hook, and each of those read the journal from the beginning before it could try. Only `cctally cache-sync` and the dashboard now attempt that recovery; every other command reads the mark and moves on. An attempt that cannot finish is not repeated for five minutes rather than being retried on the next command, and an attempt that could not take the Codex cache write locks now stops before reading the journal rather than after. The messages the recovery used to print on an ordinary command are gone, and the ones a rebuild prints are unchanged (#496).
+- A rebuild whose Codex cache recovery could not finish no longer clears its own incompleteness mark when `cache.db` is missing. With no cache to read from there is nothing to rewrite the quota view from, so the mark stayed correct and clearing it served the partial view it was there to refuse (#496).
+- A rebuild now holds its read view of `cache.db` for a fraction of a second instead of about 28 seconds. That view blocks other processes from compacting the Codex cache's write-ahead log while it is open, which is the file version 1.87.0 added `cctally db checkpoint` for. `cctally db rebuild --db stats --json` now also reports the two rebuild phases that window spans, so a `database is locked` report during a rebuild is diagnosable (#496, #297).
+- A cctally process that was interrupted just before a month boundary could append to last month's journal file after this month's had already started, leaving the journal out of order. Both writers now re-check which file is current at the moment they take the write lock, and refuse the write rather than appending out of order; a Codex quota capture that hits the refusal is retried on the next sync instead of being dropped (#511).
 - A crash while cctally was first converting its database to the journal format could leave a duplicate copy of the conversion file behind, and every later rebuild then read both copies. On one real install two such duplicates accounted for 366 MB, about a fifth of the journal. The conversion now reuses the most recent conversion file when that file is byte for byte what it was about to write, instead of writing a second copy; when the most recent file differs in any way it still writes its own. Existing duplicates are left untouched, because the journal is never rewritten (#496).
 
 ## [1.92.2] - 2026-08-06

package/bin/_cctally_cache.py

@@ -132,6 +132,9 @@ from _lib_source_identity import source_root_key
 # #416 spec §4.2: the pure tolerance-anchored reset kernel. `_lib_quota` imports
 # only `_lib_accounts` (a stdlib leaf), so binding it here is circular-safe.
 import _lib_quota
+# #496 S5b §4: the journal-to-cache coverage certificate kernel. Stdlib-only,
+# so it is circular-safe for the same reason.
+import _lib_cache_coverage
 
 
 # Module-level back-ref shims for the three out-of-scope JSONL/project
@@ -1775,6 +1778,14 @@ def _delete_codex_file_derived_rows(
         "DELETE FROM codex_session_files WHERE path = ?" + root_clause,
         params,
     )
+    # #496 S5b §4.3: this deletes `quota_window_snapshots` rows the journal still
+    # retains, so any stored coverage certificate would assert coverage for
+    # durable observations whose materialization was just removed — the
+    # `journal ⊃ cache` direction the certificate exists to exclude. Invalidate
+    # in the same transaction as the deletes, exactly as `_clear_codex_derived_
+    # rows` does for the projection certificate. This covers `reset_file=True`
+    # in `_write_codex_file_batch` and every other caller alike.
+    _invalidate_codex_journal_coverage_certificate(conn)
 
 
 def _clear_codex_derived_rows(conn: sqlite3.Connection) -> bool:
@@ -1808,6 +1819,10 @@ def _clear_codex_derived_rows(conn: sqlite3.Connection) -> bool:
             "SELECT 1 FROM codex_conversation_rollups LIMIT 1",
             "SELECT 1 FROM cache_meta "
             "WHERE key='codex_quota_projection_certificate' LIMIT 1",
+            "SELECT 1 FROM cache_meta "
+            f"WHERE key='{_lib_cache_coverage.CERTIFICATE_KEY}' LIMIT 1",
+            "SELECT 1 FROM cache_meta "
+            f"WHERE key='{_lib_cache_coverage.PROGRESS_KEY}' LIMIT 1",
         )
     )
     conn.execute("DELETE FROM codex_session_entries")
@@ -1824,9 +1839,334 @@ def _clear_codex_derived_rows(conn: sqlite3.Connection) -> bool:
     conn.execute(
         "DELETE FROM cache_meta WHERE key='codex_quota_projection_certificate'"
     )
+    # #496 S5b §4.3, for the identical reason one layer up: this clears the
+    # physical quota state the COVERAGE certificate describes, so leaving it
+    # would make it stale-valid and let a rebuild's fast path skip a replay the
+    # cache now needs. The two certificates have non-overlapping authority —
+    # coverage binds journal-to-cache, projection binds cache-to-stats — and
+    # neither may satisfy the other's gate, so both are deleted here.
+    _invalidate_codex_journal_coverage_certificate(conn)
     return state_changed
 
 
+#: The families the #496 S5b coverage certificate describes: the cache tables a
+#: journal record materializes into. `tests/test_cache_coverage_496_s5b.py`
+#: scans `bin/` for DML against exactly these names, so widening the certificate
+#: to a further family means adding it here and re-running that guard.
+COVERAGE_CACHE_FAMILIES: "tuple[str, ...]" = (
+    "quota_window_snapshots",
+    "codex_file_accounts",
+    "codex_file_incarnations",
+)
+
+#: Every path that mutates or materializes those families, mapped to the ONE
+#: action it takes on the certificate (spec §4.3). `prohibited` is the default
+#: for anything absent: a writer nobody assigned an action to would leave the
+#: certificate stale-valid, which is the failure the certificate exists to
+#: exclude.
+#:
+#: `advance` may only ever move an EXTENDABLE predecessor forward, and it bumps
+#: `codex_physical_mutation_seq` in the same transaction. `mint` is the separate
+#: action for establishing a certificate where none existed, which the rebuild's
+#: recovery pass alone may do because only that pass reads the journal; it makes
+#: no sequence bump. Keeping the two words apart is what stops the inventory
+#: describing a bump the minting path does not make.
+#:
+#: The keys are `module.function`, and the static guard asserts that every
+#: function in `bin/` whose own body issues DML against a covered family appears
+#: here. Two kinds of key are NOT leaves and therefore cannot be scanned for:
+#: the parenthesized `(reset_file=True)` variant, which distinguishes two
+#: branches of one function, and the two composite transaction owners that
+#: delegate their DML to `_apply_quota_records` and `_apply_file_account_records`
+#: while owning the certificate decision. The guard names both sets explicitly so
+#: a key nobody can reach cannot be added either.
+COVERAGE_WRITER_ACTIONS: "dict[str, str]" = {
+    # Ordinary rollout-walk batch: the observations it writes were journaled
+    # (best-effort) immediately before, so the cache stays a superset and
+    # coverage is never BROKEN here.
+    #
+    # DELIBERATE DEVIATION from spec §4.3, which assigns `advance`. Advancing
+    # requires proving that the journal delta between the prior covered boundary
+    # and now contains only records this batch applied, and this function runs
+    # once per rollout file inside one flock hold — a journal range read per file
+    # is the per-file cost issue #297 exists about.
+    #
+    # `preserve` is safe rather than merely cheaper, and the reason is the
+    # UNCONDITIONAL `_bump_codex_physical_mutation_seq` this function makes in
+    # the same transaction as its rows: that bump alone moves the sequence the
+    # certificate is bound to, so any stored certificate goes invalid on the
+    # sequence axis whatever else happened. The journal append is NOT the
+    # reason, and stating it as one would be false: `_append_codex_quota_obs` is
+    # best-effort and swallows every exception, so a batch can write cache rows
+    # while growing no segment at all. A stale certificate is possible; a
+    # stale-VALID one is not. `tests/test_quota_journal.py` pins the sequence
+    # bump, because a future change making it conditional would silently turn
+    # this path into a stale-valid one with a green suite. Coverage is then
+    # re-established by `_cache_applier`, which consumes those same journal
+    # records on the next status-line tick and owns a contiguous batch it can
+    # prove.
+    "_cctally_cache._write_codex_file_batch": "preserve",
+    # `reset_file=True` runs `_delete_codex_file_derived_rows`, which drops
+    # `quota_window_snapshots` rows the journal still retains. Advancing there
+    # would assert coverage for durable observations whose materialization was
+    # just deleted — the `journal ⊃ cache` direction the certificate exists to
+    # exclude. File resets are rare, so paying a recovery pass afterwards is
+    # cheap and unambiguous.
+    "_cctally_cache._write_codex_file_batch(reset_file=True)": "invalidate",
+    "_cctally_cache._clear_codex_derived_rows": "invalidate",
+    "_cctally_cache._delete_codex_file_derived_rows": "invalidate",
+    # `UPDATE quota_window_snapshots SET canonical_resets_at_utc = ?` over rows
+    # already stored. It changes a row VALUE and never the SET of materialized
+    # journal records, and the certificate deliberately promises nothing about
+    # values (§4.1) — `canonical_resets_at_utc` is not even journaled, because
+    # it is a property of the observation's population rather than of the
+    # observation.
+    "_cctally_cache.CodexResetAnchorResolver.apply_pending_merges": "preserve",
+    # The two attribution-map leaves. Both materialize a decision that was
+    # journaled fail-closed before the call, and neither deletes, so no caller
+    # can reach them in a way that breaks coverage. The action belongs to the
+    # transaction owner above them, not here.
+    "_cctally_cache.record_codex_file_account": "preserve",
+    "_cctally_cache.set_codex_file_incarnation": "preserve",
+    # The two journal-to-cache appliers. Same reasoning: INSERT OR IGNORE on the
+    # natural key, no deletes, and the certificate decision belongs to the
+    # composite that owns their transaction.
+    "_cctally_journal._apply_quota_records": "preserve",
+    "_cctally_journal._apply_file_account_records": "preserve",
+    # Two branches, and only the additive one leaves the covered families
+    # untouched. `authoritative=False` replays journaled decisions into
+    # `codex_file_accounts` with an idempotent upsert and writes no quota row at
+    # all, so the coverage statement is unaffected.
+    #
+    # `authoritative=True` runs `DELETE FROM codex_file_accounts`, which IS a
+    # covered family. `preserve` holds there for a reason that lives in the
+    # caller rather than in this function, so it is written down here instead of
+    # left as an ordering nobody stated: `sync_codex_cache` passes
+    # `authoritative=bool(rebuild)`, and that same `rebuild` flag already ran
+    # `_clear_codex_derived_rows` — which invalidates the certificate and the
+    # progress record — and committed, before this call. The certificate is
+    # therefore already gone when the delete runs, and the clear-then-replay
+    # re-derives the whole map from `since=None` to the journal high water. A
+    # second `authoritative=True` caller, or a reordering inside
+    # `sync_codex_cache`, would break that silently, and the static scanner
+    # cannot catch it because this key is already in the inventory with a green
+    # label. `rehydrate_codex_file_accounts` therefore checks the invariant
+    # itself and raises `CoverageInvariantViolation` rather than relying on it.
+    "_cctally_journal.rehydrate_codex_file_accounts": "preserve",
+    # Spec §4.3's migrations row, enumerated rather than named — and enumerated
+    # by the action each one TAKES, not by the action the spec's one-line row
+    # assumed. Only `_024` deletes rows the journal still retains, and it is the
+    # only one that invalidates. `_038_codex_session_files_ingest_complete` is
+    # deliberately ABSENT: the review that asked for this row listed it, but it
+    # adds a column to `codex_session_files`, which is not a covered family —
+    # which is why the guard scans rather than trusts a hand list.
+    #
+    # `DELETE FROM quota_window_snapshots WHERE source = 'codex'` with NO
+    # sequence bump. Left standing, the certificate would be stale-VALID over a
+    # cache holding zero Codex quota rows.
+    "_cctally_db._024_codex_fused_ingest_rebuild": "invalidate",
+    # `UPDATE quota_window_snapshots SET observed_model = ?`, and it bumps
+    # `codex_physical_mutation_seq` in the same transaction whenever it changes
+    # a row. The certificate is left standing and goes invalid on the SEQUENCE
+    # axis, which is a different mechanism from deleting it but the same
+    # outcome, so `preserve` is the honest label for what this path does.
+    "_cctally_db._028_split_conversation_store": "preserve",
+    # Both rewrite `canonical_resets_at_utc` on rows already stored. That is a
+    # row VALUE and never the SET of materialized journal records, and §4.1
+    # excludes values from the promise explicitly — `canonical_resets_at_utc` is
+    # not even journaled, because it is a property of the observation's
+    # population rather than of the observation.
+    "_cctally_db._032_codex_canonical_reset_anchor": "preserve",
+    "_cctally_db._033_codex_reset_anchor_component_closure": "preserve",
+    # `UPDATE quota_window_snapshots SET observed_model = ?` over stored rows.
+    # A value again, and the same §4.1 exclusion applies.
+    "_cctally_db.backfill_codex_quota_observed_model": "preserve",
+    # The composite transaction owners.
+    "_cctally_journal._cache_applier": "advance",
+    # `mint`, not `advance`. §4.3 defines advancing as including a
+    # `codex_physical_mutation_seq` bump, and the rebuild leg never bumps: it
+    # ESTABLISHES a certificate over a prefix it has just read from the journal
+    # rather than extending a predecessor's claim, and the mint reads the
+    # sequence inside its own transaction so the stored value is current
+    # whatever any other writer did. Labelling it `advance` described behaviour
+    # this path does not have.
+    "_cctally_journal._rebuild_quota_cache_leg_raw": "mint",
+}
+
+#: The inventory keys that name no scannable function body, with the reason each
+#: one cannot be found by scanning for DML. The guard asserts this set exactly,
+#: so an unreachable key cannot be parked here either.
+COVERAGE_NON_LEAF_ACTIONS: "frozenset[str]" = frozenset({
+    # One branch of a function that is itself in the inventory.
+    "_cctally_cache._write_codex_file_batch(reset_file=True)",
+    # Transaction owners whose DML lives in the two appliers they call.
+    "_cctally_journal._cache_applier",
+    "_cctally_journal._rebuild_quota_cache_leg_raw",
+})
+
+
+def _advance_codex_journal_coverage(
+    conn: sqlite3.Connection, *, prior: "dict | None", covered, applied_through,
+    pinned_vector, allow_mint: bool = False,
+) -> bool:
+    """Store the advanced certificate in the CALLER's open transaction.
+
+    Returns whether it advanced. `prior` must be the certificate the caller read
+    and validated before opening the transaction: a writer may only move a valid
+    predecessor forward, and an absent one answers False rather than minting,
+    because establishing coverage requires reading the journal and only the
+    rebuild's recovery pass does that.
+
+    ``allow_mint`` is that pass's exemption. It is the one caller that has just
+    read the journal prefix it is about to certify, so it may establish coverage
+    where none existed. Every other writer leaves False.
+
+    The physical-mutation sequence is read HERE rather than passed in, because
+    the caller bumps it in this same transaction and the certificate must carry
+    the post-bump value. Reading it before the bump would store a certificate
+    that `certificate_is_valid` rejects on its first use.
+    """
+    if prior is None and not allow_mint:
+        return False
+    if allow_mint and prior is None:
+        # The mint stores over whatever is present, so it reads what is present
+        # first and refuses to move it backward. Today no other writer can be
+        # inside this transaction — `cmd_db_rebuild` holds the ingest lock
+        # exclusively — but that safety comes from a lock in another module, and
+        # the mint is what has to hold it.
+        stored = load_codex_journal_coverage_certificate(conn)
+        if _lib_cache_coverage.applied_through_regresses(
+            stored, applied_through, pinned_vector
+        ):
+            return False
+    row = conn.execute(
+        "SELECT value FROM cache_meta WHERE key='codex_physical_mutation_seq'"
+    ).fetchone()
+    try:
+        physical_seq = 0 if row is None or row[0] is None else int(row[0])
+    except (TypeError, ValueError):
+        return False
+    try:
+        certificate = _lib_cache_coverage.advance(
+            prior, covered=covered, applied_through=applied_through,
+            pinned_vector=pinned_vector, physical_seq=physical_seq)
+    except (TypeError, ValueError):
+        # The covered boundary is outside the pinned vector, which means the
+        # journal moved under this writer. Leaving the prior certificate is the
+        # safe direction: it describes a smaller prefix, and its identity root
+        # no longer matches, so the next rebuild replays.
+        return False
+    _store_codex_journal_coverage_certificate(conn, certificate)
+    return True
+
+
+def load_codex_journal_coverage_certificate(
+    conn: sqlite3.Connection,
+) -> "dict | None":
+    """The stored coverage certificate, or None when absent or unreadable.
+
+    Unreadable answers None rather than raising, because every degraded state
+    here falls back to a full replay silently (spec §6.3).
+    """
+    try:
+        row = conn.execute(
+            "SELECT value FROM cache_meta WHERE key = ?",
+            (_lib_cache_coverage.CERTIFICATE_KEY,),
+        ).fetchone()
+    except sqlite3.Error:
+        return None
+    if row is None or row[0] is None:
+        return None
+    try:
+        payload = json.loads(row[0])
+    except (TypeError, ValueError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _store_codex_journal_coverage_certificate(
+    conn: sqlite3.Connection, certificate: dict
+) -> None:
+    """Write the certificate inside the CALLER's open transaction.
+
+    It must commit with the rows it describes and with the
+    `codex_physical_mutation_seq` bump, so a rollback leaves the prior
+    certificate unchanged even when the journal appends survived — which is the
+    safe direction.
+    """
+    conn.execute(
+        "INSERT INTO cache_meta(key, value) VALUES (?, ?) "
+        "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+        (
+            _lib_cache_coverage.CERTIFICATE_KEY,
+            json.dumps(certificate, separators=(",", ":"), sort_keys=True),
+        ),
+    )
+
+
+def load_codex_recovery_progress(conn: sqlite3.Connection) -> "dict | None":
+    """A recovery pass's stored progress, or None when absent or unreadable."""
+    try:
+        row = conn.execute(
+            "SELECT value FROM cache_meta WHERE key = ?",
+            (_lib_cache_coverage.PROGRESS_KEY,),
+        ).fetchone()
+    except sqlite3.Error:
+        return None
+    if row is None or row[0] is None:
+        return None
+    try:
+        payload = json.loads(row[0])
+    except (TypeError, ValueError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _store_codex_recovery_progress(
+    conn: sqlite3.Connection, progress: dict,
+) -> bool:
+    """Advance progress under the monotonic compare-and-swap, in this txn.
+
+    Returns whether it was written. Refusing rather than overwriting is what
+    keeps an older worker from moving a newer pass's checkpoint backwards.
+    """
+    stored = load_codex_recovery_progress(conn)
+    if not _lib_cache_coverage.progress_supersedes(stored, progress):
+        return False
+    conn.execute(
+        "INSERT INTO cache_meta(key, value) VALUES (?, ?) "
+        "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+        (
+            _lib_cache_coverage.PROGRESS_KEY,
+            json.dumps(progress, separators=(",", ":"), sort_keys=True),
+        ),
+    )
+    return True
+
+
+def _invalidate_codex_journal_coverage_certificate(
+    conn: sqlite3.Connection,
+) -> None:
+    """Drop the certificate AND any in-flight recovery progress, in this txn.
+
+    Every destructive or partial mutation of the covered families takes this
+    branch. Re-establishing coverage is recovery's job.
+
+    The two deletes are ONE function rather than two calls a writer could get
+    half right. Spec §4.5 requires that every destructive clear delete the
+    progress record in the same transaction as the certificate, because a
+    recovery pass that resumed from an in-memory cursor over cleared state would
+    eventually mint a certificate claiming coverage the cache does not have.
+    Structuring it as a single call is what makes "in the same transaction"
+    impossible to violate by omission.
+    """
+    conn.execute(
+        "DELETE FROM cache_meta WHERE key IN (?, ?)",
+        (_lib_cache_coverage.CERTIFICATE_KEY,
+         _lib_cache_coverage.PROGRESS_KEY),
+    )
+
+
 def _bump_codex_physical_mutation_seq(conn: sqlite3.Connection) -> None:
     """Advance the shared Codex physical-state invalidation token in this txn.
 
@@ -2362,6 +2702,14 @@ def _append_codex_quota_obs(quota_rows: list) -> None:
                     "individual_limit_json": individual_limit_json,
                     "reached_type": reached_type, "observed_model": observed_model,
                 }), dedupe_codex_quota=True)
+        except _jr.JournalAppendTargetStale:
+            # Retryable, NOT best-effort (#511, #496 S5b §2.4). Swallowing this
+            # one lets the file offset advance past bytes whose observation was
+            # never journaled, and the rollout JSONL those bytes came from
+            # evaporates — the exact data-loss hole the quota journal exists to
+            # close. Re-raising leaves the offset where it was, so the next sync
+            # re-reads and re-appends the same bytes.
+            raise
         except Exception as exc:  # best-effort; a journal append must not break sync
             eprint(f"[codex-cache] quota obs journal append failed: {exc}")
 
@@ -10534,6 +10882,12 @@ def cmd_cache_sync(args: argparse.Namespace) -> int:
     default is 'all'.
     """
     source = getattr(args, "source", "all")
+    # #496 S5b §4.7: this command is the documented remedy for a cache that is
+    # behind its journal, so it is one of the contexts allowed to resume a
+    # gated quota-projection recovery when it opens stats.db. The interactive
+    # render paths (`statusline`, every hook tick) never arm it — the
+    # resumption reads the whole journal.
+    _cctally_core.enable_quota_projection_reconciliation()
     # #276 perf: clear any prior tree on this thread so a leaked root can't be
     # flushed, then (below) time the Claude sync_cache call as the "sync_cache"
     # root phase and flush the tree to stderr when CCTALLY_PERF_TRACE is set.