cctally 1.59.0 → 1.61.0

package/bin/_cctally_update.py

@@ -196,7 +196,7 @@ import threading
 import time
 import urllib.error
 import urllib.request
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import Any, Callable
 
 
@@ -1872,12 +1872,22 @@ class _DashboardUpdateCheckThread(threading.Thread):
     via ``update.check.enabled = false`` is honoured inside the gate
     so the thread becomes a no-op without needing teardown.
 
-    After a successful check, republishes the current snapshot via the
-    SSE hub so long-open dashboard tabs in ``--no-sync`` mode pick up
-    the fresh ``latest_version`` written to ``update-state.json``. The
-    snapshot itself is unchanged — ``snapshot_to_envelope`` re-reads
-    the state file per envelope build, so a bare publish is enough to
-    refresh the badge for every live subscriber.
+    After a successful check (or an out-of-band ``current_version``
+    self-heal), republishes the current snapshot via the SSE hub so
+    long-open dashboard tabs in ``--no-sync`` mode pick up the fresh
+    ``latest_version`` / ``current_version`` written to
+    ``update-state.json``. Since M4 (#268) the SSE envelope reads
+    update-state / update-suppress off the snapshot's
+    ``envelope_precompute`` rather than re-reading the state file per
+    envelope build, so a BARE publish of the held snapshot would surface
+    the stale precompute. The republish therefore rebuilds
+    ``envelope_precompute`` (small config/state JSON I/O, no DB, no
+    module-cache mutation — see :meth:`_republish_with_fresh_envelope`)
+    on a fresh ``dataclasses.replace`` snapshot before publishing, and
+    persists it to the snapshot ref so the held snapshot stays current.
+    Under ``--no-sync`` this thread is the ONLY refresher of that
+    precompute (the data-sync thread that otherwise rebuilds it is
+    disabled).
     """
 
     daemon = True
@@ -1917,14 +1927,14 @@ class _DashboardUpdateCheckThread(threading.Thread):
                 ):
                     snap = self._ref.get()
                     if snap is not None:
-                        self._hub.publish(snap)
+                        self._republish_with_fresh_envelope(snap)
                 config = load_config()
                 if c._is_update_check_due(config):
                     c._do_update_check()
                     if self._hub is not None and self._ref is not None:
                         snap = self._ref.get()
                         if snap is not None:
-                            self._hub.publish(snap)
+                            self._republish_with_fresh_envelope(snap)
             except Exception as e:
                 # Log but never propagate — this thread must keep
                 # ticking so a transient registry hiccup doesn't
@@ -1940,6 +1950,36 @@ class _DashboardUpdateCheckThread(threading.Thread):
                     pass
             self._stop_event.wait(c.UPDATE_DASHBOARD_CHECK_POLL_S)
 
+    def _republish_with_fresh_envelope(self, snap) -> None:
+        """Republish ``snap`` with a freshly-rebuilt ``envelope_precompute``.
+
+        Since M4 (#268) the SSE envelope reads update-state / update-suppress
+        off ``snap.envelope_precompute`` rather than re-reading the JSON files
+        per client. ``_do_update_check`` / ``_self_heal_current_version`` write
+        ``update-state.json`` OUT OF BAND (advancing no DB signature and no
+        config render key), so a bare re-publish of the HELD snapshot would
+        surface the stale precompute — freezing the version banner on a
+        ``--no-sync`` dashboard whose data-sync thread (the only other
+        precompute refresher) is disabled.
+
+        ``_tui_precompute_envelope_config`` reads only the config / update-state
+        / update-suppress files and mutates NO module cache, so calling it from
+        this thread is safe (no shared-cache-mutation / Codex F7 hazard).
+        ``dataclasses.replace`` yields a NEW snapshot sharing ``prior``'s
+        immutable rows, so an SSE client serializing the previously-published
+        snapshot can't observe a torn value. The fresh snapshot is persisted to
+        the ref so the held snapshot stays current for the next reader.
+        """
+        c = _cctally()
+        fresh = replace(
+            snap,
+            envelope_precompute=(
+                c._cctally_tui._tui_precompute_envelope_config(load_config())
+            ),
+        )
+        self._ref.set(fresh)
+        self._hub.publish(fresh)
+
 
 def cmd_update(args) -> int:
     """`cctally update` entry point — routes by mode flag (spec §4.1)."""

package/bin/_cctally_weekrefs.py

@@ -31,6 +31,7 @@ from __future__ import annotations
 import datetime as dt
 import sqlite3
 import sys
+import threading
 from dataclasses import replace
 
 from _cctally_core import (
@@ -220,6 +221,68 @@ def _apply_reset_events_to_weekrefs(
     return out
 
 
+# === #269 M4.4 — backfill-rescan process guard ==============================
+#
+# `_backfill_week_reset_events` rescans ALL `weekly_usage_snapshots` on every
+# `open_db()`. Its output is NOT a pure function of the snapshots alone: the
+# in-place-credit branch also reads existing `week_reset_events`, and the
+# reset-events-regenerate contract deletes `week_reset_events` and re-runs the
+# backfill WITHOUT a snapshot insert. So a `MAX(weekly_usage_snapshots.id)`-only
+# guard would skip a needed regeneration. Guard instead on a process-level memo
+# of BOTH `MAX(weekly_usage_snapshots.id)` AND a `week_reset_events` signature
+# `(COUNT(*), MAX(rowid))`, scoped per DB FILE identity: skip the rescan only
+# when both are unchanged since the last successful backfill. Byte-identical (a
+# snapshot insert advances the WUS id; a reset-event delete/clear moves the
+# reset-event sig; a backfill's own inserts move the sig so the next open is a
+# clean skip). Production snapshots are append-only, so the WUS id moves on
+# every new capture. In-memory / temp DBs (no file identity) are never memoized
+# (always rescanned) — a `:memory:` identity could otherwise collide across
+# distinct databases.
+
+_BACKFILL_MEMO_LOCK = threading.Lock()
+_BACKFILL_RESET_EVENTS_MEMO: dict = {}  # db_path -> (max_wus_id, (count, max_rowid))
+
+
+def _reset_backfill_reset_events_memo() -> None:
+    """Drop the backfill-guard memo (test hook + isolation)."""
+    with _BACKFILL_MEMO_LOCK:
+        _BACKFILL_RESET_EVENTS_MEMO.clear()
+
+
+def _backfill_db_identity(conn: sqlite3.Connection) -> "str | None":
+    """The `main` schema's on-disk file path, or None for in-memory/temp DBs
+    (empty file string) — the memo key. None ⇒ never memoize (always rescan)."""
+    try:
+        for _seq, name, file in conn.execute("PRAGMA database_list"):
+            if name == "main":
+                return file or None
+    except sqlite3.Error:
+        pass
+    return None
+
+
+def _backfill_reset_events_signature(
+    conn: sqlite3.Connection,
+) -> "tuple[int, tuple[int, int]]":
+    """`(MAX(weekly_usage_snapshots.id), (COUNT, MAX(rowid)) over
+    week_reset_events)` — two O(1) MAX/COUNT descents vs the full-table rescan.
+    Degrades to zero legs on a missing table so it never raises."""
+    try:
+        max_wus = conn.execute(
+            "SELECT COALESCE(MAX(id), 0) FROM weekly_usage_snapshots"
+        ).fetchone()[0]
+    except sqlite3.DatabaseError:
+        max_wus = 0
+    try:
+        row = conn.execute(
+            "SELECT COUNT(*), COALESCE(MAX(rowid), 0) FROM week_reset_events"
+        ).fetchone()
+        wre = (int(row[0]), int(row[1]))
+    except sqlite3.DatabaseError:
+        wre = (0, 0)
+    return (int(max_wus), wre)
+
+
 def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
     """One-shot scan over historical snapshots to synthesize reset events
     for past mid-week resets the tool lived through before this feature
@@ -244,6 +307,17 @@ def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
     window. See ``_is_reset_drop`` for the full rationale.
     """
     c = _cctally()
+    # #269 M4.4: skip the full rescan when neither the snapshots nor the
+    # reset events moved since the last successful backfill on this DB file.
+    db_id = _backfill_db_identity(conn)
+    sig = _backfill_reset_events_signature(conn)
+    if db_id is not None:
+        with _BACKFILL_MEMO_LOCK:
+            if _BACKFILL_RESET_EVENTS_MEMO.get(db_id) == sig:
+                # Preserve the original's transaction-flush behavior on the
+                # skip path (harmless when there is nothing pending).
+                conn.commit()
+                return
     try:
         rows = conn.execute(
             "SELECT captured_at_utc, week_end_at, weekly_percent "
@@ -372,6 +446,13 @@ def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
     # (e.g. _backfill_five_hour_blocks) don't trip "cannot start a
     # transaction within a transaction".
     conn.commit()
+    # #269 M4.4: store the POST-backfill signature (the scan's own inserts move
+    # the reset-event sig, so the next open with no snapshot change is a clean
+    # skip). Only after a completed scan — the early `except` return above
+    # deliberately does not memoize a partial state.
+    if db_id is not None:
+        with _BACKFILL_MEMO_LOCK:
+            _BACKFILL_RESET_EVENTS_MEMO[db_id] = _backfill_reset_events_signature(conn)
 
 
 # Minimum weekly_percent drop that counts as a goodwill reset (percentage
@@ -458,11 +539,20 @@ def _week_ref_has_reset_event(
     return row is not None
 
 
-def _compute_cost_for_weekref(ref: WeekRef) -> float | None:
+def _compute_cost_for_weekref(
+    ref: WeekRef, *, skip_sync: bool = False
+) -> float | None:
     """Live-compute USD cost over `ref`'s (possibly reset-adjusted) range
     straight from session_entries. Mirrors what cmd_sync_week writes into
     weekly_cost_snapshots, minus the cache write — used for reset-affected
     weeks where the cached range disagrees with the effective range.
+
+    ``skip_sync`` (default ``False``) is threaded to ``_sum_cost_for_range``
+    so the caller can read the cache without triggering a JSONL ingest.
+    The #268 dashboard/TUI sync-thread rebuild passes ``True`` (it ingests
+    once at the top of the rebuild); ``build_trend_view`` calls this once per
+    reset-event week, so without the flag each reset week re-globbed the whole
+    ``~/.claude/projects`` tree — the CPU peg the sync-once refactor removes.
     """
     c = _cctally()
     if not ref.week_start_at or not ref.week_end_at:
@@ -474,7 +564,7 @@ def _compute_cost_for_weekref(ref: WeekRef) -> float | None:
         return None
     if end <= start:
         return 0.0
-    return c._sum_cost_for_range(start, end, mode="auto")
+    return c._sum_cost_for_range(start, end, mode="auto", skip_sync=skip_sync)
 
 
 def _apply_overlap_clamp_to_weekrefs(refs: list[WeekRef]) -> list[WeekRef]:

package/bin/_lib_doctor.py

@@ -164,6 +164,11 @@ class DoctorState:
     conv_sessions_rollup_count: Optional[int] = None
     conv_messages_distinct_sessions: Optional[int] = None
     conv_rollup_sync_in_progress: bool = False
+    # Preview channel (CCTALLY_CHANNEL=preview): "preview" when the binary runs
+    # under the preview channel, else "prod". Populated by `doctor_gather_state`
+    # from the env; surfaced in the install.mode check. Defaulted (placed last)
+    # so existing constructors stay valid and the prod path is unchanged.
+    channel: str = "prod"
 
 
 @dataclasses.dataclass(frozen=True)
@@ -359,6 +364,10 @@ def _check_install_dev_mode(s: DoctorState) -> CheckResult:
         summary = "DEV (git checkout, custom data dir via CCTALLY_DATA_DIR)"
     else:
         summary = "installed"
+    # Preview channel (CCTALLY_CHANNEL=preview): note the channel in the
+    # summary. Gated → prod (channel="prod") summary is unchanged.
+    if s.channel == "preview":
+        summary += " · channel: preview"
     return CheckResult(
         id="install.mode", title="Mode",
         severity="ok", summary=summary, remediation=None,
@@ -366,6 +375,7 @@ def _check_install_dev_mode(s: DoctorState) -> CheckResult:
             "dev_mode": s.dev_mode,
             "is_dev_checkout": s.is_dev_checkout,
             "app_dir": s.app_dir,
+            "channel": s.channel,
         },
     )