cctally 1.60.0 → 1.62.0

package/bin/_cctally_tui.py

@@ -1083,6 +1083,27 @@ class DataSnapshot:
     # ``CacheReportEnvelope | null`` and the client renders the
     # panel-empty state until the next tick replaces it.
     cache_report: Any | None = None
+    # ---- #268 M4: doctor / config / update-state precompute (spec §6) ----
+    # ``snapshot_to_envelope`` used to fork the `security` keychain subprocess
+    # (via ``doctor_gather_state``) + read ``config.json`` + the update-state
+    # files once PER SSE CLIENT PER TICK. These fields carry those reads,
+    # precomputed ONCE per rebuild on the sync thread (doctor behind a
+    # short-TTL memo), so the envelope stays a pure renderer — mirroring how
+    # ``alerts`` / ``five_hour_milestones`` are already precomputed.
+    #   * ``doctor_payload`` — the small severity/counts/fingerprint envelope
+    #     block (``{severity, counts, generated_at, fingerprint}`` or a
+    #     ``_error`` FAIL block). ``None`` on the first/empty snapshot and on
+    #     fixtures constructed positionally → the envelope falls back to
+    #     computing inline (existing behavior).
+    #   * ``envelope_precompute`` — ``{config, update_state, update_suppress}``
+    #     the envelope derives its ``display`` / ``alerts_settings`` / ``budget``
+    #     / ``dashboard`` / ``update`` blocks from purely. ``None`` → the
+    #     envelope falls back to reading ``config.json`` / the update-state
+    #     files inline.
+    # Both default at the END with ``None`` so positional fixture constructors
+    # keep working, and both are carried forward on a sync crash (Codex F6).
+    doctor_payload: dict | None = None
+    envelope_precompute: dict | None = None
 
     @classmethod
     def synthesize_for_marketing(cls, *, as_of_iso: str) -> "DataSnapshot":
@@ -1465,6 +1486,7 @@ def _tui_build_forecast(
     now_utc: dt.datetime,
     *,
     skip_sync: bool = False,
+    use_weekref_cost_cache: bool = False,
 ):
     """Build the TUI/dashboard sync-thread forecast.
 
@@ -1474,7 +1496,10 @@ def _tui_build_forecast(
     adapter, share builder). Use ``_tui_build_forecast_view`` when the
     full view is needed (e.g. ``snap.forecast_view`` population).
     """
-    view = _tui_build_forecast_view(conn, now_utc, skip_sync=skip_sync)
+    view = _tui_build_forecast_view(
+        conn, now_utc, skip_sync=skip_sync,
+        use_weekref_cost_cache=use_weekref_cost_cache,
+    )
     return view.output if view is not None else None
 
 
@@ -1483,14 +1508,20 @@ def _tui_build_forecast_view(
     now_utc: dt.datetime,
     *,
     skip_sync: bool = False,
+    use_weekref_cost_cache: bool = False,
 ):
     """Build the ``ForecastView`` (issue #57). Returns ``None`` only on
     error in callers — the empty-state View is constructed by the
     builder itself with ``output=None`` + ``verdict="LOW CONF"``.
+
+    ``use_weekref_cost_cache`` (#269 §4) threads into the trailing-4-week
+    fallback so the dashboard sync thread serves closed prior weeks from the
+    shared per-weekref cost cache; default off keeps CLI byte-identical.
     """
     c = _cctally()
     return c.build_forecast_view(
         conn, now_utc=now_utc, targets=(100, 90), skip_sync=skip_sync,
+        use_weekref_cost_cache=use_weekref_cost_cache,
     )
 
 
@@ -1498,7 +1529,7 @@ def _tui_build_trend(
     conn: sqlite3.Connection,
     now_utc: dt.datetime,
     *,
-    skip_sync: bool = False,  # noqa: ARG001 — unused today, kept for API symmetry
+    skip_sync: bool = False,
     count: int = 8,
     display_tz: "ZoneInfo | None" = None,
 ) -> list[TuiTrendRow]:
@@ -1509,10 +1540,15 @@ def _tui_build_trend(
     ``bin/_lib_view_models.build_trend_view``. The TUI snapshot module
     consumes the first 7 ``TuiTrendRow`` fields and ignores the 10
     extended fields (which exist for cmd_report's JSON contract).
+
+    ``skip_sync`` threads into ``build_trend_view`` so the reset-event
+    live-cost path reads the cache without a JSONL ingest. The share
+    period-override handler (``_share_apply_period_override``) passes
+    ``skip_sync=True`` on an HTTP thread that must not glob (#268).
     """
     c = _cctally()
     view = c.build_trend_view(conn, now_utc=now_utc, n=max(1, count),
-                               display_tz=display_tz)
+                               display_tz=display_tz, skip_sync=skip_sync)
     return list(view.rows)
 
 
@@ -1523,6 +1559,7 @@ def _tui_build_weekly_history(
     skip_sync: bool = False,
     count: int = 12,
     display_tz: "ZoneInfo | None" = None,
+    use_weekref_cost_cache: bool = False,
 ) -> list[TuiTrendRow]:
     """Return the last `count` weeks for the Trend modal (spec §4.6.3).
 
@@ -1543,6 +1580,7 @@ def _tui_build_weekly_history(
         _tui_build_weekly_history_view(
             conn, now_utc, skip_sync=skip_sync, count=count,
             display_tz=display_tz,
+            use_weekref_cost_cache=use_weekref_cost_cache,
         ).rows
     )
 
@@ -1551,9 +1589,10 @@ def _tui_build_weekly_history_view(
     conn: sqlite3.Connection,
     now_utc: dt.datetime,
     *,
-    skip_sync: bool = False,                # noqa: ARG001 — unused today, kept for API symmetry
+    skip_sync: bool = False,
     count: int = 12,
     display_tz: "ZoneInfo | None" = None,
+    use_weekref_cost_cache: bool = False,
 ):
     """Build the full ``TrendView`` for the dashboard Trend modal
     (issue #59).
@@ -1571,14 +1610,26 @@ def _tui_build_weekly_history_view(
     c = _cctally()
     return c.build_trend_view(
         conn, now_utc=now_utc, n=max(1, count), display_tz=display_tz,
+        skip_sync=skip_sync, use_weekref_cost_cache=use_weekref_cost_cache,
     )
 
 
+# #268 Group B session-cache master switch. Normally True: the sync-thread
+# rebuild serves the sessions pane from the module-level ``SessionCache``,
+# re-aggregating only the sessions touched since the last tick. Flip to False
+# to force the from-scratch 365-day fetch (the pre-#268 behavior) — the parity
+# tests toggle it to prove the cached and from-scratch rebuilds are
+# byte-identical, and the builder falls back to it automatically if the cache
+# DB can't be opened.
+_SESSION_CACHE_ENABLED = True
+
+
 def _tui_build_sessions(
     now_utc: dt.datetime,
     *,
     limit: int = 100,
     skip_sync: bool = False,
+    use_session_cache: bool = False,
 ) -> list[TuiSessionRow]:
     """Load the last `limit` Claude sessions (merged across resumes).
 
@@ -1597,6 +1648,17 @@ def _tui_build_sessions(
     consumes ``view.rows`` (the typed ``TuiSessionRow`` tuple). The
     view's parallel ``view.aggregated`` is reserved for the CLI / share
     surfaces; the TUI doesn't need ``ClaudeSessionUsage`` fields.
+
+    ``use_session_cache`` (#268 Group B): when True AND
+    ``_SESSION_CACHE_ENABLED``, serve the sessions from the module-level
+    ``SessionCache`` — re-aggregate ONLY the sessions changed since the last
+    tick, then sort+truncate the FULL cached set (so a session below the top
+    100 can still promote once it gets new activity, Codex F5). Set True ONLY
+    by the sync-thread rebuild (``_tui_build_snapshot``), which runs on a
+    process-consistent ``now``. Every OTHER caller keeps the default
+    ``False`` → the from-scratch 365-day fetch, so a non-sync-thread caller
+    with a shifted ``now`` can NEVER pollute the shared cache (the Bundle 2
+    Group A lesson). The visible rows are byte-identical either way.
     """
     # Bounded scan window — the sessions pane promises "last `limit`". A
     # 365-day scan covers virtually all users (even one-session-every-few-days
@@ -1604,11 +1666,27 @@ def _tui_build_sessions(
     # sync-tick cost stays predictable on heavy DBs: the aggregator runs
     # on every entry in the window before slicing.
     range_start = now_utc - dt.timedelta(days=365)
-    entries = get_claude_session_entries(range_start, now_utc, skip_sync=skip_sync)
     c = _cctally()
-    view = c.build_sessions_view(
-        entries, now_utc=now_utc, limit=limit, display_tz=None,
-    )
+    aggregated_override = None
+    if use_session_cache and _SESSION_CACHE_ENABLED:
+        try:
+            aggregated_override = _tui_sessions_cached(
+                now_utc, range_start, limit, skip_sync,
+            )
+        except (sqlite3.DatabaseError, OSError):
+            # Cache DB unavailable / read failure — fall back to the
+            # from-scratch fetch so the pane still renders.
+            aggregated_override = None
+    if aggregated_override is None:
+        entries = get_claude_session_entries(range_start, now_utc, skip_sync=skip_sync)
+        view = c.build_sessions_view(
+            entries, now_utc=now_utc, limit=limit, display_tz=None,
+        )
+    else:
+        view = c.build_sessions_view(
+            (), now_utc=now_utc, limit=limit, display_tz=None,
+            aggregated_override=aggregated_override,
+        )
     rows = list(view.rows)
     # Attach human-readable titles for the dashboard/TUI Sessions surface.
     # Reuses the conversation viewer's title derivation (AI title wins, else
@@ -1645,6 +1723,150 @@ def _tui_build_sessions(
     return rows
 
 
+def _tui_sessions_cached(
+    now_utc: dt.datetime,
+    range_start: dt.datetime,
+    limit: int,
+    skip_sync: bool,
+) -> "list":
+    """Assemble the full session set from the module-level ``SessionCache`` (#268).
+
+    Cold tick: aggregate every session in ``[range_start, now]`` and populate
+    the cache. Warm tick: re-aggregate ONLY the sessions touched since the
+    last tick — each from its OWN full in-window entry set (a straddling /
+    resumed session re-aggregates whole, no split-row). Returns the FULL
+    cached set, window-filtered to ``[range_start, now]`` and sorted by
+    ``last_activity`` desc; ``build_sessions_view`` then truncates to the view
+    limit, which is what preserves correct eviction/**promotion** at the
+    100-row boundary (Codex F5).
+
+    Raises ``sqlite3.DatabaseError`` / ``OSError`` on a cache-open failure so
+    ``_tui_build_sessions`` can fall back to the from-scratch path.
+    """
+    c = _cctally()
+    sc = c._load_sibling("_lib_snapshot_cache")
+    cache_conn = c.open_cache_db()
+    try:
+        def _aggregate_all():
+            entries = get_claude_session_entries(
+                range_start, now_utc, skip_sync=skip_sync,
+            )
+            return _aggregate_claude_sessions(entries)
+
+        def _reaggregate(last_seen, _affected):
+            entries = _fetch_affected_session_entries(
+                cache_conn, last_seen, range_start, now_utc,
+            )
+            return _aggregate_claude_sessions(entries)
+
+        # Identity resolution here is the resolved ``session_id`` (via the
+        # session_files join, filename-stem fallback when null). A late
+        # null→session_id backfill on an existing path (the schema migration
+        # that added the column shipped long ago) would re-key an already-cached
+        # session; that is DELIBERATELY NOT handled per-tick (a session_files
+        # rescan every tick would tax the exact hot path #268 optimizes, and
+        # reachability is near-zero because files are named ``<sessionId>.jsonl``
+        # so the stem == the sessionId in the overwhelming majority). Escape
+        # hatches: a dashboard restart, the M5.2 orphan-prune generation bump, or
+        # ``reset_session_cache_state()`` all re-cold-start the cache.
+        full = sc.build_cached_sessions(
+            cache_conn=cache_conn,
+            aggregate_all=_aggregate_all,
+            reaggregate=_reaggregate,
+        )
+    finally:
+        try:
+            cache_conn.close()
+        except sqlite3.Error:
+            pass
+    # #268 M5-additional (a): DROP aged-out sessions from the STORE, not just
+    # from the returned view. Under a sliding `now`, a session whose
+    # last_activity has fallen before range_start is out of [range_start, now]
+    # — the from-scratch fetch wouldn't return it either — so evict it from the
+    # module cache. Without this the store retains every session ever
+    # cold-populated and grows unboundedly over long dashboard uptime. No-op on
+    # a pinned `now` (every cold-populated session's last_activity is >=
+    # range_start by construction), and cheap (a scalar partition over a few
+    # thousand aggregates, not a 365-day entry re-scan).
+    aged_out = {s.session_id for s in full if s.last_activity < range_start}
+    if aged_out:
+        sc.session_cache().drop(aged_out)
+    in_window = [s for s in full if s.last_activity >= range_start]
+    in_window.sort(key=lambda s: s.last_activity, reverse=True)
+    return in_window
+
+
+def _fetch_affected_session_entries(
+    cache_conn: "sqlite3.Connection",
+    last_seen_seq: int,
+    range_start: dt.datetime,
+    range_end: dt.datetime,
+) -> "list":
+    """Fetch (timestamp-ASC) every entry of every session touched by a row
+    CHANGED since ``last_seen_seq`` — expanded across ``session_id`` siblings so
+    a resumed session re-aggregates WHOLE — within ``[range_start, range_end]``.
+
+    The column list + ``LEFT JOIN`` mirror ``get_claude_session_entries``
+    EXACTLY (including the materialized ``speed`` column → ``usage_extra``), so
+    the per-session aggregate is byte-identical to the from-scratch pass. The
+    affected-source-paths set is inlined as a SQL subquery (parameterized only
+    by ``last_seen_seq``) so the fetch stays a single timestamp-ordered result —
+    no Python ``IN`` list to chunk, and stable first-seen model order.
+
+    #270 (§7d, Codex-2c): the two affected-path subqueries key on
+    ``mutation_seq > ?``, NOT ``id > ?`` — so an id-stable in-place finalization
+    of an EXISTING session's row (which leaves ``MAX(id)`` flat) still selects
+    that session's sibling paths and it re-aggregates WHOLE. On a pure-insert
+    interval ``{mutation_seq > last}`` == ``{id > last}``, so byte-identical.
+    """
+    c = _cctally()
+    _JoinedClaudeEntry = c._JoinedClaudeEntry
+    start_iso = range_start.astimezone(dt.timezone.utc).isoformat()
+    end_iso = range_end.astimezone(dt.timezone.utc).isoformat()
+    sql = (
+        "SELECT se.timestamp_utc, se.model, se.input_tokens, se.output_tokens, "
+        "  se.cache_create_tokens, se.cache_read_tokens, se.source_path, "
+        "  sf.session_id, sf.project_path, se.cost_usd_raw, se.speed "
+        "FROM session_entries se "
+        "LEFT JOIN session_files sf ON sf.path = se.source_path "
+        "WHERE se.timestamp_utc >= ? AND se.timestamp_utc <= ? "
+        "  AND se.source_path IN ("
+        # Sibling paths of every session_id touched by a changed row ...
+        "    SELECT sf2.path FROM session_files sf2 WHERE sf2.session_id IN ("
+        "      SELECT sf1.session_id FROM session_files sf1 "
+        "      JOIN (SELECT DISTINCT source_path FROM session_entries "
+        "            WHERE mutation_seq > ?) af "
+        "        ON af.source_path = sf1.path "
+        "      WHERE sf1.session_id IS NOT NULL"
+        "    )"
+        # ... UNION the touched files themselves (covers fallback / not-yet-
+        # backfilled session_files rows keyed by filename stem).
+        "    UNION "
+        "    SELECT DISTINCT source_path FROM session_entries WHERE mutation_seq > ?"
+        "  ) "
+        "ORDER BY se.timestamp_utc ASC"
+    )
+    rows = cache_conn.execute(
+        sql, (start_iso, end_iso, last_seen_seq, last_seen_seq),
+    ).fetchall()
+    return [
+        _JoinedClaudeEntry(
+            timestamp=dt.datetime.fromisoformat(row[0]),
+            model=row[1],
+            input_tokens=row[2],
+            output_tokens=row[3],
+            cache_creation_tokens=row[4],
+            cache_read_tokens=row[5],
+            source_path=row[6],
+            session_id=row[7],
+            project_path=row[8],
+            cost_usd=row[9],
+            usage_extra=({"speed": row[10]} if row[10] is not None else None),
+        )
+        for row in rows
+    ]
+
+
 @dataclass
 class TuiSessionDetail:
     """Detailed view for the Session modal (spec §4.6.4).
@@ -1843,6 +2065,8 @@ def _tui_build_snapshot(
     now_utc: dt.datetime | None = None,
     skip_sync: bool = False,
     display_tz_pref_override: "str | None" = None,
+    precompute_envelope: bool = False,
+    runtime_bind: "str | None" = None,
 ) -> DataSnapshot:
     """Single-shot build of a DataSnapshot from the DB + cache.
 
@@ -1854,9 +2078,24 @@ def _tui_build_snapshot(
     the lifetime of this build. Used by ``cmd_dashboard`` when ``--tz``
     is supplied so the in-memory zone wins over the persisted config
     without modifying it. ``None`` means "respect config".
+
+    ``precompute_envelope`` (#268 M4, spec §6): when True, precompute the
+    dashboard envelope's doctor / config / update-state reads once here (on
+    the sync thread, doctor behind a short-TTL memo) and attach them to
+    ``DataSnapshot.doctor_payload`` / ``.envelope_precompute`` so
+    ``snapshot_to_envelope`` stays a pure renderer. Set True ONLY by the
+    DASHBOARD callers (the sync-thread rebuild + the initial snapshot); the
+    terminal TUI leaves it False so it never forks the `security` keychain
+    subprocess it doesn't render. ``runtime_bind`` is the actual host the
+    dashboard bound to, threaded into the doctor gather so
+    ``safety.dashboard_bind`` reflects the running state.
     """
     import time
     now_utc = now_utc or dt.datetime.now(dt.timezone.utc)
+    # Read config ONCE per rebuild and reuse it for the display-tz resolution
+    # here AND the envelope precompute below (#268 M4) — the envelope used to
+    # call ``load_config()`` twice per SSE client per tick.
+    raw_config = load_config()
     # Resolve the display tz once per snapshot so labels rendered into
     # BlocksPanelRow / future panel rows share a single zone with the
     # envelope's `display` block. Routed through the shared
@@ -1866,7 +2105,7 @@ def _tui_build_snapshot(
     # into label-FOR-LOOKUP paths like `_aggregate_monthly` keys (out of
     # scope for Task 11).
     _build_display_tz = _resolve_display_tz_obj(
-        _apply_display_tz_override(load_config(), display_tz_pref_override)
+        _apply_display_tz_override(raw_config, display_tz_pref_override)
     )
     conn = open_db()
     try:
@@ -1882,6 +2121,189 @@ def _tui_build_snapshot(
         blocks_panel: list[BlocksPanelRow] = []
         daily_panel:  list[DailyPanelRow]  = []
         alerts: list[dict] = []
+        # ── Sync-once (spec §4, #268) ──────────────────────────────────
+        # Ingest new JSONL bytes into the cache EXACTLY ONCE at the top of
+        # the rebuild, then read every builder with skip_sync=True (pure
+        # SQLite reads). Before this, each of the ~8 wide builders called
+        # get_entries(..., skip_sync=False) which ran its own sync_cache —
+        # ~8-10 redundant whole-tree globs + per-file stats per rebuild,
+        # the CPU-side cost that pegs a core on a large instance.
+        #
+        # The caller's skip_sync flag expresses the --no-sync intent:
+        # honor it by gating ONLY this top-of-rebuild ingest. Downstream
+        # builders always read pure regardless (skip_sync is reassigned to
+        # True below), so --no-sync means "no ingest, still read".
+        do_ingest = not skip_sync
+        if do_ingest:
+            try:
+                cache_conn = _cctally().open_cache_db()
+                try:
+                    sync_cache(cache_conn)
+                finally:
+                    cache_conn.close()
+            except Exception as exc:
+                errors.append(f"sync-cache: {exc}")
+        # Force pure reads for every view builder below, independent of the
+        # caller's flag: the single ingest above is the only glob per tick.
+        skip_sync = True
+        # ── #269 M3.1: shared per-weekref immutable-cost cache (spec §4/§6) ──
+        # Gated OFF by default; flipped ON only on the dashboard sync-thread
+        # NON-IDLE path below, AFTER the once-per-rebuild `reconcile_weekref_cache`
+        # has run. Off ⇒ the trend / weekly-history / forecast builders compute
+        # per-closed-week cost directly (CLI / TUI byte-identical). B2 (the
+        # cache-report per-day cache) was DROPPED at the M2.0 byte-identity gate
+        # (by_project net_usd is not associative across the day partition — see
+        # the spec §5 finding note), so only the weekref cache is wired here.
+        use_weekref_cost_cache = False
+        # ── #269 M4.5: projects-envelope per-(project, week) cache (spec §14) ──
+        # Same gating as the weekref cache: OFF by default, flipped ON only on
+        # the dashboard sync-thread NON-IDLE path after the once-per-rebuild
+        # `reconcile_projects_env_cache` succeeds. Off ⇒ `_build_projects_envelope`
+        # does the full-window walk (CLI / drill / test byte-identical).
+        use_projects_env_cache = False
+        # ── #271 M3: Bug-K pre-credit segment cache (spec §18) ──────────────
+        # A DEDICATED flag (Codex-BK-2 — NOT piggybacked on `use_group_a_cache`):
+        # OFF by default, flipped ON only on the dashboard sync-thread NON-IDLE
+        # path after the once-per-rebuild `reconcile_bugk_cache` succeeds. Off ⇒
+        # the Weekly builder's Bug-K synthesis re-folds the closed pre-credit
+        # window directly each tick (CLI / share / test byte-identical). A
+        # failed/absent reconcile must fall back to direct compute, never reuse
+        # stale segment state.
+        use_bugk_segment_cache = False
+        # ── #272: cache-report per-day cache (spec §5/§6) ───────────────────
+        # Same gating: OFF by default, flipped ON only on the dashboard
+        # sync-thread NON-IDLE path after the once-per-rebuild
+        # `reconcile_cache_report_cache` succeeds. Off ⇒ `build_cache_report_snapshot`
+        # fetches + folds the full 14d window every tick (byte-identical to the
+        # cached path). A failed/absent reconcile falls back to full recompute.
+        use_cache_report_cache = False
+        # ── Three-path dispatch — idle short-circuit (spec §3, #268 M5.1) ──
+        # Compute the composite data-version signature (cheap MAX(id) descents
+        # over cache.db + stats.db + the reset-event change-signal + the
+        # generation counter). When it is UNCHANGED versus the last published
+        # rebuild AND no wall-clock day/week/month boundary has rolled over,
+        # take the IDLE path: reuse the prior snapshot's heavy period/session
+        # rows and re-patch ONLY the time-derived fields + doctor-on-TTL, then
+        # return — NO re-aggregation, so an idle dashboard sits near 0% CPU.
+        # Dashboard-only (``precompute_envelope``) + sync-thread-only, mirroring
+        # the Group A / session cache gating; the shared ``(signature,
+        # snapshot)`` memo lives in ``_lib_snapshot_cache`` (single-writer here).
+        # The signature is computed AFTER the top-of-rebuild ingest so a fresh
+        # tail-ingested row is reflected before the idle decision is made.
+        dispatch_key = None
+        if precompute_envelope:
+            dispatch_sig = None
+            try:
+                dispatch_sig = _tui_compute_dispatch_signature(conn)
+            except Exception as exc:
+                errors.append(f"dispatch-signature: {exc}")
+                dispatch_sig = None
+            if dispatch_sig is not None:
+                # The idle decision keys on the DB signature AND a render key
+                # that captures the config-derived inputs the composite
+                # signature does NOT cover (spec §3 is DB-only): the resolved
+                # display-tz override + the full raw config (display.tz,
+                # alerts_settings, budget, dashboard prefs). A `POST /api/settings`
+                # edit advances neither `MAX(id)` nor the reset legs, so without
+                # this a settings change would idle-serve the stale envelope; a
+                # render-key change forces a full rebuild that re-buckets the
+                # calendar builders (their Group A cache already keys tz) and
+                # refreshes every config-derived envelope block.
+                render_key = (
+                    display_tz_pref_override,
+                    json.dumps(raw_config, sort_keys=True, default=str),
+                )
+                dispatch_key = (dispatch_sig, render_key)
+                _sc = _cctally()._load_sibling("_lib_snapshot_cache")
+                prior_key, prior_snap = _sc.dispatch_state()
+                if (prior_snap is not None and prior_key is not None
+                        and dispatch_key == prior_key
+                        and not _snapshot_period_rolled_over(
+                            prior_snap, now_utc, _build_display_tz)):
+                    idle_snap = _tui_build_idle_snapshot(
+                        prior_snap, now_utc=now_utc,
+                        precompute_envelope=precompute_envelope,
+                        runtime_bind=runtime_bind, raw_config=raw_config,
+                        errors=errors,
+                    )
+                    _sc.store_dispatch_state(dispatch_key, idle_snap)
+                    return idle_snap
+                # ── #269 M3.1: non-idle rebuild — reconcile the shared
+                # per-weekref immutable-cost cache ONCE here (spec §4/§6),
+                # before the builders run, using the dispatch-signature legs
+                # already computed for the idle decision (no extra MAX(id) /
+                # reset query). A SHORT-LIVED cache.db conn is opened only for
+                # reconcile's new-entry watermark query (Codex-4), mirroring
+                # `_tui_compute_dispatch_signature`. On success the trend /
+                # weekly-history / forecast builders opt into the cache via
+                # `use_weekref_cost_cache=True`; any failure leaves the flag OFF
+                # (safe direct-compute fallback, byte-identical output).
+                try:
+                    _rc_cache_conn = _cctally().open_cache_db()
+                    try:
+                        _sc.reconcile_weekref_cache(
+                            _rc_cache_conn,
+                            max_entry_id=dispatch_sig.max_entry_id,
+                            max_mutation_seq=dispatch_sig.entry_mutation_seq,
+                            reset_sig=dispatch_sig.reset_sig,
+                        )
+                        use_weekref_cost_cache = True
+                        # #269 M4.5: reconcile the projects-envelope cache with
+                        # the SAME short-lived cache conn (session_files_sig +
+                        # the new-entry watermark both live in cache.db). Only
+                        # after this succeeds does `_build_projects_envelope`
+                        # opt into the cache below.
+                        _sc.reconcile_projects_env_cache(
+                            _rc_cache_conn,
+                            max_entry_id=dispatch_sig.max_entry_id,
+                            max_mutation_seq=dispatch_sig.entry_mutation_seq,
+                            max_wus_id=dispatch_sig.max_wus_id,
+                            sf_sig=_sc.session_files_sig(_rc_cache_conn),
+                        )
+                        use_projects_env_cache = True
+                        # #271 M3: reconcile the Bug-K pre-credit segment cache
+                        # with the SAME short-lived cache conn (its watermark
+                        # query lives in cache.db), using the dispatch-signature
+                        # legs already computed. Only after this succeeds does
+                        # `_dashboard_build_weekly_periods` opt into the cache
+                        # below (`use_bugk_segment_cache=True`).
+                        _sc.reconcile_bugk_cache(
+                            _rc_cache_conn,
+                            max_entry_id=dispatch_sig.max_entry_id,
+                            max_mutation_seq=dispatch_sig.entry_mutation_seq,
+                            reset_sig=dispatch_sig.reset_sig,
+                        )
+                        use_bugk_segment_cache = True
+                        # #272: reconcile the cache-report per-day cache with the
+                        # SAME short-lived cache conn (its watermark query +
+                        # session_files_sig both live in cache.db), using the
+                        # dispatch-signature legs already computed. `sf_sig`
+                        # closes the lazy-`project_path`-backfill hole (Codex-1);
+                        # `tz_key` full-clears on a display-tz change (every
+                        # calendar-day key shifts). Only after this succeeds does
+                        # `build_cache_report_snapshot` opt into the cache below.
+                        _sc.reconcile_cache_report_cache(
+                            _rc_cache_conn,
+                            max_entry_id=dispatch_sig.max_entry_id,
+                            max_mutation_seq=dispatch_sig.entry_mutation_seq,
+                            reset_sig=dispatch_sig.reset_sig,
+                            sf_sig=_sc.session_files_sig(_rc_cache_conn),
+                            # `_load_sibling` is the canonical idempotent
+                            # sibling-access idiom (it returns the already-loaded
+                            # cctally-bound kernel instance). `_lib_cache_report`
+                            # is loaded eagerly at import (bin/cctally), so this
+                            # is a plain re-fetch of a populated `sys.modules`
+                            # entry — NOT a first-tick KeyError guard.
+                            bucket_tz=_cctally()._load_sibling(
+                                "_lib_cache_report"
+                            )._resolve_bucket_tz(_build_display_tz),
+                            tz_key=str(_build_display_tz),
+                        )
+                        use_cache_report_cache = True
+                    finally:
+                        _rc_cache_conn.close()
+                except Exception as exc:
+                    errors.append(f"snapshot-cache-reconcile: {exc}")
         try:
             cw = _tui_build_current_week(conn, now_utc, skip_sync=skip_sync)
         except Exception as exc:
@@ -1892,7 +2314,10 @@ def _tui_build_snapshot(
             # the legacy ``ForecastOutput`` (for ``snap.forecast``, which
             # the many TUI panel consumers still read) and the surface
             # fields the envelope adapter used to re-derive inline.
-            fc_view = _tui_build_forecast_view(conn, now_utc, skip_sync=skip_sync)
+            fc_view = _tui_build_forecast_view(
+                conn, now_utc, skip_sync=skip_sync,
+                use_weekref_cost_cache=use_weekref_cost_cache,
+            )
             fc = fc_view.output if fc_view is not None else None
         except Exception as exc:
             errors.append(f"forecast: {exc}")
@@ -1906,6 +2331,8 @@ def _tui_build_snapshot(
             c = _cctally()
             _trend_view = c.build_trend_view(
                 conn, now_utc=now_utc, n=8, display_tz=_build_display_tz,
+                skip_sync=skip_sync,
+                use_weekref_cost_cache=use_weekref_cost_cache,
             )
             trend = list(_trend_view.rows)
             trend_avg_dpp = _trend_view.avg_dollars_per_pct
@@ -1917,7 +2344,9 @@ def _tui_build_snapshot(
             # `skip_sync=True` is threaded through. Honor the caller's
             # intent so `--no-sync` and the initial cache-only paint
             # both avoid ingest latency/lock contention.
-            sessions = _tui_build_sessions(now_utc, skip_sync=skip_sync)
+            sessions = _tui_build_sessions(
+                now_utc, skip_sync=skip_sync, use_session_cache=True,
+            )
         except Exception as exc:
             errors.append(f"sessions: {exc}")
         # ---- v2 additions ----
@@ -1936,6 +2365,7 @@ def _tui_build_snapshot(
             # TrendModal.tsx stops re-deriving it client-side.
             history_view = _tui_build_weekly_history_view(
                 conn, now_utc, skip_sync=skip_sync, display_tz=_build_display_tz,
+                use_weekref_cost_cache=use_weekref_cost_cache,
             )
             history = list(history_view.rows)
             history_median_dpp = history_view.median_dpp_non_current_4w
@@ -1958,7 +2388,9 @@ def _tui_build_snapshot(
         weekly_total_tokens = 0
         try:
             weekly_periods = _dashboard_build_weekly_periods(
-                conn, now_utc, n=12, skip_sync=skip_sync
+                conn, now_utc, n=12, skip_sync=skip_sync,
+                use_group_a_cache=True,
+                use_bugk_segment_cache=use_bugk_segment_cache,
             )
             # ``stable_sum`` (math.fsum) returns float ``0.0`` on empty rows,
             # so the envelope stays byte-stable with the pre-fix ``0.0`` shape
@@ -1981,6 +2413,7 @@ def _tui_build_snapshot(
         try:
             monthly_periods = _dashboard_build_monthly_periods(
                 conn, now_utc, n=12, skip_sync=skip_sync,
+                use_group_a_cache=True,
                 display_tz=_build_display_tz,
             )
             monthly_total_cost_usd = stable_sum(
@@ -2024,6 +2457,7 @@ def _tui_build_snapshot(
         try:
             daily_panel = _dashboard_build_daily_panel(
                 conn, now_utc, n=30, skip_sync=skip_sync,
+                use_group_a_cache=True,
                 display_tz=_build_display_tz,
             )
             daily_total_cost_usd = stable_sum(
@@ -2097,6 +2531,7 @@ def _tui_build_snapshot(
                 now_utc=now_utc,
                 current_week=cw,
                 weeks_back=12,
+                use_projects_env_cache=use_projects_env_cache,
             )
         except Exception as exc:
             errors.append(f"projects-envelope: {exc}")
@@ -2189,11 +2624,35 @@ def _tui_build_snapshot(
                 anomaly_window_days=_dash_mod.CACHE_REPORT_ANOMALY_WINDOW_DAYS,
                 display_tz=_build_display_tz,
                 skip_sync=skip_sync,
+                use_cache_report_cache=use_cache_report_cache,
             )
         except Exception as exc:
             errors.append(f"cache-report: {exc}")
 
-        return DataSnapshot(
+        # ---- #268 M4: doctor / config / update-state precompute (spec §6) ----
+        # Precompute the envelope's doctor / config / update-state reads ONCE
+        # here (dashboard callers only), so `snapshot_to_envelope` stays a pure
+        # renderer that never forks `security` / reads config.json per SSE
+        # client per tick. Errors are folded into `errors` (recorded on
+        # `last_sync_error`); the fields stay None on failure → the envelope
+        # falls back to its inline computation, preserving behavior.
+        doctor_payload_block: "dict | None" = None
+        envelope_precompute_block: "dict | None" = None
+        if precompute_envelope:
+            try:
+                doctor_payload_block = _tui_precompute_doctor_payload(
+                    now_utc, runtime_bind,
+                )
+            except Exception as exc:
+                errors.append(f"doctor-precompute: {exc}")
+            try:
+                envelope_precompute_block = _tui_precompute_envelope_config(
+                    raw_config,
+                )
+            except Exception as exc:
+                errors.append(f"envelope-precompute: {exc}")
+
+        snap = DataSnapshot(
             current_week=cw,
             forecast=fc,
             trend=trend,
@@ -2222,11 +2681,222 @@ def _tui_build_snapshot(
             forecast_view=fc_view,
             projects_envelope=projects_envelope_block,
             cache_report=cache_report_block,
+            doctor_payload=doctor_payload_block,
+            envelope_precompute=envelope_precompute_block,
         )
+        # #268 M5.1: record the (signature+render key, snapshot) so the next
+        # dashboard tick can idle-short-circuit when nothing changed. Full-build
+        # path only sets it when the key was computed (precompute_envelope); the
+        # TUI path never touches the dispatch memo.
+        if precompute_envelope and dispatch_key is not None:
+            _cctally()._load_sibling("_lib_snapshot_cache").store_dispatch_state(
+                dispatch_key, snap,
+            )
+        return snap
     finally:
         conn.close()
 
 
+def _tui_precompute_doctor_payload(
+    now_utc: dt.datetime,
+    runtime_bind: "str | None",
+) -> dict:
+    """Precompute the dashboard envelope's small doctor block, via the
+    short-TTL memo (#268 M4, spec §6).
+
+    Returns the SAME ``{severity, counts, generated_at, fingerprint}`` dict
+    ``snapshot_to_envelope`` used to build inline (or a synthetic FAIL block
+    with ``_error`` on a doctor gather/checks failure), so moving the
+    computation onto the snapshot is byte-identical for a given
+    ``now_utc``/``runtime_bind``. Guarded by ``doctor_payload_memo`` so
+    back-to-back warm rebuilds don't re-fork the `security` keychain
+    subprocess every tick.
+    """
+    c = _cctally()
+    sc = c._load_sibling("_lib_snapshot_cache")
+
+    def _compute(now: dt.datetime, bind: "str | None") -> dict:
+        _ld = c._load_sibling("_lib_doctor")
+        try:
+            _doc_state = c.doctor_gather_state(now_utc=now, runtime_bind=bind)
+            _doc_report = _ld.run_checks(_doc_state)
+            return {
+                "severity": _doc_report.overall_severity,
+                "counts": dict(_doc_report.counts),
+                "generated_at": _ld._iso_z(_doc_report.generated_at),
+                "fingerprint": _ld.fingerprint(_doc_report),
+            }
+        except Exception as exc:  # noqa: BLE001 — never crash the rebuild
+            # Mirror `snapshot_to_envelope`'s inline FAIL fallback (dashboard
+            # `_iso_z`: strftime, no microseconds) so a doctor failure serves
+            # the same shape whether computed here or in the envelope.
+            return {
+                "severity": "fail",
+                "counts": {"ok": 0, "warn": 0, "fail": 1},
+                "generated_at": now.astimezone(dt.timezone.utc).strftime(
+                    "%Y-%m-%dT%H:%M:%SZ"
+                ),
+                "fingerprint": "sha1:" + ("0" * 40),
+                "_error": f"{type(exc).__name__}: {exc}",
+            }
+
+    return sc.doctor_payload_memo(
+        now_utc, runtime_bind, ttl_s=sc.DOCTOR_MEMO_TTL_S, compute=_compute,
+    )
+
+
+def _tui_precompute_envelope_config(raw_config: dict) -> dict:
+    """Precompute the config / update-state reads `snapshot_to_envelope`
+    needs (#268 M4, spec §6).
+
+    Returns ``{config, update_state, update_suppress}``: the raw
+    ``load_config()`` dict (the envelope layers the display-tz override on it
+    purely and reads the alerts/budget/dashboard blocks off it) plus the
+    update-state / update-suppress payloads with the SAME error sentinels the
+    envelope used inline, so the derived ``update`` block is unchanged.
+    """
+    c = _cctally()
+    try:
+        update_state = c._load_update_state()
+    except c.UpdateError:
+        update_state = {"_error": "update-state.json invalid"}
+    except Exception:
+        update_state = {"_error": "update-state.json read failed"}
+    try:
+        update_suppress = c._load_update_suppress()
+    except Exception:
+        update_suppress = {"skipped_versions": [], "remind_after": None}
+    return {
+        "config": raw_config,
+        "update_state": update_state,
+        "update_suppress": update_suppress,
+    }
+
+
+def _tui_compute_dispatch_signature(stats_conn):
+    """Composite data-version signature for the three-path dispatch (#268 M5.1).
+
+    Cheap ``MAX(id)`` b-tree descents over cache.db + stats.db, the reset-event
+    change-signal, and the module generation counter (spec §3). ``stats_conn``
+    is the already-open stats.db connection the rebuild holds; a throwaway
+    cache.db connection is opened for the ``session_entries`` / ``codex`` legs.
+    ``compute_signature`` never raises (each leg degrades to 0 on a missing
+    table); a cache-open failure propagates so the caller skips the idle path
+    and does a full rebuild.
+    """
+    c = _cctally()
+    sc = c._load_sibling("_lib_snapshot_cache")
+    cache_conn = c.open_cache_db()
+    try:
+        return sc.compute_signature(
+            cache_conn, stats_conn, generation=sc.current_generation(),
+        )
+    finally:
+        cache_conn.close()
+
+
+def _snapshot_period_rolled_over(prior, now_utc, display_tz):
+    """True if a day/week/month boundary was crossed since ``prior`` was built.
+
+    The idle short-circuit reuses ``prior``'s period rows, which is only valid
+    while the current day/week/month is unchanged (spec §3). A day change in the
+    display tz subsumes a month change (a new month starts on a new day), so
+    daily+monthly reduce to one day-label compare. Weekly rollover is checked
+    against the subscription week's absolute boundaries carried on
+    ``prior.current_week`` (reset-anchored UTC datetimes) — a week can roll at a
+    mid-day reset hour without the calendar day changing.
+
+    The 5-hour block is also boundary-checked here (#268 M5 Finding 4): a 5h
+    reset with zero new usage across a full window on a truly-idle dashboard
+    advances no DB signature and crosses no calendar day, so without this leg the
+    idle path would keep serving the prior "current block" past its reset. The
+    reset-anchored UTC instant carried on ``prior.current_week.five_hour_resets_at``
+    forces a full rebuild once ``now`` reaches it, re-anchoring the block.
+    """
+    prev = getattr(prior, "generated_at", None)
+    if prev is None:
+        return True
+
+    def _day(dtm):
+        # Day label in the resolved display tz — matches how the daily builder
+        # buckets (display tz, host-local when None). Not a user-facing render,
+        # only a same-day equality check.
+        localized = dtm.astimezone(display_tz) if display_tz is not None \
+            else dtm.astimezone()  # internal fallback: host-local intentional
+        return localized.strftime("%Y-%m-%d")
+
+    if _day(prev) != _day(now_utc):
+        return True
+    cw = getattr(prior, "current_week", None)
+    if cw is not None:
+        week_end = getattr(cw, "week_end_at", None)
+        week_start = getattr(cw, "week_start_at", None)
+        if week_end is not None and now_utc >= week_end:
+            return True
+        if week_start is not None and now_utc < week_start:
+            return True
+        # 5h block rollover (#268 M5 Finding 4): the reset instant is the
+        # reset-anchored UTC end of the active block (already suppressed to None
+        # by `_tui_build_current_week` once it has elapsed, so a non-None value is
+        # a future boundary at build time). Once now crosses it, force a full
+        # rebuild so the blocks panel re-anchors even with zero new usage.
+        five_hour_reset = getattr(cw, "five_hour_resets_at", None)
+        if five_hour_reset is not None and now_utc >= five_hour_reset:
+            return True
+    return False
+
+
+def _tui_build_idle_snapshot(prior, *, now_utc, precompute_envelope,
+                             runtime_bind, raw_config, errors):
+    """Fresh snapshot reusing ``prior``'s heavy rows, re-patching only the
+    time-derived fields + the doctor payload / envelope precompute on each idle
+    tick (spec §3 idle path).
+
+    ``dataclasses.replace`` builds a NEW ``DataSnapshot`` sharing ``prior``'s
+    immutable row objects (never mutated in place — Codex F7), so an SSE client
+    thread serializing the previously-published snapshot can't observe a torn
+    value. ``generated_at`` moves to ``now_utc`` (drives the envelope's display
+    block + the emitted timestamp); ``last_sync_at`` refreshes (the ingest ran,
+    so "synced Xs ago" resets); the doctor payload is refreshed through the TTL
+    memo so the doctor chip stays live on a long-idle dashboard (Codex F6). All
+    the wall-clock countdowns / freshness ages are computed from a LIVE now at
+    envelope-render time (the SSE loop passes its own ``now_utc`` /
+    ``time.monotonic()``), so nothing else needs patching here.
+
+    ``envelope_precompute`` is ALSO refreshed each idle tick (#268 M5 Finding 1):
+    since M4 the envelope reads update-state / update-suppress off the snapshot's
+    ``envelope_precompute`` rather than re-reading the JSON files per client.
+    ``_DashboardUpdateCheckThread`` writes ``update-state.json`` OUT OF BAND
+    (advancing no DB signature and no config render key), so carrying
+    ``prior.envelope_precompute`` forward would freeze the version banner on a
+    long-idle / --no-sync dashboard until new usage or a config edit lands. This
+    mirrors the doctor-on-idle treatment (spec §6): config is render-key-stable on
+    the idle path (the short-circuit only runs when the render key — which bundles
+    the full raw config — is unchanged), so recomputing is cheap small-JSON I/O,
+    not CPU, and byte-matches a full rebuild's envelope for the same state.
+    """
+    import time
+    doctor_payload = prior.doctor_payload
+    envelope_precompute = prior.envelope_precompute
+    if precompute_envelope:
+        try:
+            doctor_payload = _tui_precompute_doctor_payload(now_utc, runtime_bind)
+        except Exception as exc:  # noqa: BLE001 — never crash the rebuild
+            errors.append(f"doctor-precompute: {exc}")
+        try:
+            envelope_precompute = _tui_precompute_envelope_config(raw_config)
+        except Exception as exc:  # noqa: BLE001 — never crash the rebuild
+            errors.append(f"envelope-precompute: {exc}")
+    return dataclasses.replace(
+        prior,
+        generated_at=now_utc,
+        last_sync_at=time.monotonic(),
+        last_sync_error=("; ".join(errors) if errors else None),
+        doctor_payload=doctor_payload,
+        envelope_precompute=envelope_precompute,
+    )
+
+
 def _tui_empty_snapshot(now_utc: dt.datetime) -> DataSnapshot:
     """First-paint placeholder with no data loaded yet."""
     return DataSnapshot(
@@ -2657,6 +3327,13 @@ class _TuiSyncThread:
                     trend_avg_dollars_per_pct=prev.trend_avg_dollars_per_pct,
                     trend_history_median_dpp=prev.trend_history_median_dpp,
                     forecast_view=prev.forecast_view,
+                    # #268 M4 (Codex F6): carry the precomputed doctor payload
+                    # + config/update-state forward so the envelope stays a
+                    # pure renderer (and the doctor chip stays populated)
+                    # across a transient sync crash, instead of dropping to the
+                    # dataclass defaults and re-forking `security` per client.
+                    doctor_payload=prev.doctor_payload,
+                    envelope_precompute=prev.envelope_precompute,
                 ))
             # Wait up to interval, or until forced.
             for _ in range(int(max(1, self._interval * 10))):
@@ -3295,8 +3972,16 @@ def _tui_header_strip_a(
         sync_age = int(time.monotonic() - snap.last_sync_at)
     sync_txt = f"synced {sync_age}s ago" if snap.last_sync_at is not None else "synced —"
     err = snap.last_sync_error
+    # Preview channel (CCTALLY_CHANNEL=preview): a marker-gated PREVIEW segment
+    # so a preview-channel TUI (running against a real-data snapshot) is
+    # unmistakable next to the live prod one. Reuses the existing `{warn}` style
+    # token, so no `_TUI_VALID_STYLE_NAMES` change is needed. Empty when the
+    # marker is unset → the TUI goldens stay byte-identical.
+    preview_prefix = ""
+    if _cctally_core.is_preview_channel():
+        preview_prefix = "{warn}PREVIEW{/} {faint}│{/} "
     if cw is None:
-        hdr = (
+        hdr = preview_prefix + (
             f"{{bright.b}}Week — {{/}} {{faint}}│{{/}} "
             f"{{dim}}no data yet — run record-usage first{{/}}"
         )
@@ -3313,7 +3998,7 @@ def _tui_header_strip_a(
             # "Fcst 74% WARN" where the WARN comes from a >=90% high
             # projection, understating risk in the most glanceable line.
             fcst_pct = f"{int(round(fc.final_percent_high))}%"
-        hdr = (
+        hdr = preview_prefix + (
             f"{{bright.b}}Week {format_display_dt(cw.week_start_at, runtime.display_tz, fmt='%b %d', suffix=False)}–{format_display_dt(cw.week_end_at, runtime.display_tz, fmt='%b %d', suffix=False)}{{/}} "
             f"{{faint}}│{{/}} Used {{{used_cls}.b}}{cw.used_pct:.1f}%{{/}} "
             f"{{dim}}(5h {int(cw.five_hour_pct or 0)}%){{/}} {{faint}}│{{/}} "
@@ -4405,7 +5090,8 @@ def _tui_refresh_interval_type(s: str) -> float:
     return v
 
 
-def _make_run_sync_now_locked(*, ref, hub, pinned_now, display_tz_pref_override):
+def _make_run_sync_now_locked(*, ref, hub, pinned_now, display_tz_pref_override,
+                              runtime_bind=None):
     """Return a closure that does the snapshot-rebuild + SSE-publish work.
 
     Caller MUST hold sync_lock around the call. The naming convention
@@ -4416,6 +5102,11 @@ def _make_run_sync_now_locked(*, ref, hub, pinned_now, display_tz_pref_override)
     callers that already hold ``sync_lock`` (e.g. so they can refresh OAuth
     + rebuild snapshot atomically without releasing between steps) reuse
     this body without recursive-acquire / self-deadlock.
+
+    ``runtime_bind`` (#268 M4) is the dashboard's actual bound host; this is a
+    DASHBOARD-only factory, so every rebuild here precomputes the envelope's
+    doctor / config / update-state onto the snapshot (``precompute_envelope=True``)
+    — keeping ``snapshot_to_envelope`` a pure renderer across all SSE clients.
     """
     def _locked(skip_sync: bool) -> None:
         try:
@@ -4427,6 +5118,7 @@ def _make_run_sync_now_locked(*, ref, hub, pinned_now, display_tz_pref_override)
             snap = sys.modules["cctally"]._tui_build_snapshot(
                 now_utc=pinned_now, skip_sync=skip_sync,
                 display_tz_pref_override=display_tz_pref_override,
+                precompute_envelope=True, runtime_bind=runtime_bind,
             )
             if skip_sync:
                 # Mirror the startup override: suppress the monotonic sync