cctally 1.28.0 → 1.29.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.29.0] - 2026-06-08
+
+### Added
+- **Dashboard conversation viewer.** New full-screen Conversations workspace in `cctally dashboard`: a cost-aware transcript reader (rendered markdown, per-turn cost, collapsible thinking/tool/sidechain detail) plus cross-session full-text search that jumps to the highlighted message. Loopback-only by default; LAN needs `dashboard.expose_transcripts`. Backend shipped earlier; this adds the front end.
+
+### Fixed
+- **The local web dashboard server now tears down on a single SIGINT/SIGTERM unconditionally, closing a rare lost-wakeup race in its shutdown path.** `cctally dashboard` blocked its main thread on a `threading.Event.wait()` woken only by the SIGINT/SIGTERM handler calling `stop.set()` — and CPython can lose a single signal that races the entry into `Event.wait()` (the Python-level handler never runs, or `set()`'s `notify_all()` fires before the waiter registers), so ~0.04–0.07% of single signals failed to wake the loop and recovery needed a second signal (a timed-poll does *not* fix it: on the miss the flag is never set, so it polls forever). The wait now uses a self-pipe wakeup fd (`signal.set_wakeup_fd` + a `select` on the read end): CPython's C-level signal trampoline writes the signum to the pipe on every delivery — before and independent of the Python-level handler running — so the first signal always unblocks the loop. This was already mitigated in practice (interactive Ctrl-C sends more than one signal, a process manager escalates to SIGKILL, and the #153 harness fix already bounded test-server teardown), so there is no behavior change to the banner, browser-open, or clean-shutdown print paths and nothing to do on upgrade (#154).
+- **`cctally db recover --db stats` no longer resets a recovered DB's schema `user_version` to 0 when a known migration is recorded only under its legacy unprefixed marker name.** When healing a version-ahead `stats.db`, the all-known-applied check that decides whether to fast-path straight to the known schema head compared each migration's canonical `NNN_`-prefixed name against the recorded markers without normalizing the three pre-framework legacy aliases (`five_hour_block_models_backfill_v1`, `five_hour_block_projects_backfill_v1`, `merge_5h_block_duplicates_v1`) to their canonical names — so a DB whose those markers predate the framework rename was misread as having a missing migration and reverted to `user_version = 0`, forcing an unnecessary full migration re-walk on the next open instead of reconciling directly to head. The recover path now normalizes legacy aliases before the membership test (matching the alias-aware read in `db status`), so such a DB reconciles straight to the known head; cache.db (which has no legacy markers) is unaffected (#148).
+- **Internal (test infra, no user-facing change): the golden-file test suite no longer hangs indefinitely when a backgrounded dashboard test server drops a single SIGTERM.** The server-spawning harnesses (`dashboard`, `conversation`, `settings-api`) tore their `cctally dashboard` test servers down with an unbounded `kill "$pid"; wait "$pid"` — and CPython can lose a single SIGTERM that races the server's main-thread `threading.Event.wait()` (woken only by its signal handler's `stop.set()`; ~0.04–0.07% of single signals are dropped and recovery needs a second signal), so on the rare miss the `wait` blocked forever and wedged the whole suite (observed once under #153 as a 30+ minute hang on a non-TTY/piped run; the foreground suite always completed `1395/0`). Teardown now routes through a shared `bin/_lib-kill-server.sh` helper that escalates SIGTERM → bounded grace poll → uncatchable SIGKILL → reap (a wedge emits a non-fatal WARN rather than hanging or failing), guaranteeing teardown regardless of the server's signal-handling state; a new `bin/cctally-kill-server-test` harness pins the behavior (#153).
+
+### Changed
+- Conversation viewer: subagent (sidechain) threads are now grouped by their originating agent file so parallel subagents render as separate collapsible threads (with task-prompt label, message count, and thread cost) instead of being fused by adjacency; threads nest under a parent message where a real cross-file link exists. Reader items expose a privacy-safe subagent key + parent link (never a raw filesystem path).
+- **Internal performance (no user-facing change): the conversation-viewer search endpoint now dedups, pages, and counts entirely in SQL instead of materializing every match in Python.** `/api/conversation/search` (and the `_lib_conversation_query` FTS/LIKE kernels behind it) previously ran an unbounded `SELECT` that built a hit object — and, for FTS, a `snippet()` string; for LIKE, the full row `text` — for *every* corpus match, then deduped by `(session_id, uuid)` and sliced one page in Python, so latency and memory scaled with the number of matches rather than the page size. The match set is now deduped via a SQL window function (`ROW_NUMBER() OVER (PARTITION BY session_id, uuid …)`, keeping the same first-occurrence row as before), paged with `LIMIT/OFFSET`, and the exact post-dedup `total` is a separate `COUNT(*)` over `SELECT DISTINCT session_id, uuid`; snippet/text generation is deferred to a second query covering only the page's rowids — so Python never holds more than one page of hits/snippets regardless of corpus match count. The JSON response (`{query, mode, hits, total}`, deduped by `(session_id, uuid)`, cost-once) is byte-identical (the conversation-query unit suite and the `bin/cctally-conversation-test` search goldens are unchanged), so there is nothing to do on upgrade (#149).
+- **Internal refactor (no user-facing change): the two per-vendor budget-milestone tables are now one vendor-tagged `budget_milestones` table.** The structurally-identical Claude and Codex budget-milestone tables (`budget_milestones` keyed on `week_start_at`, `codex_budget_milestones` keyed on `period_start_at`) are merged by a new stats migration `012_unify_budget_milestones_vendor` into a single `budget_milestones` with a `vendor` column (`'claude'`/`'codex'`), the renamed `period_start_at` key, and `UNIQUE(vendor, period_start_at, period, threshold)` — history, `alerted_at`, and `period` are preserved verbatim and the migration is idempotent / partial-state-safe (the Codex table is dropped). The `budget` and `codex_budget` desktop-alert axes stay two distinct axes but now share the one table (filtered `WHERE vendor=?`), and the parallel insert / dashboard envelope / reconcile-on-set / firing code collapses to a single vendor-parameterized path with the two `maybe_record_*` entry points kept as thin vendor adapters. Also folds in a dashboard fix: the Settings `POST /api/settings` budget-reconcile trigger now fires on a changed `period` (parity with the CLI `budget set --period` path). Alert ids, dashboard envelope bytes, and notification text are unchanged (no frontend bundle change), so there is nothing to do on upgrade — the merge runs automatically on the next DB open (#143).
+- **The `0700` data-dir hardening now also covers a stats-first cold start.** The owner-only data-dir permission shipped in 1.28.0 was applied when `cache.db` was opened, but a cold start that opened `stats.db` first (e.g. `record-usage` on a fresh machine) materialized the directory at the default umask and left it that way until the next `cache.db` open. The `0700` chmod now lives in the shared `ensure_dirs()` primitive (best-effort, swallowing `OSError`) that every `stats.db` open runs through, with the `cache.db` open keeping its own chmod as a backstop — so the data dir is owner-only regardless of which database is touched first. Posture-only; no action needed on upgrade (#150).
+- **Internal refactor (no user-facing change): the three local-dashboard conversation GET handlers (`/api/conversations`, `/api/conversation/<id>`, `/api/conversation/search`) now share one `_run_conversation_query` scaffold for the open-cache → run-query → close → 500-envelope lifecycle (previously triplicated), and the single-value query-string string parse routes through a new `_qs_str` helper (the string sibling of the existing `_qs_int`).** Status codes, JSON bodies, the `cache unavailable:` / `<type>: <msg>` 500 envelopes, and the reader's 404 are byte-identical — the conversation-endpoint, conversation-query, and dashboard golden suites are unchanged (a new test also pins the cache-open-failure 500 across all three routes). Purely a maintainability / de-duplication change; nothing to do on upgrade (#151).
+- **Internal performance (no user-facing change): the cache sync now parses each changed session JSONL file once per sync instead of twice, and a `cache-sync --rebuild` / truncation re-ingest clears the conversation full-text search index without the per-row delete-trigger storm.** Cost rows and conversation message rows are now produced from a single fused pass over each changed file (previously the cost walk and the conversation walk each re-read and re-parsed the same byte range), and the rebuild/truncation full-clear drops the FTS sync triggers, truncates, then resets the index with one `'delete-all'` instead of firing an FTS shadow-write per row inside the held cache lock — on a large index (≈850k rows) the full-clear dropped from ~8.5s to ~0.3s of held-lock time. Output is byte-identical (cost totals, conversation rows, and the search index are unchanged; the reconcile and conversation-ingest suites stay green), so there is nothing to do on upgrade (#138).
+
 ## [1.28.0] - 2026-06-06
 
 ### Added

package/bin/_cctally_cache.py

@@ -168,13 +168,15 @@ _parse_usage_entries = _lib_jsonl._parse_usage_entries
 _should_replace = _lib_jsonl._should_replace
 
 # Conversation-message parser kernel (Plan 1). Pure leaf (stdlib-only), so
-# it loads at module-load time alongside _lib_jsonl. ``sync_cache``'s second
-# seek-and-walk and the backfill walker both call ``_iter_message_rows``.
+# it loads at module-load time alongside _lib_jsonl. Since #138 the per-file
+# sync ingest goes through the fused ``_iter_sync_entries`` walker (which calls
+# ``_lib_conversation.parse_message_row`` directly); ``_iter_message_rows`` is
+# now used only by ``backfill_conversation_messages``.
 _lib_conversation = _load_lib("_lib_conversation")
 _iter_message_rows = _lib_conversation.iter_message_rows
 
-# Shared by sync_cache's second seek-and-walk AND backfill_conversation_messages
-# so the column list, placeholders, and tuple order live in ONE place — a column
+# Shared by the fused per-file walk AND backfill_conversation_messages so the
+# column list, placeholders, and tuple order live in ONE place — a column
 # add/reorder can't silently desync the two ingest paths (which would land
 # values in the wrong columns on whichever path was missed).
 _CONV_INSERT_SQL = (
@@ -195,6 +197,52 @@ def _conv_row_tuple(m, path_str):
     )
 
 
+def _iter_sync_entries(fh, path_str):
+    """Fused single-pass sync walker (#138). Yields
+    ``(byte_offset, cost_or_None, msgrow_or_None)`` for each JSONL line from
+    ``fh``'s current position that produces a cost entry and/or a conversation
+    message row.
+
+    Each line is read once (readline()+tell()) and ``json.loads``-parsed ONCE,
+    then classified by both pure per-line parsers:
+
+      * ``cost_or_None`` is ``(UsageEntry, msg_id, req_id)`` when the line is a
+        billable assistant entry (``_lib_jsonl.parse_cost_entry``), else None.
+      * ``msgrow_or_None`` is a ``MessageRow`` when the line is a user/assistant
+        turn carrying a uuid (``_lib_conversation.parse_message_row``), else None.
+
+    The two are independent — a normal assistant line yields both. This replaces
+    the former cost walk + re-seek-and-walk over the identical byte span: with a
+    single walk the "identical span" invariant is structural (one stop point),
+    not a prose-enforced ``mrow.byte_offset >= final_offset`` runtime break. A
+    partial mid-write tail line (no trailing newline) rewinds the handle and
+    stops, so ``fh.tell()`` after the loop is the cost cursor's ``final_offset``
+    and the next sync re-reads the line once the newline lands.
+    """
+    while True:
+        offset = fh.tell()
+        line = fh.readline()
+        if not line:
+            return
+        if not line.endswith("\n"):
+            # Partial tail line — writer is mid-flight. Rewind so the next sync
+            # re-reads this line once the newline is in place (and so fh.tell()
+            # reports the cost cursor's stop, never past the partial).
+            fh.seek(offset)
+            return
+        stripped = line.strip()
+        if not stripped:
+            continue
+        try:
+            obj = json.loads(stripped)
+        except json.JSONDecodeError:
+            continue
+        cost = _lib_jsonl.parse_cost_entry(obj, path_str)
+        mrow = _lib_conversation.parse_message_row(obj, offset)
+        if cost is not None or mrow is not None:
+            yield offset, cost, mrow
+
+
 def _iter_claude_jsonl_files():
     """Yield every Claude transcript ``*.jsonl`` under each data dir's
     ``projects/`` tree. Shared by ``sync_cache`` and the conversation backfill
@@ -208,6 +256,10 @@ _cctally_db_sib = _load_lib("_cctally_db")
 add_column_if_missing = _cctally_db_sib.add_column_if_missing
 _run_pending_migrations = _cctally_db_sib._run_pending_migrations
 _CACHE_MIGRATIONS = _cctally_db_sib._CACHE_MIGRATIONS
+# Storm-free conversation_messages + FTS full-clear (#138). Owns the trigger
+# drop/recreate dance so the per-row delete trigger never fires O(rows) under
+# the held lock on a rebuild / truncation escalation.
+clear_conversation_messages = _cctally_db_sib.clear_conversation_messages
 
 
 # === BEGIN MOVED REGIONS ===
@@ -542,16 +594,19 @@ def sync_cache(
             # Plan 1: conversation_messages shares the cost path's lifecycle.
             # A rebuild re-derives the whole cache from on-disk JSONL, so the
             # message index is wiped here (inside the held lock) and the
-            # per-file second seek-and-walk repopulates it. The FTS delete
-            # trigger empties conversation_fts row-by-row in lockstep.
-            conn.execute("DELETE FROM conversation_messages")
+            # per-file fused walk repopulates it. clear_conversation_messages
+            # drops the FTS triggers, truncates, and clears the index via
+            # 'delete-all' so the per-row delete trigger never storms O(rows)
+            # under the lock (#138) — NOT a bare DELETE that fires conv_fts_ad
+            # per row.
+            clear_conversation_messages(conn)
             # Clear the walk-complete sentinel atomically with the wipe
             # (cctally-dev#93, D5/D2): a stale "complete" marker must never
             # survive a destructive rebuild. The end-of-loop write below
             # re-establishes it only after this rebuild's clean walk.
             conn.execute("DELETE FROM cache_meta WHERE key='claude_ingest_walk_complete'")
             # Issue #139: a rebuild walks every file from offset 0, so the
-            # per-file second seek-and-walk below repopulates the whole message
+            # per-file fused walk below repopulates the whole message
             # index — that satisfies any deferred existing-install backfill.
             # Drop the pending flag here so the post-rebuild sync does not also
             # run a redundant (idempotent but wasteful) offset-0 backfill pass.
@@ -693,10 +748,11 @@ def sync_cache(
             conn.execute("DELETE FROM session_entries")
             # Plan 1: truncation escalates to a full re-ingest of EVERY file,
             # so conversation_messages is wiped here (parallel to the
-            # session_entries full-reset) and the per-file second seek-and-walk
-            # repopulates it from offset 0. Mirrors the cost path's lifecycle;
-            # the FTS delete trigger empties conversation_fts in lockstep.
-            conn.execute("DELETE FROM conversation_messages")
+            # session_entries full-reset) and the per-file fused walk
+            # repopulates it from offset 0. Storm-free clear (#138): drop FTS
+            # triggers → truncate → 'delete-all' → recreate, so conv_fts_ad
+            # never fires O(rows) inside the held lock.
+            clear_conversation_messages(conn)
             # Clear the walk-complete sentinel atomically with the truncation
             # full-reset (cctally-dev#93, D5/D2): the cache is being wiped, so
             # any "complete" marker is now stale. The end-of-loop write below
@@ -772,54 +828,50 @@ def sync_cache(
             try:
                 with open(jp, "r", encoding="utf-8", errors="replace") as fh:
                     fh.seek(start_offset)
-                    for offset, entry, msg_id, req_id in _iter_jsonl_entries_with_offsets(fh, str(jp)):
-                        usage = entry.usage
-                        inp = int(usage.get("input_tokens", 0) or 0)
-                        out = int(usage.get("output_tokens", 0) or 0)
-                        cc = int(usage.get("cache_creation_input_tokens", 0) or 0)
-                        cr = int(usage.get("cache_read_input_tokens", 0) or 0)
-                        extras = {
-                            k: v for k, v in usage.items()
-                            if k not in (
-                                "input_tokens", "output_tokens",
-                                "cache_creation_input_tokens",
-                                "cache_read_input_tokens",
-                            )
-                        }
-                        rows.append((
-                            path_str,
-                            offset,
-                            entry.timestamp.astimezone(dt.timezone.utc).isoformat(),
-                            entry.model,
-                            msg_id,
-                            req_id,
-                            inp, out, cc, cr,
-                            json.dumps(extras, sort_keys=True) if extras else None,
-                            entry.cost_usd,
-                        ))
-                    # ``final_offset`` is the cost walk's stop. Capture it into a
-                    # local int BEFORE the conversation walk below re-seeks the
-                    # handle — the value is what session_files.last_byte_offset
-                    # is written from, so it must reflect the COST walk's
-                    # position, never the conversation walk's. (#Plan1 Task 4
-                    # cursor-consistency invariant.)
+                    # Fused single-pass walk (#138): cost rows AND conversation
+                    # message rows come from ONE parse of each line. An assistant
+                    # line yields both; a user line yields only a message row.
+                    # This replaces the former cost walk + re-seek conversation
+                    # walk over the identical span — the "identical span"
+                    # invariant is now structural (a single stop point) rather
+                    # than a prose-enforced ``>= final_offset`` runtime break.
+                    for offset, cost, mrow in _iter_sync_entries(fh, path_str):
+                        if cost is not None:
+                            entry, msg_id, req_id = cost
+                            usage = entry.usage
+                            inp = int(usage.get("input_tokens", 0) or 0)
+                            out = int(usage.get("output_tokens", 0) or 0)
+                            cc = int(usage.get("cache_creation_input_tokens", 0) or 0)
+                            cr = int(usage.get("cache_read_input_tokens", 0) or 0)
+                            extras = {
+                                k: v for k, v in usage.items()
+                                if k not in (
+                                    "input_tokens", "output_tokens",
+                                    "cache_creation_input_tokens",
+                                    "cache_read_input_tokens",
+                                )
+                            }
+                            rows.append((
+                                path_str,
+                                offset,
+                                entry.timestamp.astimezone(dt.timezone.utc).isoformat(),
+                                entry.model,
+                                msg_id,
+                                req_id,
+                                inp, out, cc, cr,
+                                json.dumps(extras, sort_keys=True) if extras else None,
+                                entry.cost_usd,
+                            ))
+                        if mrow is not None:
+                            conv_rows.append(_conv_row_tuple(mrow, path_str))
+                    # ``final_offset`` is the single walk's stop — captured AFTER
+                    # the loop drains (or rewinds a partial mid-write tail line).
+                    # It is what session_files.last_byte_offset is written from,
+                    # so it must reflect the cost cursor's position; with the
+                    # fused walk there is exactly one stop point shared by the
+                    # cost and conversation rows (#138 / #Plan1 Task 4
+                    # cursor-consistency invariant).
                     final_offset = fh.tell()
-                    # --- conversation message ingest (Plan 1) ----------------
-                    # Second seek-and-walk over the SAME
-                    # [start_offset, final_offset] byte region as the
-                    # reconcile-guarded cost walk above, BEFORE the per-file
-                    # cursor advances. Independent of the cost walk: it touches
-                    # only conversation_messages, never session_entries or the
-                    # cost-row build. We re-seek to start_offset and stop the
-                    # moment a message row's byte_offset reaches the cost walk's
-                    # final_offset, so the two walks always cover the identical
-                    # span and a partial mid-write tail line (rewound by the
-                    # parser) is left for the next sync.
-                    fh.seek(start_offset)
-                    for mrow in _iter_message_rows(fh, path_str):
-                        if mrow.byte_offset >= final_offset:
-                            break
-                        conv_rows.append(_conv_row_tuple(mrow, path_str))
             except OSError as exc:
                 eprint(f"[cache] could not read {jp}: {exc}")
                 walk_clean = False  # skipped a file without ingesting (D5a)

package/bin/_cctally_core.py

@@ -436,6 +436,16 @@ def compute_week_bounds(anchor_dt: dt.datetime, week_start_name: str) -> tuple[d
 def ensure_dirs() -> None:
     APP_DIR.mkdir(parents=True, exist_ok=True)
     LOG_DIR.mkdir(parents=True, exist_ok=True)
+    # cache.db holds plaintext conversation prose at rest (Plan 2, spec §5), so
+    # the data dir must be 0700. Hardening it here in the shared primitive means
+    # a stats-first cold start — open_db() materializing APP_DIR before any
+    # cache.db open (e.g. record-usage) — is covered, not only the
+    # open_cache_db backstop (which keeps its own chmod). Best-effort and
+    # idempotent: swallow OSError + continue (issue #150).
+    try:
+        os.chmod(APP_DIR, 0o700)
+    except OSError as exc:
+        eprint(f"[core] could not chmod data dir 0700 ({exc}); continuing")
 
 
 # === Alerts validation cluster ======================================
@@ -1261,25 +1271,28 @@ def open_db() -> sqlite3.Connection:
     # (set-then-dispatch invariant); NULL = "recorded without dispatch" (the
     # forward-only-from-set reconcile path) OR "not yet dispatched", never
     # "delivery failed".
-    # Schema owned by migration 011_budget_milestone_period_keys (the `period`
-    # column + the period-inclusive UNIQUE; see _cctally_db.py). The live CREATE
-    # below makes the new shape on fresh installs (dispatcher fast-stamps 011);
-    # pre-011 DBs trip the migration's rename-recreate-copy. `period` is the
-    # configured period noun at crossing ('calendar-week'|'calendar-month'|
-    # 'subscription-week'); NULL = pre-011 unknown.
+    # Unified vendor-tagged table (#143): one row per (vendor, period_start_at,
+    # period, threshold). `vendor` ∈ 'claude'|'codex'. `period_start_at` is the
+    # resolved period-window start instant (subscription-week OR calendar
+    # period-start). `period` is the configured period at crossing; NULL = pre-012
+    # unknown. Owned by migration 012_unify_budget_milestones_vendor (merge of the
+    # former budget_milestones + codex_budget_milestones). The Codex table is NO
+    # LONGER live-created here — migration 012 drops it and this CREATE must not
+    # resurrect it; migration 011 is hardened to skip it when absent (#143).
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS budget_milestones (
             id              INTEGER PRIMARY KEY AUTOINCREMENT,
-            week_start_at   TEXT    NOT NULL,
-            period          TEXT,                 -- configured period at crossing; NULL = pre-011 unknown (migration 011)
+            vendor          TEXT    NOT NULL,
+            period_start_at TEXT    NOT NULL,
+            period          TEXT,
             threshold       INTEGER NOT NULL,
             budget_usd      REAL    NOT NULL,
             spent_usd       REAL    NOT NULL,
             consumption_pct REAL    NOT NULL,
             crossed_at_utc  TEXT    NOT NULL,
             alerted_at      TEXT,
-            UNIQUE(week_start_at, period, threshold)
+            UNIQUE(vendor, period_start_at, period, threshold)
         )
         """
     )
@@ -1352,46 +1365,6 @@ def open_db() -> sqlite3.Connection:
         """
     )
 
-    # ── codex_budget_milestones (per-vendor Codex budget crossings) ──────────
-    # Plain CREATE TABLE IF NOT EXISTS, NO migration handler / backfill — the
-    # same posture as `budget_milestones` / `projected_milestones` /
-    # `project_budget_milestones` (write-once, forward-only, framework-untracked;
-    # calendar-period-codex-budgets feature, spec §6). The dedup key is keyed on
-    # `period_start_at` — the resolved period-window START instant stored as the
-    # `isoformat(timespec="seconds")` `+00:00` offset form (NOT a `Z` suffix),
-    # e.g. calendar-month June → `2026-06-01T00:00:00+00:00` — NOT a subscription
-    # week:
-    # Codex has no Anthropic week, so the budget runs over a calendar period
-    # (calendar-week / calendar-month). Rolling to the next period yields a fresh
-    # `period_start_at` → fresh crossings under UNIQUE(period_start_at, period,
-    # threshold) (the budget-pattern reset handling — hence NO `reset_event_id`
-    # segment column). `budget_usd` snapshots the Codex target AT crossing so the
-    # dashboard renders "$210 of $200" from the ROW, not from live config that
-    # may have changed since (the Codex P0-4 lesson, baked into the sibling
-    # tables). `alerted_at` is stamped BEFORE the osascript Popen (set-then-
-    # dispatch invariant); NULL = "recorded without dispatch" (the forward-only-
-    # from-set reconcile path) OR "not yet dispatched", never "delivery failed".
-    # Schema owned by migration 011_budget_milestone_period_keys (the `period`
-    # column + the period-inclusive UNIQUE; see _cctally_db.py). `period` is the
-    # configured Codex period noun at crossing ('calendar-week'|'calendar-
-    # month'); NULL = pre-011 unknown.
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS codex_budget_milestones (
-            id              INTEGER PRIMARY KEY AUTOINCREMENT,
-            period_start_at TEXT    NOT NULL,   -- resolved period-window start instant (+00:00 offset form, NOT Z)
-            period          TEXT,               -- configured period at crossing; NULL = pre-011 unknown (migration 011)
-            threshold       INTEGER NOT NULL,
-            budget_usd      REAL    NOT NULL,   -- Codex target snapshotted AT crossing
-            spent_usd       REAL    NOT NULL,
-            consumption_pct REAL    NOT NULL,
-            crossed_at_utc  TEXT    NOT NULL,
-            alerted_at      TEXT,
-            UNIQUE(period_start_at, period, threshold)
-        )
-        """
-    )
-
     # Migration framework dispatcher. Replaces the prior inline gate stack
     # (has_blocks + _migration_done) with the framework's _run_pending_-
     # migrations entry point. See spec §2.3, §5.2 + the migration handlers