cctally 1.64.0 → 1.66.0

package/bin/_cctally_tui.py

@@ -222,6 +222,42 @@ from _lib_display_tz import (
 )
 from _lib_aggregators import _aggregate_monthly
 from _lib_fmt import stable_sum
+# Opt-in backend phase-instrumentation collector (issue #276, Session A). Pure
+# stdlib leaf; near-noop when CCTALLY_PERF_TRACE is unset (phase() returns a
+# shared no-op singleton), so the _tui_build_snapshot seam wraps below cost
+# nothing on the default path.
+import _lib_perf as _perf
+
+import importlib.util as _ilu
+
+
+def _ensure_sibling_loaded(name: str) -> None:
+    """Register a NON-eager-loaded ``_lib_*`` sibling in ``sys.modules``.
+
+    ``_lib_forecast`` (#279 S4 F2) is a NEW consumer-only sibling — kept out
+    of ``bin/cctally``'s eager-load block so ``bin/cctally`` stays
+    byte-untouched (spec §2). Under the ``SourceFileLoader`` harness path
+    (``bin/`` absent from ``sys.path``) a bare ``from _lib_forecast import``
+    would miss, so this pre-registers the sibling ``__file__``-relative when
+    it is not already importable (mirrors ``_cctally_cache._load_lib``). The
+    honest import that follows is a ``sys.modules`` hit in every load context.
+    """
+    if name in sys.modules:
+        return
+    try:
+        __import__(name)  # bin/ on sys.path: prod script / conftest / pytest
+        return
+    except ModuleNotFoundError:
+        pass
+    _p = os.path.join(os.path.dirname(__file__), f"{name}.py")
+    _spec = _ilu.spec_from_file_location(name, _p)
+    _mod = _ilu.module_from_spec(_spec)
+    sys.modules[name] = _mod
+    _spec.loader.exec_module(_mod)
+
+
+_ensure_sibling_loaded("_lib_forecast")
+from _lib_forecast import _compute_forecast, ForecastInputs, ForecastOutput, BudgetRow
 
 
 # === Module-level back-ref shims for helpers that STAY in bin/cctally ======
@@ -252,10 +288,6 @@ def _apply_midweek_reset_override(*args, **kwargs):
     return sys.modules["cctally"]._apply_midweek_reset_override(*args, **kwargs)
 
 
-def _compute_forecast(*args, **kwargs):
-    return sys.modules["cctally"]._compute_forecast(*args, **kwargs)
-
-
 def _resolve_forecast_now(*args, **kwargs):
     return sys.modules["cctally"]._resolve_forecast_now(*args, **kwargs)
 
@@ -308,20 +340,11 @@ def sync_cache(*args, **kwargs):
     return sys.modules["cctally"].sync_cache(*args, **kwargs)
 
 
-# Forecast dataclass shims — used as bare-name constructors inside
-# ``_tui_build_forecast``. The classes themselves stay in bin/cctally
-# alongside the forecast subcommand (``cmd_forecast``); call-time
-# resolution keeps monkeypatches in sync.
-def ForecastInputs(*args, **kwargs):
-    return sys.modules["cctally"].ForecastInputs(*args, **kwargs)
-
-
-def ForecastOutput(*args, **kwargs):
-    return sys.modules["cctally"].ForecastOutput(*args, **kwargs)
-
-
-def BudgetRow(*args, **kwargs):
-    return sys.modules["cctally"].BudgetRow(*args, **kwargs)
+# ``_compute_forecast`` + the forecast dataclasses (``ForecastInputs`` /
+# ``ForecastOutput`` / ``BudgetRow``) now live in ``bin/_lib_forecast.py``
+# (#279 S4 F2) and are honest-imported at module top — used as bare-name
+# constructors inside ``_tui_build_forecast``. Single class def per name in
+# ``_lib_forecast``; everything imports it, so class identity stays unique.
 
 
 # Dashboard back-refs consumed by the TUI's snapshot builders.
@@ -1104,6 +1127,22 @@ class DataSnapshot:
     # keep working, and both are carried forward on a sync crash (Codex F6).
     doctor_payload: dict | None = None
     envelope_precompute: dict | None = None
+    # ---- #278 Theme A: first-paint hydration latch ----
+    # ``True`` ONLY on data that is genuinely still being assembled — the
+    # cheap first-paint seed (``_dashboard_initial_snapshot`` on a normal
+    # launch) and A2's throttled partial republishes (set on a
+    # ``dataclasses.replace`` copy for the PUBLISH only, never dirtying the
+    # object the dispatch memo retains). Every path that yields
+    # complete/stable data leaves/forces it ``False``: a fresh full build is
+    # ``False`` for free (this default), and each ``dataclasses.replace``
+    # clone site that copies a prior snapshot's value (idle short-circuit,
+    # update-check republish, run-sync/settings republish) forces it back to
+    # ``False``. Serialized into the dashboard envelope by
+    # ``snapshot_to_envelope`` (additive key ``"hydrating"``); consumers
+    # tolerate unknown keys, and it appears in NO ``--json``/CLI surface.
+    # Placed LAST with a default so positional fixture constructors keep
+    # working.
+    hydrating: bool = False
 
     @classmethod
     def synthesize_for_marketing(cls, *, as_of_iso: str) -> "DataSnapshot":
@@ -2092,6 +2131,13 @@ def _tui_build_snapshot(
     """
     import time
     now_utc = now_utc or dt.datetime.now(dt.timezone.utc)
+    # #276 perf: reset any prior tree on this thread, then bracket the whole
+    # snapshot build as the "snapshot" root phase. Opened via the context-
+    # manager protocol so the long body below is not reindented; closed +
+    # stashed at each return. Near-noop when CCTALLY_PERF_TRACE is unset.
+    _perf.reset_thread()
+    _p_snapshot = _perf.phase("snapshot")
+    _p_snapshot.__enter__()
     # Read config ONCE per rebuild and reuse it for the display-tz resolution
     # here AND the envelope precompute below (#268 M4) — the envelope used to
     # call ``load_config()`` twice per SSE client per tick.
@@ -2134,15 +2180,17 @@ def _tui_build_snapshot(
         # builders always read pure regardless (skip_sync is reassigned to
         # True below), so --no-sync means "no ingest, still read".
         do_ingest = not skip_sync
-        if do_ingest:
-            try:
-                cache_conn = _cctally().open_cache_db()
+        with _perf.phase("sync") as _p_sync:
+            _p_sync.set_meta(ingest=do_ingest)
+            if do_ingest:
                 try:
-                    sync_cache(cache_conn)
-                finally:
-                    cache_conn.close()
-            except Exception as exc:
-                errors.append(f"sync-cache: {exc}")
+                    cache_conn = _cctally().open_cache_db()
+                    try:
+                        sync_cache(cache_conn)
+                    finally:
+                        cache_conn.close()
+                except Exception as exc:
+                    errors.append(f"sync-cache: {exc}")
         # Force pure reads for every view builder below, independent of the
         # caller's flag: the single ingest above is the only glob per tick.
         skip_sync = True
@@ -2193,11 +2241,12 @@ def _tui_build_snapshot(
         dispatch_key = None
         if precompute_envelope:
             dispatch_sig = None
-            try:
-                dispatch_sig = _tui_compute_dispatch_signature(conn)
-            except Exception as exc:
-                errors.append(f"dispatch-signature: {exc}")
-                dispatch_sig = None
+            with _perf.phase("signature"):
+                try:
+                    dispatch_sig = _tui_compute_dispatch_signature(conn)
+                except Exception as exc:
+                    errors.append(f"dispatch-signature: {exc}")
+                    dispatch_sig = None
             if dispatch_sig is not None:
                 # The idle decision keys on the DB signature AND a render key
                 # that captures the config-derived inputs the composite
@@ -2220,13 +2269,20 @@ def _tui_build_snapshot(
                         and dispatch_key == prior_key
                         and not _snapshot_period_rolled_over(
                             prior_snap, now_utc, _build_display_tz)):
-                    idle_snap = _tui_build_idle_snapshot(
-                        prior_snap, now_utc=now_utc,
-                        precompute_envelope=precompute_envelope,
-                        runtime_bind=runtime_bind, raw_config=raw_config,
-                        errors=errors,
-                    )
-                    _sc.store_dispatch_state(dispatch_key, idle_snap)
+                    with _perf.phase("idle-decision"):
+                        idle_snap = _tui_build_idle_snapshot(
+                            prior_snap, now_utc=now_utc,
+                            precompute_envelope=precompute_envelope,
+                            runtime_bind=runtime_bind, raw_config=raw_config,
+                            errors=errors,
+                        )
+                        _sc.store_dispatch_state(dispatch_key, idle_snap)
+                    _p_snapshot.__exit__(None, None, None)
+                    if _perf.enabled():
+                        _perf.stash_last(
+                            _perf.current_root(), generation=None,
+                            generated_at=now_utc.isoformat(),
+                        )
                     return idle_snap
                 # ── #269 M3.1: non-idle rebuild — reconcile the shared
                 # per-weekref immutable-cost cache ONCE here (spec §4/§6),
@@ -2241,39 +2297,48 @@ def _tui_build_snapshot(
                 try:
                     _rc_cache_conn = _cctally().open_cache_db()
                     try:
-                        _sc.reconcile_weekref_cache(
-                            _rc_cache_conn,
-                            max_entry_id=dispatch_sig.max_entry_id,
-                            max_mutation_seq=dispatch_sig.entry_mutation_seq,
-                            reset_sig=dispatch_sig.reset_sig,
-                        )
-                        use_weekref_cost_cache = True
+                        with _perf.phase("reconcile.weekref") as _pr:
+                            _pr.set_meta(hit=False)
+                            _sc.reconcile_weekref_cache(
+                                _rc_cache_conn,
+                                max_entry_id=dispatch_sig.max_entry_id,
+                                max_mutation_seq=dispatch_sig.entry_mutation_seq,
+                                reset_sig=dispatch_sig.reset_sig,
+                            )
+                            use_weekref_cost_cache = True
+                            _pr.set_meta(hit=True)
                         # #269 M4.5: reconcile the projects-envelope cache with
                         # the SAME short-lived cache conn (session_files_sig +
                         # the new-entry watermark both live in cache.db). Only
                         # after this succeeds does `_build_projects_envelope`
                         # opt into the cache below.
-                        _sc.reconcile_projects_env_cache(
-                            _rc_cache_conn,
-                            max_entry_id=dispatch_sig.max_entry_id,
-                            max_mutation_seq=dispatch_sig.entry_mutation_seq,
-                            max_wus_id=dispatch_sig.max_wus_id,
-                            sf_sig=_sc.session_files_sig(_rc_cache_conn),
-                        )
-                        use_projects_env_cache = True
+                        with _perf.phase("reconcile.projects_env") as _pr:
+                            _pr.set_meta(hit=False)
+                            _sc.reconcile_projects_env_cache(
+                                _rc_cache_conn,
+                                max_entry_id=dispatch_sig.max_entry_id,
+                                max_mutation_seq=dispatch_sig.entry_mutation_seq,
+                                max_wus_id=dispatch_sig.max_wus_id,
+                                sf_sig=_sc.session_files_sig(_rc_cache_conn),
+                            )
+                            use_projects_env_cache = True
+                            _pr.set_meta(hit=True)
                         # #271 M3: reconcile the Bug-K pre-credit segment cache
                         # with the SAME short-lived cache conn (its watermark
                         # query lives in cache.db), using the dispatch-signature
                         # legs already computed. Only after this succeeds does
                         # `_dashboard_build_weekly_periods` opt into the cache
                         # below (`use_bugk_segment_cache=True`).
-                        _sc.reconcile_bugk_cache(
-                            _rc_cache_conn,
-                            max_entry_id=dispatch_sig.max_entry_id,
-                            max_mutation_seq=dispatch_sig.entry_mutation_seq,
-                            reset_sig=dispatch_sig.reset_sig,
-                        )
-                        use_bugk_segment_cache = True
+                        with _perf.phase("reconcile.bugk") as _pr:
+                            _pr.set_meta(hit=False)
+                            _sc.reconcile_bugk_cache(
+                                _rc_cache_conn,
+                                max_entry_id=dispatch_sig.max_entry_id,
+                                max_mutation_seq=dispatch_sig.entry_mutation_seq,
+                                reset_sig=dispatch_sig.reset_sig,
+                            )
+                            use_bugk_segment_cache = True
+                            _pr.set_meta(hit=True)
                         # #272: reconcile the cache-report per-day cache with the
                         # SAME short-lived cache conn (its watermark query +
                         # session_files_sig both live in cache.db), using the
@@ -2282,95 +2347,104 @@ def _tui_build_snapshot(
                         # `tz_key` full-clears on a display-tz change (every
                         # calendar-day key shifts). Only after this succeeds does
                         # `build_cache_report_snapshot` opt into the cache below.
-                        _sc.reconcile_cache_report_cache(
-                            _rc_cache_conn,
-                            max_entry_id=dispatch_sig.max_entry_id,
-                            max_mutation_seq=dispatch_sig.entry_mutation_seq,
-                            reset_sig=dispatch_sig.reset_sig,
-                            sf_sig=_sc.session_files_sig(_rc_cache_conn),
-                            # `_load_sibling` is the canonical idempotent
-                            # sibling-access idiom (it returns the already-loaded
-                            # cctally-bound kernel instance). `_lib_cache_report`
-                            # is loaded eagerly at import (bin/cctally), so this
-                            # is a plain re-fetch of a populated `sys.modules`
-                            # entry — NOT a first-tick KeyError guard.
-                            bucket_tz=_cctally()._load_sibling(
-                                "_lib_cache_report"
-                            )._resolve_bucket_tz(_build_display_tz),
-                            tz_key=str(_build_display_tz),
-                        )
-                        use_cache_report_cache = True
+                        with _perf.phase("reconcile.cache_report") as _pr:
+                            _pr.set_meta(hit=False)
+                            _sc.reconcile_cache_report_cache(
+                                _rc_cache_conn,
+                                max_entry_id=dispatch_sig.max_entry_id,
+                                max_mutation_seq=dispatch_sig.entry_mutation_seq,
+                                reset_sig=dispatch_sig.reset_sig,
+                                sf_sig=_sc.session_files_sig(_rc_cache_conn),
+                                # `_load_sibling` is the canonical idempotent
+                                # sibling-access idiom (it returns the already-loaded
+                                # cctally-bound kernel instance). `_lib_cache_report`
+                                # is loaded eagerly at import (bin/cctally), so this
+                                # is a plain re-fetch of a populated `sys.modules`
+                                # entry — NOT a first-tick KeyError guard.
+                                bucket_tz=_cctally()._load_sibling(
+                                    "_lib_cache_report"
+                                )._resolve_bucket_tz(_build_display_tz),
+                                tz_key=str(_build_display_tz),
+                            )
+                            use_cache_report_cache = True
+                            _pr.set_meta(hit=True)
                     finally:
                         _rc_cache_conn.close()
                 except Exception as exc:
                     errors.append(f"snapshot-cache-reconcile: {exc}")
-        try:
-            cw = _tui_build_current_week(conn, now_utc, skip_sync=skip_sync)
-        except Exception as exc:
-            errors.append(f"current-week: {exc}")
+        with _perf.phase("build.current_week"):
+            try:
+                cw = _tui_build_current_week(conn, now_utc, skip_sync=skip_sync)
+            except Exception as exc:
+                errors.append(f"current-week: {exc}")
         fc_view = None
-        try:
-            # Issue #57: build the ForecastView once so we capture both
-            # the legacy ``ForecastOutput`` (for ``snap.forecast``, which
-            # the many TUI panel consumers still read) and the surface
-            # fields the envelope adapter used to re-derive inline.
-            fc_view = _tui_build_forecast_view(
-                conn, now_utc, skip_sync=skip_sync,
-                use_weekref_cost_cache=use_weekref_cost_cache,
-            )
-            fc = fc_view.output if fc_view is not None else None
-        except Exception as exc:
-            errors.append(f"forecast: {exc}")
+        with _perf.phase("build.forecast"):
+            try:
+                # Issue #57: build the ForecastView once so we capture both
+                # the legacy ``ForecastOutput`` (for ``snap.forecast``, which
+                # the many TUI panel consumers still read) and the surface
+                # fields the envelope adapter used to re-derive inline.
+                fc_view = _tui_build_forecast_view(
+                    conn, now_utc, skip_sync=skip_sync,
+                    use_weekref_cost_cache=use_weekref_cost_cache,
+                )
+                fc = fc_view.output if fc_view is not None else None
+            except Exception as exc:
+                errors.append(f"forecast: {exc}")
         # Trend: source from build_trend_view so we capture the 3-sample
         # avg_dollars_per_pct alongside the rows. The TUI build path
         # historically called _tui_build_trend (which now wraps the
         # builder); calling the builder directly here saves one
         # `_aggregate_*` round-trip.
         trend_avg_dpp = None
-        try:
-            c = _cctally()
-            _trend_view = c.build_trend_view(
-                conn, now_utc=now_utc, n=8, display_tz=_build_display_tz,
-                skip_sync=skip_sync,
-                use_weekref_cost_cache=use_weekref_cost_cache,
-            )
-            trend = list(_trend_view.rows)
-            trend_avg_dpp = _trend_view.avg_dollars_per_pct
-        except Exception as exc:
-            errors.append(f"trend: {exc}")
-        try:
-            # The sessions aggregator goes through
-            # `get_claude_session_entries`, which runs `sync_cache` unless
-            # `skip_sync=True` is threaded through. Honor the caller's
-            # intent so `--no-sync` and the initial cache-only paint
-            # both avoid ingest latency/lock contention.
-            sessions = _tui_build_sessions(
-                now_utc, skip_sync=skip_sync, use_session_cache=True,
-            )
-        except Exception as exc:
-            errors.append(f"sessions: {exc}")
+        with _perf.phase("build.trend"):
+            try:
+                c = _cctally()
+                _trend_view = c.build_trend_view(
+                    conn, now_utc=now_utc, n=8, display_tz=_build_display_tz,
+                    skip_sync=skip_sync,
+                    use_weekref_cost_cache=use_weekref_cost_cache,
+                )
+                trend = list(_trend_view.rows)
+                trend_avg_dpp = _trend_view.avg_dollars_per_pct
+            except Exception as exc:
+                errors.append(f"trend: {exc}")
+        with _perf.phase("build.sessions"):
+            try:
+                # The sessions aggregator goes through
+                # `get_claude_session_entries`, which runs `sync_cache` unless
+                # `skip_sync=True` is threaded through. Honor the caller's
+                # intent so `--no-sync` and the initial cache-only paint
+                # both avoid ingest latency/lock contention.
+                sessions = _tui_build_sessions(
+                    now_utc, skip_sync=skip_sync, use_session_cache=True,
+                )
+            except Exception as exc:
+                errors.append(f"sessions: {exc}")
         # ---- v2 additions ----
-        try:
-            if cw is not None:
-                milestones = _tui_build_percent_milestones(conn)
-        except Exception as exc:
-            errors.append(f"milestones: {exc}")
+        with _perf.phase("build.milestones"):
+            try:
+                if cw is not None:
+                    milestones = _tui_build_percent_milestones(conn)
+            except Exception as exc:
+                errors.append(f"milestones: {exc}")
         history: list = []
         history_median_dpp: "float | None" = None
-        try:
-            # Issue #59: build the full TrendView so we capture the
-            # pre-computed 4-week-median-non-current scalar alongside
-            # the row list; the dashboard envelope adapter surfaces
-            # the scalar as ``trend.history_median_dpp`` so
-            # TrendModal.tsx stops re-deriving it client-side.
-            history_view = _tui_build_weekly_history_view(
-                conn, now_utc, skip_sync=skip_sync, display_tz=_build_display_tz,
-                use_weekref_cost_cache=use_weekref_cost_cache,
-            )
-            history = list(history_view.rows)
-            history_median_dpp = history_view.median_dpp_non_current_4w
-        except Exception as exc:
-            errors.append(f"weekly-history: {exc}")
+        with _perf.phase("build.weekly_history"):
+            try:
+                # Issue #59: build the full TrendView so we capture the
+                # pre-computed 4-week-median-non-current scalar alongside
+                # the row list; the dashboard envelope adapter surfaces
+                # the scalar as ``trend.history_median_dpp`` so
+                # TrendModal.tsx stops re-deriving it client-side.
+                history_view = _tui_build_weekly_history_view(
+                    conn, now_utc, skip_sync=skip_sync, display_tz=_build_display_tz,
+                    use_weekref_cost_cache=use_weekref_cost_cache,
+                )
+                history = list(history_view.rows)
+                history_median_dpp = history_view.median_dpp_non_current_4w
+            except Exception as exc:
+                errors.append(f"weekly-history: {exc}")
         # ---- v2.1 additions: dashboard Weekly / Monthly panels ----
         # Sync-thread view-model totals (spec §6.6): sum directly over
         # the panel rows the dashboard ACTUALLY renders. The previous
@@ -2386,23 +2460,24 @@ def _tui_build_snapshot(
         # ``test_weekly_envelope_total_matches_sum_of_visible_rows``.
         weekly_total_cost_usd = 0.0
         weekly_total_tokens = 0
-        try:
-            weekly_periods = _dashboard_build_weekly_periods(
-                conn, now_utc, n=12, skip_sync=skip_sync,
-                use_group_a_cache=True,
-                use_bugk_segment_cache=use_bugk_segment_cache,
-            )
-            # ``stable_sum`` (math.fsum) returns float ``0.0`` on empty rows,
-            # so the envelope stays byte-stable with the pre-fix ``0.0`` shape
-            # (the dashboard fixture goldens assert exact JSON match).
-            weekly_total_cost_usd = stable_sum(
-                r.cost_usd for r in weekly_periods
-            )
-            weekly_total_tokens = sum(
-                (r.total_tokens for r in weekly_periods), 0,
-            )
-        except Exception as exc:
-            errors.append(f"weekly-periods: {exc}")
+        with _perf.phase("build.weekly_periods"):
+            try:
+                weekly_periods = _dashboard_build_weekly_periods(
+                    conn, now_utc, n=12, skip_sync=skip_sync,
+                    use_group_a_cache=True,
+                    use_bugk_segment_cache=use_bugk_segment_cache,
+                )
+                # ``stable_sum`` (math.fsum) returns float ``0.0`` on empty rows,
+                # so the envelope stays byte-stable with the pre-fix ``0.0`` shape
+                # (the dashboard fixture goldens assert exact JSON match).
+                weekly_total_cost_usd = stable_sum(
+                    r.cost_usd for r in weekly_periods
+                )
+                weekly_total_tokens = sum(
+                    (r.total_tokens for r in weekly_periods), 0,
+                )
+            except Exception as exc:
+                errors.append(f"weekly-periods: {exc}")
         # Sync-thread view-model totals (spec §6.6): sum-over-visible-rows
         # (same invariant as weekly above). Monthly has no Bug-K analogue,
         # but coupling the footer total to the panel-row source of truth
@@ -2410,20 +2485,21 @@ def _tui_build_snapshot(
         # same arithmetic with no behavioral upside.
         monthly_total_cost_usd = 0.0
         monthly_total_tokens = 0
-        try:
-            monthly_periods = _dashboard_build_monthly_periods(
-                conn, now_utc, n=12, skip_sync=skip_sync,
-                use_group_a_cache=True,
-                display_tz=_build_display_tz,
-            )
-            monthly_total_cost_usd = stable_sum(
-                r.cost_usd for r in monthly_periods
-            )
-            monthly_total_tokens = sum(
-                (r.total_tokens for r in monthly_periods), 0,
-            )
-        except Exception as exc:
-            errors.append(f"monthly-periods: {exc}")
+        with _perf.phase("build.monthly_periods"):
+            try:
+                monthly_periods = _dashboard_build_monthly_periods(
+                    conn, now_utc, n=12, skip_sync=skip_sync,
+                    use_group_a_cache=True,
+                    display_tz=_build_display_tz,
+                )
+                monthly_total_cost_usd = stable_sum(
+                    r.cost_usd for r in monthly_periods
+                )
+                monthly_total_tokens = sum(
+                    (r.total_tokens for r in monthly_periods), 0,
+                )
+            except Exception as exc:
+                errors.append(f"monthly-periods: {exc}")
         # ---- v2.2 additions: dashboard Blocks / Daily panels ----
         # Issue #56: build the BlocksView once and read both rows
         # (presentation) and totals (envelope scalars) from the same
@@ -2432,20 +2508,21 @@ def _tui_build_snapshot(
         # kept as a thin shim for monkeypatch surfaces).
         blocks_total_cost_usd = 0.0
         blocks_total_tokens = 0
-        try:
-            if cw is not None:
-                _blocks_view = _dashboard_build_blocks_view(
-                    conn, now_utc,
-                    week_start_at=cw.week_start_at,
-                    week_end_at=cw.week_end_at,
-                    skip_sync=skip_sync,
-                    display_tz=_build_display_tz,
-                )
-                blocks_panel = list(_blocks_view.rows)
-                blocks_total_cost_usd = _blocks_view.total_cost_usd
-                blocks_total_tokens = _blocks_view.total_tokens
-        except Exception as exc:
-            errors.append(f"blocks-panel: {exc}")
+        with _perf.phase("build.blocks"):
+            try:
+                if cw is not None:
+                    _blocks_view = _dashboard_build_blocks_view(
+                        conn, now_utc,
+                        week_start_at=cw.week_start_at,
+                        week_end_at=cw.week_end_at,
+                        skip_sync=skip_sync,
+                        display_tz=_build_display_tz,
+                    )
+                    blocks_panel = list(_blocks_view.rows)
+                    blocks_total_cost_usd = _blocks_view.total_cost_usd
+                    blocks_total_tokens = _blocks_view.total_tokens
+            except Exception as exc:
+                errors.append(f"blocks-panel: {exc}")
         # Sync-thread view-model totals (Bundle 1 / spec §6.6):
         # sum-over-visible-rows (same invariant as weekly/monthly above).
         # Gap days in the materialized panel carry ``cost_usd=0.0`` /
@@ -2454,42 +2531,45 @@ def _tui_build_snapshot(
         # ``build_daily_view`` pass that did the same arithmetic.
         daily_total_cost_usd = 0.0
         daily_total_tokens = 0
-        try:
-            daily_panel = _dashboard_build_daily_panel(
-                conn, now_utc, n=30, skip_sync=skip_sync,
-                use_group_a_cache=True,
-                display_tz=_build_display_tz,
-            )
-            daily_total_cost_usd = stable_sum(
-                r.cost_usd for r in daily_panel
-            )
-            daily_total_tokens = sum(
-                (r.total_tokens for r in daily_panel), 0,
-            )
-        except Exception as exc:
-            errors.append(f"daily-panel: {exc}")
+        with _perf.phase("build.daily"):
+            try:
+                daily_panel = _dashboard_build_daily_panel(
+                    conn, now_utc, n=30, skip_sync=skip_sync,
+                    use_group_a_cache=True,
+                    display_tz=_build_display_tz,
+                )
+                daily_total_cost_usd = stable_sum(
+                    r.cost_usd for r in daily_panel
+                )
+                daily_total_tokens = sum(
+                    (r.total_tokens for r in daily_panel), 0,
+                )
+            except Exception as exc:
+                errors.append(f"daily-panel: {exc}")
         # ---- threshold-actions T5: alerts envelope array ----
         # Precomputed at sync time so `snapshot_to_envelope` stays a pure
         # renderer (no DB I/O on the dashboard hot path; mirrors how
         # `current_week.five_hour_block` is precomputed via
         # `_select_current_block_for_envelope`).
-        try:
-            alerts = _build_alerts_envelope_array(conn)
-        except Exception as exc:
-            errors.append(f"alerts: {exc}")
+        with _perf.phase("build.alerts"):
+            try:
+                alerts = _build_alerts_envelope_array(conn)
+            except Exception as exc:
+                errors.append(f"alerts: {exc}")
         # ---- 5h in-place credit (v1.7.x) ----
         # Load 5h milestones (pre + post credit) for the current
         # block's window so CurrentWeekModal can render a merged
         # chronological timeline alongside its weekly milestones.
         # Spec §5.3 (Codex r1 finding 3).
         fh_milestones: list[dict] = []
-        try:
-            win_key = None
-            if cw is not None and isinstance(cw.five_hour_block, dict):
-                win_key = cw.five_hour_block.get("five_hour_window_key")
-            fh_milestones = _tui_build_five_hour_milestones(conn, win_key)
-        except Exception as exc:
-            errors.append(f"five-hour-milestones: {exc}")
+        with _perf.phase("build.five_hour_milestones"):
+            try:
+                win_key = None
+                if cw is not None and isinstance(cw.five_hour_block, dict):
+                    win_key = cw.five_hour_block.get("five_hour_window_key")
+                fh_milestones = _tui_build_five_hour_milestones(conn, win_key)
+            except Exception as exc:
+                errors.append(f"five-hour-milestones: {exc}")
         # ---- Projects panel + modal envelope (spec §5.2, plan Task 1) -----
         # Per-tick aggregation lives on the sync thread; the dashboard's
         # pure ``snapshot_to_envelope`` reads ``snap.projects_envelope``
@@ -2504,6 +2584,11 @@ def _tui_build_snapshot(
         # all three tables. ATTACH/DETACH is cheap and scoped to this
         # sub-build; no schema migration / lock acquisition is needed.
         projects_envelope_block: dict | None = None
+        # #276 perf: time the projects-envelope build (ATTACH + walk + DETACH).
+        # CM protocol, not a ``with`` block, to avoid reindenting the ~40-line
+        # try/except/finally; the broad except + finally guarantee no escape.
+        _p_pe = _perf.phase("build.projects_envelope")
+        _p_pe.__enter__()
         try:
             c = _cctally()
             cache_db_path = _cctally_core.CACHE_DB_PATH
@@ -2545,6 +2630,7 @@ def _tui_build_snapshot(
                 conn.execute("DETACH DATABASE cache_db")
             except Exception:
                 pass
+        _p_pe.__exit__(None, None, None)
         # Late-bind disambiguated `project_key` onto each SessionsPanel
         # row so the SessionsPanel → ProjectsModal cross-nav (spec §4.1)
         # routes by the same identity the Projects envelope emits.
@@ -2606,28 +2692,29 @@ def _tui_build_snapshot(
         # on the DataSnapshot field and the client renders the empty
         # state.
         cache_report_block = None
-        try:
-            cfg_cr = load_config().get("cache_report") or {}
-            threshold_raw = cfg_cr.get("anomaly_threshold_pp", 15)
+        with _perf.phase("build.cache_report"):
             try:
-                threshold_pp = int(threshold_raw)
-            except (TypeError, ValueError):
-                threshold_pp = 15
-            if threshold_pp < 1 or threshold_pp > 100:
-                threshold_pp = 15
-            _dash_mod = sys.modules["_cctally_dashboard"]
-            _bcr = _dash_mod.build_cache_report_snapshot
-            cache_report_block = _bcr(
-                now_utc=now_utc,
-                anomaly_threshold_pp=threshold_pp,
-                # Hardcoded for v1; F10 tracks lifting via cache_report.anomaly_window_days config.
-                anomaly_window_days=_dash_mod.CACHE_REPORT_ANOMALY_WINDOW_DAYS,
-                display_tz=_build_display_tz,
-                skip_sync=skip_sync,
-                use_cache_report_cache=use_cache_report_cache,
-            )
-        except Exception as exc:
-            errors.append(f"cache-report: {exc}")
+                cfg_cr = load_config().get("cache_report") or {}
+                threshold_raw = cfg_cr.get("anomaly_threshold_pp", 15)
+                try:
+                    threshold_pp = int(threshold_raw)
+                except (TypeError, ValueError):
+                    threshold_pp = 15
+                if threshold_pp < 1 or threshold_pp > 100:
+                    threshold_pp = 15
+                _dash_mod = sys.modules["_cctally_dashboard"]
+                _bcr = _dash_mod.build_cache_report_snapshot
+                cache_report_block = _bcr(
+                    now_utc=now_utc,
+                    anomaly_threshold_pp=threshold_pp,
+                    # Hardcoded for v1; F10 tracks lifting via cache_report.anomaly_window_days config.
+                    anomaly_window_days=_dash_mod.CACHE_REPORT_ANOMALY_WINDOW_DAYS,
+                    display_tz=_build_display_tz,
+                    skip_sync=skip_sync,
+                    use_cache_report_cache=use_cache_report_cache,
+                )
+            except Exception as exc:
+                errors.append(f"cache-report: {exc}")
 
         # ---- #268 M4: doctor / config / update-state precompute (spec §6) ----
         # Precompute the envelope's doctor / config / update-state reads ONCE
@@ -2639,18 +2726,20 @@ def _tui_build_snapshot(
         doctor_payload_block: "dict | None" = None
         envelope_precompute_block: "dict | None" = None
         if precompute_envelope:
-            try:
-                doctor_payload_block = _tui_precompute_doctor_payload(
-                    now_utc, runtime_bind,
-                )
-            except Exception as exc:
-                errors.append(f"doctor-precompute: {exc}")
-            try:
-                envelope_precompute_block = _tui_precompute_envelope_config(
-                    raw_config,
-                )
-            except Exception as exc:
-                errors.append(f"envelope-precompute: {exc}")
+            with _perf.phase("doctor"):
+                try:
+                    doctor_payload_block = _tui_precompute_doctor_payload(
+                        now_utc, runtime_bind,
+                    )
+                except Exception as exc:
+                    errors.append(f"doctor-precompute: {exc}")
+            with _perf.phase("envelope.precompute"):
+                try:
+                    envelope_precompute_block = _tui_precompute_envelope_config(
+                        raw_config,
+                    )
+                except Exception as exc:
+                    errors.append(f"envelope-precompute: {exc}")
 
         snap = DataSnapshot(
             current_week=cw,
@@ -2692,6 +2781,16 @@ def _tui_build_snapshot(
             _cctally()._load_sibling("_lib_snapshot_cache").store_dispatch_state(
                 dispatch_key, snap,
             )
+        # #276 perf: close the "snapshot" root and freeze the completed tree
+        # into the process-global slot for the loopback /api/debug/backend
+        # endpoint. Whole-dict atomic assignment; never mutated after. No-op
+        # when tracing is off.
+        _p_snapshot.__exit__(None, None, None)
+        if _perf.enabled():
+            _perf.stash_last(
+                _perf.current_root(), generation=None,
+                generated_at=now_utc.isoformat(),
+            )
         return snap
     finally:
         conn.close()
@@ -2894,6 +2993,10 @@ def _tui_build_idle_snapshot(prior, *, now_utc, precompute_envelope,
         last_sync_error=("; ".join(errors) if errors else None),
         doctor_payload=doctor_payload,
         envelope_precompute=envelope_precompute,
+        # #278 §1.4.1: an idle snapshot means the data-version signature is
+        # unchanged (data stable) → force the hydration latch clear even if
+        # ``prior`` was a hydrating seed/partial.
+        hydrating=False,
     )
 
 
@@ -5090,6 +5193,69 @@ def _tui_refresh_interval_type(s: str) -> float:
     return v
 
 
+# ── #278 Theme A (A2): progressive first-run ingest fill ─────────────────────
+# A first-run / long-gap dashboard sync walks many files and takes seconds to
+# tens-of-seconds; before this it published exactly once at the end (empty →
+# single jump). A2 wires the existing ``sync_cache(progress=…)`` seam to a
+# THROTTLED partial republish so the heavy panels fill progressively. It is
+# self-limiting to first-run: a warm returning user's sync finishes under T, so
+# the throttle never fires and A2 is a pure no-op (exactly one publish). Not
+# user-configurable (YAGNI).
+_A2_PARTIAL_THROTTLE_S = 2.0  # T
+
+
+class _A2ThrottleClock:
+    """Completion-measured throttle for A2 partial republishes.
+
+    ``should_fire(now)`` is True at most once per ``interval_s``, measured from
+    the LAST fire's COMPLETION — call ``mark_done(now)`` after the partial build
+    finishes so a slow partial self-spaces rather than stacking (spec §2.2).
+    Seeded at the sync's START, so the first partial waits a full interval and a
+    sub-T warm sync fires zero partials.
+    """
+    __slots__ = ("_interval", "_last")
+
+    def __init__(self, interval_s: float, *, start: float):
+        self._interval = interval_s
+        self._last = start
+
+    def should_fire(self, now: float) -> bool:
+        return (now - self._last) >= self._interval
+
+    def mark_done(self, now: float) -> None:
+        self._last = now
+
+
+def _make_a2_progress_cb(*, ref, hub, build_partial, throttle, monotonic,
+                         perf=_perf):
+    """Build the A2 throttled ``sync_cache`` progress callback (extracted so the
+    throttle + suppression logic is unit-testable with injected deps).
+
+    On proceed it builds a partial via ``build_partial()`` (a fresh, complete
+    ``skip_sync=True`` snapshot over the current committed cache — NOT nested in
+    another build) and stores the clean non-hydrating object on ``ref``, then
+    publishes a ``hydrating=True`` COPY over the hub (§1.4.1 shared-object-leak:
+    only the publish carries the latch, so the memo's retained object stays
+    clean). The dispatch-memo write itself happens inside ``build_partial()`` /
+    ``_tui_build_snapshot`` (its snapshot-cache reconcile step), NOT in this cb.
+    Suppressed entirely while perf tracing is
+    active (spec §2.2): progressive fill is a UX nicety, and a partial build's
+    ``_perf.reset_thread`` would clobber the standalone ``sync_cache``'s
+    in-flight trace phases. Trace-off (all normal use) is unaffected.
+    """
+    def cb(_stats) -> None:
+        if perf.enabled():
+            return
+        now = monotonic()
+        if not throttle.should_fire(now):
+            return
+        snap = build_partial()
+        ref.set(snap)
+        hub.publish(dataclasses.replace(snap, hydrating=True))
+        throttle.mark_done(monotonic())
+    return cb
+
+
 def _make_run_sync_now_locked(*, ref, hub, pinned_now, display_tz_pref_override,
                               runtime_bind=None):
     """Return a closure that does the snapshot-rebuild + SSE-publish work.
@@ -5107,25 +5273,84 @@ def _make_run_sync_now_locked(*, ref, hub, pinned_now, display_tz_pref_override,
     DASHBOARD-only factory, so every rebuild here precomputes the envelope's
     doctor / config / update-state onto the snapshot (``precompute_envelope=True``)
     — keeping ``snapshot_to_envelope`` a pure renderer across all SSE clients.
+
+    #278 A2 (§2.1): the ``skip_sync=False`` path DECOUPLES the ingest from the
+    build — it runs ``sync_cache`` STANDALONE (with a throttled progress cb),
+    then builds the final snapshot with ``skip_sync=True``. Routing the ingest
+    through ``_tui_build_snapshot`` instead would be unsafe: that function
+    unconditionally ``_perf.reset_thread()``s (corrupting the trace §0 fixes),
+    writes dispatch state, and mutates single-writer accelerator caches — so a
+    re-entrant partial build from inside its ``sync`` phase would corrupt all
+    three. The decoupled final build reads the same post-sync cache and computes
+    the same post-sync dispatch signature, so it is byte-identical to today's
+    ``_tui_build_snapshot(skip_sync=False)``. The ``skip_sync=True`` path (POST
+    /api/settings) stays the single-build path.
     """
+    def _build(skip_sync: bool):
+        # Resolve _tui_build_snapshot via cctally's namespace so the eager
+        # re-export AND ``monkeypatch.setitem(ns, "_tui_build_snapshot", spy)``
+        # in tests propagate into this closure body (a bare-name lookup would
+        # resolve in this sibling's __dict__ and miss the cctally-side patch).
+        return sys.modules["cctally"]._tui_build_snapshot(
+            now_utc=pinned_now, skip_sync=skip_sync,
+            display_tz_pref_override=display_tz_pref_override,
+            precompute_envelope=True, runtime_bind=runtime_bind,
+        )
+
     def _locked(skip_sync: bool) -> None:
+        # #279 S5 F6.3 (gate P1-1): arm the snapshot-cache owner-thread tripwire
+        # for whichever thread holds sync_lock for THIS rebuild — the periodic
+        # sync thread, or a /api/sync / /api/settings request thread. Overwrite-
+        # on-call, so ownership transfers to the current rebuilder; the guards in
+        # _lib_snapshot_cache then catch a lock-bypassing foreign-thread mutation.
+        _cctally()._load_sibling("_lib_snapshot_cache").mark_owner_thread()
         try:
-            # Resolve _tui_build_snapshot via cctally's namespace so the
-            # eager re-export AND ``monkeypatch.setitem(ns, "_tui_build_snapshot", spy)``
-            # in tests/test_dashboard_api_sync_refresh.py propagate into
-            # this closure body (the bare-name lookup would resolve in
-            # this sibling's __dict__ and miss the cctally-side patch).
-            snap = sys.modules["cctally"]._tui_build_snapshot(
-                now_utc=pinned_now, skip_sync=skip_sync,
-                display_tz_pref_override=display_tz_pref_override,
-                precompute_envelope=True, runtime_bind=runtime_bind,
-            )
-            if skip_sync:
-                # Mirror the startup override: suppress the monotonic sync
-                # stamp so the envelope keeps emitting sync_age_s=None and
-                # the client keeps rendering "sync paused" after the user
-                # hits r / clicks the sync chip.
-                snap = dataclasses.replace(snap, last_sync_at=None)
+            if not skip_sync:
+                # ── Decoupled ingest + build (§2.1) ─────────────────────────
+                import time as _time
+                sync_error = None
+                start = _time.monotonic()
+                throttle = _A2ThrottleClock(_A2_PARTIAL_THROTTLE_S, start=start)
+                cb = _make_a2_progress_cb(
+                    ref=ref, hub=hub,
+                    build_partial=lambda: _build(skip_sync=True),
+                    throttle=throttle, monotonic=_time.monotonic,
+                )
+                cache_conn = _cctally().open_cache_db()
+                try:
+                    # Under CCTALLY_PERF_TRACE the phase tree this standalone
+                    # sync_cache builds is intentionally NOT surfaced in the live
+                    # dashboard trace: the final _build(skip_sync=True) below runs
+                    # _tui_build_snapshot, which resets the thread perf stack, so
+                    # these phases never reach an emitter. §0's trace-attribution
+                    # target is `cctally-bench --trace`, which builds directly
+                    # (no decoupled standalone ingest) and keeps its phase tree.
+                    sync_cache(cache_conn, progress=cb)
+                except Exception as exc:  # noqa: BLE001 — surfaced on the snap
+                    sync_error = f"sync-cache: {exc}"
+                finally:
+                    cache_conn.close()
+                snap = _build(skip_sync=True)  # final: hydrating=False (default)
+                if sync_error is not None:
+                    # Thread the standalone sync error into last_sync_error, sync
+                    # error FIRST (mirrors the internal path where the `sync`
+                    # phase's error is errors[0]) so the surface is unchanged.
+                    existing = snap.last_sync_error
+                    merged = (sync_error if not existing
+                              else f"{sync_error}; {existing}")
+                    snap = dataclasses.replace(snap, last_sync_error=merged)
+                ref.set(snap)
+                hub.publish(snap)
+                return
+            # ── skip_sync=True: single-build path (POST /api/settings) ──────
+            snap = _build(skip_sync=True)
+            # Mirror the startup override: suppress the monotonic sync stamp so
+            # the envelope keeps emitting sync_age_s=None and the client keeps
+            # rendering "sync paused" after the user hits r / clicks the sync
+            # chip. #278 §1.4.1: force the hydration latch clear (default False
+            # from _tui_build_snapshot, restated here since this is a replace()
+            # clone site).
+            snap = dataclasses.replace(snap, last_sync_at=None, hydrating=False)
             ref.set(snap)
             hub.publish(snap)
         except Exception as exc:
@@ -5134,6 +5359,10 @@ def _make_run_sync_now_locked(*, ref, hub, pinned_now, display_tz_pref_override,
                 prev,
                 last_sync_error=f"sync crashed: {exc}",
                 generated_at=dt.datetime.now(dt.timezone.utc),
+                # #278 §1.4.1: a crash-carry snapshot is stable (not mid-
+                # assembly); clear the latch even if ``prev`` was a hydrating
+                # seed/partial, so the client doesn't stay stuck in skeletons.
+                hydrating=False,
             )
             ref.set(crashed)
             hub.publish(crashed)
@@ -5500,6 +5729,10 @@ def _tui_render_once(
             )
         except Exception:
             snap = _tui_empty_snapshot(now_utc)
+        # #276 perf: flush the snapshot phase tree to stderr when tracing is on
+        # (the rendered frame still goes to stdout only). No-op when off.
+        if _perf.enabled():
+            _perf.flush_stderr(_perf.current_root())
 
     # --- Render -----------------------------------------------------------
     # Drift guards run at module import + inside _tui_build_theme itself,