cctally 1.11.1 → 1.13.0

package/bin/_cctally_db.py

@@ -61,6 +61,7 @@ from __future__ import annotations
 
 import argparse
 import datetime as dt
+import enum
 import json
 import os
 import pathlib
@@ -89,6 +90,13 @@ from _cctally_core import (
     parse_iso_datetime,
 )
 
+# Stats migration 008 needs the same per-entry cost computation used by
+# the live cost-report path. Direct import keeps the kernel single-sourced
+# (no shim drift); _lib_pricing is a stdlib-only leaf module so no cycle
+# risk. Other siblings (_cctally_record, _cctally_dashboard) follow the
+# same direct-import pattern.
+from _lib_pricing import _calculate_entry_cost
+
 
 # Module-level back-ref shim for the one Z-high callable that STAYS in
 # bin/cctally. Resolves `sys.modules['cctally'].X` at CALL TIME (not
@@ -199,6 +207,116 @@ class DowngradeDetected(Exception):
         )
 
 
+class MigrationGateNotMet(Exception):
+    """Migration cannot run yet because a cross-DB prerequisite is unsatisfied.
+
+    Dispatcher treats this as transient: do NOT write to
+    ``migration-errors.log``, do NOT mark the migration as skipped, do
+    NOT render the error banner. Retry on the next open.
+
+    Used by cross-DB migrations whose body needs to verify that a
+    sibling DB's migration has applied AND that downstream ingest has
+    repopulated the data the body depends on. The canonical use case
+    is stats migration 008 (recompute weekly_cost_snapshots) which
+    needs cache migration 001 (dedup wipe) AND a post-wipe
+    ``sync_cache`` cycle before it can safely re-sum cost.
+
+    Spec: docs/superpowers/specs/2026-05-22-ccusage-dedup-parity.md §D4.
+    """
+
+
+@dataclass(frozen=True)
+class UpgradeGateInputs:
+    """Frozen inputs to ``resolve_upgrade_gate`` (cctally-dev#93, spec D1).
+
+    All fields are derived by the thin I/O shell ``_gate_001_post_ingest_completed``;
+    the resolver itself does no I/O.
+    """
+    cache_001_state: str            # "applied" | "skipped" | "pending"
+    walk_complete_since_001: bool   # cache_meta marker present; missing table -> False
+    cache_has_entries: bool         # session_entries non-empty; missing table -> False
+    caller_has_historical_rows: bool
+    disk_state: str                 # "jsonl_present" | "pruned" | "absent" (REASON only)
+    marker_state_readable: bool     # False -> schema_migrations missing OR any read transiently locked
+
+
+class GateAction(enum.Enum):
+    PROCEED = "proceed"   # run the recompute body
+    DEFER = "defer"       # raise MigrationGateNotMet; stays pending, retried next open
+
+
+@dataclass(frozen=True)
+class GateResolution:
+    action: GateAction
+    reason: str
+
+
+def resolve_upgrade_gate(inp: UpgradeGateInputs) -> GateResolution:
+    """Pure decision function — the D3 truth table. First matching row wins.
+
+    Spec: docs/superpowers/specs/2026-05-23-migration-gate-state-machine-design.md D1/D3.
+    """
+    # Row 1 — marker state unreadable (missing schema_migrations or transient lock).
+    if not inp.marker_state_readable:
+        return GateResolution(
+            GateAction.DEFER,
+            "cache.db migration state unreadable (no schema_migrations table yet, "
+            "or transiently locked); retry on next open.",
+        )
+    # Row 2 — 001 not applied.
+    if inp.cache_001_state == "pending":
+        return GateResolution(
+            GateAction.DEFER,
+            "cache.db migration 001_dedup_highest_wins not yet applied; run any "
+            "JSONL-reading command (e.g. `cctally weekly`) once, or "
+            "`cctally db skip 001_dedup_highest_wins` to defer.",
+        )
+    # Rows 3/4 — 001 skipped.
+    if inp.cache_001_state == "skipped":
+        if inp.caller_has_historical_rows:
+            return GateResolution(
+                GateAction.DEFER,
+                "cache.db migration 001_dedup_highest_wins is skipped while historical "
+                "rows remain; deferring to avoid recomputing over stale pre-dedup "
+                "session_entries. Run `cctally db unskip 001_dedup_highest_wins` then "
+                "any JSONL-reading command once.",
+            )
+        return GateResolution(
+            GateAction.PROCEED,
+            "001 skipped and no historical rows to protect; proceed (body no-ops).",
+        )
+    # cache_001_state == "applied" below.
+    # Row 5 — nothing to protect.
+    if not inp.caller_has_historical_rows:
+        return GateResolution(
+            GateAction.PROCEED,
+            "no historical rows to protect; proceed (body no-ops).",
+        )
+    # Row 6 — complete, non-empty post-001 cache.
+    if inp.walk_complete_since_001 and inp.cache_has_entries:
+        return GateResolution(
+            GateAction.PROCEED,
+            "complete, non-empty post-001 walk observed; proceed.",
+        )
+    # Row 7 — DEFER; reason branches on disk_state (decision is identical).
+    if not inp.walk_complete_since_001:
+        if inp.disk_state == "jsonl_present":
+            reason = ("post-001 ingest walk not yet complete; run any JSONL-reading "
+                      "command (e.g. `cctally weekly`) once and retry.")
+        elif inp.disk_state == "pruned":
+            reason = ("no complete post-001 walk and projects/ holds no JSONL; restore "
+                      "the JSONL or `cctally db skip` this migration to accept stale "
+                      "aggregates.")
+        else:  # absent
+            reason = ("no complete post-001 walk and no projects/ dir resolves; check "
+                      "CLAUDE_CONFIG_DIR or `cctally db skip` this migration.")
+    else:  # walk complete but cache empty (rebuild/truncation over pruned disk)
+        reason = ("cache is empty after a rebuild over pruned disk; refusing to zero "
+                  "historical aggregates. Restore the JSONL or `cctally db skip` this "
+                  "migration.")
+    return GateResolution(GateAction.DEFER, reason)
+
+
 def _make_migration_decorator(registry: list[Migration], db_label: str, name: str):
     """Internal helper — builds the @stats_migration / @cache_migration decorators.
 
@@ -330,8 +448,17 @@ def _run_pending_migrations(
         auto-open on the UPDATE statements, so subsequent handler
         ``conn.execute("BEGIN")`` calls start cleanly.
       - Fresh install (schema_migrations just CREATE'd, zero rows
-        post-bootstrap) → stamp every migration applied without invoking
-        handlers.
+        post-bootstrap, AND the DB's primary data table is empty or
+        absent) → stamp every migration applied without invoking
+        handlers. The data-emptiness probe (D1) defends against the
+        pre-framework upgrade case where cache.db was populated by
+        a pre-v1.12.0 build that wrote ``session_entries`` without
+        ever creating ``schema_migrations`` — pre-fix that landscape
+        was falsely classified as fresh and stamped every migration
+        applied without running its handler, indefinitely persisting
+        the buggy summed-tokens dedup. Probe tables:
+        ``stats.db → weekly_cost_snapshots``,
+        ``cache.db → session_entries``.
       - Per migration: handler raises ``Exception`` → log + BREAK
         (Codex P1 #3 — the FIRST failure halts the registry walk so
         later migrations never see partial-prior state). ``BaseException``
@@ -443,10 +570,56 @@ def _run_pending_migrations(
         row[0] for row in conn.execute("SELECT name FROM schema_migrations_skipped").fetchall()
     }
 
-    # Fresh install: schema_migrations was just CREATE'd this open AND
-    # has zero rows post-bootstrap. (If bootstrap renamed pre-existing
-    # rows, those rows now appear in `applied`; not a fresh install.)
+    # D1 — fresh install requires BOTH "schema_migrations table did not
+    # exist" AND "the DB's primary data table is empty (or absent)".
+    # Pre-fix this check was schema_migrations-only: a pre-v1.12.0
+    # cache.db (populated session_entries but no schema_migrations
+    # table — the framework didn't exist for cache.db before this
+    # release) was falsely classified as a fresh install. The
+    # fresh-install branch then stamped EVERY pending migration's
+    # marker WITHOUT invoking its handler, so the cache 001
+    # dedup-highest-wins migration silently skipped on every upgrading
+    # user. The handler is the entire fix — skipping it leaves the
+    # buggy summed-tokens data in place indefinitely.
+    #
+    # Probe tables per DB — ANY non-empty probe table means "not fresh":
+    #   * stats.db → every table the recompute migrations (008/009/010)
+    #     touch: ``weekly_cost_snapshots`` (008), ``five_hour_blocks``
+    #     (009), ``percent_milestones`` (010). Probing ONLY
+    #     ``weekly_cost_snapshots`` was a gap: a legacy stats.db with live
+    #     5h history but no weekly snapshots (e.g. a user who only ever ran
+    #     5h-window commands) was falsely classified as a fresh install,
+    #     so 009 got stamped-without-running and its historical 5h totals
+    #     stayed inflated forever — the exact bug this patch set exists to
+    #     fix. Probe all three so non-emptiness in ANY recompute target
+    #     forces the handlers to run.
+    #   * cache.db → ``session_entries`` (the table 001 wipes; non-empty
+    #     means real session history under the buggy old dedup rule).
+    # Probe table absent → treat as empty (a brand-new DB hasn't run
+    # the schema CREATEs yet, so the data table doesn't exist; that's a
+    # genuine fresh install).
     fresh_install = (not schema_migrations_existed) and len(applied) == 0
+    if fresh_install:
+        probe_tables = {
+            "stats.db": (
+                "weekly_cost_snapshots",
+                "five_hour_blocks",
+                "percent_milestones",
+            ),
+            "cache.db": ("session_entries",),
+        }.get(db_label, ())
+        for probe_table in probe_tables:
+            # _probe_table_nonempty centralizes the "is there data here?"
+            # probe (cctally-dev#93): a present-and-non-empty table means
+            # data exists from a pre-framework write path, so the DB is
+            # NOT a fresh install — run every handler normally so the
+            # upgrading user gets the fix. A missing table contributes no
+            # signal (genuine pre-CREATE fresh install); keep checking the
+            # rest. Transient BUSY/LOCKED and any other OperationalError
+            # propagate (corrupt DB / IO error).
+            if _probe_table_nonempty(conn, probe_table):
+                fresh_install = False
+                break
 
     now_iso = now_utc_iso()
     for m in registry:
@@ -464,6 +637,40 @@ def _run_pending_migrations(
             m.handler(conn)
             _clear_migration_error_log_entries(qualified_name)
             applied.add(m.name)
+        except MigrationGateNotMet as gate_exc:
+            # Transient cross-DB gating: do NOT log to migration-errors.log,
+            # do NOT mark as skipped, do NOT render the error banner. The
+            # migration stays pending; the next open re-tries it. Spec
+            # docs/superpowers/specs/2026-05-22-ccusage-dedup-parity.md §D4.
+            #
+            # P2 — defensive log-entry clear, symmetric with the success
+            # branch above. A prior run may have logged a hard failure
+            # for this migration; if the underlying state has since
+            # shifted such that the migration now gate-defers (e.g. a
+            # prereq vanished mid-cycle, or the handler was rewritten to
+            # gate where it previously raised), the stale error log
+            # entry would persist forever and the banner would mislead.
+            # Clearing here keeps the contract crisp: any non-failure
+            # outcome (apply OR gate-defer) clears any prior failure log
+            # for this migration's qualified name.
+            _clear_migration_error_log_entries(qualified_name)
+            if os.environ.get("CCTALLY_DEBUG"):
+                eprint(
+                    f"[migration {qualified_name}] deferred: {gate_exc}"
+                )
+            # D2 — ``continue``, NOT ``break``. A gate-defer leaves the DB
+            # in a fully-consistent prior state (the handler raised before
+            # touching anything, or rolled back its own BEGIN); later
+            # registry entries can legitimately attempt to run. The
+            # all-applied predicate below uses ``applied | skipped``, so
+            # this gated migration's absence from both sets keeps
+            # ``user_version`` from advancing — a future open re-tries
+            # the gated migration even if every later one succeeded.
+            #
+            # Contrast the Exception branch below, which DOES break: a
+            # generic handler exception may have left a partial transaction
+            # state, so later migrations should not see it.
+            continue
         except Exception as exc:
             _log_migration_error(
                 name=qualified_name,
@@ -815,6 +1022,11 @@ _BANNER_SUPPRESSED_COMMANDS = frozenset({
     "doctor",          # consolidates migration + update banner state into its
                        # own report; double-printing the banner would duplicate
                        # findings doctor already surfaces structurally.
+    "blocks",          # stdout-formatted table replacing `ccusage blocks`;
+                       # stderr noise pollutes the visually-aligned report and
+                       # confuses scripted pipelines piping via `2>&1`.
+                       # Banner still lands on the next interactive non-report
+                       # command (`report`, `weekly`, `percent-breakdown`, etc.).
     # Note: `setup` carve-out handled separately (only suppressed w/o --status).
     # Note: `dashboard` carve-out handled separately (banner printed in cmd_dashboard).
 })
@@ -1679,6 +1891,1443 @@ def _migration_observed_pre_credit_pct(conn: sqlite3.Connection) -> None:
         raise
 
 
+# === Region 7b: Cross-DB migration gate helper (ccusage-parity prep) ===
+
+def _gate_001_post_ingest_completed(
+    cache_ro: sqlite3.Connection,
+    claude_projects_dirs: pathlib.Path | list[pathlib.Path],
+    *,
+    data_present: bool = False,
+) -> None:
+    """Thin I/O shell over the pure ``resolve_upgrade_gate`` resolver.
+
+    Derives the six ``UpgradeGateInputs`` from cache.db reads + the
+    on-disk JSONL state, calls the resolver (the D3 truth table), and
+    raises ``MigrationGateNotMet(reason)`` when the resolution is
+    ``DEFER``. All decision logic lives in the resolver; this function
+    does only I/O. (cctally-dev#93, spec D1/D3.)
+
+    Input derivation
+    ----------------
+      * ``cache_001_state`` — ``"applied"`` if ``schema_migrations``
+        carries ``001_dedup_highest_wins``; else ``"skipped"`` if
+        ``schema_migrations_skipped`` carries it; else ``"pending"``.
+      * ``walk_complete_since_001`` — the ``cache_meta``
+        ``claude_ingest_walk_complete`` marker is present. ``sync_cache``
+        writes it only after a clean full walk that began with 001 already
+        applied, and cache 001 / rebuild / truncation clear it atomically
+        (spec D5). This REPLACES the old ``session_files.last_ingested_at
+        >= 001.applied_at_utc`` proof — the marker is the single
+        ingest-completeness signal now. A missing ``cache_meta`` table
+        composes as ``False`` (not a hard defer).
+      * ``cache_has_entries`` — ``session_entries`` is non-empty, read
+        via an inline ``SELECT 1 FROM session_entries LIMIT 1``
+        (deliberately NOT ``_probe_table_nonempty``, which propagates
+        transient errors by design — the shell must CATCH a transient
+        BUSY/LOCKED here and flip ``marker_state_readable=False`` so the
+        resolver DEFERs at row 1; the helper cannot do that). Together
+        with ``walk_complete`` this closes the round-3 partial-walk
+        false-pass and the P1 empty-cache rebuild-over-pruned-disk case
+        (spec D3): row 6 requires BOTH.
+      * ``caller_has_historical_rows`` — caller-supplied ``data_present``;
+        each migration passes its OWN scoped row set (008
+        ``bool(snapshot_rows)``, etc.) so a no-op upgrade isn't wedged.
+      * ``disk_state`` — ``"absent"`` (no projects dirs resolve),
+        ``"jsonl_present"`` (≥1 ``*.jsonl`` under any root), or
+        ``"pruned"`` (dirs resolve but hold no JSONL). REASON-only — it
+        never changes the decision, only the row-7 operator guidance text.
+      * ``marker_state_readable`` — ``False`` only when the
+        ``schema_migrations`` read is missing-table (cache.db never ran
+        the dispatcher) OR any of the reads is transiently
+        ``BUSY``/``LOCKED``/``CANTOPEN`` (per-read split, spec P2#1). The
+        resolver maps this to row 1 DEFER (retry next open).
+
+    Parameters
+    ----------
+    cache_ro
+        Read-only sqlite3 connection to ``cache.db``. Cross-DB migrations
+        open the sibling DB read-only inside their handler body via
+        ``sqlite3.connect(f"file:{path}?mode=ro", uri=True)``. Exposed as
+        an explicit parameter so tests can inject a tmp-path connection
+        without touching ``HOME``.
+    claude_projects_dirs
+        Either a single ``pathlib.Path`` (legacy single-rooted form) or a
+        ``list[pathlib.Path]`` of projects/ directories. The disk-state
+        classification ORs across every root. Production callers resolve
+        this via ``_resolve_projects_dirs_for_gate`` (env-aware); an empty
+        list is the legitimate ``disk_state="absent"`` topology and is
+        handled by the resolver (no per-migration default-dir fallback).
+    data_present
+        Keyword-only (defaults ``False`` for the 2-arg test callers).
+        Whether the caller still holds historical rows it is about to
+        recompute from ``session_entries``.
+
+    Spec: docs/superpowers/specs/2026-05-23-migration-gate-state-machine-design.md D1/D3.
+    """
+    # Normalize to list so the disk-state classification can OR across
+    # roots. Accepting a bare Path keeps the legacy test signature working.
+    if isinstance(claude_projects_dirs, pathlib.Path):
+        projects_dirs = [claude_projects_dirs]
+    else:
+        projects_dirs = list(claude_projects_dirs)
+
+    marker_state_readable = True
+
+    # --- cache 001 state (schema_migrations / schema_migrations_skipped) ---
+    # "applied" wins; else "skipped"; else "pending". A missing
+    # ``schema_migrations`` table (cache.db never ran the dispatcher) or a
+    # transient BUSY/LOCKED on the read flips ``marker_state_readable`` so
+    # the resolver defers at row 1 instead of guessing.
+    cache_001_state = "pending"
+    try:
+        if cache_ro.execute(
+            "SELECT 1 FROM schema_migrations WHERE name=?",
+            ("001_dedup_highest_wins",),
+        ).fetchone() is not None:
+            cache_001_state = "applied"
+        else:
+            try:
+                if cache_ro.execute(
+                    "SELECT 1 FROM schema_migrations_skipped WHERE name=?",
+                    ("001_dedup_highest_wins",),
+                ).fetchone() is not None:
+                    cache_001_state = "skipped"
+            except sqlite3.OperationalError as exc:
+                if _is_transient_sqlite_error(exc):
+                    marker_state_readable = False
+                elif not _is_no_such_table_error(exc):
+                    raise
+                # no_such_table on _skipped -> treat as "not skipped" (pending)
+    except sqlite3.OperationalError as exc:
+        if _is_transient_sqlite_error(exc) or _is_no_such_table_error(exc):
+            marker_state_readable = False
+        else:
+            raise
+
+    # --- walk_complete (cache_meta marker presence) ---
+    # The single ingest-completeness signal (spec D5). ``sync_cache`` writes
+    # it only after a clean full walk begun with 001 applied; cache 001 /
+    # rebuild / truncation clear it atomically. Missing table -> walk✗.
+    walk_complete = False
+    if marker_state_readable:
+        try:
+            walk_complete = cache_ro.execute(
+                "SELECT 1 FROM cache_meta WHERE key='claude_ingest_walk_complete'"
+            ).fetchone() is not None
+        except sqlite3.OperationalError as exc:
+            if _is_transient_sqlite_error(exc):
+                marker_state_readable = False
+            elif not _is_no_such_table_error(exc):
+                raise
+
+    # --- cache_has_entries (session_entries non-empty) ---
+    cache_has_entries = False
+    if marker_state_readable:
+        try:
+            cache_has_entries = cache_ro.execute(
+                "SELECT 1 FROM session_entries LIMIT 1"
+            ).fetchone() is not None
+        except sqlite3.OperationalError as exc:
+            if _is_transient_sqlite_error(exc):
+                marker_state_readable = False
+            elif not _is_no_such_table_error(exc):
+                raise
+
+    # --- disk_state (REASON-only; never changes the decision) ---
+    if not projects_dirs:
+        disk_state = "absent"
+    elif any(any(p.glob("**/*.jsonl")) for p in projects_dirs):
+        disk_state = "jsonl_present"
+    else:
+        disk_state = "pruned"
+
+    resolution = resolve_upgrade_gate(UpgradeGateInputs(
+        cache_001_state=cache_001_state,
+        walk_complete_since_001=walk_complete,
+        cache_has_entries=cache_has_entries,
+        caller_has_historical_rows=bool(data_present),
+        disk_state=disk_state,
+        marker_state_readable=marker_state_readable,
+    ))
+    if resolution.action is GateAction.DEFER:
+        raise MigrationGateNotMet(resolution.reason)
+
+
+def _is_no_such_table_error(exc: sqlite3.OperationalError) -> bool:
+    """Return True iff ``exc`` is SQLite's "no such table" error.
+
+    Two-signal predicate to defend against future SQLite version drift
+    in the error-message format:
+
+      * Substring match on the lowercased message (stable for ~20 years).
+      * ``exc.sqlite_errorcode == SQLITE_ERROR (1)`` (Python 3.11+;
+        cctally's floor is 3.13 per ``__min_python_version__``). The
+        ``getattr(..., None) in (None, 1)`` form degrades gracefully if
+        the attribute is ever missing — substring-only on legacy Python.
+
+    Centralized so the gate shell's cache-state reads and the migration
+    table-existence checks share the same "table missing" predicate.
+    """
+    return (
+        "no such table" in str(exc).lower()
+        and getattr(exc, "sqlite_errorcode", None) in (None, 1)
+    )
+
+
+def _probe_table_nonempty(conn: sqlite3.Connection, table: str) -> bool:
+    """True iff ``table`` exists and has at least one row. Missing table -> False.
+
+    Single source for the 'is there data here?' probe shared by the dispatcher
+    fresh-install fast-path and the gate shell's cache_has_entries input
+    (cctally-dev#93). Transient BUSY/LOCKED propagates to the caller.
+    """
+    try:
+        return conn.execute(f"SELECT 1 FROM {table} LIMIT 1").fetchone() is not None
+    except sqlite3.OperationalError as exc:
+        if _is_no_such_table_error(exc):
+            return False
+        raise
+
+
+def _is_transient_sqlite_error(exc: sqlite3.OperationalError) -> bool:
+    """Return True iff ``exc`` is a transient SQLite condition the gate
+    can legitimately defer on.
+
+    Covers:
+
+      * ``SQLITE_BUSY``    (errorcode 5)  — another writer holds the DB.
+      * ``SQLITE_LOCKED``  (errorcode 6)  — a table within the DB is locked.
+      * ``SQLITE_CANTOPEN``(errorcode 14) — the DB file doesn't exist /
+        can't be opened (e.g. unlinked mid-flight between an ``exists()``
+        probe and ``sqlite3.connect``, or never created yet).
+
+    Gate-defer semantics (G4 + G5): a transient error means the gate
+    state is genuinely unknown at this instant, NOT that the migration
+    has failed. The dispatcher should translate to ``MigrationGateNotMet``
+    rather than logging to ``migration-errors.log`` (which would render
+    a misleading error banner for a self-healing condition).
+
+    Belt-and-suspenders predicate: matches on ``sqlite_errorcode`` first
+    (stable Python 3.11+ API), with a substring fallback for the rare
+    case where the attribute is missing (legacy Python builds; the
+    ``getattr(..., None) in (...)`` form degrades to substring-only).
+    """
+    code = getattr(exc, "sqlite_errorcode", None)
+    if code in (5, 6, 14):
+        return True
+    if code is None:
+        msg = str(exc).lower()
+        # Stable SQLite error-message fragments for the three transient
+        # codes; substring-only fallback when sqlite_errorcode is absent.
+        if (
+            "database is locked" in msg
+            or "database table is locked" in msg
+            or "unable to open database" in msg
+        ):
+            return True
+    return False
+
+
+# === Region 7b2: Eager cache-migration trigger (V4 — same-invocation 008 apply) ===
+
+
+def _apply_cache_schema(conn: sqlite3.Connection) -> None:
+    """Single source of cache.db's schema (cctally-dev#93, spec D4).
+
+    ``_cctally()``-free so both ``open_cache_db`` (in _cctally_cache.py, which
+    already imports _cctally_db) and ``_eagerly_apply_cache_migrations`` (here)
+    can call it without an import cycle. Idempotent (CREATE ... IF NOT EXISTS +
+    ``add_column_if_missing``). Does NOT run the dispatcher and does NOT include
+    the Codex ``last_total_tokens`` ALTER, which carries a one-time purge
+    side-effect that stays in ``open_cache_db``: a future cross-DB migration
+    that needs a Codex column on the eager-apply path must revisit that
+    exception. The eager-apply path provably never touches Codex (cache 001 +
+    the 008/009/010 RO joins are all Claude-side), so the column's absence here
+    cannot surface a ``no such column``.
+    """
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS session_files (
+            path             TEXT PRIMARY KEY,
+            size_bytes       INTEGER NOT NULL,
+            mtime_ns         INTEGER NOT NULL,
+            last_byte_offset INTEGER NOT NULL,
+            last_ingested_at TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS session_entries (
+            id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+            source_path         TEXT    NOT NULL,
+            line_offset         INTEGER NOT NULL,
+            timestamp_utc       TEXT    NOT NULL,
+            model               TEXT    NOT NULL,
+            msg_id              TEXT,
+            req_id              TEXT,
+            input_tokens        INTEGER NOT NULL DEFAULT 0,
+            output_tokens       INTEGER NOT NULL DEFAULT 0,
+            cache_create_tokens INTEGER NOT NULL DEFAULT 0,
+            cache_read_tokens   INTEGER NOT NULL DEFAULT 0,
+            usage_extra_json    TEXT,
+            cost_usd_raw        REAL
+        );
+        CREATE INDEX IF NOT EXISTS idx_entries_timestamp
+            ON session_entries(timestamp_utc);
+        CREATE INDEX IF NOT EXISTS idx_entries_source
+            ON session_entries(source_path);
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_entries_dedup
+            ON session_entries(msg_id, req_id)
+            WHERE msg_id IS NOT NULL AND req_id IS NOT NULL;
+
+        CREATE TABLE IF NOT EXISTS codex_session_files (
+            path             TEXT PRIMARY KEY,
+            size_bytes       INTEGER NOT NULL,
+            mtime_ns         INTEGER NOT NULL,
+            last_byte_offset INTEGER NOT NULL,
+            last_ingested_at TEXT NOT NULL,
+            last_session_id  TEXT,
+            last_model       TEXT
+        );
+        CREATE TABLE IF NOT EXISTS codex_session_entries (
+            id                       INTEGER PRIMARY KEY AUTOINCREMENT,
+            source_path              TEXT    NOT NULL,
+            line_offset              INTEGER NOT NULL,
+            timestamp_utc            TEXT    NOT NULL,
+            session_id               TEXT    NOT NULL,
+            model                    TEXT    NOT NULL,
+            input_tokens             INTEGER NOT NULL DEFAULT 0,
+            cached_input_tokens      INTEGER NOT NULL DEFAULT 0,
+            output_tokens            INTEGER NOT NULL DEFAULT 0,
+            reasoning_output_tokens  INTEGER NOT NULL DEFAULT 0,
+            total_tokens             INTEGER NOT NULL DEFAULT 0,
+            UNIQUE(source_path, line_offset)
+        );
+        CREATE INDEX IF NOT EXISTS idx_codex_entries_timestamp
+            ON codex_session_entries(timestamp_utc);
+        CREATE INDEX IF NOT EXISTS idx_codex_entries_session
+            ON codex_session_entries(session_id);
+        CREATE INDEX IF NOT EXISTS idx_codex_entries_source
+            ON codex_session_entries(source_path);
+
+        CREATE TABLE IF NOT EXISTS cache_meta (
+            key   TEXT PRIMARY KEY,
+            value TEXT
+        );
+        """
+    )
+    # Inline migration: add session_id / project_path columns to session_files
+    # if they're missing. These were added for A2 `session` subcommand metadata;
+    # populated lazily in sync_cache() / _ensure_session_files_row().
+    add_column_if_missing(conn, "session_files", "session_id", "TEXT")
+    add_column_if_missing(conn, "session_files", "project_path", "TEXT")
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_session_files_session_id "
+        "ON session_files(session_id)"
+    )
+
+
+def _eagerly_apply_cache_migrations() -> None:
+    """Open cache.db so its pending migrations (notably
+    ``001_dedup_highest_wins``) apply BEFORE stats migration 008's gate
+    check.
+
+    Why
+    ---
+    On the very first ``cctally`` invocation post-upgrade against a
+    populated stats.db, the natural call order is:
+
+      1. ``cmd_<reporting>`` opens stats.db via ``open_db()`` (runs the
+         stats dispatcher → stats 008 fires).
+      2. (Maybe) ``cmd_<jsonl-reader>`` opens cache.db via
+         ``open_cache_db()`` (runs the cache dispatcher → cache 001
+         fires).
+
+    Step 1 happens BEFORE step 2 — and for commands that read stats.db
+    only (e.g. ``cctally report`` without ``--sync-current``), step 2
+    NEVER happens. So stats 008's gate finds no 001 marker in
+    cache.db, raises ``MigrationGateNotMet``, the dispatcher defers,
+    and ``report`` proceeds with stale ``weekly_cost_snapshots``
+    forever (until the user happens to run a JSONL-reading command).
+
+    This helper inverts the dependency: stats 008 itself triggers
+    cache.db's dispatcher BEFORE checking the gate. After this returns,
+    cache 001's marker is present (``cache_001_state="applied"``). But
+    an eager-applied 001 WIPES the cache and clears the ``cache_meta``
+    ``claude_ingest_walk_complete`` marker (spec D5) — and the gate
+    (``_gate_001_post_ingest_completed`` → ``resolve_upgrade_gate``) now
+    keys ingest-completeness on that walk-complete marker, not on a
+    post-001 ``session_files`` row. So the gate DEFERs on this first
+    invocation until a subsequent clean ``sync_cache`` re-walks the
+    on-disk JSONL and re-establishes the marker. For users with no
+    JSONL on disk (or no projects/ dir at all), ``disk_state="absent"``
+    lets the resolver PROCEED (no data to lose) — 008 completes in the
+    SAME invocation. For users with JSONL, the operator's next
+    JSONL-reading command runs ``sync_cache``, which sets the
+    walk-complete marker → the invocation after that runs 008
+    successfully. That's worst-case one extra invocation instead of
+    unbounded deferral.
+
+    Lock ordering
+    -------------
+    Stats and cache are SEPARATE SQLite files with SEPARATE WAL locks.
+    ``open_cache_db()`` does not touch stats.db. Stats.db is currently
+    inside the migration dispatcher (the 008 handler hasn't started a
+    ``BEGIN`` on the stats connection yet — that happens later in the
+    body, AFTER this helper returns). No deadlock potential.
+
+    Failure modes
+    -------------
+    If cache.db can't be opened (rare — disk full, permission denied,
+    truly missing parent dir), let the exception propagate to the
+    stats 008 body's ``try``, where the existing
+    ``_is_transient_sqlite_error`` predicate translates it to
+    ``MigrationGateNotMet``. The dispatcher then defers — symmetric
+    with G4/G5 behavior on the read-only gate connection.
+
+    Implementation note
+    -------------------
+    We open cache.db here directly (corruption-recovery connect + PRAGMAs +
+    schema + dispatcher) rather than delegate to
+    ``_cctally_cache.open_cache_db`` because the latter calls ``_cctally()``
+    (a back-reference into ``sys.modules['cctally']``) which is set up by the
+    bin/cctally entrypoint but absent in test harnesses that exercise the
+    stats handler directly. The schema is applied via the shared
+    ``_apply_cache_schema`` helper (cctally-dev#93, D4) — the SAME source
+    ``open_cache_db`` uses — so the two paths can no longer drift (the prior
+    hand-curated inline subset was the origin of the ``no such column:
+    sf.project_path`` landmine). The only divergence from ``open_cache_db``
+    is the Codex ``last_total_tokens`` ALTER + purge, which is deliberately
+    Claude-irrelevant and provably never reached by this path (see
+    ``_apply_cache_schema``'s docstring + spec D4/P1#3).
+    """
+    cache_db_path = _cctally_core.CACHE_DB_PATH
+    _cctally_core.APP_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        conn = sqlite3.connect(cache_db_path)
+        conn.execute("SELECT 1").fetchone()
+    except sqlite3.DatabaseError as exc:
+        # Corruption recovery mirrors the contract in
+        # ``_cctally_cache.open_cache_db``: cache.db is fully
+        # re-derivable from JSONL, so we unlink + recreate. Stay quiet
+        # under tests — the dispatcher's gate-defer machinery handles
+        # the case where this fails outright.
+        eprint(f"[cache] corrupt cache DB ({exc}); recreating")
+        try:
+            cache_db_path.unlink()
+        except FileNotFoundError:
+            pass
+        conn = sqlite3.connect(cache_db_path)
+    try:
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA busy_timeout=5000")
+        # Apply the shared cache.db schema (cctally-dev#93, D4). This is the
+        # SAME source ``open_cache_db`` uses, including ``session_id`` /
+        # ``project_path`` on session_files (009 joins ``sf.project_path`` on
+        # the RO gate connection bootstrapped here; column resolution happens
+        # at prepare time even with zero rows, so an absent column would raise
+        # ``no such column: sf.project_path``) and the new ``cache_meta``
+        # table. The Codex ``last_total_tokens`` ALTER stays out of the shared
+        # helper and is intentionally not applied here (Claude-only path; see
+        # ``_apply_cache_schema``'s docstring + spec D4/P1#3).
+        _apply_cache_schema(conn)
+        # Dispatcher (cache.db side). Runs every pending cache
+        # migration, including ``001_dedup_highest_wins``. Idempotent —
+        # if 001 has already applied, this is a fast-path return.
+        _run_pending_migrations(
+            conn, registry=_CACHE_MIGRATIONS, db_label="cache.db",
+        )
+    finally:
+        # Close immediately so the WAL writer lock (if any) is
+        # released before the stats 008 body opens its read-only
+        # gate connection.
+        conn.close()
+
+
+# === Region 7c: Cache migration 001_dedup_highest_wins (ccusage-parity fix) ===
+
+
+def _recompute_banner_should_emit(
+    *,
+    data_present: bool,
+) -> bool:
+    """Shared banner-suppression gate for recompute-style migrations
+    (cache 001, stats 008, 009, 010). Combines two conditions:
+
+      (a) ``data_present`` — caller checked that the migration has
+          actual rows to recompute. Empty-data topologies (most
+          fresh-install upgrades, every golden fixture without seed
+          rows) make the migration body a marker-only no-op; the
+          banner would announce work that isn't happening. Caller
+          owns this check because each migration scopes "data" to a
+          different table (``session_entries`` for 001,
+          ``weekly_cost_snapshots`` for 008, ``five_hour_blocks`` for
+          009, ``percent_milestones`` for 010).
+
+      (b) ``sys.argv[1]`` NOT in ``_BANNER_SUPPRESSED_COMMANDS``. Hot
+          paths (``record-usage``, ``hook-tick``, ``sync-week``,
+          ``cache-sync``, ``refresh-usage``) machine-consume stderr;
+          ``tui`` / ``dashboard`` take over the screen; ``db`` and
+          ``doctor`` surface migration state in their own reports;
+          ``blocks`` is a stdout-formatted table whose stderr noise
+          confuses scripted pipelines. Banner still lands on the
+          next interactive non-report command (``report``,
+          ``weekly``, ``percent-breakdown``, etc.) once on upgrade.
+
+    Returns True iff the banner should be printed. Defensive: any
+    error reading ``sys.argv`` falls back to "don't print" — silence
+    is the safer side under uncertainty (worst case, a heavy user
+    misses the one-line announcement; not a correctness regression).
+
+    SW5-extended — replaces the per-migration ad-hoc banner gates
+    that drifted between 001 (which checked argv1 in suppression
+    list) and 008/009/010 (which only checked data-table emptiness).
+    The asymmetry caused ``cctally blocks`` to emit 009's banner
+    even when ``record-usage`` would not — surfaced by
+    ``floor-band-trap`` golden-terminal.txt drift.
+    """
+    if not data_present:
+        return False
+    try:
+        argv1 = sys.argv[1] if len(sys.argv) > 1 else None
+    except Exception:
+        argv1 = None
+    if argv1 in _BANNER_SUPPRESSED_COMMANDS:
+        return False
+    return True
+
+
+def _001_banner_should_emit(conn: sqlite3.Connection) -> bool:
+    """SW5 — gate cache migration 001's banner. Thin shim around the
+    shared ``_recompute_banner_should_emit`` helper: probes
+    ``session_entries`` for non-emptiness, then defers to the shared
+    suppression-argv1 check.
+
+    Kept as a named function (rather than inlined at the call site)
+    because cache migration 001's data check requires a defensive
+    ``sqlite3.Error`` swallow — the migration runs early and the
+    table may not yet exist on certain ALTER-mid-upgrade topologies.
+    Stats 008/009/010 don't need this swallow because their gate
+    runs after the schema is fully bootstrapped.
+    """
+    try:
+        row = conn.execute(
+            "SELECT 1 FROM session_entries LIMIT 1"
+        ).fetchone()
+    except sqlite3.Error:
+        return False
+    return _recompute_banner_should_emit(data_present=row is not None)
+
+
+@cache_migration("001_dedup_highest_wins")
+def _001_dedup_highest_wins(conn: sqlite3.Connection) -> None:
+    """One-time re-ingest of session_entries with corrected msg_id+req_id dedup.
+
+    The previous INSERT OR IGNORE kept the streaming-intermediate row of each
+    (msg_id, req_id) pair (output_tokens=1, no ``speed`` field) and rejected
+    the post-stream finalization row (output_tokens=N, ``speed='standard'``).
+    The winner's data is not recoverable from session_entries alone — it was
+    never inserted under the old rule. We wipe ``session_entries`` +
+    ``session_files`` so the next ``sync_cache`` re-reads JSONL under the new
+    ON CONFLICT DO UPDATE clause (highest-token-total wins, ``speed`` set
+    breaks ties).
+
+    Codex tables (``codex_session_entries``, ``codex_session_files``) are NOT
+    touched — the bug is Claude-side only.
+
+    Spec: docs/superpowers/specs/2026-05-22-ccusage-dedup-parity.md §I2.
+
+    Invariants:
+      * Marker row INSERTed inside the same BEGIN/COMMIT as the DELETEs.
+      * Empty session_entries (no JSONL ingested yet) still writes the
+        marker — table-emptiness is not the sentinel (CLAUDE.md "Pricing
+        & schema"). A truly fresh install short-circuits earlier via the
+        dispatcher's ``fresh_install`` fast-path; this handler only sees
+        the post-shipped-empty case where the cache.db schema and
+        migration tables already exist but ``session_entries`` is empty.
+      * Migration handler does NOT call ``_log_migration_error`` /
+        ``_clear_migration_error_log_entries``; the dispatcher owns that
+        surface (CLAUDE.md "Migration error sentinel is uniform").
+
+    SW5 — Banner suppression. Two gates compose:
+
+      (a) ``session_entries`` non-emptiness — if the table is empty (most
+          fresh-install upgrade topologies + every golden fixture), the
+          handler's body is a marker-only no-op and the banner has
+          nothing to announce. Mirrors the snapshot-rows gate on
+          migration 008's banner.
+
+      (b) ``sys.argv[1]`` in ``_BANNER_SUPPRESSED_COMMANDS`` — the same
+          set the dispatcher consults for its post-failure banner. Hot
+          paths (record-usage, hook-tick, sync-week, cache-sync,
+          refresh-usage, tui, dashboard, db, doctor) machine-consume
+          stderr or take over the screen, so the banner has nowhere
+          safe to land. Migration handlers don't receive ``args``, so
+          we read ``sys.argv`` directly — `argparse` hasn't run yet at
+          handler time anyway. Interactive surfaces (``report``,
+          ``weekly``, ``percent-breakdown``, etc.) still see it once.
+    """
+    if _001_banner_should_emit(conn):
+        eprint(
+            "[cctally] Re-ingesting Claude session history with "
+            "corrected dedup (one-time; may take 10-30s depending on "
+            "JSONL volume)..."
+        )
+    # D3 — BEGIN IMMEDIATE so the destructive DELETEs are race-guarded,
+    # not just the marker insert. The dispatcher snapshots the applied
+    # set ONCE before its registry walk (``_run_pending_migrations``),
+    # so two concurrent openers (e.g. dashboard + CLI on the same
+    # cache.db) can BOTH classify 001 as pending and BOTH enter this
+    # handler. With a plain ``BEGIN`` (deferred), each acquires the
+    # write lock only on its first DELETE: the loser would wait for the
+    # winner's COMMIT, then DELETE — wiping the rows the winner's
+    # subsequent ``sync_cache`` already reingested, leaving the cache
+    # partially rebuilt until another full sync. ``BEGIN IMMEDIATE``
+    # grabs the write lock up front, so the loser blocks here BEFORE
+    # touching any data; once it acquires the lock the winner's marker
+    # is already committed, and the in-transaction re-check below turns
+    # the loser's body into a no-op. The marker INSERT stays
+    # ``INSERT OR IGNORE`` as a belt-and-suspenders against an
+    # IntegrityError banner.
+    conn.execute("BEGIN IMMEDIATE")
+    try:
+        already_applied = conn.execute(
+            "SELECT 1 FROM schema_migrations WHERE name = ? LIMIT 1",
+            ("001_dedup_highest_wins",),
+        ).fetchone() is not None
+        if already_applied:
+            # A concurrent opener won the race and already wiped +
+            # stamped 001 (and may already be repopulating via
+            # sync_cache). Re-running the DELETEs here would destroy that
+            # reingested data. Commit the empty IMMEDIATE transaction
+            # (releases the write lock) and return — the marker is
+            # present, so the dispatcher records us as applied.
+            conn.commit()
+            return
+        conn.execute("DELETE FROM session_entries")
+        conn.execute("DELETE FROM session_files")
+        # Clear the walk-complete sentinel atomically with the wipe
+        # (cctally-dev#93, D5/D2): a wiped session_entries must never coexist
+        # with a "complete walk" marker. The end-of-loop write in sync_cache
+        # re-establishes it only after a subsequent clean walk. In production
+        # ``_apply_cache_schema`` always creates ``cache_meta`` before the
+        # dispatcher fires 001 (open_cache_db / _eagerly_apply_cache_migrations
+        # both apply the schema first), so the table is present. Tolerate its
+        # absence defensively (a pre-cache_meta cache.db invoked through the
+        # handler directly, e.g. older per-migration goldens): a missing table
+        # means there is no stale marker to clear, so the no-op is correct.
+        # The "no such table" prepare-time error never opened a write, so the
+        # enclosing BEGIN IMMEDIATE transaction stays intact for the stamp +
+        # commit below.
+        try:
+            conn.execute("DELETE FROM cache_meta WHERE key='claude_ingest_walk_complete'")
+        except sqlite3.OperationalError as exc:
+            if not _is_no_such_table_error(exc):
+                raise
+        conn.execute(
+            "INSERT OR IGNORE INTO schema_migrations (name, applied_at_utc) "
+            "VALUES (?, ?)",
+            ("001_dedup_highest_wins", now_utc_iso()),
+        )
+        conn.commit()
+    except Exception:
+        conn.rollback()
+        raise
+
+
+# === Region 7d: Stats migration 008_recompute_weekly_cost_snapshots_dedup_fix ===
+
+@stats_migration("008_recompute_weekly_cost_snapshots_dedup_fix")
+def _008_recompute_weekly_cost_snapshots_dedup_fix(
+    conn: sqlite3.Connection,
+) -> None:
+    """Recompute ``weekly_cost_snapshots.cost_usd`` from the now-corrected
+    ``session_entries``. Gated on cache migration 001 having applied AND
+    ``sync_cache`` having repopulated ``session_entries`` since.
+
+    Scope: only rows with ``mode='auto'`` AND ``project IS NULL``.
+    ``mode='display'`` rows preserve a user-supplied cost from a prior
+    ``calculate`` run (``docs/commands/sync-week.md``); per-project
+    snapshots have aggregation boundaries this fix doesn't know about.
+    Both are left untouched.
+
+    Legacy rows with ``range_start_iso IS NULL`` or
+    ``range_end_iso IS NULL`` are skipped (their pre-fix value stays);
+    CHANGELOG calls this out as the one exception to "post-fix
+    ``report`` matches ``weekly``."
+
+    Cross-DB plumbing
+    -----------------
+    Opens ``cache.db`` read-only via the ``file:?mode=ro`` URI form. We
+    do NOT ``ATTACH DATABASE`` — the existing transactional isolation
+    (write side on ``conn`` inside ``BEGIN``/``COMMIT``, read side on a
+    separate read-only connection) is the cleanest design and matches
+    how Task 3's gate helper already wires it.
+
+    Timestamp comparison
+    --------------------
+    ``range_start_iso`` and ``range_end_iso`` originate from
+    ``insert_cost_snapshot`` → ``parse_iso_datetime(...).isoformat()``,
+    which keeps the offset of whatever the caller passed (typically
+    ``+00:00`` from ``week_start_at`` canonicalization, but
+    ``parse_iso_datetime`` returns ``parsed.astimezone()`` so naive
+    inputs end up host-local). ``session_entries.timestamp_utc`` is
+    written via ``entry.timestamp.astimezone(dt.timezone.utc).isoformat()``
+    in ``sync_cache`` — canonical UTC ISO with ``+00:00`` offset.
+    Both sides are normalized at the Python boundary through
+    ``_canonical_utc_iso_for_index`` so plain lex compare against
+    ``timestamp_utc`` hits ``idx_entries_timestamp``. Mirrors the
+    canonicalization that ``iter_entries`` /
+    ``get_claude_session_entries`` apply to user-facing queries in
+    ``bin/_cctally_cache.py``.
+
+    Spec: docs/superpowers/specs/2026-05-22-ccusage-dedup-parity.md §I3.
+    """
+    # Banner is gated on "we actually have rows to recompute" via the
+    # shared ``_recompute_banner_should_emit`` helper (composed below).
+    # The all-empty no-op case (most upgrade-time fresh-install
+    # topologies, and most goldens with no snapshot rows) skips the
+    # banner so we don't pollute thousands of test goldens /
+    # per-command stderr with a benign one-line announcement. Heavy
+    # users with 52+ snapshots still see it once.
+    #
+    # ``_open_cache_ro_with_gate_defer`` (shared with 009/010) eagerly
+    # applies cache.db's dispatcher (V4: ensures cache migration 001's
+    # marker is in place even on stats-only invocations) then opens
+    # cache.db RO with the G4/G5 transient-defer translation baked in.
+    cache_ro = _open_cache_ro_with_gate_defer()
+    try:
+        # Resolve projects dirs via the shared helper (mirrors 009/010).
+        # Empty list returned only when NO projects/ dir resolves under
+        # any env-configured or default root; the resolver classifies
+        # that as ``disk_state="absent"`` and decides accordingly.
+        projects_dirs = _resolve_projects_dirs_for_gate()
+
+        # F3 scope: only rows we have authority over (see docstring).
+        snapshot_rows = conn.execute(
+            "SELECT id, range_start_iso, range_end_iso "
+            "FROM weekly_cost_snapshots "
+            "WHERE mode = 'auto' AND project IS NULL"
+        ).fetchall()
+
+        # The gate is now a pure state machine (cctally-dev#93): the old
+        # inline G3 fail-closed block and the defensive default-dir
+        # fallback are gone. An empty ``projects_dirs`` is the legitimate
+        # ``disk_state="absent"`` topology — the resolver DEFERS (row 7)
+        # when ``data_present`` and PROCEEDS (row 5, body no-ops) when
+        # there's nothing to protect, with the operator-guidance reason
+        # text baked into the resolver. No body-level recompute guard
+        # (spec D7): the recompute below computes every in-range value
+        # from surviving ``session_entries``, INCLUDING to $0 — the
+        # wholesale-zeroing protection lives entirely in the gate.
+        _gate_001_post_ingest_completed(
+            cache_ro, projects_dirs, data_present=bool(snapshot_rows),
+        )
+
+        # Banner gated on "we actually have eligible rows to recompute"
+        # AND "active subcommand is not in _BANNER_SUPPRESSED_COMMANDS"
+        # — composed via the shared ``_recompute_banner_should_emit``
+        # helper that 001/008/009/010 all funnel through. Empty-
+        # snapshot topologies (most goldens, fresh-install upgrades)
+        # plus hot/scripted paths (`blocks`, `record-usage`, etc.)
+        # stay quiet. Heavy users invoking interactive non-report
+        # commands (52+ weekly snapshots) still see it once.
+        if _recompute_banner_should_emit(data_present=bool(snapshot_rows)):
+            eprint(
+                "[cctally] Recomputing weekly_cost_snapshots from "
+                "corrected session_entries (one-time; may take 30-60s "
+                "on heavy histories)..."
+            )
+
+        conn.execute("BEGIN")
+        try:
+            for snap_id, range_start_iso, range_end_iso in snapshot_rows:
+                if range_start_iso is None or range_end_iso is None:
+                    # Legacy row written before range_*_iso columns
+                    # existed. Skip (not crash) — leaves the snapshot at
+                    # its pre-fix value; CHANGELOG calls this out.
+                    continue
+                # V1 — closed interval ``<=`` matches the production
+                # writer (``iter_entries`` in bin/_cctally_cache.py: lex
+                # ``timestamp_utc >= ? AND timestamp_utc <= ?``). The
+                # migration's prior half-open ``<`` end silently excluded
+                # any ``session_entries`` row whose ``timestamp_utc``
+                # equalled the snapshot's ``range_end_iso`` boundary —
+                # an edge with positive probability on subscription-week
+                # boundaries where Claude Code's status-line tick can
+                # land an entry exactly on the reset instant. After this
+                # fix, the migration's recompute is byte-for-byte
+                # symmetric with every subsequent ``sync-week`` row that
+                # gets written through ``compute_week_cost`` →
+                # ``iter_entries`` — so R-DEDUP2 in
+                # ``bin/cctally-reconcile-test`` no longer needs to
+                # caveat the divergence.
+                # Canonicalize range bounds to the same UTC ISO shape
+                # ``session_entries.timestamp_utc`` carries on disk so
+                # lex compare hits ``idx_entries_timestamp`` instead of
+                # SCANning. See ``_canonical_utc_iso_for_index`` for the
+                # EXPLAIN QUERY PLAN rationale; mirrors
+                # ``iter_entries`` in bin/_cctally_cache.py.
+                entries = cache_ro.execute(
+                    "SELECT model, input_tokens, output_tokens, "
+                    "cache_create_tokens, cache_read_tokens, "
+                    "usage_extra_json, cost_usd_raw "
+                    "FROM session_entries "
+                    "WHERE timestamp_utc >= ? AND timestamp_utc <= ?",
+                    (
+                        _canonical_utc_iso_for_index(range_start_iso),
+                        _canonical_utc_iso_for_index(range_end_iso),
+                    ),
+                ).fetchall()
+                total = 0.0
+                for model, i, o, cc, cr, extras_json, raw in entries:
+                    usage = {
+                        "input_tokens": i,
+                        "output_tokens": o,
+                        "cache_creation_input_tokens": cc,
+                        "cache_read_input_tokens": cr,
+                    }
+                    if extras_json:
+                        usage.update(json.loads(extras_json))
+                    total += _calculate_entry_cost(
+                        model, usage, mode="auto", cost_usd=raw,
+                    )
+                conn.execute(
+                    "UPDATE weekly_cost_snapshots "
+                    "SET cost_usd = ? WHERE id = ?",
+                    (total, snap_id),
+                )
+            # D3 — INSERT OR IGNORE for race safety. Mirrors the
+            # convention applied to every other production migration
+            # and the matching change to cache migration 001.
+            conn.execute(
+                "INSERT OR IGNORE INTO schema_migrations "
+                "(name, applied_at_utc) VALUES (?, ?)",
+                (
+                    "008_recompute_weekly_cost_snapshots_dedup_fix",
+                    now_utc_iso(),
+                ),
+            )
+            conn.execute("COMMIT")
+        except Exception:
+            conn.execute("ROLLBACK")
+            raise
+    finally:
+        cache_ro.close()
+
+
+# === Region 7e: Shared cross-DB gate setup for 008/009/010 ==================
+
+
+def _open_cache_ro_with_gate_defer() -> sqlite3.Connection:
+    """Shared bootstrap for stats migrations 008/009/010 that recompute
+    from cache.db's ``session_entries``.
+
+    Eagerly applies cache.db's dispatcher (so cache 001's marker is in
+    place even on stats-only invocations), then opens cache.db read-only
+    for the gate check. Either step's failure modes translate to
+    ``MigrationGateNotMet`` so the dispatcher's defer machinery handles
+    them cleanly (no migration-error banner). Mirrors the V4 + G4/G5
+    fixes baked into 008's body.
+
+    Returns the read-only cache.db connection. Caller is responsible for
+    ``.close()``.
+    """
+    try:
+        _eagerly_apply_cache_migrations()
+    except sqlite3.OperationalError as exc:
+        if _is_transient_sqlite_error(exc):
+            raise MigrationGateNotMet(
+                "cache.db not yet initialized or transiently locked; "
+                "run any JSONL-reading command (e.g. `cctally weekly`) "
+                "once and retry."
+            ) from None
+        raise
+
+    cache_db_path = _cctally_core.CACHE_DB_PATH
+    try:
+        cache_ro = sqlite3.connect(
+            f"file:{cache_db_path}?mode=ro", uri=True,
+        )
+    except sqlite3.OperationalError as exc:
+        if _is_transient_sqlite_error(exc):
+            raise MigrationGateNotMet(
+                "cache.db not yet initialized or transiently locked; "
+                "run any JSONL-reading command (e.g. `cctally weekly`) "
+                "once and retry."
+            ) from None
+        raise
+
+    # Pin a SINGLE consistent cache.db snapshot for the whole recompute
+    # (cctally-dev#93 review). cache.db is WAL (bin/_cctally_cache.py:
+    # `PRAGMA journal_mode=WAL`), and Python's sqlite3 only auto-BEGINs
+    # before DML — every read on this RO connection would otherwise run
+    # in autocommit, so each `cache_ro.execute(SELECT …)` could observe a
+    # NEWER `session_entries` snapshot if `record-usage`/`hook-tick`/
+    # `cache-sync` committed between loop iterations. That lets one
+    # migration run recompute different rows from different cache states
+    # and still stamp its schema marker (an internally-inconsistent
+    # recompute). An explicit deferred BEGIN starts a read transaction
+    # whose snapshot is locked at the first read (the gate's
+    # schema_migrations probe) and held until COMMIT/ROLLBACK; in WAL the
+    # reader never blocks the writer, so concurrent ingests still
+    # proceed — they just land in a newer WAL frame this transaction
+    # won't see. The caller's `finally: cache_ro.close()` ends the
+    # transaction. The recompute writes target stats.db (`conn`), NOT
+    # this connection, so a still-open read txn here never blocks them.
+    try:
+        cache_ro.execute("BEGIN")
+    except sqlite3.OperationalError as exc:
+        cache_ro.close()
+        if _is_transient_sqlite_error(exc):
+            raise MigrationGateNotMet(
+                "cache.db not yet initialized or transiently locked; "
+                "run any JSONL-reading command (e.g. `cctally weekly`) "
+                "once and retry."
+            ) from None
+        raise
+    return cache_ro
+
+
+def _resolve_projects_dirs_for_gate() -> list[pathlib.Path]:
+    """Shared resolver for stats migrations 008/009/010 gate checks.
+
+    Returns the list of Claude projects/ dirs to feed to
+    ``_gate_001_post_ingest_completed``. Mirrors 008's resolution chain:
+    env-aware resolver first, defensive fallback to
+    ``CLAUDE_PROJECTS_DIR`` when the resolver returns ``[]`` but the
+    default exists on disk (covers test-time monkeypatch overrides).
+
+    Empty list returned only when NO projects/ dir resolves under any
+    env-configured or default root. An empty list is the legitimate
+    ``disk_state="absent"`` topology — callers no longer fail-closed
+    inline (Task 5 removed every caller's G3 block); they unconditionally
+    delegate the empty-list decision to the resolver, which DEFERs at
+    row 7 when historical rows remain and PROCEEDs at row 5 otherwise.
+    """
+    projects_dirs = _cctally_core._resolve_claude_projects_dirs()
+    if not projects_dirs and _cctally_core.CLAUDE_PROJECTS_DIR.is_dir():
+        projects_dirs = [_cctally_core.CLAUDE_PROJECTS_DIR]
+    return projects_dirs
+
+
+def _canonical_utc_iso_for_index(value: str) -> str:
+    """Normalize an ISO-8601 timestamp string to the canonical UTC form
+    that ``session_entries.timestamp_utc`` stores on disk, so a lex
+    comparison against the indexed column hits ``idx_entries_timestamp``
+    instead of degrading to a full SCAN.
+
+    Why this exists
+    ---------------
+    ``session_entries.timestamp_utc`` is always written via
+    ``entry.timestamp.astimezone(dt.timezone.utc).isoformat()`` in
+    ``sync_cache`` (bin/_cctally_cache.py — the only writer). On disk
+    every row therefore looks like ``2026-05-01T12:34:56.789012+00:00``.
+
+    Migration 008/009/010's range bounds arrive in mixed shapes:
+
+      * ``weekly_cost_snapshots.range_start_iso`` /
+        ``range_end_iso`` — host-local-offset bytes if the writer's
+        ``parse_iso_datetime`` saw a naive input (returns
+        ``parsed.astimezone()``) or ``+00:00`` when fed canonical
+        week-start instants.
+      * ``five_hour_blocks.block_start_at`` — host-local-offset
+        bytes (same ``parse_iso_datetime`` chokepoint).
+      * ``five_hour_blocks.last_observed_at_utc`` — always
+        ``Z``-suffixed (``now_utc_iso()``).
+      * ``percent_milestones.week_start_at`` /
+        ``captured_at_utc`` — same mix.
+
+    The prior implementation wrapped both sides of the WHERE in
+    ``unixepoch(...)`` to absorb the offset mix. That made the
+    comparison correct but defeated ``idx_entries_timestamp`` —
+    ``EXPLAIN QUERY PLAN`` rendered ``SCAN session_entries`` on every
+    range slice. On a heavy user's cache.db (10k+ rows) that turned
+    the one-time recompute from "30-60s" into multiple minutes.
+
+    By canonicalizing at the Python boundary into the same shape the
+    writer uses, both sides of ``WHERE timestamp_utc >= ? AND
+    timestamp_utc <= ?`` carry the same offset notation and lex
+    compare is correct. Index hit:
+    ``SEARCH session_entries USING INDEX idx_entries_timestamp
+    (timestamp_utc>? AND timestamp_utc<?)``.
+
+    Matches the canonicalization pattern in
+    ``bin/_cctally_cache.py``'s ``iter_entries`` /
+    ``get_claude_session_entries`` (the production read paths).
+    """
+    return parse_iso_datetime(
+        value, "migration-range-bound",
+    ).astimezone(dt.timezone.utc).isoformat()
+
+
+# === Region 7f: Stats migration 009_recompute_five_hour_blocks_dedup_fix ====
+
+@stats_migration("009_recompute_five_hour_blocks_dedup_fix")
+def _009_recompute_five_hour_blocks_dedup_fix(
+    conn: sqlite3.Connection,
+) -> None:
+    """Recompute ``five_hour_blocks.total_*`` + rollup-children
+    (``five_hour_block_models`` / ``five_hour_block_projects``) from the
+    now-corrected ``session_entries``. Gated on cache migration 001
+    having applied AND ``sync_cache`` having re-walked the on-disk JSONL
+    since (the ``cache_meta`` ``claude_ingest_walk_complete`` marker is
+    present) — the shared gate (``_gate_001_post_ingest_completed`` →
+    ``resolve_upgrade_gate``), same as 008.
+
+    Scope (B1)
+    ----------
+    The 5h block writer (``maybe_update_five_hour_block``) only recomputes
+    totals for the CURRENTLY ACTIVE block — closed historical blocks
+    keep their pre-dedup totals forever. ``five_hour_block_models`` /
+    ``five_hour_block_projects`` are recompute-every-tick on the active
+    block too. Without this migration, every historical 5h block + its
+    rollup children stays at the inflated pre-dedup numbers.
+
+    This migration walks EVERY row in ``five_hour_blocks`` (active and
+    closed), recomputes ``total_*`` from the corrected
+    ``session_entries`` over ``[block_start_at, last_observed_at_utc]``,
+    and replace-alls the per-(window, model) and per-(window, project)
+    rollup children. Mirrors the live writer's algorithm in
+    ``maybe_update_five_hour_block`` byte-for-byte — same closed
+    interval, same ``unixepoch()`` cross-offset normalization, same
+    ``LEFT JOIN session_files`` for project attribution, same
+    ``project_path or '(unknown)'`` sentinel.
+
+    Timestamp comparison
+    --------------------
+    ``block_start_at`` is stored with the host's display offset
+    (``parse_iso_datetime`` returns ``parsed.astimezone()``;
+    ``+03:00`` on a non-UTC host); ``last_observed_at_utc`` is
+    ``Z``-suffixed (``now_utc_iso()``); ``session_entries.timestamp_utc``
+    is canonical UTC ISO (``+00:00``) on disk. Both range bounds
+    normalize through ``_canonical_utc_iso_for_index`` at the Python
+    boundary so plain lex compare against ``timestamp_utc`` hits
+    ``idx_entries_timestamp`` — same shape as 008/010 and the
+    user-facing read paths in ``bin/_cctally_cache.py``.
+
+    Closed interval (V1)
+    --------------------
+    ``<=`` matches the live writer's ``get_claude_session_entries``
+    predicate (``timestamp >= ? AND timestamp <= ?``). A pre-fix
+    half-open ``<`` would silently exclude any session_entries row
+    whose ``timestamp_utc`` exactly equalled a block's
+    ``last_observed_at_utc`` — an edge with positive probability since
+    ``last_observed_at_utc`` IS the timestamp of some session-line tick.
+
+    Banner
+    ------
+    Gated on ``five_hour_blocks`` non-emptiness so test goldens and
+    fresh-install upgrades stay quiet (mirrors 008's ``snapshot_rows``
+    gate). Heavy users with dozens of historical blocks still see it
+    once.
+
+    Spec: docs/superpowers/specs/2026-05-22-ccusage-dedup-parity.md §I3 (B1).
+    """
+    cache_ro = _open_cache_ro_with_gate_defer()
+    try:
+        projects_dirs = _resolve_projects_dirs_for_gate()
+
+        block_rows = conn.execute(
+            "SELECT id, five_hour_window_key, block_start_at, "
+            "last_observed_at_utc "
+            "FROM five_hour_blocks"
+        ).fetchall()
+
+        # Pure state-machine gate (cctally-dev#93): the inline G3
+        # fail-closed block and the default-dir fallback are gone; an
+        # empty ``projects_dirs`` is the ``disk_state="absent"`` topology
+        # the resolver handles (row 7 DEFER when data_present, row 5
+        # PROCEED otherwise). No body-level recompute guard (spec D7) —
+        # every in-range block recomputes from surviving
+        # ``session_entries``, including to $0.
+        _gate_001_post_ingest_completed(
+            cache_ro, projects_dirs, data_present=bool(block_rows),
+        )
+
+        # SW5-style banner gating via the shared
+        # ``_recompute_banner_should_emit`` helper: only print when
+        # block_rows is non-empty AND the active subcommand is not in
+        # ``_BANNER_SUPPRESSED_COMMANDS`` (notably ``blocks``, whose
+        # stdout-formatted table would otherwise get prefixed by a
+        # stderr announcement — surfaced by floor-band-trap fixture).
+        if _recompute_banner_should_emit(data_present=bool(block_rows)):
+            eprint(
+                "[cctally] Recomputing closed 5h block totals after "
+                "dedup fix (one-time; may take 30-60s on heavy "
+                "histories)..."
+            )
+
+        conn.execute("BEGIN")
+        try:
+            for (
+                block_id, window_key, block_start_at,
+                last_observed_at_utc,
+            ) in block_rows:
+                # Walk session_entries over [block_start, last_observed]
+                # joined to session_files for project_path attribution.
+                # NULL session_files.project_path collapses to
+                # '(unknown)' at the bucket layer — same sentinel as the
+                # live writer (_compute_block_totals at
+                # bin/_cctally_record.py).
+                # Canonicalize range bounds to the same UTC ISO shape
+                # ``session_entries.timestamp_utc`` carries on disk so
+                # lex compare hits ``idx_entries_timestamp`` instead of
+                # SCANning. See ``_canonical_utc_iso_for_index`` for the
+                # EXPLAIN QUERY PLAN rationale; mirrors
+                # ``get_claude_session_entries`` in
+                # bin/_cctally_cache.py.
+                entries = cache_ro.execute(
+                    "SELECT se.model, se.input_tokens, se.output_tokens, "
+                    "       se.cache_create_tokens, se.cache_read_tokens, "
+                    "       se.usage_extra_json, se.cost_usd_raw, "
+                    "       sf.project_path "
+                    "FROM session_entries se "
+                    "LEFT JOIN session_files sf "
+                    "  ON sf.path = se.source_path "
+                    "WHERE se.timestamp_utc >= ? "
+                    "  AND se.timestamp_utc <= ?",
+                    (
+                        _canonical_utc_iso_for_index(block_start_at),
+                        _canonical_utc_iso_for_index(
+                            last_observed_at_utc
+                        ),
+                    ),
+                ).fetchall()
+
+                total_in = 0
+                total_out = 0
+                total_cc = 0
+                total_cr = 0
+                total_cost = 0.0
+                by_model: dict[str, dict[str, Any]] = {}
+                by_project: dict[str, dict[str, Any]] = {}
+                for (
+                    model, in_t, out_t, cc_t, cr_t,
+                    extras_json, raw_cost, project_path,
+                ) in entries:
+                    usage = {
+                        "input_tokens": in_t,
+                        "output_tokens": out_t,
+                        "cache_creation_input_tokens": cc_t,
+                        "cache_read_input_tokens": cr_t,
+                    }
+                    if extras_json:
+                        usage.update(json.loads(extras_json))
+                    cost = _calculate_entry_cost(
+                        model, usage, mode="auto", cost_usd=raw_cost,
+                    )
+                    total_in += int(in_t or 0)
+                    total_out += int(out_t or 0)
+                    total_cc += int(cc_t or 0)
+                    total_cr += int(cr_t or 0)
+                    total_cost += cost
+
+                    proj_key = project_path or "(unknown)"
+                    for bucket_key, bucket_dict in (
+                        (model, by_model),
+                        (proj_key, by_project),
+                    ):
+                        b = bucket_dict.setdefault(
+                            bucket_key,
+                            {
+                                "input_tokens": 0,
+                                "output_tokens": 0,
+                                "cache_create_tokens": 0,
+                                "cache_read_tokens": 0,
+                                "cost_usd": 0.0,
+                                "entry_count": 0,
+                            },
+                        )
+                        b["input_tokens"] += int(in_t or 0)
+                        b["output_tokens"] += int(out_t or 0)
+                        b["cache_create_tokens"] += int(cc_t or 0)
+                        b["cache_read_tokens"] += int(cr_t or 0)
+                        b["cost_usd"] += cost
+                        b["entry_count"] += 1
+
+                conn.execute(
+                    "UPDATE five_hour_blocks "
+                    "SET total_input_tokens = ?, "
+                    "    total_output_tokens = ?, "
+                    "    total_cache_create_tokens = ?, "
+                    "    total_cache_read_tokens = ?, "
+                    "    total_cost_usd = ? "
+                    "WHERE id = ?",
+                    (
+                        total_in, total_out, total_cc, total_cr,
+                        total_cost, block_id,
+                    ),
+                )
+
+                # Replace-all per-(window, model) and per-(window,
+                # project) rollup-children. Same pattern as the live
+                # writer (DELETE WHERE five_hour_window_key = ? +
+                # bulk INSERT). DELETE keyed on window_key (NOT
+                # block_id) so the replace-all sweeps any orphans from
+                # earlier parent rebuilds.
+                conn.execute(
+                    "DELETE FROM five_hour_block_models "
+                    "WHERE five_hour_window_key = ?",
+                    (int(window_key),),
+                )
+                if by_model:
+                    conn.executemany(
+                        "INSERT INTO five_hour_block_models "
+                        "(block_id, five_hour_window_key, model, "
+                        " input_tokens, output_tokens, "
+                        " cache_create_tokens, cache_read_tokens, "
+                        " cost_usd, entry_count) "
+                        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                        [
+                            (
+                                int(block_id),
+                                int(window_key),
+                                model,
+                                b["input_tokens"],
+                                b["output_tokens"],
+                                b["cache_create_tokens"],
+                                b["cache_read_tokens"],
+                                b["cost_usd"],
+                                b["entry_count"],
+                            )
+                            for model, b in by_model.items()
+                        ],
+                    )
+
+                conn.execute(
+                    "DELETE FROM five_hour_block_projects "
+                    "WHERE five_hour_window_key = ?",
+                    (int(window_key),),
+                )
+                if by_project:
+                    conn.executemany(
+                        "INSERT INTO five_hour_block_projects "
+                        "(block_id, five_hour_window_key, "
+                        " project_path, "
+                        " input_tokens, output_tokens, "
+                        " cache_create_tokens, cache_read_tokens, "
+                        " cost_usd, entry_count) "
+                        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                        [
+                            (
+                                int(block_id),
+                                int(window_key),
+                                proj,
+                                b["input_tokens"],
+                                b["output_tokens"],
+                                b["cache_create_tokens"],
+                                b["cache_read_tokens"],
+                                b["cost_usd"],
+                                b["entry_count"],
+                            )
+                            for proj, b in by_project.items()
+                        ],
+                    )
+
+            conn.execute(
+                "INSERT OR IGNORE INTO schema_migrations "
+                "(name, applied_at_utc) VALUES (?, ?)",
+                (
+                    "009_recompute_five_hour_blocks_dedup_fix",
+                    now_utc_iso(),
+                ),
+            )
+            conn.execute("COMMIT")
+        except Exception:
+            conn.execute("ROLLBACK")
+            raise
+    finally:
+        cache_ro.close()
+
+
+# === Region 7g: Stats migration 010_recompute_percent_milestones_dedup_fix ==
+
+@stats_migration("010_recompute_percent_milestones_dedup_fix")
+def _010_recompute_percent_milestones_dedup_fix(
+    conn: sqlite3.Connection,
+) -> None:
+    """Recompute ``percent_milestones.cumulative_cost_usd`` +
+    ``marginal_cost_usd`` from the now-corrected ``session_entries``.
+    Gated on cache migration 001 having applied AND ``sync_cache``
+    having repopulated ``session_entries`` since.
+
+    Scope (B2)
+    ----------
+    ``percent_milestones`` is normally write-once forward-only (per
+    "Write-once milestones" gotcha): the cost-at-moment-of-crossing is
+    captured at insert time and never recomputed. After the upstream
+    dedup fix, every historical milestone's ``cumulative_cost_usd`` is
+    inflated by the same factor that inflated
+    ``weekly_cost_snapshots`` — keeping them as-recorded would leave
+    ``percent-breakdown`` showing systematically higher numbers than
+    the corrected weekly cost for the same window.
+
+    This migration is the one-time scoped exception. For each row:
+
+      * ``cumulative_cost_usd`` = SUM cost over
+        ``[week_start_at_iso, captured_at_utc]`` from the corrected
+        ``session_entries``. Sentinel for week_start: prefer
+        ``week_start_at`` (ISO); fall back to ``week_start_date``
+        normalized to midnight UTC if ``week_start_at IS NULL``
+        (legacy rows; same shape as ``weekly_cost_snapshots``).
+      * ``marginal_cost_usd`` = ``cumulative - prior.cumulative``,
+        where ``prior`` is the immediately lower
+        ``percent_threshold`` for the same ``(week_start_date,
+        reset_event_id)``. First milestone of a week has
+        ``marginal == cumulative``.
+
+    Forward-going behavior is unchanged — new crossings keep their
+    "write-once at moment of crossing" semantics. This migration only
+    rewrites the historical rows once.
+
+    Timestamp comparison
+    --------------------
+    Range bounds normalize through ``_canonical_utc_iso_for_index``
+    at the Python boundary so plain lex compare against
+    ``timestamp_utc`` hits ``idx_entries_timestamp``. Same rule as
+    008/009 and the user-facing read paths in
+    ``bin/_cctally_cache.py``.
+
+    Closed interval (V1)
+    --------------------
+    Same ``<=`` rule as 008/009 — matches the live writer's
+    ``iter_entries`` predicate.
+
+    Banner
+    ------
+    Gated on ``percent_milestones`` non-emptiness (symmetric with
+    008's ``snapshot_rows`` and 009's ``block_rows`` gates).
+
+    Spec: docs/superpowers/specs/2026-05-22-ccusage-dedup-parity.md §I3 (B2).
+    """
+    cache_ro = _open_cache_ro_with_gate_defer()
+    try:
+        projects_dirs = _resolve_projects_dirs_for_gate()
+
+        milestone_rows = conn.execute(
+            "SELECT id, week_start_date, week_start_at, captured_at_utc, "
+            "       percent_threshold, reset_event_id "
+            "FROM percent_milestones "
+            "ORDER BY week_start_date ASC, reset_event_id ASC, "
+            "         percent_threshold ASC, id ASC"
+        ).fetchall()
+
+        # Pure state-machine gate (cctally-dev#93): no inline G3 block, no
+        # default-dir fallback. The resolver classifies an empty
+        # ``projects_dirs`` as ``disk_state="absent"`` and decides (row 7
+        # DEFER when data_present, row 5 PROCEED otherwise). No body-level
+        # recompute guard and NO segment guard (spec D7): every milestone
+        # recomputes from surviving ``session_entries`` — a zero-entry
+        # segment correctly yields cumulative=0/marginal=0, kept isolated
+        # by the ``seg_key`` partitioning of the marginal chain.
+        _gate_001_post_ingest_completed(
+            cache_ro, projects_dirs, data_present=bool(milestone_rows),
+        )
+
+        # SW5-style banner gating via the shared
+        # ``_recompute_banner_should_emit`` helper: only print when
+        # milestone_rows is non-empty AND the active subcommand is not
+        # in ``_BANNER_SUPPRESSED_COMMANDS``. Mirrors 008/009.
+        if _recompute_banner_should_emit(
+            data_present=bool(milestone_rows)
+        ):
+            eprint(
+                "[cctally] Recomputing percent milestone costs after "
+                "dedup fix (one-time; may take 30-60s on heavy "
+                "histories)..."
+            )
+
+        conn.execute("BEGIN")
+        try:
+            # Track per-(week_start_date, reset_event_id) the cumulative
+            # cost of the immediately-prior threshold in the SAME segment
+            # so we can derive marginal = cumulative - prior.cumulative.
+            # The ORDER BY week_start_date, reset_event_id, threshold
+            # above is what makes this single-pass safe.
+            prev_cum_by_segment: dict[tuple[str, int], float] = {}
+
+            for (
+                mid, week_start_date, week_start_at, captured_at_utc,
+                threshold, reset_event_id,
+            ) in milestone_rows:
+                # week_start_at preferred; legacy rows fall back to
+                # week_start_date treated as midnight UTC (same shape
+                # weekly_cost_snapshots writers use when week_start_at
+                # is absent).
+                if week_start_at:
+                    range_start_iso = week_start_at
+                elif week_start_date:
+                    range_start_iso = f"{week_start_date}T00:00:00+00:00"
+                else:
+                    # Truly unrecoverable boundary — skip the row, leave
+                    # cumulative_cost as-recorded. CHANGELOG notes
+                    # parallel to 008's NULL range_*_iso skip.
+                    continue
+
+                # Canonicalize range bounds to the same UTC ISO shape
+                # ``session_entries.timestamp_utc`` carries on disk so
+                # lex compare hits ``idx_entries_timestamp`` instead of
+                # SCANning. See ``_canonical_utc_iso_for_index`` for the
+                # EXPLAIN QUERY PLAN rationale; mirrors 008/009.
+                entries = cache_ro.execute(
+                    "SELECT model, input_tokens, output_tokens, "
+                    "       cache_create_tokens, cache_read_tokens, "
+                    "       usage_extra_json, cost_usd_raw "
+                    "FROM session_entries "
+                    "WHERE timestamp_utc >= ? AND timestamp_utc <= ?",
+                    (
+                        _canonical_utc_iso_for_index(range_start_iso),
+                        _canonical_utc_iso_for_index(captured_at_utc),
+                    ),
+                ).fetchall()
+
+                cumulative = 0.0
+                for (
+                    model, i, o, cc, cr, extras_json, raw,
+                ) in entries:
+                    usage = {
+                        "input_tokens": i,
+                        "output_tokens": o,
+                        "cache_creation_input_tokens": cc,
+                        "cache_read_input_tokens": cr,
+                    }
+                    if extras_json:
+                        usage.update(json.loads(extras_json))
+                    cumulative += _calculate_entry_cost(
+                        model, usage, mode="auto", cost_usd=raw,
+                    )
+
+                seg_key = (week_start_date, int(reset_event_id or 0))
+                prior_cum = prev_cum_by_segment.get(seg_key)
+                marginal = (
+                    cumulative
+                    if prior_cum is None
+                    else cumulative - prior_cum
+                )
+                prev_cum_by_segment[seg_key] = cumulative
+
+                conn.execute(
+                    "UPDATE percent_milestones "
+                    "SET cumulative_cost_usd = ?, "
+                    "    marginal_cost_usd = ? "
+                    "WHERE id = ?",
+                    (cumulative, marginal, mid),
+                )
+
+            conn.execute(
+                "INSERT OR IGNORE INTO schema_migrations "
+                "(name, applied_at_utc) VALUES (?, ?)",
+                (
+                    "010_recompute_percent_milestones_dedup_fix",
+                    now_utc_iso(),
+                ),
+            )
+            conn.execute("COMMIT")
+        except Exception:
+            conn.execute("ROLLBACK")
+            raise
+    finally:
+        cache_ro.close()
+
+
 # === Region 8: Test-only migration registration (was bin/cctally:12086-12140) ===
 
 # ──────────────────────────────────────────────────────────────────────