cctally 1.52.1 → 1.53.0

package/bin/_cctally_db.py

@@ -2391,6 +2391,39 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
         CREATE INDEX IF NOT EXISTS idx_conv_sessions_recent
             ON conversation_sessions(last_activity_utc DESC, session_id DESC);
 
+        -- #217 S2 / I-3: file-path search axis. One row per WRITE-class file
+        -- touch (Edit/MultiEdit/Write/NotebookEdit) inside a conversation message,
+        -- derived from blocks_json by _derive_file_touches. message_id =
+        -- conversation_messages.id (the turn anchor). Derived/re-derivable state:
+        -- _fill_file_touches accumulates via INSERT OR IGNORE, the destructive
+        -- message paths delete it (clear_conversation_messages / per-source
+        -- reingest), and migration 019 arms a one-time history backfill.
+        --
+        -- CRITICAL: this is a PLAIN table with NO dependency on the FTS shape, and
+        -- it is created HERE — inside the unconditional executescript, BEFORE the
+        -- FTS5 ``legacy_present`` early-return below — so it ALWAYS exists
+        -- regardless of FTS topology. (The I-2 title-FTS bug created its vtable
+        -- AFTER that early-return, so its consumer crashed on a legacy-shape +
+        -- both-pending upgrade; the file-touches table must not repeat that class.)
+        CREATE TABLE IF NOT EXISTS conversation_file_touches (
+            message_id  INTEGER NOT NULL,
+            session_id  TEXT NOT NULL,
+            uuid        TEXT,
+            file_path   TEXT NOT NULL,
+            tool        TEXT NOT NULL,
+            UNIQUE(message_id, file_path, tool)
+        );
+        -- COLLATE NOCASE is load-bearing (#217 S2 / I-3 review Important #1): the
+        -- default ``LIKE`` is case-insensitive, and SQLite only rides a btree index
+        -- for ``file_path LIKE 'prefix%'`` when the index column folds the same way
+        -- (NOCASE) — a BINARY-collated index leaves the prefix probe a full SCAN. So
+        -- the kind=files PREFIX branch (``_search_files``) is genuinely index-assisted
+        -- ONLY with this NOCASE collation. (The substring branch leads with '%' and is
+        -- a documented scan regardless.) NOCASE folds A-Z/a-z the same way the LIKE
+        -- built-in does, so matching semantics are byte-identical to the prior index.
+        CREATE INDEX IF NOT EXISTS idx_file_touches_path
+            ON conversation_file_touches(file_path COLLATE NOCASE);
+
         CREATE TABLE IF NOT EXISTS codex_session_files (
             path             TEXT PRIMARY KEY,
             size_bytes       INTEGER NOT NULL,
@@ -2447,17 +2480,19 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
     add_column_if_missing(conn, "conversation_messages", "source_tool_use_id", "TEXT")
     # #177 Session 1: enriched data-contract columns. Idempotent column-adds (no
     # marker, no version — exactly like source_tool_use_id); cache migration 007
-    # then re-ingests so the values actually land on historical rows. search_aux
-    # is the parser-populated non-prose blob the conversation_fts_aux index reads.
+    # then re-ingests so the values actually land on historical rows.
     add_column_if_missing(conn, "conversation_messages", "stop_reason", "TEXT")
     add_column_if_missing(conn, "conversation_messages", "attribution_skill", "TEXT")
     add_column_if_missing(conn, "conversation_messages", "attribution_plugin", "TEXT")
-    add_column_if_missing(
-        conn, "conversation_messages", "search_aux", "TEXT NOT NULL DEFAULT ''")
-    # #177 S6: split the non-prose search index into two columns so kind facets
-    # (Tools / Thinking) are exact in SQL. ``search_aux`` above is documented-dead
-    # — the writer stops populating it (always ''); the consolidated multi-column
-    # conversation_fts(text, search_tool, search_thinking) indexes these instead.
+    # #217 S1 / U7a: ``search_aux`` (the pre-#177-S6 non-prose FTS blob, always
+    # '' since the split) is NO LONGER emitted here — a fresh install never
+    # carries it, and cache migration ``016_drop_search_aux`` drops it from an
+    # existing install once the migration-010 search split is consumed. The
+    # legacy ``conversation_fts_aux`` test/fixture standup
+    # (``_create_conversation_fts_aux_table``) adds the column locally itself.
+    # #177 S6: the split non-prose search index — two columns so kind facets
+    # (Tools / Thinking) are exact in SQL. The consolidated multi-column
+    # conversation_fts(text, search_tool, search_thinking) indexes these.
     # Idempotent column-adds (no marker, no version); migration 010 backfills the
     # values onto existing history from blocks_json under the cache.db.lock flock.
     add_column_if_missing(
@@ -2515,22 +2550,40 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
             # (clear_conversation_messages, which drops + recreates the trigger
             # set) can never drift.
             _create_conversation_fts_triggers(conn)
+            # #217 S2 / E7: the external-content title FTS rides the SAME
+            # FTS5-available envelope (P1-6). It is independent of the message
+            # FTS (external-content over conversation_ai_titles, not
+            # conversation_messages), so a failed message-FTS create above never
+            # reaches here; but a failed title-FTS create must drop both message
+            # and title triggers and mark unavailable, so the shared except below
+            # owns the cleanup. Idempotent (IF NOT EXISTS).
+            conn.execute(_CONV_TITLE_FTS_DDL)
+            _create_conversation_title_fts_triggers(conn)
             if recovering:
                 # Repopulate the freshly-(re)created index from the base table
                 # so pre-recovery history is searchable. Cheap no-op when
                 # conversation_messages is empty.
                 conn.execute(
                     "INSERT INTO conversation_fts(conversation_fts) VALUES('rebuild')")
+                # The title FTS is external-content over conversation_ai_titles,
+                # so a prior FTS5-unavailable run that ingested titles without the
+                # AI trigger left the title index stale too — rebuild it the same
+                # way (cheap no-op when conversation_ai_titles is empty).
+                conn.execute(
+                    "INSERT INTO conversation_title_fts(conversation_title_fts) "
+                    "VALUES('rebuild')")
             conn.execute("DELETE FROM cache_meta WHERE key='fts5_unavailable'")
         except sqlite3.OperationalError:
             # partial create cleanup, then mark unavailable. _drop drops the
-            # split trigger set (and any legacy aux trigger names, harmlessly),
-            # and we drop both possible vtables, so a failed create can't leave a
-            # live trigger over a missing table.
+            # split trigger set (and any legacy aux trigger names, harmlessly)
+            # plus the title trigger set, and we drop all three possible vtables,
+            # so a failed create can't leave a live trigger over a missing table.
             _drop_conversation_fts_triggers(conn)
+            _drop_conversation_title_fts_triggers(conn)
             try:
                 conn.execute("DROP TABLE IF EXISTS conversation_fts")
                 conn.execute("DROP TABLE IF EXISTS conversation_fts_aux")
+                conn.execute("DROP TABLE IF EXISTS conversation_title_fts")
             except sqlite3.OperationalError:
                 pass
             _set_cache_meta(conn, "fts5_unavailable", "1")
@@ -2545,6 +2598,14 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
         # itself can't be DROPped without the fts5 module, but with no triggers
         # nothing writes to it.)
         _drop_conversation_fts_triggers(conn)
+        # #217 S2 / E7 (P1-6): same hazard for the title FTS — a prior
+        # FTS5-capable run may have left conv_title_fts_* triggers that now
+        # reference an unusable conversation_title_fts. They fire inside the
+        # SAME per-file ingest transaction (the conversation_ai_titles upsert),
+        # so an orphan title trigger would roll back the cost ingest too. Drop
+        # them under the LIKE fallback; kind=title degrades to a LIKE scan over
+        # conversation_ai_titles.
+        _drop_conversation_title_fts_triggers(conn)
         _set_cache_meta(conn, "fts5_unavailable", "1")
     # The FTS branch above issues DML (DELETE/INSERT on cache_meta) which opens
     # an implicit transaction under sqlite3's legacy autocommit mode. Close it
@@ -2616,6 +2677,19 @@ def _create_conversation_fts_aux_table(conn: sqlite3.Connection) -> None:
     # the column — notably ``sqlite3.Connection.iterdump`` (the dump emits
     # ``SELECT quote(aux) FROM conversation_fts_aux`` → "no such column"). Aligning
     # the names keeps the index dumpable and is the documented FTS5 posture.
+    #
+    # #217 S1 / U7a: the live ``_apply_cache_schema`` no longer emits
+    # ``search_aux`` (migration 016 drops it once the search split is consumed),
+    # so this LEGACY standup adds the column LOCALLY here — it stands up the
+    # pre-S6 aux shape and needs the content-table column to exist by NAME.
+    # Idempotent (duplicate-column tolerated) so a DB that still carries the
+    # column (pre-016 existing install) is a no-op.
+    try:
+        conn.execute(
+            "ALTER TABLE conversation_messages "
+            "ADD COLUMN search_aux TEXT NOT NULL DEFAULT ''")
+    except sqlite3.OperationalError:
+        pass  # column already present (pre-016 existing install)
     conn.execute(
         "CREATE VIRTUAL TABLE IF NOT EXISTS conversation_fts_aux "
         "USING fts5(search_aux, content='conversation_messages', content_rowid='id')")
@@ -2726,6 +2800,77 @@ def _drop_conversation_fts_triggers(conn: sqlite3.Connection) -> None:
             pass
 
 
+# #217 S2 / E7: external-content FTS5 over the per-session AI title
+# (conversation_ai_titles). The single column name MUST match the content table
+# column (``ai_title``) BY NAME (external-content FTS5 resolves columns through
+# the content table by name — same rule the message FTS follows). Fresh installs
+# create this directly inside ``_apply_cache_schema``'s FTS5-available branch;
+# migration 018 creates it for existing installs. The content-table ``rowid`` is
+# STABLE across title updates (``_AI_TITLE_UPSERT_SQL`` is ``ON CONFLICT(session_id)
+# DO UPDATE``, not delete+reinsert), so the AU trigger covers the update path and
+# the external-content choice is sound.
+_CONV_TITLE_FTS_DDL = (
+    "CREATE VIRTUAL TABLE IF NOT EXISTS conversation_title_fts USING fts5("
+    "ai_title, content='conversation_ai_titles', content_rowid='rowid')"
+)
+
+# Title-FTS sync triggers (external-content FTS5). Mirror the message-FTS
+# conv_fts_ai/ad/au idiom: AD/AU carry the OLD rowid via the ``'delete'``
+# command. Defined ONCE here so every create/drop site stays in lockstep.
+_CONV_TITLE_FTS_TRIGGER_DDL = (
+    "CREATE TRIGGER IF NOT EXISTS conv_title_fts_ai "
+    "AFTER INSERT ON conversation_ai_titles "
+    "BEGIN INSERT INTO conversation_title_fts(rowid, ai_title) "
+    "VALUES (new.rowid, new.ai_title); END",
+    "CREATE TRIGGER IF NOT EXISTS conv_title_fts_ad "
+    "AFTER DELETE ON conversation_ai_titles "
+    "BEGIN INSERT INTO conversation_title_fts(conversation_title_fts, rowid, ai_title) "
+    "VALUES('delete', old.rowid, old.ai_title); END",
+    "CREATE TRIGGER IF NOT EXISTS conv_title_fts_au "
+    "AFTER UPDATE OF ai_title ON conversation_ai_titles "
+    "BEGIN INSERT INTO conversation_title_fts(conversation_title_fts, rowid, ai_title) "
+    "VALUES('delete', old.rowid, old.ai_title); "
+    "INSERT INTO conversation_title_fts(rowid, ai_title) "
+    "VALUES (new.rowid, new.ai_title); END",
+)
+_CONV_TITLE_FTS_TRIGGER_NAMES = (
+    "conv_title_fts_au", "conv_title_fts_ad", "conv_title_fts_ai")
+
+
+def _create_conversation_title_fts_triggers(conn: sqlite3.Connection) -> None:
+    """Create the #217 S2 title-FTS sync trigger set — idempotent (each is
+    ``IF NOT EXISTS``). The caller must have already created
+    ``conversation_title_fts`` (the triggers reference it)."""
+    for stmt in _CONV_TITLE_FTS_TRIGGER_DDL:
+        conn.execute(stmt)
+
+
+def _drop_conversation_title_fts_triggers(conn: sqlite3.Connection) -> None:
+    """Drop the title-FTS sync trigger set — idempotent (``IF EXISTS``). Swallows
+    ``OperationalError`` per statement so an absent set (FTS5-unavailable build)
+    is tolerated. P1-6: dropping these on a no-FTS5 build is what keeps a
+    ``conversation_ai_titles`` upsert from firing a trigger against the missing
+    vtable and rolling back the shared per-file ingest transaction."""
+    for name in _CONV_TITLE_FTS_TRIGGER_NAMES:
+        try:
+            conn.execute(f"DROP TRIGGER IF EXISTS {name}")
+        except sqlite3.OperationalError:
+            pass
+
+
+def _clear_conversation_file_touches(conn: sqlite3.Connection) -> None:
+    """#217 S2 / I-3 (P1-4): drop ALL file-touch rows on a full
+    clear/rebuild/truncation. ``conversation_file_touches`` is derived state keyed
+    by ``conversation_messages.id``, and a full clear recycles those rowids — so a
+    surviving touch row would point at a future, unrelated message. Tolerates a
+    missing table defensively (belt-and-suspenders; ``_apply_cache_schema`` always
+    creates it before the FTS branch, so it should exist on any schema'd conn)."""
+    try:
+        conn.execute("DELETE FROM conversation_file_touches")
+    except sqlite3.OperationalError:
+        pass   # table not yet created (pre-schema conn); nothing to clear
+
+
 def clear_conversation_messages(conn: sqlite3.Connection) -> None:
     """Full-clear ``conversation_messages`` + its FTS index WITHOUT firing the
     per-row delete trigger O(rows) (#138).
@@ -2765,10 +2910,12 @@ def clear_conversation_messages(conn: sqlite3.Connection) -> None:
 
     if fts_unavailable:
         conn.execute("DELETE FROM conversation_messages")
+        _clear_conversation_file_touches(conn)
         return
 
     _drop_conversation_fts_triggers(conn)
     conn.execute("DELETE FROM conversation_messages")
+    _clear_conversation_file_touches(conn)
     conn.execute("INSERT INTO conversation_fts(conversation_fts) VALUES('delete-all')")
     # #177 S6: the consolidated split table is the only FTS vtable on a swapped /
     # fresh DB. A pre-swap legacy install still carries conversation_fts_aux, so
@@ -3502,6 +3649,195 @@ def _015_conversation_sessions_filter_columns(conn: sqlite3.Connection) -> None:
     conn.commit()
 
 
+def _conversation_messages_has_column(conn: sqlite3.Connection, column: str) -> bool:
+    """True iff ``conversation_messages`` carries *column*. Tolerates a missing
+    table (a path-less / schema-not-applied connection) -> False."""
+    try:
+        cols = [r[1] for r in conn.execute(
+            "PRAGMA table_info(conversation_messages)")]
+    except sqlite3.OperationalError:
+        return False
+    return column in cols
+
+
+def _legacy_aux_fts_present(conn: sqlite3.Connection) -> bool:
+    """True iff the pre-#177-S6 ``conversation_fts_aux`` external-content table
+    OR any of its sync triggers (which reference ``search_aux``) still exist.
+
+    While EITHER is live, an ``ALTER TABLE conversation_messages DROP COLUMN
+    search_aux`` FAILS (the trigger/index body references the column). Migration
+    010's state machine (``_consume_search_split`` in sync_cache) owns tearing
+    these down; 016 only WAITS until they are gone. Tolerates a missing
+    ``sqlite_master`` read -> False (no aux shape to block on)."""
+    try:
+        _trig_ph = ",".join("?" for _ in _CONV_FTS_AUX_TRIGGER_NAMES)
+        row = conn.execute(
+            "SELECT 1 FROM sqlite_master "
+            "WHERE (type='table' AND name='conversation_fts_aux') "
+            f"   OR (type='trigger' AND name IN ({_trig_ph})) "
+            "LIMIT 1",
+            _CONV_FTS_AUX_TRIGGER_NAMES,
+        ).fetchone()
+    except sqlite3.OperationalError:
+        return False
+    return row is not None
+
+
+@cache_migration("016_drop_search_aux")
+def _016_drop_search_aux(conn: sqlite3.Connection) -> None:
+    """Drop the documented-dead ``conversation_messages.search_aux`` column
+    (#217 S1 / U7a) — it has been ``''`` on every row since #177 S6 split the
+    non-prose search index into ``search_tool``/``search_thinking`` and the live
+    ``conversation_fts`` stopped referencing it.
+
+    THREE guards, in order (the drop is the LAST thing that happens):
+
+      1. Column-presence — idempotent skip-as-applied when ``search_aux`` is
+         already gone. A fresh install never carries it (``_apply_cache_schema``
+         no longer emits it post-#217), so the dispatcher stamps 016 without the
+         column ever existing; an existing install drops it once.
+      2. ``sqlite_version() >= 3.35`` — ``ALTER TABLE … DROP COLUMN`` did not
+         exist before SQLite 3.35. On an older build we SKIP-as-applied, leaving
+         the harmless dead column (never a hard fail; cache.db is re-derivable,
+         and a later open on a newer SQLite still can't re-run a stamped
+         migration — the column simply persists, which is benign).
+      3. Search-split-consumed gate (Codex P1) — DEFER via ``MigrationGateNotMet``
+         (retried next open) when migration 010's
+         ``conversation_search_split_pending`` flag is set OR the legacy
+         ``conversation_fts_aux`` table / its triggers still exist. ``DROP COLUMN``
+         FAILS while a trigger references ``search_aux`` (confirmed in-memory), so
+         016 must wait for ``_consume_search_split`` (sync_cache) to backfill the
+         split columns + swap the FTS shape. 016 does NOT tear the aux table down
+         itself — 010's state machine owns that. On a ``--no-sync``-forever DB the
+         split never consumes and the column persists harmlessly (re-derivable).
+
+    The handler does its own DDL only; the dispatcher central-stamps the marker
+    (#140) on a clean return (the apply path) — it does NOT stamp on the
+    ``MigrationGateNotMet`` defer path, so the migration stays pending and retries.
+    """
+    if not _conversation_messages_has_column(conn, "search_aux"):
+        # Guard 1: already absent (fresh install, or a prior 016 run). The
+        # dispatcher central-stamps on this clean return.
+        return
+    sqlite_version = tuple(
+        int(p) for p in sqlite3.sqlite_version.split(".")[:3]
+    )
+    if sqlite_version < (3, 35, 0):
+        # Guard 2: no DROP COLUMN on this build. Skip-as-applied (stamp on the
+        # clean return) — the dead column stays, harmless.
+        return
+    try:
+        split_pending = conn.execute(
+            "SELECT 1 FROM cache_meta "
+            "WHERE key='conversation_search_split_pending'"
+        ).fetchone() is not None
+    except sqlite3.OperationalError:
+        # No cache_meta table (a bare / path-less connection) -> no pending
+        # flag to honor; the legacy-aux probe below still guards the topology.
+        split_pending = False
+    if split_pending or _legacy_aux_fts_present(conn):
+        # Guard 3: the search split is not yet consumed — the legacy aux FTS
+        # may still reference search_aux, so DROP COLUMN would fail. DEFER; the
+        # next sync's _consume_search_split clears the flag + drops the aux
+        # shape, and a later open then drops the column.
+        raise MigrationGateNotMet(
+            "search_aux drop deferred: migration-010 search split not yet "
+            "consumed (pending flag or legacy conversation_fts_aux still present)"
+        )
+    conn.execute(
+        "ALTER TABLE conversation_messages DROP COLUMN search_aux")
+    conn.commit()
+
+
+@cache_migration("017_arm_nested_agent_reingest")
+def _017_arm_nested_agent_reingest(conn: sqlite3.Connection) -> None:
+    """Flag-only re-ingest so existing nested-subagent (grandchild) results whose
+    ``agentId:`` trailer landed PAST the 16 KB ``_TOOL_RESULT_CAP`` clip re-link
+    on existing history (#217 S1 / U6). The parser now stamps a structured
+    ``block["agent_id"]`` (+ usage) at INGEST — over the FULL raw, before the clip
+    — so the offset-0 re-parse re-derives the link with zero new consumption code
+    (the kernel's existing ``b.pop("agent_id")`` consumer picks it up). Until
+    consumed, old rows fall back to the read-time regex over the (clipped) text —
+    today's behavior, no worse.
+
+    Sets the DISTINCT ``conversation_reingest_nested_agent_pending`` flag (NOT the
+    shared ``conversation_reingest_pending``, which also gates migration 005's
+    read-time human-fallback in the query kernel — re-arming it could misclassify
+    a genuine human prompt during the pre-reingest window). Consumption rides the
+    #179 RESUMABLE per-file reingest (``_resumable_reingest_conversation_messages``)
+    — the flag is wired into ``_TARGETED_DECLINE_FLAGS`` + ``_REINGEST_FLAG_KEYS``
+    + the resumable-reingest flag SELECT + the two cleanup DELETE lists in
+    ``_cctally_cache.py`` (all five sites; missing one either never triggers or
+    re-arms forever). Central stamp via the dispatcher (#140); a fresh install
+    stamps it WITHOUT running (empty table -> the flag, if ever set, is a harmless
+    no-op). Mirrors 014/009/007."""
+    _set_cache_meta(conn, "conversation_reingest_nested_agent_pending", "1")
+    conn.commit()
+
+
+@cache_migration("018_create_conversation_title_fts")
+def _018_create_conversation_title_fts(conn: sqlite3.Connection) -> None:
+    """#217 S2 / E7: arm the external-content title FTS over
+    ``conversation_ai_titles`` so AI titles are findable via ``kind=title``.
+
+    Flag-only arm. The ``conversation_title_fts`` virtual table + its
+    conv_title_fts_ai/ad/au sync triggers are created by ``_apply_cache_schema``
+    (runs on every open, fresh + existing installs) inside the SAME FTS5-available
+    envelope as the message FTS (P1-6) — so on a no-FTS5 build the table+triggers
+    are simply absent and a title upsert never rolls back the ingest. This handler
+    does NO DDL (mirrors 012's flag-only pattern): it just arms the DISTINCT
+    ``conversation_title_fts_backfill_pending`` flag (the "distinct reingest flag
+    per enrichment" rule — its own flag, never the shared one) so the next
+    flock-held full sync runs ``_consume_title_fts`` (an FTS5 ``'rebuild'``, P1-7)
+    to populate the index from existing history.
+
+    The flag joins ``_TARGETED_DECLINE_FLAGS`` ONLY — NEVER ``_REINGEST_FLAG_KEYS``
+    (P1-2): that set means "run ``_resumable_reingest_conversation_messages``" (a
+    full message delete/reinsert + rowid churn) which a title-FTS backfill must
+    not trigger; the title index is external-content over conversation_ai_titles
+    and a ``'rebuild'`` repopulates it without touching conversation_messages.
+
+    No data work here -> the dispatcher's central stamp (#140) marks a complete
+    handler; a fresh install stamps WITHOUT a populated history (its incremental
+    walk fills the title FTS via the AI trigger as titles ingest, and the consumed
+    backfill 'rebuild' no-ops). Mirrors 012's flag-only arm."""
+    _set_cache_meta(conn, "conversation_title_fts_backfill_pending", "1")
+    conn.commit()
+
+
+@cache_migration("019_create_conversation_file_touches")
+def _019_create_conversation_file_touches(conn: sqlite3.Connection) -> None:
+    """#217 S2 / I-3: arm the file-path search axis backfill so existing history's
+    WRITE-class file touches (Edit/MultiEdit/Write/NotebookEdit) are searchable via
+    ``kind=files``.
+
+    Flag-only arm (mirrors 018's pattern). The ``conversation_file_touches`` table
+    + its ``COLLATE NOCASE`` path index (``idx_file_touches_path``) are created by
+    ``_apply_cache_schema`` (runs on every open, fresh + existing installs) — and
+    CRITICALLY before the FTS5 ``legacy_present`` early-return, since the table is
+    plain and has NO dependency on the FTS shape (so a legacy-shape upgrade still
+    gets it). The NOCASE collation is what lets the kind=files PREFIX search ride
+    the index (default LIKE is case-insensitive; a BINARY index can't serve it —
+    review Important #1). This handler does NO DDL: it just
+    arms the DISTINCT ``conversation_reingest_file_touches_pending`` flag (the
+    "distinct reingest flag per enrichment" rule — its own flag, never the shared
+    one) so the next flock-held full sync runs ``_consume_file_touches`` to derive
+    touches from existing ``blocks_json`` history.
+
+    The flag joins ``_TARGETED_DECLINE_FLAGS`` ONLY — NEVER ``_REINGEST_FLAG_KEYS``
+    (P1-2): that set means "run ``_resumable_reingest_conversation_messages``" (a
+    full message delete/reinsert + rowid churn) which a file-touches backfill must
+    not trigger; the backfill derives from the already-present ``blocks_json`` and
+    INSERT-OR-IGNOREs into a separate table without touching conversation_messages.
+
+    No data work here -> the dispatcher's central stamp (#140) marks a complete
+    handler; a fresh install stamps WITHOUT a populated history (its incremental
+    walk fills touches per ingested tick via _fill_file_touches, and the consumed
+    backfill no-ops). Mirrors 018's flag-only arm."""
+    _set_cache_meta(conn, "conversation_reingest_file_touches_pending", "1")
+    conn.commit()
+
+
 # === Region 7d: Stats migration 008_recompute_weekly_cost_snapshots_dedup_fix ===
 
 @stats_migration("008_recompute_weekly_cost_snapshots_dedup_fix")

package/bin/_cctally_doctor.py

@@ -274,6 +274,71 @@ def doctor_gather_state(
     except Exception:
         pass
 
+    # Conversation-sessions rollup consistency (#217 S1 / U9). Two cheap COUNTs
+    # (graceful None on a missing table / unreadable DB) + an in-progress signal
+    # so a transient mid-sync mismatch never WARNs. The in-progress signal is a
+    # NON-BLOCKING cache.db.lock flock probe (a writer mid-walk holds it) OR the
+    # presence of any pending reingest/split/backfill cache_meta flag — doctor
+    # stays read-only and never blocks on the lock.
+    conv_sessions_rollup_count = None
+    conv_messages_distinct_sessions = None
+    conv_rollup_sync_in_progress = False
+    try:
+        if _cctally_core.CACHE_DB_PATH.exists():
+            conn = sqlite3.connect(str(_cctally_core.CACHE_DB_PATH))
+            try:
+                try:
+                    row = conn.execute(
+                        "SELECT COUNT(*) FROM conversation_sessions"
+                    ).fetchone()
+                    if row is not None:
+                        conv_sessions_rollup_count = int(row[0])
+                except sqlite3.OperationalError:
+                    pass  # table absent (pre-rollup) — leave None
+                try:
+                    row = conn.execute(
+                        "SELECT COUNT(DISTINCT session_id) "
+                        "FROM conversation_messages WHERE session_id IS NOT NULL"
+                    ).fetchone()
+                    if row is not None:
+                        conv_messages_distinct_sessions = int(row[0])
+                except sqlite3.OperationalError:
+                    pass
+                # Pending reingest/split/backfill flags ⇒ a full sync hasn't yet
+                # reconciled the rollup. Read the canonical flag set from
+                # _cctally_cache so it stays in lockstep with the sync consumers.
+                try:
+                    import _cctally_cache as _cc_sib  # lazy sibling
+                    flags = tuple(_cc_sib._TARGETED_DECLINE_FLAGS)
+                    placeholders = ",".join("?" for _ in flags)
+                    pend = conn.execute(
+                        f"SELECT 1 FROM cache_meta WHERE key IN ({placeholders}) "
+                        "LIMIT 1", flags).fetchone()
+                    if pend is not None:
+                        conv_rollup_sync_in_progress = True
+                except Exception:
+                    pass
+            finally:
+                conn.close()
+        # Non-blocking flock probe: if a writer (sync_cache / a reingest) holds
+        # the cache.db.lock, the rollup may be mid-recompute → in progress. We
+        # acquire LOCK_EX|LOCK_NB and immediately release; failure (held) is the
+        # signal. Never blocks (LOCK_NB), so doctor stays read-only + prompt.
+        if not conv_rollup_sync_in_progress:
+            lock_path = _cctally_core.CACHE_LOCK_PATH
+            if lock_path is not None and pathlib.Path(lock_path).exists():
+                import fcntl as _fcntl
+                lock_fh = open(str(lock_path), "w")
+                try:
+                    _fcntl.flock(lock_fh, _fcntl.LOCK_EX | _fcntl.LOCK_NB)
+                    _fcntl.flock(lock_fh, _fcntl.LOCK_UN)  # acquired ⇒ quiescent
+                except (BlockingIOError, OSError):
+                    conv_rollup_sync_in_progress = True  # held ⇒ writer mid-flight
+                finally:
+                    lock_fh.close()
+    except Exception:
+        pass
+
     claude_jsonl_present = False
     try:
         claude_dir = pathlib.Path.home() / ".claude" / "projects"
@@ -453,6 +518,10 @@ def doctor_gather_state(
         is_dev_checkout=_cctally_core._is_dev_checkout(),
         # Pricing-freshness check (spec §5.1): trailing-30d coverage gaps.
         pricing_coverage=pricing_coverage,
+        # Conversation-sessions rollup consistency (#217 S1 / U9).
+        conv_sessions_rollup_count=conv_sessions_rollup_count,
+        conv_messages_distinct_sessions=conv_messages_distinct_sessions,
+        conv_rollup_sync_in_progress=conv_rollup_sync_in_progress,
     )
 
 

package/bin/_cctally_record.py

@@ -2217,6 +2217,15 @@ def _build_credit_plan(*, week_start_date, week_start_at, week_end_at,
     `at` either way."""
     to_pct = _normalize_percent(to_pct)
     from_pct = _normalize_percent(from_pct)
+    # Defensive None-guard (issue #212 N3). `_normalize_percent` returns None
+    # for a None input. The CLI never reaches here with None (`--to` is
+    # required + type=float; `--from` always resolves to a float or the caller
+    # errors out first), but this is a public pure helper called directly by
+    # tests and any future non-CLI caller — surface a None as a clear ValueError
+    # (caller -> exit 2) instead of a TypeError from the `0.0 <= None` compare
+    # immediately below.
+    if to_pct is None or from_pct is None:
+        raise ValueError("--to/--from must be numeric")
     if not (0.0 <= to_pct <= 100.0) or not (0.0 <= from_pct <= 100.0):
         raise ValueError("--to/--from must be in [0, 100]")
     if to_pct >= from_pct:
@@ -2666,6 +2675,22 @@ def cmd_record_credit(args) -> int:
             eprint("record-credit: --json requires --yes or --dry-run")
             return 2
 
+        # Fully-applied refuse (M2; state classified at step 2a). A credit
+        # already fully recorded for this week (floor row + command-owned
+        # snapshot) is refused by default. Hoisted ABOVE the interactive
+        # confirm prompt so a TTY user is refused immediately, rather than
+        # being shown the preview, prompted, answering y, and only THEN refused
+        # (issue #212 N2). `--force` is intentionally NOT refused here — it
+        # takes the clear + re-record path at step 4a; a half-applied credit
+        # (is_completion) falls through to finish idempotently. This fires
+        # regardless of --yes/TTY so the precondition failure is uniform; the
+        # earlier --dry-run path still previews (writes nothing) and returns 0.
+        if existing is not None and not is_force and not is_completion:
+            eprint(f"record-credit: a credit is already recorded for this "
+                   f"week (effective={existing[1]}, pre_credit={existing[2]}); "
+                   f"pass --force to re-record")
+            return 2
+
         # No --yes: prompt (TTY) or refuse (non-TTY).
         if not is_yes:
             if not sys.stdin.isatty():
@@ -2682,23 +2707,18 @@ def cmd_record_credit(args) -> int:
                 print("aborted — nothing written")
                 return 0
 
-        # 4a. Existing-floor handling (M2; state classified at step 2a).
-        #     _apply_credit commits the floor row + cleanup BEFORE the synthetic
-        #     snapshot, so a crash in between leaves a half-applied credit
-        #     (floor row, no command-owned snapshot). `existing` /
-        #     `is_completion` were resolved up front (above) keyed on
-        #     week_start_date / weekly_credit_floors.
+        # 4a. Existing-floor handling (M2; state classified at step 2a). The
+        #     fully-applied refuse was hoisted above the confirm prompt (#212
+        #     N2), so only two cases remain here: `--force` clears the prior
+        #     floor + re-records at a fresh effective; a half-applied credit
+        #     (floor row, no command-owned snapshot — a crash between
+        #     _apply_credit's floor commit and the synthetic snapshot) falls
+        #     through to a completion (the plan reuses the existing effective
+        #     and the apply steps are idempotent). `existing`/`is_completion`
+        #     were resolved up front keyed on week_start_date /
+        #     weekly_credit_floors.
         forced = False
-        if existing is not None and not is_force:
-            if not is_completion:
-                # Fully applied -> refuse by default.
-                eprint(f"record-credit: a credit is already recorded for this "
-                       f"week (effective={existing[1]}, pre_credit={existing[2]}); "
-                       f"pass --force to re-record")
-                return 2
-            # else: half-applied -> fall through (completion path; the plan
-            # reuses the existing effective and the apply steps are idempotent).
-        elif existing is not None and is_force:
+        if existing is not None and is_force:
             _force_clear_credit(conn, plan.week_start_date)
             forced = True