cctally 1.60.0 → 1.61.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,30 @@ 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, open_cache_db, sync_cache,
+    _prune_orphaned_cache_entries,
+)
+from _lib_snapshot_cache import (
+    build_cached_group_a,
+    bump_generation,
+    reset_group_a_state,
+    reset_projects_env_state,
+    reset_session_cache_state,
+    reset_weekref_cost_state,
+    _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 +374,76 @@ 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. (B2 cache-report cache was dropped at the M2.0 gate,
+            # so there is no reset_cache_report_state() to call here.)
+            reset_weekref_cost_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()
+            # #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, 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)
 
@@ -2464,10 +2557,98 @@ 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)
+
+        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),
+        )
+        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 +2677,136 @@ 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
+
+        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,
+        )
+        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) -> "list[WeeklyPeriodRow]":
     """Latest n subscription weeks as WeeklyPeriodRow, newest-first.
 
     Thin builder-using prelude + Bug-K pre-credit synthesis on top of
@@ -2534,7 +2834,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 +2841,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 +2939,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,12 +3014,16 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
                 # No pre-credit interval to aggregate.
                 continue
 
-            # Aggregate entries in [original_start, effective).
+            # 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.
             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:
+            for e in get_entries(original_start_dt, eff_dt, skip_sync=True):
                 if original_start_dt <= e.timestamp < eff_dt:
                     usage = e.usage
                     pre_input  += usage.get("input_tokens", 0)
@@ -2965,11 +3294,95 @@ 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)
+            )
+
+        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),
+        )
+        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 +3417,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 []
 
@@ -3135,12 +3574,189 @@ def _projects_iter_session_entries(conn: "sqlite3.Connection",
         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 _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.
+    """
+    c = _cctally()
+    _resolve_project_key = c._resolve_project_key
+    week_total = 0.0
+    mut: "dict[str, dict]" = {}
+    for row in _projects_iter_session_entries(
+        conn, since=week_start, until=week_end,
+    ):
+        (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
+        ts = parse_iso_datetime(ts_iso, "session_entries.timestamp_utc")
+        if _projects_week_start_monday_utc(ts) != week_start:
+            continue
+        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 = _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
+        week_total += entry_cost
+    out = {
+        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()
+    }
+    return out, week_total
+
+
+def _assemble_projects_via_cache(
+    conn: "sqlite3.Connection",
+    *,
+    weeks_full: "list[dt.datetime]",
+    cw_start: "dt.datetime",
+    cw_end: "dt.datetime",
+) -> "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.
+    """
+    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
+
+    for w in weeks_full:
+        if w == cw_start:
+            week_buckets, week_total = _aggregate_projects_week(
+                conn, week_start=w, week_end=cw_end, resolver_cache=resolver_cache,
+            )
+        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.
 
@@ -3220,95 +3836,105 @@ 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,
         )
+    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 +5121,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 +5238,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 +5522,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 +5615,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 +5651,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 +5919,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 +9327,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 +9344,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 +9425,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 +9466,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 +9512,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 +9552,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]