cctally 1.72.0 → 1.74.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.74.0] - 2026-07-19
+
+### Fixed
+- Dashboard Daily, Weekly, and Monthly details now use the same bounded history density across Claude, Codex, and All sources—30 days, 12 weeks, and 8 months—with compact date labels and contained mobile tables; Codex Blocks remains explicitly unavailable when native 5-hour activity does not exist. (#319)
+- Dashboard Trend, Projects, Cache Report, Forecast, and Alerts details now keep their canonical composed structure for Codex and All sources, show provider-native values or explicit unavailable reasons in every slot, and route provider-qualified project rows through the source-bound detail foundation. (#319)
+- Dashboard source-qualified Session and Project details now preserve Codex accounting totals when project metadata is incomplete; the combined source retains server-issued Claude Block identities and opens the canonical Block modal; source details share the standard focus, Escape, return-focus, and scroll-lock lifecycle; and desktop Share previews retain the captured provider. (#319)
+- Codex accounting no longer double-counts parent token events copied into a forked/subagent rollout before its first model context. Those records remain available to the physical conversation reader but are excluded from accounting; cache migration 027 safely replays retained Codex rollouts to remove existing `unknown` duplicates. Consequently, `cctally pricing-check` and `doctor` no longer report those ingest artifacts as a missing embedded price, while real unknown model IDs remain actionable. The complete scoped OpenAI model set and tracked rates were reverified against the live pricing sources, and the embedded pricing snapshot date is now 2026-07-19.
+- Dashboard Codex Weekly rows now follow observed native seven-day quota-cycle re-anchors instead of calendar weeks, collapsing reset jitter and clipping an older cycle when OpenAI grants an early reset. Codex quota forecasts now use elapsed native-cycle pace rather than activity-only bursts, avoiding misleading projections pinned at 100%. (#312)
+- Dashboard Codex source reads now retain accounting, quota, budget, session, and forensics panels when retained historical rows still lack project attribution. The cache replay path repairs this metadata when possible; until then the source is fresh-but-partial and disables Projects only, with a rebuild remedy. (#312)
+- Dashboard Codex hero cost and token counters now cover the active native seven-day reset cycle, rather than an unrelated calendar slice. A missing or conflicting active seven-day boundary leaves quota and budget visible while clearly marking the hero unavailable; Codex panels regain bounded native chrome and source warnings degrade only the affected domain. (#312)
+
+## [1.73.0] - 2026-07-18
+
+### Added
+- Codex conversations (#294 S7): the S6 kernel layer is now reachable. The dashboard's twelve conversation routes qualify in place — an entity id beginning `v1.` opts into the provider-neutral envelope (`ok`/`normalization_pending` → `200` JSON, `not_found` → `404`, payload `gone` → `410`, export → `200 text/markdown`, Codex media → `404 capability_unsupported`), and the three collection routes (`/api/conversations`, `/api/conversations/facets`, `/api/conversation/search`) take a strict `?source={claude,codex}`. Absent qualification, the Claude routes stay byte-identical, and the transcript privacy gate remains the first act of every handler. (#294)
+- `cctally transcript export` now accepts a Claude `sessionId` **or** a `v1.` conversation key (Codex conversations are addressable only by their `v1.` key), anonymizes qualified exports by default via a provider-aware plan (`--raw` escapes), and adds a Codex-only `--speed {auto,standard,fast}` (rejected on any non-Codex ref); the CLI export byte-matches the dashboard `/export` download in both anonymize and raw modes. (#294)
+- `cctally transcript search --source {claude,codex}` searches either provider. The Codex output is its own `Key / When / Project / Kinds / Snippet` table and a stamped-first camelCase JSON envelope paginated by an opaque base64url `--cursor`; the default-Claude table and JSON stay byte-frozen. (#294)
+- Codex conversation live-tail: `GET /api/conversation/<v1key>/events` preflights as plain JSON before any SSE bytes and then streams `conversationKey`-framed frames, and a budgeted directory-frontier discovery joins child threads spawned mid-watch. Targeted Codex ingest keeps each tick's cost proportional to the watched conversation. (#294)
+
+### Fixed
+- Statusline usage persistence now arbitrates concurrent regular-pool Claude sessions through privacy-safe per-session candidates instead of accepting the first lock winner. A fresher 5h or 7d observation is selected independent of render arrival order; lower same-window values retain a full-cycle consensus path for credits/resets, including an extra revalidated tick for reset-to-zero. This replaces the internal 25-second persistence throttle; the existing `statusLine.refreshInterval: 30` remains the idle-time trigger. OAuth and manual credits share a fail-closed selected-state recovery protocol, the periodic dashboard remains OAuth-free and publishes accepted observations through its normal SSE path, and `cctally doctor` reports passive pipeline evidence when repair is needed. (#318)
+
 ## [1.72.0] - 2026-07-17
 
 ### Added

package/bin/_cctally_cache.py

@@ -692,6 +692,78 @@ def _discover_codex_files_with_roots() -> list[CodexDiscoveredFile]:
     return discovered
 
 
+def _qualify_codex_targets(only_paths: "set[str]") -> list[CodexDiscoveredFile]:
+    """Resolve each requested path through the ordered configured roots exactly
+    as full discovery would (spec §5.1) — producing the same per-file facts a
+    ``CodexDiscoveredFile`` carries (configured spelling, physical path, provider
+    root, walk root, source-root key) with first-match containment + physical
+    dedup. A path resolving under no configured root, not a ``*.jsonl`` file, or
+    an alias of an already-resolved physical file is DROPPED (clean, not
+    ingested). Targeted mode's analogue of ``_discover_codex_files_with_roots``:
+    it does NOT walk any tree — it qualifies only the caller's exact paths."""
+    roots = _codex_provider_roots()
+    resolved: list[CodexDiscoveredFile] = []
+    seen_physical: set[pathlib.Path] = set()
+    # Deterministic order so first-match physical dedup is stable across a set.
+    for p in sorted(only_paths):
+        candidate = pathlib.Path(p)
+        for root in roots:
+            try:
+                inside = candidate.is_relative_to(root.walk_root)
+            except (ValueError, TypeError):
+                inside = False
+            if not inside:
+                continue
+            # Under this root's walk boundary: it is qualified here (first match)
+            # or dropped — a different-spelled alias never re-qualifies under a
+            # later root, matching full discovery's yielded-source-path identity.
+            if candidate.suffix != ".jsonl" or not candidate.is_file():
+                break  # vanished / non-rollout under this root → drop (clean)
+            physical = _canonical_codex_path(candidate)
+            if physical in seen_physical:
+                break  # first-match physical dedup → drop the alias
+            seen_physical.add(physical)
+            resolved.append(CodexDiscoveredFile(
+                source_path=candidate,
+                physical_path=physical,
+                provider_root=root.provider_root,
+                walk_root=root.walk_root,
+                source_root_key=root.source_root_key,
+            ))
+            break
+    return resolved
+
+
+def _load_codex_session_files_rows(
+    conn: sqlite3.Connection, paths: "list[str]"
+) -> dict:
+    """Cursor rows from ``codex_session_files`` for ONLY the given paths (spec
+    §5.1 — the targeted preload must never load every row like the full-sync
+    path). Same 12-tuple value shape as ``sync_codex_cache``'s full ``existing``
+    map, so the per-file delta logic is byte-identical between the two modes."""
+    out: dict = {}
+    if not paths:
+        return out
+    cols = (
+        "path, size_bytes, mtime_ns, last_byte_offset, "
+        "last_session_id, last_model, last_total_tokens, source_root_key, "
+        "last_native_thread_id, last_root_thread_id, last_parent_thread_id, "
+        "last_conversation_key, last_turn_id"
+    )
+    for i in range(0, len(paths), 400):
+        chunk = paths[i:i + 400]
+        placeholders = ",".join("?" for _ in chunk)
+        for row in conn.execute(
+            f"SELECT {cols} FROM codex_session_files WHERE path IN ({placeholders})",
+            chunk,
+        ):
+            out[row[0]] = (
+                row[1], row[2], row[3], row[4], row[5], row[6], row[7],
+                row[8], row[9], row[10], row[11], row[12],
+            )
+    return out
+
+
 def _delete_codex_file_derived_rows(
     conn: sqlite3.Connection,
     path_str: str,
@@ -741,8 +813,30 @@ def _delete_codex_file_derived_rows(
     )
 
 
-def _clear_codex_derived_rows(conn: sqlite3.Connection) -> None:
-    """Clear every re-derivable Codex row family in child-before-root order."""
+def _clear_codex_derived_rows(conn: sqlite3.Connection) -> bool:
+    """Clear every re-derivable Codex row family and report whether state changed.
+
+    The FTS5 ``delete-all`` command can increment SQLite's cumulative change
+    counter even when the semantic Codex surface was already empty.  Callers
+    use this return value, rather than ``Connection.total_changes``, when
+    deciding whether to advance the physical-mutation sequence.
+    """
+    state_changed = any(
+        conn.execute(query).fetchone() is not None
+        for query in (
+            "SELECT 1 FROM codex_session_entries LIMIT 1",
+            "SELECT 1 FROM quota_window_snapshots WHERE source = 'codex' LIMIT 1",
+            "SELECT 1 FROM codex_conversation_threads LIMIT 1",
+            "SELECT 1 FROM codex_conversation_events LIMIT 1",
+            "SELECT 1 FROM codex_session_files LIMIT 1",
+            "SELECT 1 FROM codex_source_roots LIMIT 1",
+            "SELECT 1 FROM codex_conversation_messages LIMIT 1",
+            "SELECT 1 FROM codex_conversation_file_touches LIMIT 1",
+            "SELECT 1 FROM codex_conversation_rollups LIMIT 1",
+            "SELECT 1 FROM cache_meta "
+            "WHERE key='codex_quota_projection_certificate' LIMIT 1",
+        )
+    )
     conn.execute("DELETE FROM codex_session_entries")
     conn.execute("DELETE FROM quota_window_snapshots WHERE source = 'codex'")
     conn.execute("DELETE FROM codex_conversation_threads")
@@ -760,6 +854,7 @@ def _clear_codex_derived_rows(conn: sqlite3.Connection) -> None:
     conn.execute(
         "DELETE FROM cache_meta WHERE key='codex_quota_projection_certificate'"
     )
+    return state_changed
 
 
 def _bump_codex_physical_mutation_seq(conn: sqlite3.Connection) -> None:
@@ -1075,8 +1170,14 @@ def _write_codex_file_batch(
     normalized_rows: list,
     normalized_touches: list,
     active_root_keys: set[str],
+    prune_roots: bool = True,
 ) -> int:
-    """Write one fully-buffered Codex file atomically and return entry changes."""
+    """Write one fully-buffered Codex file atomically and return entry changes.
+
+    ``prune_roots`` gates the whole-tree ``_prune_inactive_codex_source_roots``
+    call: a targeted (only_paths) ingest passes ``False`` so it never deletes a
+    ``codex_source_roots`` row for a root it wasn't asked about (spec §5.1
+    whole-tree bypass — ``active_root_keys`` then covers only the targets)."""
     now_iso = dt.datetime.now(dt.timezone.utc).isoformat()
     # #294 S6: rollups are recomputed-affected-or-deleted (§3.2), so capture the
     # conversation keys this file's normalized rows touch BEFORE a reset delete
@@ -1174,7 +1275,8 @@ def _write_codex_file_batch(
             last_conversation_key, last_turn_id,
         ),
     )
-    _prune_inactive_codex_source_roots(conn, active_root_keys)
+    if prune_roots:
+        _prune_inactive_codex_source_roots(conn, active_root_keys)
     # A file batch owns accounting, quota, thread, event, root, and cursor
     # facts as one physical unit. Keep the version bump in that same commit so
     # a rolled-back batch never appears newer to the dashboard signature.
@@ -3719,6 +3821,25 @@ class CodexIngestStats:
     lines_malformed: int = 0
     token_events_skipped: int = 0
     skip_reasons: dict = field(default_factory=dict)
+    # #294 S7 targeted (only_paths) live-tail fast-path fields. Default-clean so
+    # every existing only_paths=None caller reads targeted_clean=True and is
+    # otherwise unaffected — the exact Claude ``IngestStats`` semantics (§5.1).
+    # ``deferred_reason`` carries the whole-call preflight decline
+    # (shrink/requalification — Codex's ENTIRE pending-global condition; there is
+    # NO ``cache_meta`` decline-marker tuple, pinned §5.1). ``files_failed``
+    # counts per-file declines (post-preflight late shrink/requalification, I/O,
+    # normalization, DB exception).
+    files_failed: int = 0
+    deferred_reason: "str | None" = None
+
+    @property
+    def targeted_clean(self) -> bool:
+        """True ⇔ a targeted ingest fully applied: not contended, not deferred,
+        and no per-file failure (§5.1). The watch loop emits + advances ``seen``
+        only when this is True — byte-for-byte the Claude ``IngestStats`` rule."""
+        return (not self.lock_contended
+                and self.deferred_reason is None
+                and self.files_failed == 0)
 
 
 def _progress_codex_stderr(stats: CodexIngestStats, *, force: bool = False) -> None:
@@ -3736,8 +3857,10 @@ def sync_codex_cache(
     *,
     progress: Callable[[CodexIngestStats], None] | None = None,
     rebuild: bool = False,
+    only_paths: "set[str] | None" = None,
     lock_timeout: "float | None" = None,
     _on_first_file_rollback: Callable[[], None] | None = None,
+    _on_file_committed: Callable[[str], None] | None = None,
 ) -> CodexIngestStats:
     """Read-through delta ingest of ~/.codex/sessions/**/*.jsonl.
 
@@ -3777,6 +3900,16 @@ def sync_codex_cache(
             stats.lock_contended = True
             return stats
 
+        # #294 S7 targeted (only_paths) live-tail fast path (§5.1). Mutually
+        # exclusive with rebuild (matches the Claude rule). Targeted mode
+        # qualifies ONLY the caller's paths, scopes the cursor preload to them,
+        # and bypasses every whole-tree operation (orphan prune, root prune,
+        # global quota reconcile) — see the guards threaded through below.
+        targeted = only_paths is not None
+        if targeted and rebuild:
+            raise ValueError(
+                "sync_codex_cache: only_paths is incompatible with rebuild")
+
         # F4 (#313): the reconcile trigger gate is "did the Codex physical
         # mutation sequence advance during this sync", NOT rows_changed —
         # rows_changed counts only inserted accounting rows and misses
@@ -3793,17 +3926,19 @@ def sync_codex_cache(
             # Clear INSIDE the lock — see sync_cache() for the full
             # rationale. Done before the existing SELECT so delta
             # detection sees an empty baseline.
-            before_clear = conn.total_changes
-            _clear_codex_derived_rows(conn)
-            if conn.total_changes != before_clear:
+            if _clear_codex_derived_rows(conn):
                 _bump_codex_physical_mutation_seq(conn)
             conn.commit()
             eprint("[cache-sync] rebuild: cleared Codex cached entries")
 
         # Pure read (glob + is_file only); safe to run before the SELECT and
-        # the per-file loop, where no cache.db write lock may be held.
+        # the per-file loop, where no cache.db write lock may be held. Targeted
+        # mode qualifies ONLY the requested paths — never a tree walk (§5.1).
         with _perf.phase("discover") as _p_disc:
-            files = _discover_codex_files_with_roots()
+            if targeted:
+                files = _qualify_codex_targets(only_paths)
+            else:
+                files = _discover_codex_files_with_roots()
             stats.files_total = len(files)
             _p_disc.set_count(len(files))
 
@@ -3820,7 +3955,7 @@ def sync_codex_cache(
         # ingest (same invariant as the --rebuild clear above). Concurrent
         # processes with different $CODEX_HOME would prune each other; the
         # flock serializes them and that is a pathological configuration.
-        if not rebuild:  # --rebuild already cleared both tables above
+        if not rebuild and not targeted:  # --rebuild already cleared; targeted bypasses
             current_file_identities = {
                 (str(item.source_path), item.source_root_key) for item in files
             }
@@ -3875,19 +4010,53 @@ def sync_codex_cache(
         # delta detection consults size alone (Codex rollout JSONLs are
         # append-only, so a size change is a sufficient signal and mtime
         # is prone to clock-skew false-positives).
-        existing = {
-            row[0]: (
-                row[1], row[2], row[3], row[4], row[5], row[6], row[7],
-                row[8], row[9], row[10], row[11], row[12],
-            )
-            for row in conn.execute(
-                "SELECT path, size_bytes, mtime_ns, last_byte_offset, "
-                "last_session_id, last_model, last_total_tokens, source_root_key, "
-                "last_native_thread_id, last_root_thread_id, last_parent_thread_id, "
-                "last_conversation_key, last_turn_id "
-                "FROM codex_session_files"
-            )
-        }
+        if targeted:
+            # §5.1: the cursor preload queries codex_session_files for the
+            # REQUESTED paths only (the full-sync path loads every row; targeted
+            # must not, so its cost stays proportional to its targets).
+            existing = _load_codex_session_files_rows(
+                conn, [str(item.source_path) for item in files])
+        else:
+            existing = {
+                row[0]: (
+                    row[1], row[2], row[3], row[4], row[5], row[6], row[7],
+                    row[8], row[9], row[10], row[11], row[12],
+                )
+                for row in conn.execute(
+                    "SELECT path, size_bytes, mtime_ns, last_byte_offset, "
+                    "last_session_id, last_model, last_total_tokens, source_root_key, "
+                    "last_native_thread_id, last_root_thread_id, last_parent_thread_id, "
+                    "last_conversation_key, last_turn_id "
+                    "FROM codex_session_files"
+                )
+            }
+
+        # §5.1 whole-call read-only shrink/requalification preflight. Because
+        # ``targeted_clean`` is CALL-wide while the Codex path commits per file,
+        # a shrink/requalification on ANY resolved target declines the whole call
+        # with ZERO mutations (no partial commit where a healthy file's cursor
+        # advances but no event can be emitted). A shrink landing AFTER this
+        # snapshot is caught per-file at its write turn (below). This is Codex's
+        # ENTIRE pending-global condition — there is NO cache_meta decline-marker
+        # tuple (pinned §5.1). A target that vanished between qualification and
+        # here is skipped, not declined — the per-file loop clean-drops it.
+        if targeted:
+            for discovered in files:
+                prev = existing.get(str(discovered.source_path))
+                if prev is None:
+                    continue  # brand-new file: nothing to shrink/requalify
+                prev_size = prev[0]
+                prev_root_key = prev[6]
+                if prev_root_key != discovered.source_root_key:
+                    stats.deferred_reason = "requalification"
+                    return stats
+                try:
+                    cur_size = discovered.source_path.stat().st_size
+                except OSError:
+                    continue  # vanished post-qualify → clean-drop in the loop
+                if cur_size < prev_size:
+                    stats.deferred_reason = "truncation"
+                    return stats
 
         # #279 S2 F4: ONE coarse `walk` phase bracketing the per-file loop
         # (count = files_processed, never per-row — §2 rule). Manual CM so
@@ -3901,6 +4070,8 @@ def sync_codex_cache(
                 st = jp.stat()
             except OSError as exc:
                 eprint(f"[codex-cache] stat failed for {jp}: {exc}")
+                if targeted:
+                    stats.files_failed += 1  # §5.1 I/O decline → call dirty
                 continue
 
             size = st.st_size
@@ -3929,6 +4100,17 @@ def sync_codex_cache(
                     int(prev_ttot) if prev_ttot is not None else None
                 )
                 requalified = prev_root_key != discovered.source_root_key
+                if targeted and (requalified or size < prev_size):
+                    # §5.1 preflight-snapshot scoped: a shrink or requalification
+                    # landing AFTER the preflight is declined HERE, per file —
+                    # earlier per-file commits in this call stand, the call still
+                    # reports dirty (files_failed → not targeted_clean), so the
+                    # watch advances no cursor and emits nothing, and recovery
+                    # rides the next full sync's per-file reset. Targeted mode
+                    # NEVER runs the full-file offset-0 reset re-ingest (below)
+                    # — that whole-cache-affecting escalation is the full sync's.
+                    stats.files_failed += 1
+                    continue
                 if not requalified and size == prev_size:
                     stats.files_skipped_unchanged += 1
                     continue
@@ -4070,6 +4252,8 @@ def sync_codex_cache(
                         stats.skip_reasons[_r] = stats.skip_reasons.get(_r, 0) + _n
             except OSError as exc:
                 eprint(f"[codex-cache] could not read {jp}: {exc}")
+                if targeted:
+                    stats.files_failed += 1  # §5.1 I/O decline → call dirty
                 continue
 
             # Pull terminal session_id/model from the iterator's tracker.
@@ -4119,11 +4303,22 @@ def sync_codex_cache(
             # seeded from the persisted resume seed. Buffered before the first DML
             # (like every other family), so the single retry re-runs the same
             # in-memory batch. The terminal sticky turn persists as last_turn_id.
-            norm_result = _lib_codex_conversation.normalize_codex_events(
-                events_list,
-                initial=_lib_codex_conversation.CodexStickyState(
-                    turn_id=initial_turn_id, model=initial_model),
-            )
+            try:
+                norm_result = _lib_codex_conversation.normalize_codex_events(
+                    events_list,
+                    initial=_lib_codex_conversation.CodexStickyState(
+                        turn_id=initial_turn_id, model=initial_model),
+                )
+            except Exception as exc:  # noqa: BLE001
+                # §5.1: a normalization exception during a targeted ingest is a
+                # per-file decline → the call is dirty (files_failed) but earlier
+                # commits stand. A full sync keeps its historical crash-loud
+                # behavior (there the whole walk is authoritative).
+                if not targeted:
+                    raise
+                eprint(f"[codex-cache] normalization failed for {jp}: {exc}")
+                stats.files_failed += 1
+                continue
             new_last_turn_id = norm_result.terminal.turn_id
 
             # Every derived row above was buffered before the first DML. A
@@ -4155,6 +4350,9 @@ def sync_codex_cache(
                         normalized_rows=norm_result.rows,
                         normalized_touches=norm_result.touches,
                         active_root_keys={item.source_root_key for item in files},
+                        # §5.1 whole-tree bypass: targeted mode never prunes
+                        # codex_source_roots for roots outside its target set.
+                        prune_roots=not targeted,
                     )
                 except sqlite3.DatabaseError as exc:
                     conn.rollback()
@@ -4174,8 +4372,16 @@ def sync_codex_cache(
                 committed = True
                 break
             if not committed:
+                if targeted:
+                    stats.files_failed += 1  # §5.1 DB-exception decline → dirty
                 continue
 
+            # Private test seam (§5.1 post-preflight late-shrink race): fires
+            # after each file's successful commit, so a race test can shrink a
+            # not-yet-written target and assert the earlier commit stands.
+            if _on_file_committed is not None:
+                _on_file_committed(path_str)
+
             if progress is not None:
                 progress(stats)
 
@@ -4230,36 +4436,46 @@ def sync_codex_cache(
         # projection, so the skip decision on that branch is DEFERRED to the
         # post-flock stats-side signature check below — making the gate's
         # skip-condition identical to reconcile's own short-circuit-condition.
-        cur_seq = codex_physical_mutation_seq(conn)
-        if cur_seq != seq_before:
-            project_after_unlock = True
-        else:
-            active_roots = _cache_root_keys(conn)
-            if not active_roots:
-                project_after_unlock = False
+        #
+        # §5.1: a targeted (only_paths) ingest NEVER invokes the global quota
+        # reconciler (its observation load reconciles all roots at seconds-scale
+        # cost). Quota projection is deferred to the next full sync, which the
+        # ordinary hook cadence supplies. Skip the whole decision block so
+        # project_after_unlock / deferred_cert_* / did_from_zero_replay keep
+        # their no-op defaults — the post-flock reconcile paths below then all
+        # short-circuit for a targeted call.
+        if not targeted:
+            cur_seq = codex_physical_mutation_seq(conn)
+            if cur_seq != seq_before:
+                project_after_unlock = True
             else:
-                certificate = load_codex_quota_projection_certificate(conn)
-                certificate_current = (
-                    certificate is not None
-                    and certificate[0] == cur_seq
-                    and active_roots <= set(certificate[1])
-                )
-                if certificate_current:
-                    # The CACHE certificate is current, but that alone does NOT
-                    # prove stats.db still holds the projection (F1). Defer the
-                    # stats-side signature match until AFTER the Codex flock
-                    # releases below — only then may the reconcile be skipped.
+                active_roots = _cache_root_keys(conn)
+                if not active_roots:
                     project_after_unlock = False
-                    deferred_cert_roots = set(active_roots)
-                    assert certificate is not None
-                    deferred_cert_sigs = dict(certificate[1])
                 else:
-                    project_after_unlock = True
-        # #313 P3 (F9): a Codex rebuild or a truncation/requalification
-        # re-ingest replays from offset 0 and restores >retention-day
-        # codex_conversation_events. Force an unthrottled prune after the flock
-        # releases (below), so restored old rows don't persist for up to 24h.
-        did_from_zero_replay = rebuild or stats.files_reset_truncated > 0
+                    certificate = load_codex_quota_projection_certificate(conn)
+                    certificate_current = (
+                        certificate is not None
+                        and certificate[0] == cur_seq
+                        and active_roots <= set(certificate[1])
+                    )
+                    if certificate_current:
+                        # The CACHE certificate is current, but that alone does
+                        # NOT prove stats.db still holds the projection (F1).
+                        # Defer the stats-side signature match until AFTER the
+                        # Codex flock releases below — only then may the
+                        # reconcile be skipped.
+                        project_after_unlock = False
+                        deferred_cert_roots = set(active_roots)
+                        assert certificate is not None
+                        deferred_cert_sigs = dict(certificate[1])
+                    else:
+                        project_after_unlock = True
+            # #313 P3 (F9): a Codex rebuild or a truncation/requalification
+            # re-ingest replays from offset 0 and restores >retention-day
+            # codex_conversation_events. Force an unthrottled prune after the
+            # flock releases (below), so restored old rows don't persist for 24h.
+            did_from_zero_replay = rebuild or stats.files_reset_truncated > 0
     finally:
         try:
             fcntl.flock(lock_fh, fcntl.LOCK_UN)

package/bin/_cctally_core.py

@@ -67,6 +67,9 @@ def _init_paths_from_env() -> None:
     global HOOK_TICK_LOG_DIR, HOOK_TICK_LOG_PATH, HOOK_TICK_LOG_ROTATED_PATH
     global HOOK_TICK_THROTTLE_PATH, HOOK_TICK_THROTTLE_LOCK_PATH
     global STATUSLINE_OBSERVE_MARKER_PATH, STATUSLINE_PERSIST_LOCK_PATH
+    global STATUSLINE_CANDIDATE_DIR, STATUSLINE_SELECTED_PATH
+    global STATUSLINE_TRANSPORT_MARKER_PATH
+    global STATUSLINE_AUTHORITATIVE_7D_PATH, STATUSLINE_AUTHORITATIVE_5H_PATH
     global OAUTH_BACKOFF_MARKER_PATH, OAUTH_BACKOFF_COUNT_PATH
     global UPDATE_STATE_PATH, UPDATE_SUPPRESS_PATH
     global UPDATE_LOCK_PATH, UPDATE_LOG_PATH, UPDATE_LOG_ROTATED_PATH
@@ -126,25 +129,17 @@ def _init_paths_from_env() -> None:
     HOOK_TICK_THROTTLE_PATH = APP_DIR / "hook-tick.last-fetch"
     HOOK_TICK_THROTTLE_LOCK_PATH = APP_DIR / "hook-tick.last-fetch.lock"
 
-    # Statusline usage-persistence markers + lock (spec 2026-07-17
-    # usage-statusline-fallback). The statusline is the PRIMARY automatic
-    # writer of weekly/5h usage snapshots; these gate it.
-    #   - STATUSLINE_OBSERVE_MARKER_PATH: liveness marker (mtime-based,
-    #     like HOOK_TICK_THROTTLE_PATH) — touched after every statusline
-    #     persist that fed valid 7d input through cmd_record_usage, INCLUDING
-    #     a dedup no-op. Represents "the statusline is alive and feeding".
-    #     The statusline persist throttle AND the OAuth backfill gate both
-    #     key off this, NOT snapshot age (cmd_record_usage dedups unchanged
-    #     percentages without refreshing captured_at, so snapshot age keeps
-    #     growing while the statusline is actively feeding).
-    #   - STATUSLINE_PERSIST_LOCK_PATH: cross-process flock serializing the
-    #     detached persist feeder so a multi-session render herd yields at
-    #     most one snapshot per throttle window.
-    #   - OAUTH_BACKOFF_MARKER_PATH: shared 429 cooldown. Stores an ABSOLUTE
-    #     epoch deadline in the file CONTENT (never the mtime — future-dating
-    #     an mtime would corrupt HOOK_TICK_THROTTLE_PATH's age reading).
+    # Statusline candidate arbitration (#318). The spool and derived selected
+    # state are entirely APP_DIR-derived so dev/data-dir redirection remains
+    # complete. The observation marker now means selected/authoritative
+    # freshness; transport liveness has its own marker.
     STATUSLINE_OBSERVE_MARKER_PATH = APP_DIR / "statusline-observe.last"
     STATUSLINE_PERSIST_LOCK_PATH = APP_DIR / "statusline-persist.lock"
+    STATUSLINE_CANDIDATE_DIR = APP_DIR / "statusline-candidates"
+    STATUSLINE_SELECTED_PATH = APP_DIR / "statusline-selected.json"
+    STATUSLINE_TRANSPORT_MARKER_PATH = APP_DIR / "statusline-transport.last"
+    STATUSLINE_AUTHORITATIVE_7D_PATH = APP_DIR / "statusline-authoritative-7d.json"
+    STATUSLINE_AUTHORITATIVE_5H_PATH = APP_DIR / "statusline-authoritative-5h.json"
     OAUTH_BACKOFF_MARKER_PATH = APP_DIR / "oauth-backoff.until"
     # Consecutive-429 counter (text int) driving the headerless exponential
     # backoff (base * 2**count). Separate from the deadline marker so the
@@ -246,38 +241,23 @@ def _real_prod_data_dir() -> pathlib.Path:
 # Internal (no config UI — YAGNI, spec §Out of scope); test injection only.
 # Spec 2026-07-17-usage-statusline-fallback-design.
 #
-# STATUSLINE_PERSIST_THROTTLE_SECONDS: min seconds between statusline
-#   persist attempts (keyed off STATUSLINE_OBSERVE_MARKER_PATH liveness).
-#   Retuned 60.0 -> 25.0 for #311: the setup-managed statusLine.refreshInterval
-#   timer fires the statusline on a 30s cadence, and the throttle MUST be
-#   strictly LESS than that interval. When interval <= throttle, phase jitter
-#   produces beat-frequency skips (a tick at 59.9s of marker age is throttled;
-#   the next persist waits ~120s), so a 60/60 pairing oscillates 60<->120s.
-#   With interval 30 > throttle 25, every tick whose predecessor's record
-#   completed promptly (within interval - throttle = 5s) passes the gate.
-#   CADENCE QUALIFIER: the marker is touched at persist COMPLETION, so a tick
-#   observes marker age = 30 - d where d is the previous record's duration;
-#   if d > 5s (the record kernel can run cmd_sync_week JSONL scans) that tick
-#   throttles and the cycle degrades to skip-one-tick (~60s), self-correcting
-#   on the next tick. Exact-30s is NOT an invariant (no attempt-start marker
-#   exists — one would let a hung/failed record claim liveness and suppress
-#   the OAuth backfill). Still strictly better than the 60/60 beat's 60-120s.
 # OAUTH_BACKFILL_STALE_SECONDS: the OAuth poll only backfills once the
-#   observation marker is at least this stale (i.e. the statusline has
-#   NOT fed recently). Strictly greater than the persist throttle so the
-#   statusline is the primary writer and OAuth only covers its absence
-#   (300 > 25 still holds).
+#   selected-freshness marker is at least this stale. The 30-second statusline
+#   transport tick does not run OAuth.
 # OAUTH_BACKOFF_BASE_SECONDS / OAUTH_BACKOFF_CAP_SECONDS: the headerless
 #   exponential 429 backoff (base * 2**consecutive_429, capped).
-STATUSLINE_PERSIST_THROTTLE_SECONDS = 25.0
+STATUSLINE_CANDIDATE_TTL_SECONDS = 90
+STATUSLINE_CANDIDATE_FUTURE_SKEW_SECONDS = 5
+STATUSLINE_CANDIDATE_DOCUMENT_MAX_BYTES = 4 * 1024
+STATUSLINE_SELECTED_DOCUMENT_MAX_BYTES = 1024 * 1024
+STATUSLINE_TOMBSTONE_DOCUMENT_MAX_BYTES = 1024
 # STATUSLINE_REFRESH_INTERVAL_DEFAULT (#311): the value `cctally setup`
 # writes into Claude Code's settings.json `statusLine.refreshInterval` when a
 # recognized cctally statusLine block lacks one. Claude Code re-runs the
 # statusline command on this fixed timer "in addition to the event-driven
 # updates", which keeps the usage-persistence feeder ticking while a parent
 # session waits on a long subagent (event-driven updates go quiet then). MUST
-# exceed STATUSLINE_PERSIST_THROTTLE_SECONDS (30 > 25) — see the pairing rule
-# above. Add-when-absent only; a user-set value is never mutated.
+# Add-when-absent only; a user-set value is never mutated.
 STATUSLINE_REFRESH_INTERVAL_DEFAULT = 30
 OAUTH_BACKFILL_STALE_SECONDS = 300.0
 OAUTH_BACKOFF_BASE_SECONDS = 60.0

package/bin/_cctally_dashboard.py

@@ -763,6 +763,35 @@ def _build_codex_source_detail(snapshot, *, resource: str, key: str) -> dict[str
     raise SourceResourceNotFound()
 
 
+def _codex_partial_source_detail(snapshot, row: Mapping, *, resource: str,
+                                 key: str) -> dict[str, Any]:
+    """Keep a published cache-only row usable when project metadata is partial."""
+    detail = _source_safe_native_detail(
+        row, source="codex", resource=resource, key=key,
+    )
+    detail.update({
+        "metadata_availability": "partial",
+        "metadata_reason": (
+            "Codex project metadata is incomplete; available accounting totals "
+            "are preserved."
+        ),
+    })
+    if resource == "session":
+        detail.setdefault("models", [])
+        detail["model_breakdowns"] = []
+    elif resource == "project":
+        generated_at = getattr(snapshot, "generated_at", None)
+        detail.setdefault("range_start", detail.get("first_seen"))
+        detail.setdefault(
+            "range_end",
+            generated_at.astimezone(dt.timezone.utc).isoformat()
+            if isinstance(generated_at, dt.datetime) else detail.get("last_seen"),
+        )
+        detail["models"] = []
+        detail["sessions"] = []
+    return detail
+
+
 def _source_safe_claude_session_detail(detail, *, key: str) -> dict[str, Any]:
     """Adapt the existing Claude session detail builder to S4's safe route."""
     payload = _session_detail_to_envelope(detail)
@@ -958,7 +987,12 @@ def build_source_detail(*, snapshot, source: str, resource: str,
     row = source_detail_lookup(snapshot.source_bundle, source, resource, key)
     if source == "claude":
         return _build_claude_source_detail(snapshot, resource=resource, key=key)
-    return _build_codex_source_detail(snapshot, resource=resource, key=key)
+    try:
+        return _build_codex_source_detail(snapshot, resource=resource, key=key)
+    except sys.modules["_cctally_source_analytics"].QualifiedMetadataUnavailable:
+        return _codex_partial_source_detail(
+            snapshot, row, resource=resource, key=key,
+        )
 
 _ensure_sibling_loaded("_cctally_dashboard_share")
 from _cctally_dashboard_share import (