cctally 1.60.0 → 1.62.0

package/bin/_cctally_dashboard.py

@@ -247,7 +247,7 @@ import urllib.request
 import webbrowser as _wb
 from dataclasses import dataclass, field, replace
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
-from typing import Any
+from typing import Any, NamedTuple
 from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 
@@ -316,7 +316,35 @@ from _lib_subscription_weeks import _compute_subscription_weeks
 from _lib_blocks import _group_entries_into_blocks
 from _cctally_config import save_config, _load_config_unlocked
 from _cctally_db import _render_migration_error_banner
-from _cctally_cache import get_entries, open_cache_db, sync_cache
+from _cctally_cache import (
+    get_entries, iter_entries, iter_entries_with_id, open_cache_db, sync_cache,
+    _prune_orphaned_cache_entries,
+)
+from _lib_snapshot_cache import (
+    build_cached_group_a,
+    bump_generation,
+    cached_bugk_segment,
+    reset_bugk_segment_state,
+    reset_cache_report_state,
+    reset_group_a_state,
+    reset_projects_env_state,
+    reset_session_cache_state,
+    reset_weekref_cost_state,
+    BugKSegment,
+    _bugk_key,
+    _max_id as _snapshot_max_id,
+    _reset_sig as _snapshot_reset_sig,
+)
+
+
+# #268 Group A cached-bucket path master switch. Normally True: the
+# calendar builders (daily / monthly / weekly) assemble their per-bucket
+# aggregates through the module-level BucketCache and recompute only the
+# current/dirty slice. Flip to False to force the from-scratch wide-fetch
+# path (the pre-#268 behavior) — the parity tests toggle it to prove the
+# cached and from-scratch rebuilds are byte-identical, and the builders
+# fall back to it automatically if the cache DB can't be opened.
+_GROUP_A_CACHE_ENABLED = True
 
 
 # === Module-level back-ref shims for helpers that STAY in bin/cctally ======
@@ -351,6 +379,84 @@ def _make_run_sync_now_locked(*args, **kwargs):
     return sys.modules["cctally"]._make_run_sync_now_locked(*args, **kwargs)
 
 
+def _register_faulthandler_sigusr1():
+    """Register a SIGUSR1 handler that dumps all-thread tracebacks (#268 M6.1).
+
+    So any future dashboard spin (a sync thread stuck in a rebuild) is
+    self-diagnosing — ``kill -USR1 <pid>`` prints every thread's stack to stderr
+    — without needing a root py-spy. Guarded for platforms lacking SIGUSR1
+    (Windows), where it is a silent no-op. Idempotent; returns True when the
+    handler was registered, False when SIGUSR1 is unavailable."""
+    import faulthandler
+    import signal
+    if not hasattr(signal, "SIGUSR1"):
+        return False
+    faulthandler.register(signal.SIGUSR1, all_threads=True)
+    return True
+
+
+def _dashboard_self_heal_orphans(*, skip_sync):
+    """Prune removed-worktree orphans from the cache using a throwaway
+    connection. No-op under frozen (--no-sync) mode. Non-blocking on the
+    cache lock (retries on the next cadence if contended). Never raises.
+
+    #268 M5.2 (spec §7 / Codex F4): a prune that actually deleted rows rewrites
+    history in place — which `MAX(id)` alone can't detect (deleting a NON-max
+    row leaves the max unchanged). So on any real deletion, bump the
+    cache-generation counter (a composite-signature leg, so the next rebuild
+    can't idle-short-circuit) AND clear the Group A / session caches, forcing a
+    correct cold recompute on the next tick. The prune runs AFTER the tick's
+    publish on the same sync thread, so the very next tick recomputes."""
+    if skip_sync:
+        return None
+    try:
+        conn = open_cache_db()
+        try:
+            result = _prune_orphaned_cache_entries(conn, lock_timeout=None)
+        finally:
+            conn.close()
+    except Exception:
+        return None
+    if result is not None and (result.pruned_entries or result.pruned_files):
+        try:
+            bump_generation()
+            reset_group_a_state()
+            reset_session_cache_state()
+            # #269 M3.2 (spec §6): the shared per-weekref immutable-cost cache
+            # (B1 trend/weekly-history + B3 forecast) rides the SAME prune-site
+            # clear — a non-max deletion the reconcile's max-id regression check
+            # can't catch.
+            reset_weekref_cost_state()
+            # #272: the per-day cache-report cache rides the same prune-site
+            # clear — a non-max deletion inside a closed day the reconcile's
+            # max-id / mutation-seq regression check can't catch.
+            reset_cache_report_state()
+            # #269 M4.5 (spec §14 Win 2): the projects-envelope per-(project,
+            # week) cache rides the same prune-site clear for the same reason.
+            reset_projects_env_state()
+            # #271 M3 (spec §18): the Bug-K pre-credit segment cache rides the
+            # same prune-site clear — a non-max deletion inside a closed
+            # pre-credit window the reconcile's max-id regression check can't
+            # catch.
+            reset_bugk_segment_state()
+            # #269 (final reviewer): the per-(project, week) cache clear above is
+            # NOT sufficient on its own. `_build_projects_envelope` consults the
+            # whole-envelope memo `_PROJECTS_ENV_MEMO` FIRST — and its memo_key is
+            # `(max_id, max_wus_id, entry_mutation_seq, cw_key, weeks_back)`, which
+            # carries NO generation counter. A prune that deletes only NON-max
+            # `session_entries` rows leaves `max_id` unchanged, so the memo_key
+            # still matches and the memo would stale-serve the pre-prune envelope
+            # (still showing the deleted project + its cost) before the fresh
+            # per-week cache path is ever reached. Clear the memo too so a real
+            # prune actually changes the envelope output.
+            _projects_reset_memo()
+        except Exception:
+            # Invalidation must never turn a successful prune into a failure;
+            # a stale-cache tick is self-corrected once the signature next moves.
+            pass
+    return result
+
+
 def _build_forecast_json_payload(*args, **kwargs):
     return sys.modules["cctally"]._build_forecast_json_payload(*args, **kwargs)
 
@@ -1978,6 +2084,77 @@ def _cache_report_load_kernel():
     return sys.modules["cctally"]._load_sibling("_lib_cache_report")
 
 
+def _cache_report_needed_closed_dates(since, now_utc, bucket_tz):
+    """The CLOSED display-tz dates a full-window cache-report build needs (#272 §6).
+
+    Every display-tz calendar date overlapping ``[since, now_utc]`` EXCEPT the
+    current open day (Codex-2: a ``since``-straddling window yields up to
+    ``window_days + 1`` display dates, and classification runs over the full
+    set BEFORE the ``days`` cap). Returned sorted ascending. The ``have_all``
+    gate requires every one of these to be cached before serving the warm
+    (today-only-fetch) path. A genuinely activity-free calendar day produces
+    no per-day fold row, so the cold/miss populate branch stores an
+    ``is_empty`` sentinel (``empty_cached_day``) for every needed closed date
+    the fold didn't emit — registering the quiet day as a cache HIT (the same
+    computed-empty registration ``projects_env_week_put`` does for an empty
+    week). That keeps ``have_all`` reachable, so a weekend/vacation gap day
+    does NOT permanently defeat the warm path; the sentinel is skipped in the
+    restitch, so the output stays byte-identical to from-scratch.
+    """
+    today_key = now_utc.astimezone(bucket_tz).strftime("%Y-%m-%d")
+    d = since.astimezone(bucket_tz).date()
+    end_date = now_utc.astimezone(bucket_tz).date()
+    out: list = []
+    while d <= end_date:
+        key = d.strftime("%Y-%m-%d")
+        if key != today_key:
+            out.append(key)
+        d += dt.timedelta(days=1)
+    return out
+
+
+def _day_start(date_iso, bucket_tz):
+    """The aware-UTC instant of ``date_iso``'s local midnight in ``bucket_tz`` (#272 §6).
+
+    Lower-bounds the warm-path current-day fetch so it returns exactly the
+    entries ``_aggregate_cache_by_day`` buckets to ``date_iso`` (which buckets
+    via ``entry.timestamp.astimezone(bucket_tz)``). DST-correct: attaching the
+    zone to the naive local-midnight then converting to UTC lets ``ZoneInfo``
+    pick the right offset for that wall time.
+    """
+    naive = dt.datetime.strptime(date_iso, "%Y-%m-%d")
+    return naive.replace(tzinfo=bucket_tz).astimezone(dt.timezone.utc)
+
+
+def _cache_report_empty(
+    *, today_iso, window_days, anomaly_threshold_pp, anomaly_window_days,
+):
+    """The empty (no in-window entries) ``CacheReportSnapshot`` — factored so the
+    warm and cold builder paths share one ``is_empty`` return (#272 §6)."""
+    empty_today = CacheReportTodaySpotlight(
+        date=today_iso,
+        cache_hit_percent=0.0,
+        baseline_median_percent=None,
+        delta_pp=None,
+        net_usd=0.0, saved_usd=0.0, wasted_usd=0.0,
+        anomaly_triggered=False,
+        anomaly_reasons=(),
+        baseline_daily_row_count=0,
+    )
+    return CacheReportSnapshot(
+        window_days=window_days,
+        anomaly_threshold_pp=anomaly_threshold_pp,
+        anomaly_window_days=anomaly_window_days,
+        today=empty_today,
+        days=(), by_project=(), by_model=(),
+        seven_day_net_usd=0.0,
+        seven_day_anomaly_count=0,
+        fourteen_day_counterfactual_usd=0.0,
+        fourteen_day_efficiency_ratio=0.0,
+        is_empty=True,
+    )
+
+
 def build_cache_report_snapshot(
     *,
     now_utc: dt.datetime,
@@ -1985,91 +2162,167 @@ def build_cache_report_snapshot(
     anomaly_window_days: int,
     display_tz: "ZoneInfo | None",
     skip_sync: bool = False,
+    use_cache_report_cache: bool = False,
 ) -> CacheReportSnapshot:
     """Build the ``cache_report`` envelope field from the session-entry cache.
 
     Pulls entries via ``get_claude_session_entries`` (uses the cache when
     warm, falls back to direct-JSONL parse on cache miss / lock
-    contention — same chain the CLI uses). Delegates aggregation +
-    anomaly classification to ``_lib_cache_report._build_cache_report``;
-    shapes the result into a frozen ``CacheReportSnapshot``.
+    contention — same chain the CLI uses). Aggregates per closed day via
+    ``_lib_cache_report.build_cached_days`` (served from the per-day cache
+    when ``use_cache_report_cache`` and reconciled), reconstructs fresh
+    rows (``reconstruct_cache_row``), runs the cross-row
+    ``classify_and_summarize`` + ``combine_day_project_partials`` restitch,
+    and shapes the result into a frozen ``CacheReportSnapshot``.
 
     ``window_days`` is hardcoded at 14 in v1 (spec §6.1 hardcodes
     ``anomaly_window_days`` too; ``anomaly_threshold_pp`` is the only
     user-configurable knob). F10 from spec §10 tracks making the window
     configurable, plus the UI-copy work it'd require.
+
+    **Per-day cache (#272 §6).** With ``use_cache_report_cache=True`` (set by
+    the dashboard sync thread AFTER ``reconcile_cache_report_cache`` succeeds),
+    the CLOSED days are served from the immutable per-day cache and only the
+    current (open) day is fetched + folded fresh — the warm-tick win. The
+    reconcile (in ``_tui_build_snapshot``) owns invalidation; this builder only
+    reads/populates the cache. With the flag OFF (default / safe fallback), the
+    full window is fetched every tick and the output is byte-identical to the
+    cached path (same restructured assembly, cache bypassed).
     """
     crk = _cache_report_load_kernel()
     cctally_ns = sys.modules["cctally"]
+    _sc = sys.modules["_lib_snapshot_cache"]
 
     window_days = CACHE_REPORT_WINDOW_DAYS  # v1: hardcoded per spec §6.1.
     since = now_utc - dt.timedelta(days=window_days)
+    pricing = cctally_ns.CLAUDE_MODEL_PRICING
 
-    entries = list(
-        get_claude_session_entries(since, now_utc, project=None, skip_sync=skip_sync)
-    )
-
+    # Cache mechanics key on the BUCKETING tz (``_resolve_bucket_tz`` — the same
+    # tz ``_aggregate_cache_by_day`` buckets by), so ``today_key`` / the closed-
+    # day keys line up with ``CacheRow.date``. The spotlight's ``today_iso``
+    # keeps its own UTC-fallback derivation unchanged (byte-identity); the two
+    # agree whenever ``display_tz`` is set — always, on the dashboard.
+    bucket_tz = crk._resolve_bucket_tz(display_tz)
+    today_key = now_utc.astimezone(bucket_tz).strftime("%Y-%m-%d")
     today_iso = now_utc.astimezone(
         display_tz if display_tz is not None else dt.timezone.utc
     ).strftime("%Y-%m-%d")
 
-    if not entries:
-        empty_today = CacheReportTodaySpotlight(
-            date=today_iso,
-            cache_hit_percent=0.0,
-            baseline_median_percent=None,
-            delta_pp=None,
-            net_usd=0.0, saved_usd=0.0, wasted_usd=0.0,
-            anomaly_triggered=False,
-            anomaly_reasons=(),
-            baseline_daily_row_count=0,
+    def _wrap_day_entries(raw):
+        # Day-mode kernel expects entries with a ``usage`` dict (matches
+        # ``UsageEntry``); ``get_claude_session_entries`` returns flat
+        # ``_JoinedClaudeEntry`` objects. SimpleNamespace keeps the wrapper
+        # pure-Python and avoids a new dataclass type just for the bridge.
+        from types import SimpleNamespace as _NS
+        return [
+            _NS(
+                timestamp=e.timestamp,
+                model=e.model,
+                cost_usd=e.cost_usd,
+                usage={
+                    "input_tokens": e.input_tokens,
+                    "output_tokens": e.output_tokens,
+                    "cache_creation_input_tokens": e.cache_creation_tokens,
+                    "cache_read_input_tokens": e.cache_read_tokens,
+                },
+            )
+            for e in raw
+        ]
+
+    # Which CLOSED display-tz dates the window needs (every date overlapping
+    # [since, now] except the current open day). If the cache holds them ALL,
+    # fetch only the current day (the warm win); else one full-window fetch
+    # (re)populates the closed days + recomputes today.
+    needed_closed = _cache_report_needed_closed_dates(since, now_utc, bucket_tz)
+    have_all = use_cache_report_cache and all(
+        _sc.cache_report_day_get(d) is not None for d in needed_closed
+    )
+
+    cached_days: dict = {}  # date_key -> CachedCacheReportDay
+    if have_all:
+        # Steady-state warm: recompute ONLY the open bucket; reuse cached closed.
+        raw_today = list(get_claude_session_entries(
+            _day_start(today_key, bucket_tz), now_utc,
+            project=None, skip_sync=skip_sync,
+        ))
+        built = crk.build_cached_days(
+            _wrap_day_entries(raw_today), raw_today,
+            display_tz=display_tz, pricing=pricing,
+            cost_calculator=_calculate_entry_cost,
+        )
+        for d in needed_closed:
+            cached_days[d] = _sc.cache_report_day_get(d)
+        cached_days.update(built)  # the fresh current day (today only)
+    else:
+        # Cold / partial-miss / post-eviction: pay one full-window fetch, then
+        # (re)compute + store every closed day. Runs on the rare stale tick.
+        raw = list(get_claude_session_entries(
+            since, now_utc, project=None, skip_sync=skip_sync,
+        ))
+        if not raw:
+            return _cache_report_empty(
+                today_iso=today_iso, window_days=window_days,
+                anomaly_threshold_pp=anomaly_threshold_pp,
+                anomaly_window_days=anomaly_window_days,
+            )
+        built = crk.build_cached_days(
+            _wrap_day_entries(raw), raw,
+            display_tz=display_tz, pricing=pricing,
+            cost_calculator=_calculate_entry_cost,
         )
-        return CacheReportSnapshot(
-            window_days=window_days,
+        cached_days = dict(built)
+        if use_cache_report_cache:
+            for d, unit in built.items():
+                if d != today_key:  # never store the OPEN day as a closed unit
+                    _sc.cache_report_day_store(d, unit)
+            # Empty/gap-day sentinel: a genuinely activity-free CLOSED day never
+            # appears in ``built`` (``build_cached_days`` only emits days with
+            # entries), so register an ``is_empty`` sentinel for every needed
+            # closed date the fold produced nothing for. Without this,
+            # ``have_all`` would see that quiet day as a perpetual miss and the
+            # builder would full-window-refetch on EVERY warm tick — permanently
+            # defeating the cache for any user with an off day. Mirrors
+            # ``projects_env_week_put`` registering a computed-empty week as a
+            # hit. ``needed_closed`` already excludes ``today_key``; the sentinel
+            # is skipped in the restitch below, so this is byte-identical.
+            for d in needed_closed:
+                if d not in built:
+                    _sc.cache_report_day_store(d, crk.empty_cached_day(d))
+            # Window-rolloff eviction (#275): the reconcile's seq-gated pass only
+            # evicts CHANGED days (>= the change watermark); days that roll off the
+            # trailing edge of the [since, now] window are never pruned there and
+            # would accrete one frozen unit/day on a long-uptime dashboard. Drop
+            # them here on this rare cold/rollover store tick (the warm path never
+            # reaches this branch). ``needed_closed`` is sorted ascending, so its
+            # first element is the window's oldest still-needed closed day; every
+            # needed day (real or ``is_empty`` sentinel) is >= it and survives.
+            if needed_closed:
+                _sc.cache_report_day_evict_before(needed_closed[0])
+
+    if not cached_days:
+        return _cache_report_empty(
+            today_iso=today_iso, window_days=window_days,
             anomaly_threshold_pp=anomaly_threshold_pp,
             anomaly_window_days=anomaly_window_days,
-            today=empty_today,
-            days=(), by_project=(), by_model=(),
-            seven_day_net_usd=0.0,
-            seven_day_anomaly_count=0,
-            fourteen_day_counterfactual_usd=0.0,
-            fourteen_day_efficiency_ratio=0.0,
-            is_empty=True,
         )
 
-    pricing = cctally_ns.CLAUDE_MODEL_PRICING
-
-    # Day-mode kernel expects entries with a ``usage`` dict (matches
-    # ``UsageEntry``). ``get_claude_session_entries`` returns flat
-    # ``_JoinedClaudeEntry`` objects, so wrap each into the right shape
-    # before passing to the kernel. SimpleNamespace keeps the wrapper
-    # pure-Python and avoids a new dataclass type just for the bridge.
-    from types import SimpleNamespace as _NS
-    day_entries = [
-        _NS(
-            timestamp=e.timestamp,
-            model=e.model,
-            cost_usd=e.cost_usd,
-            usage={
-                "input_tokens": e.input_tokens,
-                "output_tokens": e.output_tokens,
-                "cache_creation_input_tokens": e.cache_creation_tokens,
-                "cache_read_input_tokens": e.cache_read_tokens,
-            },
-        )
-        for e in entries
+    # Reconstruct fresh MUTABLE rows from the frozen cached days (F7 — cached
+    # units are never touched), then run the cross-row classify + summarize
+    # pass over the FULL assembled set every tick (the cached day aggregates
+    # carry no anomaly state).
+    rows = [
+        crk.reconstruct_cache_row(cached_days[d])
+        for d in sorted(cached_days)
+        if not cached_days[d].is_empty  # sentinel gap days emit no CacheRow
     ]
-
-    result = crk._build_cache_report(
-        day_entries,
+    result = crk.classify_and_summarize(
+        rows,
         now_utc=now_utc,
         window_days=window_days,
         anomaly_threshold_pp=anomaly_threshold_pp,
         anomaly_window_days=anomaly_window_days,
         display_tz=display_tz,
-        pricing=pricing,
         mode="day",
-        cost_calculator=_calculate_entry_cost,
     )
 
     # Pick out today's row (if any) and the baseline-daily-row count for
@@ -2206,17 +2459,22 @@ def build_cache_report_snapshot(
     # cache entry and its corresponding day row always agree on which
     # bucket they belong to.
     kept_dates = frozenset(r.date for r in days if r.date)
-    bucket_tz = display_tz if display_tz is not None else dt.timezone.utc
-    entries_in_window = [
-        e for e in entries
-        if e.timestamp.astimezone(bucket_tz).strftime("%Y-%m-%d") in kept_dates
-    ]
     rows_in_window = [r for r in result.rows if r.date in kept_dates]
-    by_project_rows = crk._aggregate_cache_breakdown(
-        entries_in_window,
-        key_fn=lambda e: (getattr(e, "project_path", None) or "(unknown)"),
-        pricing=pricing,
-        skip_synthetic=True,
+    # by_project via the #272 §4 two-level ``stable_sum`` fold
+    # (grouping-invariant). The per-(day, project) partials are carried on each
+    # ``CachedCacheReportDay`` (§5) — served from cache for closed days and
+    # freshly folded for today — so restitching them here memoizes the fold
+    # byte-identically. Their day keys use ``_resolve_bucket_tz(display_tz)``
+    # (matching ``CacheRow.date`` / ``kept_dates``), so combining over
+    # ``kept_dates`` is exactly the old full-window slice, modulo the one-time
+    # ULP fold move. Every ``kept_date`` is in ``cached_days`` (it came from a
+    # day row); the ``if d in cached_days`` guard is defensive.
+    by_project_rows = crk.combine_day_project_partials(
+        {
+            d: dict(cached_days[d].project_partials)
+            for d in kept_dates
+            if d in cached_days and not cached_days[d].is_empty
+        }
     )
     by_model_rows = crk._aggregate_cache_breakdown_from_rows(
         rows_in_window,
@@ -2464,10 +2722,130 @@ def _compute_intensity_buckets(rows: "list[DailyPanelRow]") -> list[float]:
     return thresholds
 
 
+def _group_a_monthly_buckets(now_utc, *, n, range_start, display_tz):
+    """Assemble the monthly panel's per-month ``BucketUsage`` list via the
+    #268 Group A cache, or ``None`` to fall back to the wide fetch (spec §5.1).
+
+    ``all_bucket_labels`` is the contiguous set of display-tz ``"%Y-%m"``
+    months spanned by the wide window ``[range_start, now_utc]`` — from
+    ``range_start``'s display-tz month (the oldest an entry in the window can
+    bucket into, including the west-of-UTC boundary-spillover month) up to
+    the current display-tz month — in ascending order. ``build_monthly_view``
+    then reverses + caps to ``n``, dropping any spillover month exactly as
+    the from-scratch path does. Each recompute fetches a ±2-day-padded window
+    (clamped to the wide window) and filters ``_aggregate_monthly`` to the
+    target month, so the boundary follows ``display_tz`` and per-bucket
+    first-seen model order matches the wide pass byte-for-byte.
+    """
+    if not _GROUP_A_CACHE_ENABLED:
+        return None
+    try:
+        cache_conn = open_cache_db()
+    except Exception:
+        return None
+    try:
+        def _tz_month(instant):
+            local = (
+                instant.astimezone(display_tz) if display_tz is not None
+                # internal fallback: host-local intentional
+                else instant.astimezone()
+            )
+            return local.year, local.month
+
+        oldest_y, oldest_m = _tz_month(range_start)
+        newest_y, newest_m = _tz_month(now_utc)
+        # Contiguous months oldest → newest (ascending).
+        labels: list[str] = []
+        y, m = oldest_y, oldest_m
+        while (y, m) <= (newest_y, newest_m):
+            labels.append(f"{y:04d}-{m:02d}")
+            m += 1
+            if m == 13:
+                m = 1
+                y += 1
+        current_label = f"{newest_y:04d}-{newest_m:02d}"
+        tz_sig = display_tz.key if display_tz is not None else "local"
+
+        def _month_bounds(label):
+            yy, mm = (int(x) for x in label.split("-"))
+            start = dt.datetime(yy, mm, 1, tzinfo=dt.timezone.utc)
+            ny, nm = (yy + 1, 1) if mm == 12 else (yy, mm + 1)
+            nxt = dt.datetime(ny, nm, 1, tzinfo=dt.timezone.utc)
+            return start, nxt
+
+        def _fetch(label):
+            start, nxt = _month_bounds(label)
+            # ±2 days of slack covers the display-tz month boundary for any
+            # offset; clamp to the wide window so nothing after now_utc /
+            # before range_start leaks in.
+            lo = max(start - dt.timedelta(days=2), range_start)
+            hi = min(nxt + dt.timedelta(days=2), now_utc)
+            if hi <= lo:
+                return []
+            return iter_entries(cache_conn, lo, hi)
+
+        def _agg_one(label, entries):
+            for b in _aggregate_monthly(entries, tz=display_tz):
+                if b.bucket == label:
+                    return b
+            return None
+
+        def _end_of(label):
+            _start, nxt = _month_bounds(label)
+            return nxt + dt.timedelta(days=2)
+
+        # #271: current-bucket accumulator inputs. `_membership` IS
+        # `_aggregate_monthly`'s own key (display-tz `%Y-%m`);
+        # `_all_fetch`/`_delta_fetch` reuse `_fetch`'s ±2-day-padded month
+        # window (clamped to now_utc) via the `(id, UsageEntry)` delta sibling.
+        def _membership(e):
+            local = (
+                e.timestamp.astimezone(display_tz) if display_tz is not None
+                # internal fallback: host-local intentional
+                else e.timestamp.astimezone()
+            )
+            return local.strftime("%Y-%m") == current_label
+
+        def _current_window(label):
+            start, nxt = _month_bounds(label)
+            lo = max(start - dt.timedelta(days=2), range_start)
+            hi = min(nxt + dt.timedelta(days=2), now_utc)
+            return lo, hi
+
+        def _all_fetch(label):
+            lo, hi = _current_window(label)
+            return [] if hi <= lo else iter_entries_with_id(cache_conn, lo, hi)
+
+        def _delta_fetch(label, after_seq, after_ts):
+            lo, hi = _current_window(label)
+            return [] if hi <= lo else iter_entries_with_id(
+                cache_conn, lo, hi, after_seq=after_seq, after_ts=after_ts)
+
+        buckets = build_cached_group_a(
+            "monthly",
+            cache_conn=cache_conn,
+            all_bucket_labels=labels,
+            current_label=current_label,
+            bucket_end_of=_end_of,
+            fetch_bucket_entries=_fetch,
+            aggregate_one=_agg_one,
+            extra_signature=("monthly", tz_sig),
+            use_current_accumulator=True,
+            now_utc=now_utc,
+            current_all_fetch=_all_fetch,
+            current_delta_fetch=_delta_fetch,
+            membership_of=_membership,
+        )
+        return tuple(buckets)
+    finally:
+        cache_conn.close()
+
+
 def _dashboard_build_monthly_periods(conn: "sqlite3.Connection",
                                      now_utc: "dt.datetime",
                                      *, n: int = 12,
                                      skip_sync: bool = False,
+                                     use_group_a_cache: bool = False,
                                      display_tz: "ZoneInfo | None" = None) -> "list[MonthlyPeriodRow]":
     """Latest n calendar months as MonthlyPeriodRow, newest-first.
 
@@ -2496,17 +2874,188 @@ def _dashboard_build_monthly_periods(conn: "sqlite3.Connection",
     range_start = dt.datetime(sy, sm, 1, tzinfo=dt.timezone.utc)
     range_end = now_utc
 
-    entries = get_entries(range_start, range_end, skip_sync=skip_sync)
+    # #268 Group A cache: assemble the per-month BucketUsage list through the
+    # module cache (recompute only the current + watermark-dirty months;
+    # serve immutable past months from memory) and hand it to
+    # build_monthly_view as aggregated_override. Gated on ``use_group_a_cache``
+    # — set ONLY by the sync-thread rebuild, never by ``skip_sync`` (the
+    # share-period-override path also runs ``skip_sync=True`` but on an HTTP
+    # thread with a shifted PAST now, which would pollute the shared cache with
+    # a partial past-month bucket — see ``_dashboard_build_daily_panel``). Every
+    # non-sync-thread caller falls through to the from-scratch wide fetch. Also
+    # falls back when disabled / cache DB unavailable.
+    aggregated_override = (
+        _group_a_monthly_buckets(
+            now_utc, n=n, range_start=range_start, display_tz=display_tz,
+        )
+        if use_group_a_cache else None
+    )
     c = _cctally()
-    view = c.build_monthly_view(entries, now_utc=now_utc, n=n,
-                                 display_tz=display_tz)
+    if aggregated_override is None:
+        entries = get_entries(range_start, range_end, skip_sync=skip_sync)
+        view = c.build_monthly_view(entries, now_utc=now_utc, n=n,
+                                    display_tz=display_tz)
+    else:
+        view = c.build_monthly_view((), now_utc=now_utc, n=n,
+                                    display_tz=display_tz,
+                                    aggregated_override=aggregated_override)
     return list(view.rows)
 
 
+def _group_a_weekly_buckets(stats_conn, now_utc, *, weeks):
+    """Assemble the weekly panel's per-week ``BucketUsage`` list via the #268
+    Group A cache, or ``None`` to fall back to the wide fetch (spec §5.1).
+
+    ``all_bucket_labels`` = each SubWeek's ``start_date.isoformat()`` in
+    ascending order (matching ``_aggregate_weekly``'s sorted-key output);
+    ``current_label`` = the SubWeek containing ``now_utc`` (always recomputed
+    as the open week). Each recompute fetches ``[week.start_ts, min(week.end_ts,
+    now_utc)]`` (clamped to now, matching the wide fetch's ``range_end`` bound)
+    and runs ``_aggregate_weekly`` over the FULL ``weeks`` list — extracting
+    the target week's bucket — so overlapping SubWeeks (reset-day drift) keep
+    their first-match-wins assignment byte-for-byte with the wide pass.
+
+    Weekly is the multi-table case (spec §5.1): the SubWeek boundaries derive
+    from ``weekly_usage_snapshots`` + the reset-event tables, so the cached raw
+    aggregate could shift when any of those move. ``extra_signature`` folds in
+    ``MAX(weekly_usage_snapshots.id)`` / ``MAX(weekly_cost_snapshots.id)`` /
+    the reset-event change-signal — a change to any full-invalidates the weekly
+    namespace (the scoped M2.4 fallback: recompute-all on a weekly-relevant
+    change, cache-hit only when nothing weekly-relevant moved — still the idle
+    win, and trivially byte-identical). Pure session-entry adds stay per-week
+    via the watermark. The overlay / Bug-K presentation reruns fresh each tick,
+    so a snapshot change is reflected even on a cache-served bucket.
+    """
+    if not _GROUP_A_CACHE_ENABLED:
+        return None
+    try:
+        cache_conn = open_cache_db()
+    except Exception:
+        return None
+    try:
+        sw_by_label = {w.start_date.isoformat(): w for w in weeks}
+        labels = [w.start_date.isoformat() for w in weeks]  # ascending
+        # current_label = the SubWeek that contains now_utc (the open week);
+        # fall back to the newest week if none contains it.
+        current_label = None
+        for w in weeks:
+            try:
+                s = parse_iso_datetime(w.start_ts, "week.start_ts")
+                e = parse_iso_datetime(w.end_ts, "week.end_ts")
+            except ValueError:
+                continue
+            if s <= now_utc < e:
+                current_label = w.start_date.isoformat()
+                break
+        if current_label is None:
+            current_label = max(
+                weeks, key=lambda w: w.start_date
+            ).start_date.isoformat()
+
+        # Weekly-relevant signature legs: any change full-invalidates.
+        extra_signature = (
+            _snapshot_max_id(stats_conn, "weekly_usage_snapshots"),
+            _snapshot_max_id(stats_conn, "weekly_cost_snapshots"),
+            _snapshot_reset_sig(stats_conn),
+        )
+
+        def _fetch(label):
+            w = sw_by_label[label]
+            s = parse_iso_datetime(w.start_ts, "week.start_ts")
+            e = parse_iso_datetime(w.end_ts, "week.end_ts")
+            hi = min(e, now_utc)  # cap the open week at now, like the wide fetch
+            if hi <= s:
+                return []
+            return iter_entries(cache_conn, s, hi)
+
+        def _agg_one(label, entries):
+            # Aggregate against the FULL weeks list so overlapping SubWeeks
+            # resolve first-match-wins exactly as the wide pass does; extract
+            # the target week's bucket.
+            for b in _aggregate_weekly(entries, weeks):
+                if b.bucket == label:
+                    return b
+            return None
+
+        def _end_of(label):
+            w = sw_by_label[label]
+            try:
+                return parse_iso_datetime(w.end_ts, "week.end_ts")
+            except ValueError:
+                return None
+
+        # #271: current-bucket accumulator inputs. Membership REUSES
+        # _aggregate_weekly's exact bisect + first-match-wins assignment
+        # (bin/_lib_aggregators.py::_week_key_or_none) — the parsed-bounds list
+        # is built identically (same order, same parse) so an entry in an
+        # overlap region (reset-day drift) keys to the SAME week the full pass
+        # assigns it. _all_fetch/_delta_fetch reuse _fetch's
+        # [week.start, min(week.end, now_utc)] window via the (id, UsageEntry)
+        # delta sibling.
+        _parsed_bounds = [
+            (parse_iso_datetime(w.start_ts, "week.start_ts"),
+             parse_iso_datetime(w.end_ts, "week.end_ts"),
+             w.start_date.isoformat())
+            for w in weeks
+        ]
+        _bound_starts = [b[0] for b in _parsed_bounds]
+
+        def _week_key(e):
+            ts = e.timestamp
+            idx = bisect.bisect_right(_bound_starts, ts) - 1
+            if idx < 0:
+                return None
+            while idx > 0 and (
+                _parsed_bounds[idx - 1][0] <= ts < _parsed_bounds[idx - 1][1]
+            ):
+                idx -= 1
+            s_dt, e_dt, key = _parsed_bounds[idx]
+            return key if s_dt <= ts < e_dt else None
+
+        def _membership(e):
+            return _week_key(e) == current_label
+
+        def _current_window(label):
+            w = sw_by_label[label]
+            s = parse_iso_datetime(w.start_ts, "week.start_ts")
+            e = parse_iso_datetime(w.end_ts, "week.end_ts")
+            return s, min(e, now_utc)
+
+        def _all_fetch(label):
+            s, hi = _current_window(label)
+            return [] if hi <= s else iter_entries_with_id(cache_conn, s, hi)
+
+        def _delta_fetch(label, after_seq, after_ts):
+            s, hi = _current_window(label)
+            return [] if hi <= s else iter_entries_with_id(
+                cache_conn, s, hi, after_seq=after_seq, after_ts=after_ts)
+
+        buckets = build_cached_group_a(
+            "weekly",
+            cache_conn=cache_conn,
+            all_bucket_labels=labels,
+            current_label=current_label,
+            bucket_end_of=_end_of,
+            fetch_bucket_entries=_fetch,
+            aggregate_one=_agg_one,
+            extra_signature=extra_signature,
+            use_current_accumulator=True,
+            now_utc=now_utc,
+            current_all_fetch=_all_fetch,
+            current_delta_fetch=_delta_fetch,
+            membership_of=_membership,
+        )
+        return tuple(buckets)
+    finally:
+        cache_conn.close()
+
+
 def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
                                     now_utc: "dt.datetime",
                                     *, n: int = 12,
-                                    skip_sync: bool = False) -> "list[WeeklyPeriodRow]":
+                                    skip_sync: bool = False,
+                                    use_group_a_cache: bool = False,
+                                    use_bugk_segment_cache: bool = False) -> "list[WeeklyPeriodRow]":
     """Latest n subscription weeks as WeeklyPeriodRow, newest-first.
 
     Thin builder-using prelude + Bug-K pre-credit synthesis on top of
@@ -2534,7 +3083,6 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
         range_start,
         parse_iso_datetime(weeks[0].start_ts, "week_start_at"),
     )
-    entries = get_entries(fetch_start, range_end, skip_sync=skip_sync)
     as_of_utc = (
         range_end.astimezone(dt.timezone.utc)
         .replace(microsecond=0)
@@ -2542,12 +3090,37 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
         .replace("+00:00", "Z")
     )
 
-    # Builder prelude: produce the natural newest-first rows + overlay.
-    c = _cctally()
-    view = c.build_weekly_view(
-        conn, entries, weeks=weeks, now_utc=now_utc,
-        display_tz=None, as_of_utc=as_of_utc,
+    # #268 Group A cache: assemble the per-week BucketUsage list through the
+    # module cache (recompute only the current + watermark-dirty weeks; serve
+    # immutable past weeks from memory) and hand it to build_weekly_view as
+    # aggregated_override. Gated on ``use_group_a_cache`` — set ONLY by the
+    # sync-thread rebuild, never by ``skip_sync``. The share-period-override
+    # path also runs ``skip_sync=True`` but on an HTTP thread with a shifted
+    # PAST now; routing it through the shared cache would clamp the
+    # now_override-current week to a partial aggregate and cache it under a real
+    # PAST-week label (weekly is the worst case — its extra_signature is
+    # stats-only, so nothing invalidates the polluted week until a data change
+    # lands). Every non-sync-thread caller falls through to the from-scratch
+    # wide fetch, as does the cache-disabled / cache-unavailable case. The
+    # overlay + Bug-K + delta + is_current presentation always reruns fresh over
+    # the assembled list.
+    aggregated_override = (
+        _group_a_weekly_buckets(conn, now_utc, weeks=weeks)
+        if use_group_a_cache else None
     )
+    c = _cctally()
+    if aggregated_override is None:
+        entries = get_entries(fetch_start, range_end, skip_sync=skip_sync)
+        view = c.build_weekly_view(
+            conn, entries, weeks=weeks, now_utc=now_utc,
+            display_tz=None, as_of_utc=as_of_utc,
+        )
+    else:
+        view = c.build_weekly_view(
+            conn, (), weeks=weeks, now_utc=now_utc,
+            display_tz=None, as_of_utc=as_of_utc,
+            aggregated_override=aggregated_override,
+        )
     if not view.rows:
         return []
 
@@ -2615,9 +3188,10 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
     # _apply_reset_events_to_subweeks shifts the credited SubWeek's
     # start_ts to ``effective_reset_at_utc``, so _aggregate_weekly's
     # bucket for that SubWeek already covers ONLY the post-credit
-    # interval. We rebuild the pre-credit bucket here by filtering the
-    # same ``entries`` list to ``[original_start, effective)`` and
-    # re-aggregating cost / tokens / per-model.
+    # interval. We rebuild the pre-credit bucket here by fetching the
+    # ``[original_start, effective)`` window directly (#268: no longer a
+    # wide ``entries`` list on the cached path) and re-aggregating cost /
+    # tokens / per-model.
     #
     # The pre-credit row's ``used_pct`` comes from the
     # weekly_usage_snapshots row captured at-or-before the credit
@@ -2689,24 +3263,64 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
                 # No pre-credit interval to aggregate.
                 continue
 
-            # Aggregate entries in [original_start, effective).
-            pre_input = pre_output = pre_cc = pre_cr = 0
-            pre_cost = 0.0
-            pre_models: dict[str, float] = {}
-            pre_entry_count = 0
-            for e in entries:
-                if original_start_dt <= e.timestamp < eff_dt:
-                    usage = e.usage
-                    pre_input  += usage.get("input_tokens", 0)
-                    pre_output += usage.get("output_tokens", 0)
-                    pre_cc     += usage.get("cache_creation_input_tokens", 0)
-                    pre_cr     += usage.get("cache_read_input_tokens", 0)
-                    c = _calc(
-                        e.model, usage, mode="auto", cost_usd=e.cost_usd,
-                    )
-                    pre_cost += c
-                    pre_models[e.model] = pre_models.get(e.model, 0.0) + c
-                    pre_entry_count += 1
+            # Aggregate entries in [original_start, effective). Fetch this
+            # window directly (skip_sync=True — the rebuild already ingested,
+            # or the fallback's wide fetch above did) rather than filtering a
+            # wide `entries` list, so Bug-K works identically on the cached
+            # path (where no wide entry list exists) and the fallback path.
+            #
+            # #271 §18: the [original_start, effective) window is a CLOSED past
+            # interval (effective is a historical credit moment), so this folded
+            # aggregate is IMMUTABLE — cache it byte-identically (the same
+            # "re-aggregate immutable history every tick" pattern the #269
+            # weekref cost cache fixed). `_compute_pre_segment` is the exact
+            # from-scratch fetch+fold closure; on the sync thread
+            # (`use_bugk_segment_cache=True`) it routes through
+            # `cached_bugk_segment` (get-or-compute over the canonical window
+            # key), on EVERY other caller (CLI / share / tests / reconcile-
+            # failed) it computes directly — byte-unchanged. The `used_pct`
+            # snapshot query + WeeklyPeriodRow build BELOW always rerun fresh
+            # from the segment (do NOT cache the row — Codex-BK-5).
+            def _compute_pre_segment(_orig=original_start_dt, _eff=eff_dt):
+                pi = po = pcc = pcr = 0
+                pcost = 0.0
+                pmodels: dict[str, float] = {}
+                pcount = 0
+                for e in get_entries(_orig, _eff, skip_sync=True):
+                    if _orig <= e.timestamp < _eff:
+                        usage = e.usage
+                        pi  += usage.get("input_tokens", 0)
+                        po  += usage.get("output_tokens", 0)
+                        pcc += usage.get("cache_creation_input_tokens", 0)
+                        pcr += usage.get("cache_read_input_tokens", 0)
+                        c = _calc(
+                            e.model, usage, mode="auto", cost_usd=e.cost_usd,
+                        )
+                        pcost += c
+                        pmodels[e.model] = pmodels.get(e.model, 0.0) + c
+                        pcount += 1
+                # Codex-BK-4: freeze `models` as a tuple of (model, cost) in
+                # first-seen (dict-insertion) order so the row's stable cost-desc
+                # sort tie-order can't be mutated after caching.
+                return BugKSegment(
+                    input=pi, output=po, cache_create=pcc, cache_read=pcr,
+                    cost=pcost, models=tuple(pmodels.items()), entry_count=pcount,
+                )
+
+            if use_bugk_segment_cache:
+                seg = cached_bugk_segment(
+                    key=_bugk_key(original_start_dt, eff_dt),
+                    compute=_compute_pre_segment,
+                )
+            else:
+                seg = _compute_pre_segment()
+            pre_input = seg.input
+            pre_output = seg.output
+            pre_cc = seg.cache_create
+            pre_cr = seg.cache_read
+            pre_cost = seg.cost
+            pre_models = seg.models  # ((model, cost), ...) in first-seen order
+            pre_entry_count = seg.entry_count
             if pre_entry_count == 0 and pre_cost <= 0:
                 # No measurable pre-credit activity — skip insertion.
                 continue
@@ -2729,9 +3343,12 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
             )
 
             pre_total = pre_input + pre_output + pre_cc + pre_cr
+            # `pre_models` is a first-seen-order tuple of (model, cost); the
+            # stable cost-desc sort preserves that tie-order byte-for-byte,
+            # identical to the pre-#271 `sorted(dict.items(), ...)`.
             pre_model_breakdowns = [
                 {"modelName": m, "cost": c}
-                for m, c in sorted(pre_models.items(), key=lambda kv: -kv[1])
+                for m, c in sorted(pre_models, key=lambda kv: -kv[1])
             ]
             pre_label = original_start_dt.strftime("%m-%d")
             pre_row = WeeklyPeriodRow(
@@ -2965,11 +3582,130 @@ def _dashboard_build_blocks_panel(conn: "sqlite3.Connection",
     return list(view.rows)
 
 
+def _group_a_daily_buckets(now_utc, *, n, display_tz):
+    """Assemble the daily panel's per-day ``BucketUsage`` list via the #268
+    Group A cache, or ``None`` to signal the caller should take the
+    from-scratch wide-fetch path (spec §5.1).
+
+    Returns a tuple of ``BucketUsage`` in ascending date order (matching
+    ``_aggregate_daily``'s sorted output), so ``build_daily_view`` consumes
+    it as ``aggregated_override`` with no reorder. Each recompute fetches a
+    ±1-day-padded window and filters ``_aggregate_daily`` to the target date,
+    so the day boundary follows ``display_tz`` exactly (DST-safe) and the
+    per-bucket first-seen model order reproduces the wide pass byte-for-byte.
+    ``None`` is returned when the cache path is disabled or the cache DB is
+    unavailable — the builder then does the original wide aggregation.
+    """
+    if not _GROUP_A_CACHE_ENABLED:
+        return None
+    try:
+        cache_conn = open_cache_db()
+    except Exception:
+        return None
+    try:
+        # The from-scratch path fetches exactly [range_start, now_utc]; the
+        # per-day fetches below clamp to the SAME window so the current day's
+        # bucket never picks up an entry after now_utc (and nothing outside
+        # the wide window leaks in) — byte-identical to the wide fetch.
+        range_start = now_utc - dt.timedelta(days=n + 1)
+        today_local = (
+            now_utc.astimezone(display_tz) if display_tz is not None
+            # internal fallback: host-local intentional
+            else now_utc.astimezone()
+        ).date()
+        # Contiguous n-day window, oldest → newest (ascending, so the
+        # assembled list matches _aggregate_daily's sorted-key order).
+        labels = [
+            (today_local - dt.timedelta(days=i)).isoformat()
+            for i in range(n - 1, -1, -1)
+        ]
+        current_label = today_local.isoformat()
+        tz_sig = display_tz.key if display_tz is not None else "local"
+
+        def _fetch(label):
+            d = dt.date.fromisoformat(label)
+            base = dt.datetime(d.year, d.month, d.day, tzinfo=dt.timezone.utc)
+            # ±1 day of slack fully covers the display-tz day for any tz
+            # offset; the aggregate filter below selects exactly the label's
+            # entries, so over-fetch is harmless and DST-robust. Clamp to the
+            # wide [range_start, now_utc] window for exact parity.
+            lo = max(base - dt.timedelta(days=1), range_start)
+            hi = min(base + dt.timedelta(days=2), now_utc)
+            if hi <= lo:
+                return []
+            return iter_entries(cache_conn, lo, hi)
+
+        def _agg_one(label, entries):
+            for b in _aggregate_daily(entries, tz=display_tz):
+                if b.bucket == label:
+                    return b
+            return None
+
+        def _end_of(label):
+            d = dt.date.fromisoformat(label)
+            # Over-estimate the day's UTC end (true end ≤ (d+1) 12:00 UTC for
+            # any tz); over-marking dirty is safe, under-marking is not.
+            return (
+                dt.datetime(d.year, d.month, d.day, tzinfo=dt.timezone.utc)
+                + dt.timedelta(days=2)
+            )
+
+        # #271: current-bucket accumulator inputs. `_membership` IS
+        # `_aggregate_daily`'s own key (display-tz `%Y-%m-%d`), so the id-bounded
+        # fetch keeps exactly the entries the full pass assigns to the current
+        # day, byte-identically. `_all_fetch`/`_delta_fetch` reuse `_fetch`'s
+        # ±1-day-padded window (clamped to now_utc) via the `(id, UsageEntry)`
+        # delta sibling.
+        def _membership(e):
+            local = (
+                e.timestamp.astimezone(display_tz) if display_tz is not None
+                # internal fallback: host-local intentional
+                else e.timestamp.astimezone()
+            )
+            return local.strftime("%Y-%m-%d") == current_label
+
+        def _current_window(label):
+            d = dt.date.fromisoformat(label)
+            base = dt.datetime(d.year, d.month, d.day, tzinfo=dt.timezone.utc)
+            lo = max(base - dt.timedelta(days=1), range_start)
+            hi = min(base + dt.timedelta(days=2), now_utc)
+            return lo, hi
+
+        def _all_fetch(label):
+            lo, hi = _current_window(label)
+            return [] if hi <= lo else iter_entries_with_id(cache_conn, lo, hi)
+
+        def _delta_fetch(label, after_seq, after_ts):
+            lo, hi = _current_window(label)
+            return [] if hi <= lo else iter_entries_with_id(
+                cache_conn, lo, hi, after_seq=after_seq, after_ts=after_ts)
+
+        buckets = build_cached_group_a(
+            "daily",
+            cache_conn=cache_conn,
+            all_bucket_labels=labels,
+            current_label=current_label,
+            bucket_end_of=_end_of,
+            fetch_bucket_entries=_fetch,
+            aggregate_one=_agg_one,
+            extra_signature=("daily", tz_sig),
+            use_current_accumulator=True,
+            now_utc=now_utc,
+            current_all_fetch=_all_fetch,
+            current_delta_fetch=_delta_fetch,
+            membership_of=_membership,
+        )
+        return tuple(buckets)
+    finally:
+        cache_conn.close()
+
+
 def _dashboard_build_daily_panel(conn: "sqlite3.Connection",
                                   now_utc: "dt.datetime",
                                   *,
                                   n: int = 30,
                                   skip_sync: bool = False,
+                                  use_group_a_cache: bool = False,
                                   display_tz: "ZoneInfo | None" = None) -> "list[DailyPanelRow]":
     """Latest n display-tz dates as DailyPanelRow, newest-first.
 
@@ -3004,11 +3740,37 @@ def _dashboard_build_daily_panel(conn: "sqlite3.Connection",
     # forgiving of tz boundary issues.
     range_start = now_utc - dt.timedelta(days=n + 1)
     range_end = now_utc
-    entries = get_entries(range_start, range_end, skip_sync=skip_sync)
+
+    # #268 Group A cache: assemble the per-day BucketUsage list through the
+    # module-level cache (recompute only the current + watermark-dirty days;
+    # serve immutable past days from memory) and hand it to build_daily_view
+    # as ``aggregated_override`` so every downstream derivation stays
+    # single-sourced. Gated on ``use_group_a_cache`` — set ONLY by the
+    # sync-thread rebuild (``_tui_build_snapshot``), which runs on a
+    # process-consistent ``now``. NOT gated on ``skip_sync``: the
+    # share-period-override path (``_share_apply_period_override``) also runs
+    # ``skip_sync=True`` but on an HTTP handler thread with a shifted (PAST)
+    # ``now_override`` — routing it through the shared module cache would clamp
+    # the now_override-current bucket to a partial aggregate and cache it under
+    # a real PAST-period label, truncating the live dashboard's past day (and
+    # would mutate the module cache unlocked, off the sync thread). So every
+    # non-sync-thread caller (default ``use_group_a_cache=False``) takes the
+    # original from-scratch wide fetch. Also falls back when the cache is
+    # disabled (parity tests) or the cache DB can't be opened.
+    aggregated_override = (
+        _group_a_daily_buckets(now_utc, n=n, display_tz=display_tz)
+        if use_group_a_cache else None
+    )
 
     c = _cctally()
-    view = c.build_daily_view(entries, now_utc=now_utc,
-                              display_tz=display_tz)
+    if aggregated_override is None:
+        entries = get_entries(range_start, range_end, skip_sync=skip_sync)
+        view = c.build_daily_view(entries, now_utc=now_utc,
+                                  display_tz=display_tz)
+    else:
+        view = c.build_daily_view((), now_utc=now_utc,
+                                  display_tz=display_tz,
+                                  aggregated_override=aggregated_override)
     if not view.rows:
         return []
 
@@ -3106,13 +3868,41 @@ def _projects_week_label(week_start: "dt.datetime") -> str:
 def _projects_iter_session_entries(conn: "sqlite3.Connection",
                                    *,
                                    since: "dt.datetime",
-                                   until: "dt.datetime"):
+                                   until: "dt.datetime",
+                                   after_seq: "int | None" = None):
     """Read ``session_entries`` joined with ``session_files`` over
     [since, until]. Yields rows directly off the passed conn — no
     cache.db monkeypatch, no production ``get_claude_session_entries``
     pipeline. The fixture DBs co-locate both schemas in one file; the
     production wiring opens both DBs and ATTACHes cache.db as a schema
     on the stats conn (see ``_run_dashboard_sync_tick``).
+
+    ``after_seq`` (#270 §8, re-key of Codex-P2b — #271 §20): when set, the
+    current-week accumulator's warm delta seeks by the **mutation_seq range**
+    (``WHERE e.mutation_seq > ?``) with the ``[since, until]`` timestamp bounds
+    applied as a residual filter. Two hints keep the planner on the
+    ``idx_entries_mutation_seq`` seek (``SEARCH e USING INDEX
+    idx_entries_mutation_seq (mutation_seq>?)``) instead of a full ``SCAN`` /
+    ``idx_entries_timestamp`` window scan (which would re-read the whole ~12K-entry
+    current week and let the ~63ms floor creep back): (1) the unary-plus no-op
+    ``+e.timestamp_utc`` deprioritizes ``idx_entries_timestamp`` (a TRUE no-op —
+    it preserves the TEXT value AND the string comparison, unlike ``+ 0``); and
+    (2) ``ORDER BY e.mutation_seq`` matches the index's leading column so the
+    planner satisfies the order from the seek itself. ``INDEXED BY`` is NOT usable
+    here — production runs this against a TEMP VIEW (``session_entries`` over the
+    ATTACHed ``cache_db.session_entries``), and a view has no indexes; the hint
+    pair drives the same seek on both the view and a base-table fixture. Unlike
+    the old ``e.id > ?`` leg (a free INTEGER PRIMARY KEY rowid range), a bare
+    ``e.mutation_seq > ?`` lets the planner fall back to a scan on a small table,
+    so the hints are load-bearing. Re-keying from ``e.id`` to ``e.mutation_seq``
+    catches an id-stable in-place finalization (it advances the seq while
+    ``MAX(id)`` stays flat, so the pre-#270 ``e.id > ?`` leg missed it); on a
+    pure-insert tick ``{mutation_seq > ?}`` == ``{id > ?}`` (seq monotone with
+    id), so the delta row SET is byte-identical. The caller (``_fetch_delta_rows``)
+    re-sorts the small result by ``(timestamp_utc, id)`` to reproduce the full
+    pass's fold order, so the ``mutation_seq``-ASC SQL order is irrelevant
+    downstream. An ``EXPLAIN QUERY PLAN`` regression asserts the mutation_seq
+    index seek (``tests/test_projects_envelope.py``).
     """
     since_iso = since.astimezone(dt.timezone.utc).strftime(
         "%Y-%m-%dT%H:%M:%SZ"
@@ -3120,27 +3910,338 @@ def _projects_iter_session_entries(conn: "sqlite3.Connection",
     until_iso = until.astimezone(dt.timezone.utc).strftime(
         "%Y-%m-%dT%H:%M:%SZ"
     )
-    cur = conn.execute(
-        "SELECT e.id, e.timestamp_utc, e.model, e.input_tokens, "
-        "       e.output_tokens, e.cache_create_tokens, e.cache_read_tokens, "
-        "       e.cost_usd_raw, e.source_path, "
-        "       sf.session_id, sf.project_path "
-        "FROM session_entries e "
-        "LEFT JOIN session_files sf ON sf.path = e.source_path "
-        "WHERE e.timestamp_utc >= ? AND e.timestamp_utc <= ? "
-        "ORDER BY e.timestamp_utc ASC, e.id ASC",
-        (since_iso, until_iso),
-    )
+    if after_seq is not None:
+        cur = conn.execute(
+            "SELECT e.id, e.timestamp_utc, e.model, e.input_tokens, "
+            "       e.output_tokens, e.cache_create_tokens, e.cache_read_tokens, "
+            "       e.cost_usd_raw, e.source_path, "
+            "       sf.session_id, sf.project_path "
+            "FROM session_entries e "
+            "LEFT JOIN session_files sf ON sf.path = e.source_path "
+            "WHERE e.mutation_seq > ? AND +e.timestamp_utc >= ? AND +e.timestamp_utc <= ? "
+            "ORDER BY e.mutation_seq ASC",
+            (after_seq, since_iso, until_iso),
+        )
+    else:
+        cur = conn.execute(
+            "SELECT e.id, e.timestamp_utc, e.model, e.input_tokens, "
+            "       e.output_tokens, e.cache_create_tokens, e.cache_read_tokens, "
+            "       e.cost_usd_raw, e.source_path, "
+            "       sf.session_id, sf.project_path "
+            "FROM session_entries e "
+            "LEFT JOIN session_files sf ON sf.path = e.source_path "
+            "WHERE e.timestamp_utc >= ? AND e.timestamp_utc <= ? "
+            "ORDER BY e.timestamp_utc ASC, e.id ASC",
+            (since_iso, until_iso),
+        )
     for row in cur:
         yield row
 
 
+class _ProjWeekBucket(NamedTuple):
+    """One (bucket_path, week) immutable aggregate for the projects-envelope
+    per-week cache (#269 §14 Win 2).
+
+    All fields are entry-local — each entry belongs to exactly one bucket and
+    one week — so a CLOSED week's values are stable and reproduce the
+    full-window walk's contribution for that week byte-for-byte.
+
+    ``first_seen`` / ``last_seen`` are the min / max PARSED event datetimes
+    (emitted via ``_iso_z``). ``first_order`` / ``first_id`` / ``first_key`` are
+    the SQL-FIRST entry for this bucket in this week (first-encountered under
+    ``ORDER BY timestamp_utc ASC, id ASC``): ``first_order`` is the RAW
+    ``timestamp_utc`` string, so the ``key_by_bucket`` reconstruction argmin
+    reproduces the from-scratch global first-seen exactly (Codex-M4 P1 — the
+    no-git ``display_key`` makes ``key_by_bucket[bp]`` non-deterministic per
+    bucket_path; the envelope picks by global first-seen order).
+    """
+    cost_usd: float
+    sessions_count: int
+    first_seen: "dt.datetime"
+    last_seen: "dt.datetime"
+    first_order: str
+    first_id: int
+    first_key: "Any"
+
+
+def _fold_projects_entry(
+    mut: dict,
+    row: tuple,
+    *,
+    resolver_cache: dict,
+    week_start: "dt.datetime",
+) -> "float | None":
+    """Fold ONE ``_projects_iter_session_entries`` row onto ``mut`` (the shared
+    per-row body, #271 §20 Codex-P1a).
+
+    Used by BOTH the full-window cold fold (``_aggregate_projects_week_raw``)
+    and the current-week accumulator's warm incremental append, so their
+    per-bucket cost sums, session sets, and first/last-seen captures are
+    byte-identical BY CONSTRUCTION. Returns the entry cost, or ``None`` when the
+    row is filtered out (``<synthetic>`` model, or its Monday-anchored week ≠
+    ``week_start``) — the caller then skips ``week_total`` / ``tail`` advance.
+
+    ``mut[bp]`` is the running mutable dict ``{"cost_usd": float,
+    "sessions": set, "first_seen": dt, "last_seen": dt, "first_order": ts_iso,
+    "first_id": int, "first_key": ProjectKey}``. The first row seen for a
+    ``bucket_path`` captures ``first_order`` / ``first_id`` / ``first_key`` —
+    order-safe for the warm append because every delta row sorts strictly after
+    ``tail`` (#271 §20), so a delta row is never the first-seen of a bucket that
+    already exists in ``mut``.
+    """
+    c = _cctally()
+    (entry_id, ts_iso, model, input_tok, output_tok,
+     cache_create, cache_read, cost_raw, source_path,
+     session_id, project_path) = row
+    if model == "<synthetic>":
+        return None
+    ts = parse_iso_datetime(ts_iso, "session_entries.timestamp_utc")
+    if _projects_week_start_monday_utc(ts) != week_start:
+        return None
+    entry_cost = _calculate_entry_cost(
+        model,
+        {
+            "input_tokens": input_tok or 0,
+            "output_tokens": output_tok or 0,
+            "cache_creation_input_tokens": cache_create or 0,
+            "cache_read_input_tokens": cache_read or 0,
+        },
+        mode="auto",
+        cost_usd=cost_raw,
+    )
+    pkey = c._resolve_project_key(project_path, "git-root", resolver_cache)
+    bp = pkey.bucket_path
+    a = mut.get(bp)
+    if a is None:
+        a = {
+            "cost_usd": 0.0,
+            "sessions": set(),
+            "first_seen": ts,
+            "last_seen": ts,
+            "first_order": ts_iso,
+            "first_id": entry_id,
+            "first_key": pkey,
+        }
+        mut[bp] = a
+    a["cost_usd"] += entry_cost
+    if session_id:
+        a["sessions"].add(session_id)
+    elif source_path:
+        a["sessions"].add(source_path)
+    if ts < a["first_seen"]:
+        a["first_seen"] = ts
+    if ts > a["last_seen"]:
+        a["last_seen"] = ts
+    return entry_cost
+
+
+def _aggregate_projects_week_raw(
+    conn: "sqlite3.Connection",
+    *,
+    week_start: "dt.datetime",
+    week_end: "dt.datetime",
+    resolver_cache: dict,
+) -> "tuple[dict, float, tuple | None]":
+    """Full-window fold for one Monday-anchored subscription week, returning the
+    RAW mutable ``mut`` (sessions kept as SETS, so the current-week accumulator
+    can dedup across ticks), the entry-order ``week_total`` float, and the
+    ``tail`` ``(ts_iso, id)`` of the last folded CURRENT-WEEK entry (``None``
+    when no row folded).
+
+    Shared by the finalizing ``_aggregate_projects_week`` wrapper (closed-week
+    cache path) and the current-week accumulator's cold seed (#271 §20
+    Codex-P1a — the finalized public shape discards the sessions SET into a
+    count, so cold seeding needs the raw ``mut``). Byte-identical to the
+    original single-loop aggregate: same ``timestamp_utc ASC, id ASC`` order,
+    same per-row ``_fold_projects_entry`` arithmetic, same entry-order
+    ``week_total`` left-fold.
+    """
+    mut: "dict[str, dict]" = {}
+    week_total = 0.0
+    tail: "tuple | None" = None
+    for row in _projects_iter_session_entries(
+        conn, since=week_start, until=week_end,
+    ):
+        entry_cost = _fold_projects_entry(
+            mut, row, resolver_cache=resolver_cache, week_start=week_start,
+        )
+        if entry_cost is None:
+            continue
+        week_total += entry_cost
+        tail = (row[1], row[0])  # (ts_iso, id)
+    return mut, week_total, tail
+
+
+def _finalize_projects_mut(mut: dict) -> "dict[str, _ProjWeekBucket]":
+    """Finalize a raw ``mut`` (sessions SETS) into ``{bucket_path:
+    _ProjWeekBucket}`` — ``sessions_count = len(sessions)``, the rest copied
+    through. The public shape both the closed-week cache and the current-week
+    accumulator return (#271 §20).
+    """
+    return {
+        bp: _ProjWeekBucket(
+            cost_usd=a["cost_usd"],
+            sessions_count=len(a["sessions"]),
+            first_seen=a["first_seen"],
+            last_seen=a["last_seen"],
+            first_order=a["first_order"],
+            first_id=a["first_id"],
+            first_key=a["first_key"],
+        )
+        for bp, a in mut.items()
+    }
+
+
+def _aggregate_projects_week(
+    conn: "sqlite3.Connection",
+    *,
+    week_start: "dt.datetime",
+    week_end: "dt.datetime",
+    resolver_cache: dict,
+) -> "tuple[dict[str, _ProjWeekBucket], float]":
+    """Aggregate one Monday-anchored subscription week's entry slice.
+
+    Returns ``({bucket_path: _ProjWeekBucket}, week_total_cost)``. Byte-identical
+    to the contribution the full-window walk in ``_build_projects_envelope``
+    makes for this week: the per-week query returns entries in the same
+    ``timestamp_utc ASC, id ASC`` order, filtered to those whose
+    Monday-anchored week equals ``week_start``, so the per-bucket cost sum, the
+    entry-order ``week_total`` sum, the session set, and the first/last-seen +
+    SQL-first-entry captures all reproduce the full pass. ``week_end`` is the
+    inclusive query bound (``<= ?``); the exact next-Monday boundary entry is
+    fetched but filtered out (it belongs to the next week) — the next week's
+    slice keeps it, so no entry is lost or double-counted.
+
+    Thin wrapper over ``_aggregate_projects_week_raw`` + ``_finalize_projects_mut``
+    (#271 §20 Codex-P1a); the public shape is unchanged for the closed-week
+    cache path.
+    """
+    mut, week_total, _tail = _aggregate_projects_week_raw(
+        conn, week_start=week_start, week_end=week_end,
+        resolver_cache=resolver_cache,
+    )
+    return _finalize_projects_mut(mut), week_total
+
+
+def _assemble_projects_via_cache(
+    conn: "sqlite3.Connection",
+    *,
+    weeks_full: "list[dt.datetime]",
+    cw_start: "dt.datetime",
+    cw_end: "dt.datetime",
+    cur_max_id: int,
+    cur_max_seq: int,
+) -> "tuple[dict, dict, dict]":
+    """Flag-ON assembly (#269 §14 Win 2): recompute only the CURRENT week each
+    warm tick; serve CLOSED weeks from the per-(project, week) cache on a hit and
+    RECOMPUTE-AND-POPULATE on a miss (cold / Monday rollover / window slide,
+    Codex-M4 P2). Returns ``(buckets, total_cost_by_week, key_by_bucket)`` in the
+    exact shape the from-scratch walk produces, so the downstream disambiguation
+    / attribution / trend assembly runs unchanged and byte-identically.
+
+    #271 M4 (spec §20): the CURRENT week is no longer re-folded from scratch each
+    warm tick — it goes through the single-slot ``accumulate_projects_current_week``
+    accumulator, which folds only the changed-row delta (or finalizes the cached
+    running ``mut`` unchanged on an empty-delta tick), byte-identically.
+    ``cur_max_id`` is the tick's ``MAX(session_entries.id)`` (the regression
+    backstop + pre-existing-row cold-refold trigger); ``cur_max_seq`` is the
+    tick's ``MAX(mutation_seq)`` (the #270 §8 delta watermark, so an id-stable
+    in-place finalization is caught). The accumulator is single-writer here (this
+    runs only on the sync-thread ``use_projects_env_cache=True`` path).
+    """
+    c = _cctally()
+    sc = c._load_sibling("_lib_snapshot_cache")
+    resolver_cache: dict = {}
+    buckets: dict = {}
+    total_cost_by_week: dict = {}
+    key_by_bucket: dict = {}
+    # Reconstruct key_by_bucket by the GLOBAL first-seen SQL order
+    # (timestamp_utc ASC, id ASC): per bucket_path, the argmin of
+    # (first_order, first_id) across its assembled weeks (Codex-M4 P1).
+    best_order: dict = {}
+
+    def _merge_week(w, week_buckets, week_total):
+        # `total_cost_by_week` mirrors the from-scratch dict, which is only
+        # populated for weeks that had entries (an empty week stays absent and
+        # falls back to `.get(w, 0.0)` downstream).
+        if week_buckets:
+            total_cost_by_week[w] = week_total
+        for bp, wb in week_buckets.items():
+            buckets[(bp, w)] = {
+                "cost_usd": wb.cost_usd,
+                # `sessions` is only ever `len()`-d downstream; a `range` of the
+                # cached count reproduces that without storing the id set.
+                "sessions": range(wb.sessions_count),
+                "first_seen": wb.first_seen,
+                "last_seen": wb.last_seen,
+            }
+            cand = (wb.first_order, wb.first_id)
+            if bp not in best_order or cand < best_order[bp]:
+                best_order[bp] = cand
+                key_by_bucket[bp] = wb.first_key
+
+    def _fetch_all_raw():
+        return _aggregate_projects_week_raw(
+            conn, week_start=cw_start, week_end=cw_end,
+            resolver_cache=resolver_cache,
+        )
+
+    def _fetch_delta_rows(after_seq):
+        # Index-seek the changed-row delta (mutation_seq > after_seq, #270 §8)
+        # over the current-week window, then PRE-FILTER to genuine current-week
+        # non-synthetic rows (mirrors _fold_projects_entry's membership filter) so
+        # the accumulator's fold-order gate compares a REAL current-week entry as
+        # rows[0]. Sort by (ts_iso, id) to reproduce the full pass's fold order
+        # exactly (SQLite BINARY collation on the Z-normalized ISO string ==
+        # Python str compare).
+        out = []
+        for r in _projects_iter_session_entries(
+            conn, since=cw_start, until=cw_end, after_seq=after_seq,
+        ):
+            if r[2] == "<synthetic>":  # r[2] = model
+                continue
+            ts = parse_iso_datetime(r[1], "session_entries.timestamp_utc")
+            if _projects_week_start_monday_utc(ts) != cw_start:
+                continue
+            out.append(r)
+        out.sort(key=lambda r: (r[1], r[0]))  # (ts_iso, id)
+        return out
+
+    for w in weeks_full:
+        if w == cw_start:
+            week_buckets, week_total = sc.accumulate_projects_current_week(
+                week_key=sc.projects_env_week_key(cw_start),
+                cur_max_id=cur_max_id,
+                cur_max_seq=cur_max_seq,
+                fetch_all_raw=_fetch_all_raw,
+                fetch_delta_rows=_fetch_delta_rows,
+                finalize=_finalize_projects_mut,
+                fold=lambda mut, row: _fold_projects_entry(
+                    mut, row, resolver_cache=resolver_cache, week_start=cw_start,
+                ),
+            )
+        else:
+            week_iso = sc.projects_env_week_key(w)
+            hit = sc.projects_env_week_get(week_iso)
+            if hit is not None:
+                week_buckets, week_total = hit
+            else:
+                week_buckets, week_total = _aggregate_projects_week(
+                    conn, week_start=w, week_end=w + dt.timedelta(days=7),
+                    resolver_cache=resolver_cache,
+                )
+                sc.projects_env_week_put(week_iso, week_buckets, week_total)
+        _merge_week(w, week_buckets, week_total)
+    return buckets, total_cost_by_week, key_by_bucket
+
+
 def _build_projects_envelope(
     conn: "sqlite3.Connection",
     *,
     now_utc: "dt.datetime",
     current_week: "Any | None" = None,
     weeks_back: int = 12,
+    use_projects_env_cache: bool = False,
 ) -> dict:
     """Build the ``projects.{current_week, trend}`` envelope block.
 
@@ -3161,7 +4262,9 @@ def _build_projects_envelope(
 
     Determinism: same conn + same ``now_utc`` ⇒ byte-identical JSON
     (R-PROJ5 invariant). Per-tick memoized on
-    ``(max(session_entries.id), cw_week_start, weeks_back)``.
+    ``(max(session_entries.id), max_wus_id, max(mutation_seq), cw_week_start,
+    weeks_back)`` — the ``mutation_seq`` leg (#270 §7d) busts the memo on an
+    id-stable in-place finalization.
     """
     c = _cctally()
 
@@ -3181,10 +4284,30 @@ def _build_projects_envelope(
         max_wus_id = cur.fetchone()[0]
     except sqlite3.OperationalError:
         max_wus_id = 0
+    # #270 (§7d, Codex-2b): this OUTER whole-envelope memo returns BEFORE the
+    # inner per-(project, week) reconcile cache, so an id-stable in-place
+    # finalization — which leaves MAX(id)/MAX(wus id) flat — would serve the
+    # stale envelope regardless of the inner seq fix. Fold the mutation signal
+    # into the memo key so it busts on any changed row. `MAX(mutation_seq)` is
+    # read off the SAME `session_entries` surface as `max_id` (an id-stable
+    # UPSERT advances it), index-backed by `idx_entries_mutation_seq`, and
+    # degrades to 0 where the column is absent (old fixtures) — byte-identical.
+    # Deliberately `MAX(mutation_seq)`, NOT the `cache_meta` counter the reconciles
+    # read via `_entry_mutation_seq` (this conn is a project-detail view without a
+    # `cache_meta` surface). The two are consistent — the counter is always
+    # >= MAX(mutation_seq), and no row exists strictly between them at read time —
+    # so do not "unify" them here (the divergence is intentional; see #270 §M3-1).
+    try:
+        cur = conn.execute(
+            "SELECT COALESCE(MAX(mutation_seq), 0) FROM session_entries"
+        )
+        entry_mutation_seq = cur.fetchone()[0]
+    except sqlite3.OperationalError:
+        entry_mutation_seq = 0
     cw_key: "dt.datetime | None" = None
     if current_week is not None:
         cw_key = getattr(current_week, "week_start_at", None)
-    memo_key = (max_id, max_wus_id, cw_key, weeks_back)
+    memo_key = (max_id, max_wus_id, entry_mutation_seq, cw_key, weeks_back)
     cached = _PROJECTS_ENV_MEMO.get("value")
     if cached is not None and _PROJECTS_ENV_MEMO.get("key") == memo_key:
         return cached
@@ -3220,95 +4343,106 @@ def _build_projects_envelope(
     until_dt = cw_end  # exclusive end; SQL is `>= since AND <= until`
 
     # ---- Bucket entries per (ProjectKey, week_start) --------------------
-    # `_resolve_project_key` is the production resolver; we use git-root
-    # mode (default for `cmd_project --group` absent) — matches the
-    # CLI's default.
-    _resolve_project_key = c._resolve_project_key
-    resolver_cache: dict = {}
-
-    # buckets[(bucket_path, week_start)] -> {key, cost, sessions, ...}
-    buckets: dict[tuple[str, dt.datetime], dict] = {}
-    # Track total cost per week across ALL entries (attribution denominator).
-    total_cost_by_week: dict[dt.datetime, float] = {}
-    # Track first-seen ProjectKey instance per bucket_path so we can pass
-    # the dict to `_project_disambiguate_labels` (which keys on `key.bucket_path`
-    # equality via ProjectKey.__eq__).
-    key_by_bucket: dict[str, Any] = {}
-
-    def _week_for(ts: dt.datetime) -> "dt.datetime | None":
-        wstart = _projects_week_start_monday_utc(ts)
-        if wstart < weeks_full[0] or wstart > weeks_full[-1]:
-            return None
-        return wstart
-
-    # Orphan handling: `_projects_iter_session_entries` LEFT JOINs
-    # `session_files` so entries whose source_path has no
-    # `session_files` row return `project_path = NULL`. Below,
-    # `_resolve_project_key(None, ...)` maps that to the
-    # `(unknown)` bucket — same identity the drill-down's explicit
-    # orphan scan in `_project_detail_for_window` (see the
-    # ``if unknown_bucket:`` branch around the
-    # `orphan_cur` SELECT) collects via a NULL-side LEFT JOIN. The
-    # two paths converge on the same `(unknown)` source_path set.
-    for row in _projects_iter_session_entries(
-        conn, since=since_dt, until=until_dt,
-    ):
-        (entry_id, ts_iso, model, input_tok, output_tok,
-         cache_create, cache_read, cost_raw, source_path,
-         session_id, project_path) = row
-        if model == "<synthetic>":
-            continue
-        # Parse timestamp; assume Z / +00:00 — production iterators do
-        # the same via `parse_iso_datetime`.
-        ts = parse_iso_datetime(ts_iso, "session_entries.timestamp_utc")
-        wstart = _week_for(ts)
-        if wstart is None:
-            continue
-
-        # Entry cost via the shared pricing chokepoint.
-        entry_cost = _calculate_entry_cost(
-            model,
-            {
-                "input_tokens": input_tok or 0,
-                "output_tokens": output_tok or 0,
-                "cache_creation_input_tokens": cache_create or 0,
-                "cache_read_input_tokens": cache_read or 0,
-            },
-            mode="auto",
-            cost_usd=cost_raw,
+    # The three structures the downstream disambiguation / attribution /
+    # trend assembly consume:
+    #   buckets[(bucket_path, week_start)] -> {cost_usd, sessions, first/last_seen}
+    #   total_cost_by_week[week_start]     -> attribution denominator
+    #   key_by_bucket[bucket_path]         -> global first-seen ProjectKey
+    # Flag ON (#269 §14 Win 2, sync-thread only): the CURRENT week is recomputed
+    # fresh each warm tick; CLOSED weeks are served from the per-(project, week)
+    # cache (hit) or recomputed-and-populated (miss). Flag OFF (CLI / tests /
+    # HTTP-drill): the original single full-window walk, byte-unchanged.
+    if use_projects_env_cache:
+        buckets, total_cost_by_week, key_by_bucket = _assemble_projects_via_cache(
+            conn, weeks_full=weeks_full, cw_start=cw_start, cw_end=cw_end,
+            cur_max_id=max_id, cur_max_seq=entry_mutation_seq,
         )
+    else:
+        # `_resolve_project_key` is the production resolver; we use git-root
+        # mode (default for `cmd_project --group` absent) — matches the
+        # CLI's default.
+        _resolve_project_key = c._resolve_project_key
+        resolver_cache: dict = {}
+
+        buckets = {}
+        total_cost_by_week = {}
+        # First-seen ProjectKey per bucket_path (feeds `_project_disambiguate_labels`).
+        key_by_bucket = {}
+
+        def _week_for(ts: dt.datetime) -> "dt.datetime | None":
+            wstart = _projects_week_start_monday_utc(ts)
+            if wstart < weeks_full[0] or wstart > weeks_full[-1]:
+                return None
+            return wstart
+
+        # Orphan handling: `_projects_iter_session_entries` LEFT JOINs
+        # `session_files` so entries whose source_path has no
+        # `session_files` row return `project_path = NULL`. Below,
+        # `_resolve_project_key(None, ...)` maps that to the
+        # `(unknown)` bucket — same identity the drill-down's explicit
+        # orphan scan in `_project_detail_for_window` (see the
+        # ``if unknown_bucket:`` branch around the
+        # `orphan_cur` SELECT) collects via a NULL-side LEFT JOIN. The
+        # two paths converge on the same `(unknown)` source_path set.
+        for row in _projects_iter_session_entries(
+            conn, since=since_dt, until=until_dt,
+        ):
+            (entry_id, ts_iso, model, input_tok, output_tok,
+             cache_create, cache_read, cost_raw, source_path,
+             session_id, project_path) = row
+            if model == "<synthetic>":
+                continue
+            # Parse timestamp; assume Z / +00:00 — production iterators do
+            # the same via `parse_iso_datetime`.
+            ts = parse_iso_datetime(ts_iso, "session_entries.timestamp_utc")
+            wstart = _week_for(ts)
+            if wstart is None:
+                continue
 
-        # Project-key identity (`git_root` mode = production default).
-        pkey = _resolve_project_key(project_path, "git-root", resolver_cache)
-        bkey = (pkey.bucket_path, wstart)
-        b = buckets.get(bkey)
-        if b is None:
-            b = {
-                "key": pkey,
-                "cost_usd": 0.0,
-                "sessions": set(),
-                "first_seen": ts,
-                "last_seen": ts,
-            }
-            buckets[bkey] = b
-        b["cost_usd"] += entry_cost
-        if session_id:
-            b["sessions"].add(session_id)
-        elif source_path:
-            # Fallback: treat one source_path as one session when
-            # session_files.session_id is NULL (lazy population).
-            b["sessions"].add(source_path)
-        if ts < b["first_seen"]:
-            b["first_seen"] = ts
-        if ts > b["last_seen"]:
-            b["last_seen"] = ts
-        total_cost_by_week[wstart] = (
-            total_cost_by_week.get(wstart, 0.0) + entry_cost
-        )
-        # Remember first-seen ProjectKey for each bucket_path so the
-        # disambiguator pass below sees consistent ProjectKey instances.
-        if pkey.bucket_path not in key_by_bucket:
-            key_by_bucket[pkey.bucket_path] = pkey
+            # Entry cost via the shared pricing chokepoint.
+            entry_cost = _calculate_entry_cost(
+                model,
+                {
+                    "input_tokens": input_tok or 0,
+                    "output_tokens": output_tok or 0,
+                    "cache_creation_input_tokens": cache_create or 0,
+                    "cache_read_input_tokens": cache_read or 0,
+                },
+                mode="auto",
+                cost_usd=cost_raw,
+            )
+
+            # Project-key identity (`git_root` mode = production default).
+            pkey = _resolve_project_key(project_path, "git-root", resolver_cache)
+            bkey = (pkey.bucket_path, wstart)
+            b = buckets.get(bkey)
+            if b is None:
+                b = {
+                    "key": pkey,
+                    "cost_usd": 0.0,
+                    "sessions": set(),
+                    "first_seen": ts,
+                    "last_seen": ts,
+                }
+                buckets[bkey] = b
+            b["cost_usd"] += entry_cost
+            if session_id:
+                b["sessions"].add(session_id)
+            elif source_path:
+                # Fallback: treat one source_path as one session when
+                # session_files.session_id is NULL (lazy population).
+                b["sessions"].add(source_path)
+            if ts < b["first_seen"]:
+                b["first_seen"] = ts
+            if ts > b["last_seen"]:
+                b["last_seen"] = ts
+            total_cost_by_week[wstart] = (
+                total_cost_by_week.get(wstart, 0.0) + entry_cost
+            )
+            # Remember first-seen ProjectKey for each bucket_path so the
+            # disambiguator pass below sees consistent ProjectKey instances.
+            if pkey.bucket_path not in key_by_bucket:
+                key_by_bucket[pkey.bucket_path] = pkey
 
     # ---- Load weekly_usage_snapshots for attribution --------------------
     # weekly_percent keyed by week_start (UTC datetime, Monday). We
@@ -4495,6 +5629,28 @@ def _build_alerts_envelope_array(
     return out[:limit]
 
 
+def _resolve_dashboard_port(port_arg):
+    """Effective dashboard port: an explicit --port always wins; otherwise
+    8790 under the preview channel (CCTALLY_CHANNEL=preview), else 8789.
+    Byte-stable when the marker is unset because any explicit port (incl. 0)
+    short-circuits before the env check — the golden harness passes --port 0,
+    so the port default is never exercised there."""
+    if port_arg is not None:
+        return port_arg
+    if _cctally_core.is_preview_channel():
+        return 8790
+    return 8789
+
+
+def _channel_env_fragment() -> dict:
+    """`{'channel': 'preview'}` under the preview channel, else `{}` — so the
+    envelope key is omitted when the marker is unset (additive-optional, keeps
+    the dashboard goldens byte-identical). Spliced into the envelope via `**`."""
+    if _cctally_core.is_preview_channel():
+        return {"channel": "preview"}
+    return {}
+
+
 def snapshot_to_envelope(snap: "DataSnapshot", *,
                          now_utc: "dt.datetime",
                          monotonic_now: "float | None" = None,
@@ -4590,8 +5746,16 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     # process. The override flows in as a canonical tz token; we layer it
     # onto the config dict via _apply_display_tz_override before resolving
     # so every reader downstream sees one zone.
+    # #268 M4: read the config + update-state + doctor from the sync-thread
+    # precompute (spec §6) so this stays a PURE renderer — no config.json read,
+    # no `security` fork, no update-state file read per SSE client per tick.
+    # When the fields are absent (fixtures / the initial empty snapshot /
+    # positionally-constructed DataSnapshots) fall back to the inline reads so
+    # behavior is byte-identical for those callers.
+    _precomp = getattr(snap, "envelope_precompute", None)
+    _raw_config = _precomp["config"] if _precomp is not None else load_config()
     config = _apply_display_tz_override(
-        load_config(), display_tz_pref_override
+        _raw_config, display_tz_pref_override
     )
     display_block = _compute_display_block(config, snap.generated_at)
     resolved_tz_obj = ZoneInfo(display_block["resolved_tz"])
@@ -4866,7 +6030,11 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     # the entire snapshot — fall back to safe defaults and rely on
     # `_warn_alerts_bad_config_once` for the user-visible signal.
     alerts_array = list(getattr(snap, "alerts", []) or [])
-    _cfg_for_alerts = load_config()
+    # #268 M4: reuse the precompute's config (or the fallback load_config()
+    # resolved above) — the envelope used to call load_config() a SECOND time
+    # here. Within one tick both reads returned the same file, so this is
+    # byte-identical.
+    _cfg_for_alerts = _raw_config
     try:
         _alerts_cfg = _get_alerts_config(_cfg_for_alerts)
     except _AlertsConfigError as exc:
@@ -4955,19 +6123,30 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     # produce a `null` block so a missing/corrupt state file doesn't
     # 500 the entire envelope; the client falls back to the defensive
     # null-state shape `coerceUpdateState` already understands.
-    try:
-        _update_state_envelope = _load_update_state()
-    except sys.modules["cctally"].UpdateError:
-        # _load_update_state() raises on truly malformed JSON. Surface
-        # an _error sentinel so the client renders "no update info" the
-        # same way it does for unreachable /api/update/status.
-        _update_state_envelope = {"_error": "update-state.json invalid"}
-    except Exception:
-        _update_state_envelope = {"_error": "update-state.json read failed"}
-    try:
-        _update_suppress_envelope = _load_update_suppress()
-    except Exception:
-        _update_suppress_envelope = {"skipped_versions": [], "remind_after": None}
+    #
+    # #268 M4: read from the sync-thread precompute (spec §6) when present so
+    # this stays pure — no update-state file reads per SSE client. The inline
+    # try/except is the fallback for fixtures / the initial snapshot, and keeps
+    # the SAME error sentinels so the derived block is byte-identical.
+    if _precomp is not None:
+        _update_state_envelope = _precomp["update_state"]
+        _update_suppress_envelope = _precomp["update_suppress"]
+    else:
+        try:
+            _update_state_envelope = _load_update_state()
+        except sys.modules["cctally"].UpdateError:
+            # _load_update_state() raises on truly malformed JSON. Surface
+            # an _error sentinel so the client renders "no update info" the
+            # same way it does for unreachable /api/update/status.
+            _update_state_envelope = {"_error": "update-state.json invalid"}
+        except Exception:
+            _update_state_envelope = {"_error": "update-state.json read failed"}
+        try:
+            _update_suppress_envelope = _load_update_suppress()
+        except Exception:
+            _update_suppress_envelope = {
+                "skipped_versions": [], "remind_after": None,
+            }
     update_envelope = {
         "state":    _update_state_envelope,
         "suppress": _update_suppress_envelope,
@@ -4980,24 +6159,37 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     # `safety.dashboard_bind` reflects the running state, not just
     # `config.json`. Defensive: never crash the snapshot pipeline on
     # a doctor failure — surface a synthetic FAIL block with `_error`.
-    try:
-        _ld = sys.modules["cctally"]._load_sibling("_lib_doctor")
-        _doc_state = doctor_gather_state(now_utc=now_utc, runtime_bind=runtime_bind)
-        _doc_report = _ld.run_checks(_doc_state)
-        doctor_envelope: "dict" = {
-            "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 SSE on doctor failure
-        doctor_envelope = {
-            "severity":     "fail",
-            "counts":       {"ok": 0, "warn": 0, "fail": 1},
-            "generated_at": _iso_z(now_utc),
-            "fingerprint":  "sha1:" + ("0" * 40),
-            "_error":       f"{type(exc).__name__}: {exc}",
-        }
+    #
+    # #268 M4: read the precomputed doctor block from the snapshot (spec §6)
+    # so this render path never forks the `security` keychain subprocess. The
+    # sync thread computes it ONCE per rebuild via `doctor_payload_memo`
+    # (`_tui_precompute_doctor_payload`). The inline try/except below is the
+    # fallback for fixtures / the initial snapshot / positionally-constructed
+    # DataSnapshots (`doctor_payload=None`) and produces the SAME block, so
+    # moving the computation is byte-identical. The lazy `GET /api/doctor`
+    # endpoint keeps computing LIVE (an explicit user refresh must be fresh).
+    _doctor_payload = getattr(snap, "doctor_payload", None)
+    if _doctor_payload is not None:
+        doctor_envelope: "dict" = _doctor_payload
+    else:
+        try:
+            _ld = sys.modules["cctally"]._load_sibling("_lib_doctor")
+            _doc_state = doctor_gather_state(now_utc=now_utc, runtime_bind=runtime_bind)
+            _doc_report = _ld.run_checks(_doc_state)
+            doctor_envelope = {
+                "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 SSE on doctor failure
+            doctor_envelope = {
+                "severity":     "fail",
+                "counts":       {"ok": 0, "warn": 0, "fail": 1},
+                "generated_at": _iso_z(now_utc),
+                "fingerprint":  "sha1:" + ("0" * 40),
+                "_error":       f"{type(exc).__name__}: {exc}",
+            }
 
     # B1 (#207): the "vs last week" header delta reuses the is_current trend
     # row's delta_dpp ($/1% vs the previous trend row — normally the prior
@@ -5235,6 +6427,12 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         # Doctor aggregate-only block (spec §5.5). Full per-check
         # report fetched lazily via GET /api/doctor.
         "doctor":           doctor_envelope,
+
+        # Preview channel (CCTALLY_CHANNEL=preview): additive-optional
+        # `channel` key. Omitted when the marker is unset so prod payloads
+        # (and the dashboard goldens) stay byte-identical; feeds the header
+        # PREVIEW badge when set.
+        **_channel_env_fragment(),
     }
 
 
@@ -8637,6 +9835,13 @@ def _dashboard_initial_snapshot(args, *, pinned_now, display_tz_pref_override):
     return sys.modules["cctally"]._tui_build_snapshot(
         now_utc=pinned_now, skip_sync=True,
         display_tz_pref_override=display_tz_pref_override,
+        # #268 M4: precompute doctor / config / update-state on the initial
+        # snapshot too, so the envelope is pure from the very first paint AND
+        # under --no-sync (where no later sync tick would set them). One
+        # `security` fork here is negligible next to the heavy sync #179 moved
+        # to the background thread. ``getattr`` so minimal test ``args``
+        # namespaces (no ``host``) still build an initial snapshot.
+        precompute_envelope=True, runtime_bind=getattr(args, "host", None),
     )
 
 
@@ -8647,6 +9852,11 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     import time as _time
     import webbrowser as _wb
 
+    # #268 M6.1: arm the SIGUSR1 all-thread traceback dump so any future spin is
+    # self-diagnosing (`kill -USR1 <pid>`) without root py-spy. No-op where
+    # SIGUSR1 is unavailable (Windows).
+    _register_faulthandler_sigusr1()
+
     # Spec §5.7: capture the un-mutated argv + PATH-resolved entrypoint
     # at boot so the in-place ``execvp`` after a successful update
     # re-enters the user-facing wrapper (npm Node shim → CCTALLY_PYTHON
@@ -8723,6 +9933,15 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     # _DashboardSyncThread (started below, before the bind) owns the first full
     # sync_cache — including any pending conversation-enrichment reingest — and
     # SSE-pushes the populated snapshot on completion.
+    # Self-heal removed-worktree orphans BEFORE building the first snapshot so
+    # the initial render already excludes stale sessions from a deleted
+    # worktree (rather than showing them until the first periodic tick).
+    # Gated off under --no-sync (a frozen dashboard mutates nothing).
+    _heal = _dashboard_self_heal_orphans(skip_sync=bool(args.no_sync))
+    if _heal is not None and _heal.pruned_files:
+        print(f"dashboard: pruned {_heal.pruned_files} orphaned cache file(s) "
+              f"from removed sessions on startup", flush=True)
+
     initial = _dashboard_initial_snapshot(
         args, pinned_now=pinned_now,
         display_tz_pref_override=display_tz_pref_override,
@@ -8755,6 +9974,10 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     _run_sync_now_locked = _make_run_sync_now_locked(
         ref=ref, hub=hub, pinned_now=pinned_now,
         display_tz_pref_override=display_tz_pref_override,
+        # #268 M4: the dashboard's bound host, threaded into the sync-thread
+        # doctor precompute so `safety.dashboard_bind` reflects the running
+        # bind and the envelope reads the precomputed doctor block.
+        runtime_bind=args.host,
     )
     _run_sync_now = _make_run_sync_now(
         sync_lock=sync_lock, ref=ref, hub=hub, pinned_now=pinned_now,
@@ -8797,8 +10020,17 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
 
     class _DashboardSyncThread(_c_for_subclass._TuiSyncThread):
         def _run(self) -> None:
+            last_heal = _time.monotonic()
             while not self._stop.is_set():
                 _run_sync_now(skip_sync=self._skip_sync)
+                # Self-heal removed-worktree orphans on a ~60s cadence (far
+                # rarer than the sync tick — a deleted worktree is not urgent).
+                # Non-blocking on the flock, so a contended tick just retries
+                # next cadence; gated off under --no-sync.
+                if (not self._skip_sync
+                        and _time.monotonic() - last_heal >= 60.0):
+                    last_heal = _time.monotonic()
+                    _dashboard_self_heal_orphans(skip_sync=self._skip_sync)
                 for _ in range(int(max(1, self._interval * 10))):
                     if self._stop.is_set():
                         return
@@ -8828,7 +10060,8 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     # HTTP server on its own thread so the main thread can block on signal.
     # `_QuietThreadingHTTPServer` folds in `daemon_threads = True` and silences
     # client-disconnect tracebacks (spec §5).
-    srv = _QuietThreadingHTTPServer((args.host, args.port), DashboardHTTPHandler)
+    resolved_port = _resolve_dashboard_port(args.port)
+    srv = _QuietThreadingHTTPServer((args.host, resolved_port), DashboardHTTPHandler)
 
     bind_host = args.host
     bind_port = srv.server_address[1]