cctally 1.68.0 → 1.69.0

package/bin/_cctally_db.py

@@ -2331,11 +2331,11 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
     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``.
+    side-effect that stays in ``open_cache_db``. The eager dispatcher can run
+    024, but that handler acquires its own Codex flock and only deletes
+    Codex-derived rows; it neither reads nor requires ``last_total_tokens``.
+    Normal ``open_cache_db`` remains responsible for the ALTER and its historic
+    purge, so leaving it outside this shared schema is safe.
     """
     conn.executescript(
         """
@@ -2411,6 +2411,19 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
             ON conversation_messages(cwd)
             WHERE cwd IS NOT NULL AND cwd != '';
 
+        -- #301: partial covering index on (model, session_id). list_conversation_facets
+        -- and _model_clause source model facets/filters with `SELECT DISTINCT ... model
+        -- FROM conversation_messages WHERE model IS NOT NULL AND model != ''`; without
+        -- this index those DISTINCTs do an index->heap walk of the whole table (~22s
+        -- cold on a 5.5 GB cache). The partial (model, session_id) index answers all
+        -- three model queries index-only: the facets DISTINCT and distinct-model
+        -- enumeration as ordered index walks, and the ?models= filter as a model seek.
+        -- MIRRORS migration 022 (base schema here for fresh/rebuilt caches, migration
+        -- for existing ones) — same discipline as idx_conversation_messages_cwd (#289).
+        CREATE INDEX IF NOT EXISTS idx_conversation_messages_model_session
+            ON conversation_messages(model, session_id)
+            WHERE model IS NOT NULL AND model != '';
+
         -- #193: per-session AI-generated title, isolated from the six places
         -- that iterate conversation_messages. The explicit NOT NULL on the
         -- non-INTEGER PRIMARY KEY matters (SQLite's legacy NULL-in-PK bug);
@@ -2429,18 +2442,25 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
         -- render a 50-row page, PLUS three filter columns
         -- (project_label/cost_usd/cache_rebuild_count, migration 015) so the
         -- Browse list's date/project/cost/cache-rebuild filters are pure-SQL
-        -- predicates. The structural columns are recomputed by a COUNT/MIN/MAX
-        -- GROUP BY; the filter columns are filled per-session by
+        -- predicates, PLUS three DISPLAYED-enrichment columns
+        -- (git_branch/models_json/title, migration 023 / #302) so the rail's
+        -- per-session enrichment (git branch, ordered model list, stable
+        -- first-prompt title) is read straight off the rollup instead of
+        -- re-scanning conversation_messages per session on every cold page.
+        -- The structural columns are recomputed by a COUNT/MIN/MAX GROUP BY; the
+        -- filter + enrichment columns are filled per-session by
         -- _fill_conversation_sessions_filter_columns in the same flock-held
-        -- recompute (cost via the query kernel's batch maps, cache_rebuild_count
-        -- via a per-session assemble). The explicit NOT NULL on the non-INTEGER PK
-        -- matters (SQLite's legacy NULL-in-PK bug); the rail keys on a concrete
-        -- session_id and the recompute's GROUP BY already filters nulls. The
-        -- index lets the only paginated ordering (recent) early-terminate at
-        -- LIMIT with no temp B-tree. Re-derivable like the rest of cache.db;
-        -- sync_cache keeps it honest (scoped DELETE+INSERT re-derive +
-        -- flag-gated full recompute) — migration 013 arms the one-time
-        -- history backfill.
+        -- recompute (cost/models/title/branch via the query kernel's batch maps,
+        -- cache_rebuild_count via a per-session assemble). The AI title is NOT
+        -- stored here — it is volatile, so list_conversations overlays it live
+        -- from conversation_ai_titles (#302 Q2-B). The explicit NOT NULL on the
+        -- non-INTEGER PK matters (SQLite's legacy NULL-in-PK bug); the rail keys
+        -- on a concrete session_id and the recompute's GROUP BY already filters
+        -- nulls. The index lets the only paginated ordering (recent)
+        -- early-terminate at LIMIT with no temp B-tree. Re-derivable like the
+        -- rest of cache.db; sync_cache keeps it honest (scoped DELETE+INSERT
+        -- re-derive + flag-gated full recompute) — migration 013 arms the
+        -- one-time history backfill, 023 re-arms it for the enrichment columns.
         CREATE TABLE IF NOT EXISTS conversation_sessions (
             session_id          TEXT NOT NULL PRIMARY KEY,
             msg_count           INTEGER NOT NULL DEFAULT 0,
@@ -2448,7 +2468,10 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
             last_activity_utc   TEXT,
             project_label       TEXT,
             cost_usd            REAL NOT NULL DEFAULT 0,
-            cache_rebuild_count INTEGER NOT NULL DEFAULT 0
+            cache_rebuild_count INTEGER NOT NULL DEFAULT 0,
+            git_branch          TEXT,
+            models_json         TEXT,
+            title               TEXT
         );
         CREATE INDEX IF NOT EXISTS idx_conv_sessions_recent
             ON conversation_sessions(last_activity_utc DESC, session_id DESC);
@@ -2517,6 +2540,87 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
         CREATE INDEX IF NOT EXISTS idx_codex_entries_source
             ON codex_session_entries(source_path);
 
+        -- #294 S1: physical Codex rollout retention. These tables deliberately
+        -- live in the unconditional base-schema script, before the legacy-FTS
+        -- topology checks below: an existing cache with an old FTS shape must
+        -- still gain the S1 tables on every open, just as conversation_file_touches
+        -- does above.
+        CREATE TABLE IF NOT EXISTS codex_source_roots (
+            source_root_key      TEXT NOT NULL PRIMARY KEY,
+            canonical_root_path  TEXT NOT NULL UNIQUE,
+            first_seen_utc       TEXT NOT NULL,
+            last_seen_utc        TEXT NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS codex_conversation_threads (
+            conversation_key     TEXT NOT NULL PRIMARY KEY,
+            source_root_key      TEXT NOT NULL,
+            native_thread_id     TEXT NOT NULL,
+            root_thread_id       TEXT NOT NULL,
+            parent_thread_id     TEXT,
+            source_path          TEXT NOT NULL,
+            cwd                  TEXT,
+            git_json             TEXT,
+            source_kind          TEXT,
+            thread_source_json   TEXT,
+            model_provider       TEXT,
+            context_window       INTEGER,
+            first_seen_utc       TEXT,
+            last_seen_utc        TEXT,
+            UNIQUE(source_root_key, root_thread_id, native_thread_id)
+        );
+        CREATE INDEX IF NOT EXISTS idx_codex_threads_source_root
+            ON codex_conversation_threads(source_root_key);
+        CREATE INDEX IF NOT EXISTS idx_codex_threads_source_path
+            ON codex_conversation_threads(source_path);
+
+        CREATE TABLE IF NOT EXISTS quota_window_snapshots (
+            id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+            source                TEXT NOT NULL CHECK(source IN ('claude','codex')),
+            source_root_key       TEXT,
+            source_path           TEXT NOT NULL,
+            line_offset           INTEGER NOT NULL,
+            captured_at_utc       TEXT NOT NULL,
+            observed_slot         TEXT,
+            logical_limit_key     TEXT NOT NULL,
+            limit_id              TEXT,
+            limit_name            TEXT,
+            window_minutes        INTEGER NOT NULL CHECK(window_minutes > 0),
+            used_percent          REAL NOT NULL CHECK(used_percent >= 0 AND used_percent <= 100),
+            resets_at_utc         TEXT NOT NULL,
+            plan_type             TEXT,
+            individual_limit_json TEXT,
+            reached_type          TEXT,
+            UNIQUE(source, source_path, line_offset, logical_limit_key),
+            CHECK(source != 'codex' OR source_root_key IS NOT NULL)
+        );
+        CREATE INDEX IF NOT EXISTS idx_quota_window_source_root
+            ON quota_window_snapshots(source_root_key);
+        CREATE INDEX IF NOT EXISTS idx_quota_window_captured_at
+            ON quota_window_snapshots(captured_at_utc);
+
+        CREATE TABLE IF NOT EXISTS codex_conversation_events (
+            id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+            source_path          TEXT NOT NULL,
+            line_offset          INTEGER NOT NULL,
+            source_root_key      TEXT NOT NULL,
+            conversation_key     TEXT,
+            native_thread_id     TEXT,
+            root_thread_id       TEXT,
+            parent_thread_id     TEXT,
+            timestamp_utc        TEXT,
+            record_type          TEXT,
+            event_type           TEXT,
+            turn_id              TEXT,
+            call_id              TEXT,
+            payload_json         TEXT NOT NULL,
+            UNIQUE(source_path, line_offset)
+        );
+        CREATE INDEX IF NOT EXISTS idx_codex_events_conversation
+            ON codex_conversation_events(conversation_key);
+        CREATE INDEX IF NOT EXISTS idx_codex_events_timestamp
+            ON codex_conversation_events(timestamp_utc);
+
         CREATE TABLE IF NOT EXISTS cache_meta (
             key   TEXT PRIMARY KEY,
             value TEXT
@@ -2528,6 +2632,44 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
     # 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")
+    # #294 S1: old Codex accounting rows have no truthful provider-root or
+    # conversation identity, so the linkage remains nullable until migration
+    # 024 clears them for a source-derived reingest. Existing report selectors
+    # intentionally keep selecting their shipped columns only.
+    add_column_if_missing(conn, "codex_session_entries", "source_root_key", "TEXT")
+    add_column_if_missing(conn, "codex_session_entries", "conversation_key", "TEXT")
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_codex_entries_source_root "
+        "ON codex_session_entries(source_root_key)"
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_codex_entries_conversation "
+        "ON codex_session_entries(conversation_key)"
+    )
+    # #294 S3: the qualified accounting adapter is bounded by timestamp and
+    # joins only through the S1 root-qualified conversation identity.  Keep
+    # this re-derivable index in the unconditional schema path so an existing
+    # cache gains the same scale-safe plan without a data migration.
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_codex_entries_ts_root_conversation "
+        "ON codex_session_entries(timestamp_utc, source_root_key, conversation_key)"
+    )
+    # The per-file terminal thread facts seed a later append without rereading
+    # the prefix. They are nullable for old cache rows; migration 024 never
+    # fabricates these source facts and instead clears/rederives them.
+    add_column_if_missing(conn, "codex_session_files", "source_root_key", "TEXT")
+    add_column_if_missing(conn, "codex_session_files", "last_native_thread_id", "TEXT")
+    add_column_if_missing(conn, "codex_session_files", "last_root_thread_id", "TEXT")
+    add_column_if_missing(conn, "codex_session_files", "last_parent_thread_id", "TEXT")
+    add_column_if_missing(conn, "codex_session_files", "last_conversation_key", "TEXT")
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_codex_files_source_root "
+        "ON codex_session_files(source_root_key)"
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_codex_files_conversation "
+        "ON codex_session_files(last_conversation_key)"
+    )
     # #181: materialize the only-ever-consumed extra `usage` key (`speed`) into
     # a real session_entries column so the hot cache read paths (iter_entries /
     # get_claude_session_entries) stop json.loads-ing the deeply-nested
@@ -2604,6 +2746,17 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
         conn, "conversation_messages", "search_tool", "TEXT NOT NULL DEFAULT ''")
     add_column_if_missing(
         conn, "conversation_messages", "search_thinking", "TEXT NOT NULL DEFAULT ''")
+    # #302: the browse-rail DISPLAYED-enrichment columns on the conversation_sessions
+    # rollup (git_branch / models_json / title). Idempotent column-adds (no marker,
+    # no version — the repo's column-addition rule, NOT a raw ALTER in a migration
+    # handler; Codex P1-2). They MUST land here — after the CREATE TABLE above (so
+    # the table exists on a fresh DB) and BEFORE the legacy-FTS early-return below
+    # (so an old-shape existing cache.db still receives them before any rail read
+    # SELECTs them). Migration 023 arms the one-time full backfill that fills the
+    # values on existing history; a fresh DB fills them at ingest.
+    add_column_if_missing(conn, "conversation_sessions", "git_branch", "TEXT")
+    add_column_if_missing(conn, "conversation_sessions", "models_json", "TEXT")
+    add_column_if_missing(conn, "conversation_sessions", "title", "TEXT")
     conn.execute(
         "CREATE INDEX IF NOT EXISTS idx_session_files_session_id "
         "ON session_files(session_id)"
@@ -3269,6 +3422,29 @@ def _cache_db_lock_path_for_conn(conn: sqlite3.Connection) -> "pathlib.Path | No
     return None
 
 
+def _cache_db_codex_lock_path_for_conn(
+    conn: sqlite3.Connection,
+) -> "pathlib.Path | None":
+    """Return this connection's ``<cache.db>.codex.lock`` sibling.
+
+    Codex ingest deliberately uses a separate fcntl lock from Claude ingest.
+    Derive it from the connection rather than the global path constant so a
+    migration test or recovery connection never contends on the caller's real
+    cache lock. ``sync_codex_cache`` opens this exact sibling in production.
+    """
+    try:
+        rows = conn.execute("PRAGMA database_list").fetchall()
+    except sqlite3.DatabaseError:
+        return None
+    for row in rows:
+        if row[1] == "main":
+            db_file = row[2]
+            if not db_file:
+                return None
+            return pathlib.Path(str(db_file) + ".codex.lock")
+    return 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.
@@ -4018,6 +4194,103 @@ def _021_index_conversation_messages_cwd(conn: sqlite3.Connection) -> None:
     )
 
 
+@cache_migration("022_index_conversation_messages_model")
+def _022_index_conversation_messages_model(conn: sqlite3.Connection) -> None:
+    """#301: partial covering index on conversation_messages(model, session_id) to
+    collapse the full-table `SELECT DISTINCT ... model` walks in
+    list_conversation_facets and _model_clause (~22s cold on a 5.5 GB cache) into
+    index-only walks/seeks.
+
+    Fresh installs never run this handler: the dispatcher stamps it WITHOUT running
+    (the fresh-install branch), and `_apply_cache_schema` already created the index
+    on the fresh DB. NO self-stamp — the dispatcher central-stamps on a clean return
+    (#140). Run-twice safe: CREATE INDEX is IF NOT EXISTS. cache.db is re-derivable —
+    `cache-sync --rebuild` is the escape hatch.
+
+    No flock/BEGIN IMMEDIATE (like 021): a single CREATE INDEX IF NOT EXISTS performs
+    no row mutations (it reads the table once to build the index but modifies no
+    rows), so it needs no mutual-exclusion scaffolding.
+    """
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_conversation_messages_model_session "
+        "ON conversation_messages(model, session_id) "
+        "WHERE model IS NOT NULL AND model != ''"
+    )
+
+
+@cache_migration("023_conversation_sessions_enrichment_columns")
+def _023_conversation_sessions_enrichment_columns(conn: sqlite3.Connection) -> None:
+    """Flag-only arm for the #302 browse-rail enrichment columns (git_branch,
+    models_json, title). The columns themselves are added by _apply_cache_schema's
+    CREATE TABLE + add_column_if_missing (the repo's column-addition rule, NOT an
+    ALTER here); this migration only arms the SHARED
+    conversation_sessions_backfill_pending flag so the next sync_cache full
+    recompute fills the new (empty) columns via the augmented
+    _fill_conversation_sessions_filter_columns. Central stamp via the dispatcher
+    (#140); the handler does NOT self-stamp.
+
+    A fresh install gets the columns from _apply_cache_schema's CREATE TABLE and
+    stamps 023 WITHOUT running this handler; its empty rollup needs no backfill
+    (the incremental DELETE+INSERT re-derive fills all columns in lockstep).
+    Mirrors 013/015."""
+    _set_cache_meta(conn, "conversation_sessions_backfill_pending", "1")
+    conn.commit()
+
+
+@cache_migration("024_codex_fused_ingest_rebuild")
+def _024_codex_fused_ingest_rebuild(conn: sqlite3.Connection) -> None:
+    """Clear stale Codex cache state for #294 S1's fused source reingest.
+
+    Pre-S1 Codex rows lack provider-root identity, qualified conversation
+    linkage, quota observations, and physical event payloads. Those facts are
+    not recoverable from the cache, so this migration clears only the Codex
+    accounting/file surface and partial S1 derived rows; the next normal Codex
+    sync rederives them from rollout source. Claude tables and Claude quota
+    snapshots remain untouched.
+
+    The handler takes ``cache.db.codex.lock`` before ``BEGIN IMMEDIATE`` — the
+    same fcntl-then-SQLite order as ``sync_codex_cache``. Contention raises
+    ``MigrationGateNotMet`` before any DML, so both ordinary and eager cache
+    dispatch defer without a partial clear. The DELETE-only transition is safe
+    to retry after a crash between this commit and the dispatcher's separate
+    marker stamp: rerunning against its own empty Codex state is a no-op.
+    Never self-stamp; the dispatcher owns ``schema_migrations`` and
+    ``user_version``.
+    """
+    lock_path = _cache_db_codex_lock_path_for_conn(conn)
+    lock_fh = None
+    if lock_path is not None:
+        lock_fh = open(lock_path, "w")
+        try:
+            fcntl.flock(lock_fh, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            lock_fh.close()
+            raise MigrationGateNotMet(
+                "cache.db.codex.lock held by a concurrent sync_codex_cache; "
+                "deferring cache 024 fused-ingest rebuild (#294 S1)"
+            )
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        try:
+            conn.execute("DELETE FROM codex_session_entries")
+            conn.execute("DELETE FROM codex_session_files")
+            conn.execute("DELETE FROM quota_window_snapshots WHERE source = 'codex'")
+            conn.execute("DELETE FROM codex_conversation_threads")
+            conn.execute("DELETE FROM codex_conversation_events")
+            conn.execute("DELETE FROM codex_source_roots")
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
+    finally:
+        if lock_fh is not None:
+            try:
+                fcntl.flock(lock_fh, fcntl.LOCK_UN)
+            except OSError:
+                pass
+            lock_fh.close()
+
+
 # === Region 7d: Stats migration 008_recompute_weekly_cost_snapshots_dedup_fix ===
 
 @stats_migration("008_recompute_weekly_cost_snapshots_dedup_fix")
@@ -5001,6 +5274,19 @@ def _migration_unify_budget_milestones_vendor(conn: sqlite3.Connection) -> None:
         raise
 
 
+@stats_migration("013_codex_quota_projection_state")
+def _migration_codex_quota_projection_state(conn: sqlite3.Connection) -> None:
+    """Create the durable provider-neutral quota projection tables.
+
+    All physical evidence stays in cache.db's ``quota_window_snapshots``.  This
+    migration deliberately performs no cache read or data backfill: a later
+    full projector transaction creates the interpreted rows from the committed
+    physical set.  The schema helper is safe after a crash before central
+    stamping, so the dispatcher can retry without duplicate state.
+    """
+    _cctally_core._apply_quota_projection_schema(conn)
+
+
 # === Region 8: Test-only migration registration (was bin/cctally:12086-12140) ===
 
 # ──────────────────────────────────────────────────────────────────────

package/bin/_cctally_diff.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 
 import argparse
 import dataclasses
+import json
 import shutil
 import sqlite3
 import sys
@@ -104,14 +105,24 @@ def _emit_diff_debug_samples(args, window_a, window_b) -> None:
 def cmd_diff(args: argparse.Namespace) -> int:
     """Compare Claude usage between two windows."""
     c = _cctally()
+    c._share_validate_args(args)
     now_utc = _command_as_of()
     if getattr(args, "debug_now", False):
         print(f"now_utc={c._iso_z(now_utc)}")
         return 0
 
-    # Resolve anchors (None when no snapshots exist; week tokens then
-    # raise NoAnchorError in the parser).
-    anchor_week_start, anchor_resets_at = dk._diff_resolve_anchor(now_utc)
+    # The source-aware all-provider path resolves calendar week tokens once
+    # before dispatching either provider.  Reuse those absolute, half-open
+    # windows for Claude instead of attempting to reinterpret the original
+    # tokens against its subscription-week anchor.  Ordinary Claude invocations
+    # keep the established anchor/parser path byte-for-byte.
+    supplied_windows = getattr(args, "_source_analytics_windows", None)
+    if supplied_windows is None:
+        # Resolve anchors (None when no snapshots exist; week tokens then
+        # raise NoAnchorError in the parser).
+        anchor_week_start, anchor_resets_at = dk._diff_resolve_anchor(now_utc)
+    else:
+        anchor_week_start, anchor_resets_at = None, None
 
     # Validation already happened via _argparse_tz; resolve now to a ZoneInfo
     # (or None for "local") and derive the IANA name for window resolution.
@@ -124,18 +135,35 @@ def cmd_diff(args: argparse.Namespace) -> int:
     tz_name = (tz_obj.key if tz_obj is not None else c._local_tz_name())
 
     try:
-        window_a = dk._parse_diff_window(
-            args.a, now_utc=now_utc,
-            anchor_resets_at=anchor_resets_at,
-            anchor_week_start=anchor_week_start,
-            tz_name=tz_name,
-        )
-        window_b = dk._parse_diff_window(
-            args.b, now_utc=now_utc,
-            anchor_resets_at=anchor_resets_at,
-            anchor_week_start=anchor_week_start,
-            tz_name=tz_name,
-        )
+        if supplied_windows is not None:
+            def _from_source_window(window):
+                start = window.start_at
+                end = window.end_at
+                return dk.ParsedWindow(
+                    label=window.label,
+                    start_utc=start,
+                    end_utc=end,
+                    length_days=(end - start).total_seconds() / 86400,
+                    kind=window.kind,
+                    week_aligned=False,
+                    full_weeks_count=0,
+                )
+
+            window_a = _from_source_window(supplied_windows[0])
+            window_b = _from_source_window(supplied_windows[1])
+        else:
+            window_a = dk._parse_diff_window(
+                args.a, now_utc=now_utc,
+                anchor_resets_at=anchor_resets_at,
+                anchor_week_start=anchor_week_start,
+                tz_name=tz_name,
+            )
+            window_b = dk._parse_diff_window(
+                args.b, now_utc=now_utc,
+                anchor_resets_at=anchor_resets_at,
+                anchor_week_start=anchor_week_start,
+                tz_name=tz_name,
+            )
     except dk.NoAnchorError as exc:
         print(f"diff: {exc}", file=sys.stderr)
         return 1
@@ -221,7 +249,12 @@ def cmd_diff(args: argparse.Namespace) -> int:
     }
 
     if args.emit_json:
-        print(dk._diff_render_json(result, options=options))
+        payload = dk._diff_to_json_payload(result, options=options)
+        sink = getattr(args, "_source_result_sink", None)
+        if sink is not None:
+            sink(payload)
+        else:
+            print(json.dumps(payload, indent=2))
         return 0
 
     # Session A (spec §7.3): route through the new color resolver so

package/bin/_cctally_doctor.py

@@ -42,6 +42,65 @@ def _cctally():
     return sys.modules["cctally"]
 
 
+def _codex_lifecycle_activity_24h(
+    *, root_keys: set[str], now_utc: dt.datetime,
+) -> dict[str, dict]:
+    """Read root-qualified Codex lifecycle outcomes from bounded local logs.
+
+    The parser intentionally accepts only timestamped token records and retains
+    aggregate lifecycle counters.  It never loads session, prompt, or response
+    content into doctor state.
+    """
+    cutoff = now_utc - dt.timedelta(hours=24)
+    records: dict[str, dict] = {}
+    for path in (
+        _cctally_core.HOOK_TICK_LOG_ROTATED_PATH,
+        _cctally_core.HOOK_TICK_LOG_PATH,
+    ):
+        try:
+            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+        except OSError:
+            continue
+        for line in lines:
+            tokens = line.split()
+            if not tokens:
+                continue
+            try:
+                captured_at = parse_iso_datetime(tokens[0], "codex lifecycle log timestamp")
+                captured_at = captured_at.astimezone(dt.timezone.utc)
+            except (IndexError, ValueError, TypeError):
+                continue
+            if captured_at > now_utc:
+                continue
+            fields = {
+                token.split("=", 1)[0]: token.split("=", 1)[1]
+                for token in tokens[1:] if "=" in token
+            }
+            if fields.get("provider") != "codex":
+                continue
+            key = fields.get("source_root_key")
+            if key not in root_keys:
+                continue
+            outcome = fields.get("result")
+            if outcome not in {"success", "error"}:
+                continue
+            row = records.setdefault(key, {
+                "last_tick_at": None,
+                "success_count_24h": 0,
+                "error_count_24h": 0,
+            })
+            if outcome == "success":
+                prior = row["last_tick_at"]
+                if prior is None or captured_at > prior:
+                    row["last_tick_at"] = captured_at
+            if captured_at >= cutoff:
+                if outcome == "success":
+                    row["success_count_24h"] += 1
+                else:
+                    row["error_count_24h"] += 1
+    return records
+
+
 def doctor_gather_state(
     *,
     now_utc: "dt.datetime | None" = None,
@@ -398,6 +457,62 @@ def doctor_gather_state(
     except Exception:
         pass
 
+    # ── Codex quota lifecycle (#294 S2) ──────────────────────────────
+    # All three probes are read-only and root-qualified.  The physical cache
+    # adapter preserves S1's per-window degradation, while setup's existing
+    # inspector supplies the exact owned-hook state without exposing paths.
+    codex_quota_windows: list[dict] = []
+    try:
+        observations = c._cctally_quota.load_codex_quota_observations()
+        by_identity: dict[object, list] = {}
+        for observation in observations:
+            by_identity.setdefault(observation.identity, []).append(observation)
+        for identity in sorted(
+            by_identity,
+            key=lambda item: (
+                item.source, item.source_root_key, item.logical_limit_key,
+                item.observed_slot, item.window_minutes,
+            ),
+        ):
+            freshness = c.quota_freshness(by_identity[identity], now_utc)
+            codex_quota_windows.append({
+                "identity": {
+                    "source": identity.source,
+                    "source_root_key": identity.source_root_key,
+                    "logical_limit_key": identity.logical_limit_key,
+                    "observed_slot": identity.observed_slot,
+                    "window_minutes": identity.window_minutes,
+                },
+                "latest_capture_at": freshness.captured_at,
+                "freshness_state": freshness.state,
+                "age_seconds": freshness.age_seconds,
+                "stale_after_seconds": freshness.stale_after_seconds,
+            })
+    except Exception:
+        codex_quota_windows = []
+
+    codex_hook_roots: list[dict] = []
+    try:
+        codex_binary = str(c._setup_resolve_hook_target(repo_root))
+        hook_rows = [
+            c._cctally_setup._codex_hook_row(root, codex_binary)
+            for root in c._setup_codex_hook_roots()
+        ]
+        codex_hook_roots = [
+            {"source_root_key": row["source_root_key"], "state": row["state"]}
+            for row in sorted(hook_rows, key=lambda row: row["source_root_key"])
+        ]
+    except Exception:
+        codex_hook_roots = []
+
+    try:
+        codex_lifecycle_activity_24h = _codex_lifecycle_activity_24h(
+            root_keys={row["source_root_key"] for row in codex_hook_roots},
+            now_utc=now_utc,
+        )
+    except Exception:
+        codex_lifecycle_activity_24h = {}
+
     # ── Parse health (#279 S2 F5a) ───────────────────────────────────
     parse_health_claude = parse_health_codex = None
     try:
@@ -659,6 +774,9 @@ def doctor_gather_state(
         locks_held=locks_held,
         # #297: cache.db WAL size backstop (gathered outside the deep branch).
         cache_db_wal_bytes=cache_db_wal_bytes,
+        codex_quota_windows=codex_quota_windows,
+        codex_hook_roots=codex_hook_roots,
+        codex_lifecycle_activity_24h=codex_lifecycle_activity_24h,
     )
 
 

package/bin/_cctally_forecast.py

@@ -1011,9 +1011,12 @@ def cmd_report(args: argparse.Namespace) -> int:
                 c._share_render_and_emit(snap, args)
                 return 0
             if args.json:
-                print(json.dumps(
-                    c.stamp_schema_version({"current": None, "trend": []}),
-                    indent=2))
+                payload = c.stamp_schema_version({"current": None, "trend": []})
+                sink = getattr(args, "_source_result_sink", None)
+                if sink is not None:
+                    sink(payload)
+                else:
+                    print(json.dumps(payload, indent=2))
             else:
                 print("No data yet. Add record-usage to your status line script (see record-usage --help).")
             return 0
@@ -1206,7 +1209,12 @@ def cmd_report(args: argparse.Namespace) -> int:
             return 0
 
         if args.json:
-            print(json.dumps(c.stamp_schema_version(output), indent=2))
+            payload = c.stamp_schema_version(output)
+            sink = getattr(args, "_source_result_sink", None)
+            if sink is not None:
+                sink(payload)
+            else:
+                print(json.dumps(payload, indent=2))
             return 0
 
         if current_row is not None: