cctally 1.73.0 → 1.75.0

package/bin/_cctally_source_analytics.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import datetime as dt
+import dataclasses
 import hashlib
 import json
 import pathlib
@@ -20,6 +21,7 @@ from _cctally_core import (
 )
 from _cctally_cache import _codex_provider_roots
 from _lib_quota import build_blocks
+from _lib_pricing import _calculate_codex_entry_cost
 from _cctally_quota import load_codex_quota_observations
 from _lib_source_analytics import (
     AnalyticsWindow,
@@ -50,6 +52,37 @@ class SourceUsageError(ValueError):
     """A provider-aware request is syntactically or semantically invalid."""
 
 
+@dataclasses.dataclass(frozen=True)
+class CodexProjectMetadataHealth:
+    """A root-qualified partition of retained Codex accounting metadata."""
+
+    total_rows: int
+    qualified_rows: int
+    missing_conversation_key_rows: int
+    missing_thread_join_rows: int
+
+    @property
+    def incomplete_rows(self) -> int:
+        return self.missing_conversation_key_rows + self.missing_thread_join_rows
+
+
+@dataclasses.dataclass(frozen=True)
+class RootedCodexAccountingEntry:
+    """One cache-only Codex accounting row with authoritative root identity."""
+
+    timestamp: dt.datetime
+    session_id: str
+    source_path: str
+    source_root_key: str
+    model: str
+    input_tokens: int
+    cached_input_tokens: int
+    output_tokens: int
+    reasoning_output_tokens: int
+    total_tokens: int
+    cost_usd: float
+
+
 _OPAQUE_PROJECT_KEY_RE = re.compile(r"^project:[0-9a-f]{24}$")
 
 
@@ -74,6 +107,18 @@ _QUALIFIED_CODEX_ENTRIES_SQL = """
 """
 
 
+_INHERITED_CODEX_PROJECT_METADATA_SQL = """
+    SELECT files.source_root_key, files.path, inherited.cwd, inherited.git_json
+      FROM codex_session_files AS files
+      JOIN codex_conversation_threads AS inherited
+        ON inherited.source_root_key = files.source_root_key
+       AND inherited.native_thread_id = files.last_native_thread_id
+     WHERE files.last_native_thread_id IS NOT NULL
+       AND files.last_native_thread_id != ''
+     ORDER BY inherited.last_seen_utc DESC, inherited.conversation_key DESC
+"""
+
+
 _CODEX_ACCOUNTING_ENTRIES_SQL = """
     SELECT timestamp_utc, source_root_key, conversation_key, model,
            input_tokens, cached_input_tokens, output_tokens,
@@ -86,6 +131,75 @@ _CODEX_ACCOUNTING_ENTRIES_SQL = """
 """
 
 
+_ROOTED_CODEX_ACCOUNTING_ENTRIES_SQL = """
+    SELECT timestamp_utc, session_id, source_path, source_root_key, model,
+           input_tokens, cached_input_tokens, output_tokens,
+           reasoning_output_tokens, total_tokens
+      FROM codex_session_entries INDEXED BY idx_codex_entries_ts_root_conversation
+     WHERE timestamp_utc >= ?
+       AND timestamp_utc < ?
+     {root_predicate}
+     ORDER BY timestamp_utc ASC, source_root_key ASC, conversation_key ASC, id ASC
+"""
+
+
+_CODEX_PROJECT_METADATA_HEALTH_SQL = """
+    SELECT
+      COUNT(*) AS total_rows,
+      COALESCE(SUM(CASE
+          WHEN entries.conversation_key IS NULL OR entries.conversation_key = ''
+          THEN 1 ELSE 0 END), 0) AS missing_conversation_key_rows,
+      COALESCE(SUM(CASE
+           WHEN entries.conversation_key IS NOT NULL
+           AND entries.conversation_key != ''
+           AND threads.conversation_key IS NULL
+           AND NOT EXISTS (
+             SELECT 1 FROM codex_session_files AS files
+             JOIN codex_conversation_threads AS inherited
+               ON inherited.source_root_key = entries.source_root_key
+              AND inherited.native_thread_id = files.last_native_thread_id
+            WHERE files.path = entries.source_path
+              AND files.source_root_key = entries.source_root_key
+           )
+          THEN 1 ELSE 0 END), 0) AS missing_thread_join_rows
+      FROM codex_session_entries AS entries
+      LEFT JOIN codex_conversation_threads AS threads
+        ON threads.conversation_key = entries.conversation_key
+       AND threads.source_root_key = entries.source_root_key
+     WHERE (? IS NULL OR entries.timestamp_utc >= ?)
+       AND (? IS NULL OR entries.timestamp_utc < ?)
+"""
+
+
+_CODEX_PROJECT_METADATA_HEALTH_LEGACY_SQL = """
+    SELECT
+      COUNT(*) AS total_rows,
+      COALESCE(SUM(CASE
+          WHEN entries.conversation_key IS NULL OR entries.conversation_key = ''
+          THEN 1 ELSE 0 END), 0) AS missing_conversation_key_rows,
+      COALESCE(SUM(CASE
+          WHEN entries.conversation_key IS NOT NULL
+           AND entries.conversation_key != ''
+           AND threads.conversation_key IS NULL
+          THEN 1 ELSE 0 END), 0) AS missing_thread_join_rows
+      FROM codex_session_entries AS entries
+      LEFT JOIN codex_conversation_threads AS threads
+        ON threads.conversation_key = entries.conversation_key
+       AND threads.source_root_key = entries.source_root_key
+     WHERE (? IS NULL OR entries.timestamp_utc >= ?)
+       AND (? IS NULL OR entries.timestamp_utc < ?)
+"""
+
+
+def _supports_native_file_aliases(cache_conn: sqlite3.Connection) -> bool:
+    """Return whether this cache generation can link child files to a root task."""
+    try:
+        columns = cache_conn.execute("PRAGMA table_info(codex_session_files)").fetchall()
+    except sqlite3.Error:
+        return False
+    return any(len(row) > 1 and row[1] == "last_native_thread_id" for row in columns)
+
+
 def _cctally():
     return sys.modules["cctally"]
 
@@ -100,6 +214,160 @@ def _parse_timestamp(value: object) -> dt.datetime:
     return timestamp.astimezone(UTC)
 
 
+def _metadata_health_bound(value: dt.datetime | None, *, name: str) -> str | None:
+    if value is None:
+        return None
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise ValueError(f"{name} must be timezone-aware")
+    # Retain the canonical ``+00:00`` representation written by Codex ingest
+    # and consumed by the accounting readers: SQLite TEXT bounds must sort in
+    # the same encoding for the [start, end) window to remain exact.
+    return value.astimezone(UTC).isoformat()
+
+
+def load_codex_project_metadata_health(
+    *,
+    cache_conn: sqlite3.Connection,
+    start: dt.datetime | None = None,
+    end: dt.datetime | None = None,
+) -> CodexProjectMetadataHealth:
+    """Classify retained Codex accounting in one root-qualified SQL read.
+
+    Bounds are both timezone-aware or both omitted; the omitted form serves the
+    all-history doctor check.  The output is an exhaustive, mutually-exclusive
+    count partition and contains no source or identity data.
+    """
+    if (start is None) != (end is None):
+        raise ValueError("start and end must be supplied together or both omitted")
+    bound_start = _metadata_health_bound(start, name="start")
+    bound_end = _metadata_health_bound(end, name="end")
+    if start is not None and end is not None and start > end:
+        raise ValueError("start must not be after end")
+
+    row = cache_conn.execute(
+        (_CODEX_PROJECT_METADATA_HEALTH_SQL if _supports_native_file_aliases(cache_conn)
+         else _CODEX_PROJECT_METADATA_HEALTH_LEGACY_SQL),
+        (bound_start, bound_start, bound_end, bound_end),
+    ).fetchone()
+    if row is None or len(row) != 3:
+        raise RuntimeError("Codex project metadata health query returned no partition")
+    try:
+        total_rows, missing_key_rows, missing_join_rows = (int(value) for value in row)
+    except (TypeError, ValueError) as exc:
+        raise RuntimeError("Codex project metadata health query returned invalid counts") from exc
+    qualified_rows = total_rows - missing_key_rows - missing_join_rows
+    values = (total_rows, qualified_rows, missing_key_rows, missing_join_rows)
+    if any(value < 0 for value in values) or total_rows != sum(values[1:]):
+        raise RuntimeError("Codex project metadata health partition is invalid")
+    return CodexProjectMetadataHealth(
+        total_rows=total_rows,
+        qualified_rows=qualified_rows,
+        missing_conversation_key_rows=missing_key_rows,
+        missing_thread_join_rows=missing_join_rows,
+    )
+
+
+def load_cached_rooted_codex_accounting_entries(
+    start: dt.datetime,
+    end: dt.datetime,
+    *,
+    speed: str,
+    cache_conn: sqlite3.Connection,
+    source_root_keys: Iterable[str] | None = None,
+) -> tuple[RootedCodexAccountingEntry, ...]:
+    """Read bounded accounting from one caller-owned cache snapshot only.
+
+    This reader intentionally never syncs, opens or closes a database, reads
+    rollouts, resolves projects, or discovers configured Codex roots.  The
+    cached root key plus source path are the dashboard's file identity.  A
+    caller can additionally constrain the read to roots that established one
+    native cycle; root identities remain internal to this adapter.
+    """
+    if start.tzinfo is None or start.utcoffset() is None:
+        raise ValueError("start must be timezone-aware")
+    if end.tzinfo is None or end.utcoffset() is None:
+        raise ValueError("end must be timezone-aware")
+    if end <= start:
+        raise ValueError("end must be after start")
+    root_keys = (
+        tuple(sorted({key for key in source_root_keys if isinstance(key, str) and key}))
+        if source_root_keys is not None else ()
+    )
+    if source_root_keys is not None and not root_keys:
+        return ()
+    root_predicate = (
+        "AND source_root_key IN (" + ", ".join("?" for _ in root_keys) + ")"
+        if source_root_keys is not None else ""
+    )
+    try:
+        rows = tuple(cache_conn.execute(
+            _ROOTED_CODEX_ACCOUNTING_ENTRIES_SQL.format(root_predicate=root_predicate),
+            (
+                start.astimezone(UTC).isoformat(), end.astimezone(UTC).isoformat(), *root_keys,
+            ),
+        ))
+    except sqlite3.Error as exc:
+        raise QualifiedMetadataUnavailable("Codex accounting metadata is unavailable") from exc
+
+    result: list[RootedCodexAccountingEntry] = []
+    for row in rows:
+        try:
+            (
+                timestamp_raw, session_id_raw, source_path_raw, source_root_key_raw,
+                model_raw, input_raw, cached_input_raw, output_raw, reasoning_raw,
+                total_raw,
+            ) = row
+            source_path = source_path_raw if isinstance(source_path_raw, str) else ""
+            source_root_key = source_root_key_raw if isinstance(source_root_key_raw, str) else ""
+            if not source_path or not source_root_key:
+                raise ValueError("rooted accounting identity is absent")
+            model = str(model_raw)
+            input_tokens = int(input_raw)
+            cached_input_tokens = int(cached_input_raw)
+            output_tokens = int(output_raw)
+            reasoning_output_tokens = int(reasoning_raw)
+            total_tokens = int(total_raw)
+            cost_usd = _calculate_codex_entry_cost(
+                model,
+                input_tokens,
+                cached_input_tokens,
+                output_tokens,
+                reasoning_output_tokens,
+                speed=speed,
+            )
+        except (TypeError, ValueError, OverflowError) as exc:
+            raise QualifiedMetadataUnavailable("Codex accounting metadata is unavailable") from exc
+        result.append(RootedCodexAccountingEntry(
+            timestamp=_parse_timestamp(timestamp_raw),
+            session_id=str(session_id_raw or ""),
+            source_path=source_path,
+            source_root_key=source_root_key,
+            model=model,
+            input_tokens=input_tokens,
+            cached_input_tokens=cached_input_tokens,
+            output_tokens=output_tokens,
+            reasoning_output_tokens=reasoning_output_tokens,
+            total_tokens=total_tokens,
+            cost_usd=cost_usd,
+        ))
+    return tuple(result)
+
+
+def has_cached_codex_accounting_entries(*, cache_conn: sqlite3.Connection) -> bool:
+    """Return whether any retained Codex accounting exists without range filtering.
+
+    This intentionally tiny caller-owned cache read lets a missing native cycle
+    fail closed even when the dashboard's visible or budget range is empty.
+    It neither resolves roots nor reads rollout files.
+    """
+    try:
+        return cache_conn.execute(
+            "SELECT 1 FROM codex_session_entries LIMIT 1"
+        ).fetchone() is not None
+    except sqlite3.Error as exc:
+        raise QualifiedMetadataUnavailable("Codex accounting metadata is unavailable") from exc
+
+
 def _project_label(value: object) -> str:
     """Render only a basename-like label; absolute paths remain internal."""
     raw = str(value).strip()
@@ -191,6 +459,12 @@ def load_qualified_codex_entries(
             _QUALIFIED_CODEX_ENTRIES_SQL,
             (start.astimezone(UTC).isoformat(), end.astimezone(UTC).isoformat()),
         ))
+        inherited_metadata: dict[tuple[str, str], sqlite3.Row] = {}
+        if _supports_native_file_aliases(conn):
+            for inherited in conn.execute(_INHERITED_CODEX_PROJECT_METADATA_SQL):
+                identity = (str(inherited["source_root_key"] or ""), str(inherited["path"] or ""))
+                if all(identity):
+                    inherited_metadata.setdefault(identity, inherited)
     except sqlite3.Error as exc:
         raise QualifiedMetadataUnavailable("Codex qualified project metadata is unavailable") from exc
     finally:
@@ -204,8 +478,19 @@ def load_qualified_codex_entries(
     resolved_by_git_json: dict[str, str | None] = {}
     result: list[QualifiedCodexEntry] = []
     for row in rows:
-        root_key, conversation_key = _require_joined_metadata(row)
-        cwd = row["cwd"]
+        root_key = row["source_root_key"]
+        conversation_key = row["conversation_key"]
+        inherited = inherited_metadata.get((str(root_key or ""), str(row["source_path"] or "")))
+        try:
+            root_key, conversation_key = _require_joined_metadata(row)
+        except QualifiedMetadataUnavailable:
+            if (
+                inherited is None
+                or not isinstance(root_key, str) or not root_key
+                or not isinstance(conversation_key, str) or not conversation_key
+            ):
+                raise
+        cwd = row["cwd"] or (inherited["cwd"] if inherited is not None else None)
         if isinstance(cwd, str) and cwd:
             project = resolved_by_cwd.get(cwd)
             if project is None:
@@ -218,7 +503,7 @@ def load_qualified_codex_entries(
                 else _project_label(project.display_key)
             )
         else:
-            git_json = row["git_json"]
+            git_json = row["git_json"] or (inherited["git_json"] if inherited is not None else None)
             if isinstance(git_json, str) and git_json not in resolved_by_git_json:
                 resolved_by_git_json[git_json] = _git_resolved_key(git_json)
             git_key = resolved_by_git_json.get(git_json) if isinstance(git_json, str) else None

package/bin/_cctally_statusline.py

@@ -940,9 +940,9 @@ def _authoritative_record_usage(
 ) -> _AuthoritativeRecordResult:
     """Record OAuth authority under write-ahead tombstones and reconcile it.
 
-    ``lock_held`` is reserved for automatic polling, which holds the selected
-    lock across its post-lock freshness/backoff recheck and network request.
-    All other callers acquire the same blocking lock here.
+    ``lock_held`` is for OAuth refresh callers that already hold the selected
+    lock across their fetch, authoritative publication, and matching backoff
+    transition. All other callers acquire the same blocking lock here.
     """
     if not lock_held:
         try:

package/bin/_cctally_tui.py

@@ -227,6 +227,7 @@ from _lib_fmt import stable_sum
 # shared no-op singleton), so the _tui_build_snapshot seam wraps below cost
 # nothing on the default path.
 import _lib_perf as _perf
+import _lib_log
 
 import importlib.util as _ilu
 
@@ -261,7 +262,6 @@ from _lib_forecast import _compute_forecast, ForecastInputs, ForecastOutput, Bud
 _ensure_sibling_loaded("_lib_dashboard_sources")
 _ensure_sibling_loaded("_cctally_dashboard_sources")
 from _cctally_dashboard_sources import (
-    CodexProjectionIncoherent,
     DashboardReadContext,
     build_codex_source_state,
     refresh_codex_source_clock,
@@ -2520,8 +2520,18 @@ def _tui_build_source_bundle(
                 else unavailable_source_state("codex", warning)
             )
         else:
-            codex = reuse_coherent_source_state(
-                prior_codex, data_version=codex_version,
+            # Projection coherence can recover when S2 writes its certificate
+            # without changing physical accounting.  A current, hero-scoped
+            # incoherence generation is intentionally not retained through
+            # that repair opportunity; all other fresh partial states remain
+            # eligible for exact reuse.
+            codex = (
+                None if prior_codex is not None and any(
+                    warning.code == "codex_projection_incoherent"
+                    for warning in prior_codex.warnings
+                ) else reuse_coherent_source_state(
+                    prior_codex, data_version=codex_version,
+                )
             )
         if codex is None:
             try:
@@ -2536,21 +2546,17 @@ def _tui_build_source_bundle(
                         week_start_name=semantics.week_start_name,
                         speed=semantics.speed,
                         codex_budget=semantics.codex_budget,
+                        codex_quota_actual_thresholds=semantics.codex_quota_actual_thresholds,
+                        codex_quota_projected_thresholds=semantics.codex_quota_projected_thresholds,
+                        cache_report_anomaly_threshold_pp=semantics.cache_report_anomaly_threshold_pp,
                     ),
                     data_version=codex_version,
                 )
-            except CodexProjectionIncoherent:
-                warning = SourceDashboardWarning(
-                    "codex_projection_incoherent",
-                    "Codex quota projection is unavailable.",
-                    "quota",
-                )
-                codex = (
-                    degrade_source_state(prior_codex, warning)
-                    if prior_codex is not None
-                    else unavailable_source_state("codex", warning)
-                )
             except Exception:
+                _lib_log.get_logger("dashboard").error(
+                    "codex_read_model source build failed",
+                    exc_info=True,
+                )
                 warning = SourceDashboardWarning(
                     "source_build_failed", "Source data could not be built.", "read_model",
                 )

package/bin/_lib_aggregators.py

@@ -42,7 +42,7 @@ import os
 import pathlib
 import sys
 from dataclasses import dataclass
-from typing import Any, Callable
+from typing import Any, Callable, Iterable
 
 
 def _cctally():
@@ -378,6 +378,13 @@ class CodexBucketUsage:
     cost_usd: float
     models: list[str]                         # Distinct full model names (first-seen order)
     model_breakdowns: list[dict[str, Any]]    # Sorted by cost desc
+    # Native quota-cycle context. Calendar daily/monthly callers leave these
+    # null; the dashboard's subscription-week adapter fills them from the
+    # retained OpenAI rate-limit observations.
+    period_start_at: dt.datetime | None = None
+    period_end_at: dt.datetime | None = None
+    used_pct: float | None = None
+    dollar_per_pct: float | None = None
 
 
 @dataclass
@@ -414,6 +421,17 @@ class CodexSessionUsage:
     codex_root: str = ""
 
 
+@dataclass(frozen=True)
+class CodexSessionIdentity:
+    """Caller-supplied identity for the pure Codex session accumulator."""
+
+    group_key: tuple[str, str]
+    session_id_path: str
+    session_file: str
+    directory: str
+    codex_root: str
+
+
 @dataclass
 class ClaudeSessionUsage:
     """Aggregated Claude usage for one sessionId (may span multiple JSONL files)."""
@@ -619,41 +637,19 @@ def _codex_home_root_from_prefix(root_prefix: str) -> str:
     return s
 
 
-def _aggregate_codex_sessions(entries: list[CodexEntry], speed: str = "standard") -> list[CodexSessionUsage]:
-    """Group by session file path (upstream-compatible).
-
-    Sessions are keyed by the full relative-path-without-.jsonl rather than
-    the inner UUID. Result is sorted by last_activity descending (most
-    recent first), matching upstream's default view.
-
-    Per-model breakdowns include `isFallback: bool` — true when the model is
-    absent from CODEX_MODEL_PRICING.
-    """
+def _aggregate_codex_sessions_keyed(
+    entries: Iterable[tuple[CodexEntry, CodexSessionIdentity]],
+    speed: str = "standard",
+) -> list[CodexSessionUsage]:
+    """Pure Codex session arithmetic over caller-owned file identities."""
     by_session: dict[tuple[str, str], dict[str, Any]] = {}
-    for entry in entries:
-        id_path, file_name, directory = _session_path_parts(entry.source_path)
-        # Disambiguate identical relative paths under DIFFERENT $CODEX_HOME
-        # roots (issue #108). _session_path_parts strips the matched root, so
-        # <rootA>/sessions/2026/04/17/rollout-x.jsonl and the same relative
-        # path under <rootB> both yield id_path "2026/04/17/rollout-x";
-        # grouping on id_path alone would silently merge two distinct sessions
-        # (summed tokens, one UUID). Key on (root_prefix, id_path), where
-        # root_prefix is source_path with the id_path tail removed. Single-root
-        # data — and the bare-relative fixture form — has a constant prefix, so
-        # the grouping, insertion order, and every golden stay byte-identical;
-        # only a genuine cross-root collision splits into separate rows.
-        suffix = id_path + ".jsonl"
-        sp = entry.source_path
-        root_prefix = sp[: -len(suffix)] if sp.endswith(suffix) else sp
-        sess = by_session.setdefault((root_prefix, id_path), {
+    for entry, identity in entries:
+        sess = by_session.setdefault(identity.group_key, {
             "session_id_uuid": entry.session_id,
-            "session_id_path": id_path,
-            "session_file": file_name,
-            "directory": directory,
-            # Matched $CODEX_HOME root (home-root form) — issue #110 display
-            # disambiguator. Derived from the same root_prefix that keys the
-            # group, so it's constant per group.
-            "codex_root": _codex_home_root_from_prefix(root_prefix),
+            "session_id_path": identity.session_id_path,
+            "session_file": identity.session_file,
+            "directory": identity.directory,
+            "codex_root": identity.codex_root,
             "input": 0, "cached_input": 0, "output": 0, "reasoning": 0,
             "cost": 0.0, "models": {}, "models_order": [],
             "last": entry.timestamp,
@@ -724,6 +720,31 @@ def _aggregate_codex_sessions(entries: list[CodexEntry], speed: str = "standard"
     return result
 
 
+def _aggregate_codex_sessions(entries: list[CodexEntry], speed: str = "standard") -> list[CodexSessionUsage]:
+    """Group CLI Codex entries by their existing filesystem-derived identity.
+
+    The wrapper preserves the historic CLI path parsing and byte-stable output;
+    only the accumulation itself lives in the keyed pure seam above.
+    """
+    keyed: list[tuple[CodexEntry, CodexSessionIdentity]] = []
+    for entry in entries:
+        id_path, file_name, directory = _session_path_parts(entry.source_path)
+        # Disambiguate equal relative paths under separate configured roots.
+        suffix = id_path + ".jsonl"
+        source_path = entry.source_path
+        root_prefix = (
+            source_path[: -len(suffix)] if source_path.endswith(suffix) else source_path
+        )
+        keyed.append((entry, CodexSessionIdentity(
+            group_key=(root_prefix, id_path),
+            session_id_path=id_path,
+            session_file=file_name,
+            directory=directory,
+            codex_root=_codex_home_root_from_prefix(root_prefix),
+        )))
+    return _aggregate_codex_sessions_keyed(keyed, speed=speed)
+
+
 def _aggregate_claude_sessions(
     entries: list["_JoinedClaudeEntry"],
     mode: str = "auto",

package/bin/_lib_cache_report.py

@@ -359,9 +359,17 @@ def _aggregate_cache_by_day(
         cost = cost_calculator(entry.model, entry.usage, "auto", entry.cost_usd)
         create_tok = entry.usage.get("cache_creation_input_tokens", 0)
         read_tok = entry.usage.get("cache_read_input_tokens", 0)
-        saved, wasted, net = _compute_entry_cache_dollars(
-            entry.model, create_tok, read_tok, pricing=pricing,
-        )
+        explicit_saved = getattr(entry, "cache_saved_usd", None)
+        explicit_wasted = getattr(entry, "cache_wasted_usd", None)
+        explicit_net = getattr(entry, "cache_net_usd", None)
+        if all(value is not None for value in (explicit_saved, explicit_wasted, explicit_net)):
+            saved, wasted, net = (
+                float(explicit_saved), float(explicit_wasted), float(explicit_net),
+            )
+        else:
+            saved, wasted, net = _compute_entry_cache_dollars(
+                entry.model, create_tok, read_tok, pricing=pricing,
+            )
         models = day_model_buckets.setdefault(day_key, {})
         b = models.setdefault(entry.model, _Bucket())
         b.input_tokens += entry.usage.get("input_tokens", 0)
@@ -792,12 +800,20 @@ def _aggregate_cache_breakdown(
         b.input_tokens += getattr(e, "input_tokens", 0)
         b.cache_creation_tokens += getattr(e, "cache_creation_tokens", 0)
         b.cache_read_tokens += getattr(e, "cache_read_tokens", 0)
-        saved, wasted, net = _compute_entry_cache_dollars(
-            getattr(e, "model", ""),
-            getattr(e, "cache_creation_tokens", 0),
-            getattr(e, "cache_read_tokens", 0),
-            pricing=pricing,
-        )
+        explicit_saved = getattr(e, "cache_saved_usd", None)
+        explicit_wasted = getattr(e, "cache_wasted_usd", None)
+        explicit_net = getattr(e, "cache_net_usd", None)
+        if all(value is not None for value in (explicit_saved, explicit_wasted, explicit_net)):
+            saved, wasted, net = (
+                float(explicit_saved), float(explicit_wasted), float(explicit_net),
+            )
+        else:
+            saved, wasted, net = _compute_entry_cache_dollars(
+                getattr(e, "model", ""),
+                getattr(e, "cache_creation_tokens", 0),
+                getattr(e, "cache_read_tokens", 0),
+                pricing=pricing,
+            )
         b.saved_usd += saved
         b.wasted_usd += wasted
         b.net_usd += net

package/bin/_lib_conversation_retention.py

@@ -1,4 +1,4 @@
-"""#313 P3: 180-day conversation-transcript retention prune kernel.
+"""#313 P3: conversation-transcript retention prune kernel.
 
 Prunes ONLY the re-derivable transcript rows:
   * Claude: ``conversation_messages`` + their ``conversation_file_touches`` /
@@ -63,7 +63,7 @@ def _cutoff_iso(cutoff_utc: dt.datetime) -> str:
     ``...Z`` timestamps.
 
     Second-granular: the sub-second mixed-precision edge at the exact cutoff
-    second is immaterial for a 180-day window — any message wrongly classified
+    second is immaterial for a multi-day retention window — any message wrongly classified
     there is re-derivable from JSONL and the boundary self-corrects on the next
     (daily) prune.
     """
@@ -259,6 +259,26 @@ def _maybe_prune_conversation_retention(
                 except Exception:
                     conn.rollback()
                     raise
+                # Return the freed pages to the OS. On an INCREMENTAL auto-vacuum
+                # cache.db (the default for freshly-created DBs, #313 P3) this
+                # shrinks the file on disk instead of leaving a growing freelist,
+                # so the transcript prune reclaims space automatically without a
+                # manual `cctally db vacuum`; on a legacy auto_vacuum=NONE cache it
+                # is a harmless no-op (those still reclaim via `db vacuum` or a
+                # `cache-sync --rebuild`). Runs OUTSIDE the committed transaction,
+                # still under the maintenance + provider flocks (no concurrent
+                # writer), and best-effort — a reclaim error must never fail the
+                # already-durable prune.
+                if stats.total_rows > 0:
+                    try:
+                        # `.fetchall()` drives the pragma to completion — a bare
+                        # execute() steps it once and reclaims a single page. This
+                        # clears the freelist and drops page_count; the physical
+                        # file shrinks on the next `wal_checkpoint(TRUNCATE)` the
+                        # sync loop already forces (#297).
+                        conn.execute("PRAGMA incremental_vacuum").fetchall()
+                    except sqlite3.Error:
+                        pass
                 return stats
             finally:
                 try: