cctally 1.8.1 → 1.8.2

package/CHANGELOG.md

@@ -5,6 +5,17 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.8.2] - 2026-05-18
+
+### Added
+- dashboard envelope: new `blocks.total_cost_usd` and `blocks.total_tokens` fields exposed alongside `blocks.rows[]` so `BlocksPanel` reads the footer total from the envelope instead of running `rows.reduce((acc, r) => acc + r.cost_usd, 0)` in JS. Additive — pre-#56 envelopes without the fields fall back to `?? 0` so first-paint stays stable. Sourced from the new `BlocksView.total_cost_usd` / `total_tokens` view-model fields populated by `build_blocks_view` at sync-thread time.
+
+### Changed
+- view-model kernel: extend `bin/_lib_view_models.py` with `BlocksView` and two builders — `build_blocks_view(entries, …)` for the heuristic-aware path (`cmd_blocks` + dashboard Blocks panel) and `build_blocks_view_from_table_rows(rows, …)` for the API-anchored path (`cmd_five_hour_blocks` + share snapshot). Both return the same `BlocksView` dataclass (`rows: tuple[BlocksPanelRow, …]` + `aggregated: tuple` + totals + period metadata). `cmd_blocks`, `_dashboard_build_blocks_panel`, and `_build_five_hour_blocks_snapshot` now all route through the kernel; `BlocksPanelRow` moves from `bin/_cctally_tui.py` to `bin/_lib_view_models.py` alongside the other panel row dataclasses (re-exported from `_cctally_tui` for back-compat). Reset-aware totals invariant preserved (API-anchored path reads `five_hour_blocks.total_cost_usd` straight from the table — not recomputed from `session_entries`). Closes #56.
+- view-model kernel: extend `bin/_lib_view_models.py` with `ForecastView` + `build_forecast_view(conn, *, now_utc, targets, skip_sync, display_tz)` wrapping the existing `_load_forecast_inputs` + `_compute_forecast` math kernel. The View carries the wrapped `ForecastOutput` plus surface fields the dashboard envelope adapter used to re-derive inline — per-method projections (`week_avg_projection_pct` / `recent_24h_projection_pct`), `verdict` (TUI design language) / `dashboard_verdict` (cap/capped/ok), `header_projection_pct` (the "pick pessimistic when verdict warns" routing so the header pct and verdict pill agree), the (100%, 90%) budget pair, and `low_confidence` / `low_confidence_reasons`. `cmd_forecast`, `_tui_build_forecast`, `snapshot_to_envelope`, and `_build_forecast_share_panel_data` now all route through the View instead of duplicating the projection / verdict / budget routing across three call sites; the legacy inline routing in `snapshot_to_envelope` is retained as a fallback for fixture snapshots that construct `DataSnapshot` positionally without populating `forecast_view`. Envelope contract unchanged — byte-stable across all 27 forecast harness scenarios + 18 dashboard scenarios + 1124 pytest tests. Closes #57.
+- view-model kernel: extend `bin/_lib_view_models.py` with `CodexDailyView` / `CodexMonthlyView` / `CodexWeeklyView` / `CodexSessionView` + their four `build_codex_{daily,monthly,weekly,session}_view(entries, *, now_utc, tz_name, …)` builders, wrapping the existing `_aggregate_codex_{daily,monthly,weekly,sessions}` math kernel without changing it. The intentional Codex divergences from upstream (LiteLLM token semantics where `input_tokens` includes `cached_input_tokens` and `output_tokens` includes `reasoning_output_tokens`, the `info.total_token_usage.total_tokens` monotonic-advance dedup, `codex-session` descending-by-`last_activity` default, `--offline` no-op, and the `CODEX_LEGACY_FALLBACK_MODEL = "gpt-5"` one-shot stderr warning) are preserved end-to-end since the builders delegate to the same aggregator entrypoints. The Codex domain has no dashboard panel or share consumer, so each View carries `rows: tuple[CodexBucketUsage | CodexSessionUsage, …]` (the aggregator's typed output IS the surface) plus totals and `display_tz_label` — no parallel typed row dataclass is needed (`TrendView.rows` precedent). `cmd_codex_daily` / `cmd_codex_monthly` / `cmd_codex_weekly` / `cmd_codex_session` now route through the kernel; the `--order` reversal and per-mode no-data sentinel + JSON/table rendering paths stay in the CLI consumer. Byte-stable across all 27 codex harness scenarios (`codex-daily` 12/12, `codex-monthly` 4/4, `codex-weekly` 4/4, `codex-session` 7/7). Closes #58.
+- view-model kernel: extend `TrendView` in `bin/_lib_view_models.py` with a pre-computed `median_dpp_non_current_4w: float | None` scalar — the dashboard Trend modal's "4-week median" hero KV used to derive this client-side via `median4NonCurrent` in `dashboard/web/src/modals/TrendModal.tsx`. The rule (drop the current row, keep finite dpp values, sort the last 4 ascending, take the midpoint `(s[1]+s[2])/2`, `None` when fewer than 4 valid non-current samples) now lives in `build_trend_view` so a future change ports across CLI / TUI / dashboard / share in one edit. The sync thread captures the 12-row history's `TrendView` (via new `_tui_build_weekly_history_view` sibling — same forecast-pattern wrap as `_tui_build_forecast_view`) and threads the scalar onto `DataSnapshot.trend_history_median_dpp`. `snapshot_to_envelope` adds an additive `trend.history_median_dpp` field on the envelope (additive contract — older snapshots that omit it fall back to the client-side `median4NonCurrentFallback` helper in TrendModal.tsx). All 18 dashboard harness scenarios regenerated to include the new field; rest of the suite (1004/0 + pytest PASS) unchanged. Closes #59.
+
 ## [1.8.1] - 2026-05-18
 
 ### Fixed

package/bin/_cctally_dashboard.py

@@ -1350,13 +1350,16 @@ def _build_forecast_share_panel_data(options: dict,
                                       snap: "DataSnapshot | None") -> dict:
     """Forecast panel_data — projection + per-day budgets + days-to-ceiling.
 
-    Reuses `DataSnapshot.forecast` (ForecastOutput).
-    `projection_curve` is synthesized from `r_avg` / `r_recent` /
-    `inputs.p_now` — the same arithmetic `snapshot_to_envelope` does for
-    `week_avg_projection_pct` / `recent_24h_projection_pct`, extended
-    across the next 7 days.
+    Reuses ``DataSnapshot.forecast`` (ForecastOutput) and, when populated
+    by the sync thread, ``DataSnapshot.forecast_view`` (the kernel
+    wrapper from issue #57) for the (100, 90) budget pair.
+    ``projection_curve`` is synthesized from ``r_avg`` / ``r_recent`` /
+    ``inputs.p_now`` — the same arithmetic ``snapshot_to_envelope`` does
+    for ``week_avg_projection_pct`` / ``recent_24h_projection_pct``,
+    extended across the next 7 days.
     """
     fc = getattr(snap, "forecast", None) if snap else None
+    fc_view = getattr(snap, "forecast_view", None) if snap else None
     if fc is None:
         return {
             "projected_end_pct":  0.0,
@@ -1388,16 +1391,26 @@ def _build_forecast_share_panel_data(options: dict,
         return max(0.0, hours / 24.0)
     days_to_100 = _days_to_ceiling(100.0)
     days_to_90 = _days_to_ceiling(90.0)
-    # Daily budgets — pull from fc.budgets[] when present
+    # Daily budgets — prefer ForecastView's pre-routed pair (issue #57)
+    # when available; otherwise replay the legacy ``fc.budgets`` scan
+    # inline so positionally-constructed fixture snapshots still work.
     budgets: dict = {"avg": 0.0, "recent_24h": 0.0,
                      "until_90pct": 0.0, "until_100pct": 0.0}
-    for b in getattr(fc, "budgets", None) or []:
-        tp = getattr(b, "target_percent", None)
-        dpd = float(getattr(b, "dollars_per_day", 0.0) or 0.0)
-        if tp == 100:
-            budgets["until_100pct"] = dpd
-        elif tp == 90:
-            budgets["until_90pct"] = dpd
+    if fc_view is not None:
+        budgets["until_100pct"] = float(
+            fc_view.budget_100_per_day_usd or 0.0,
+        )
+        budgets["until_90pct"] = float(
+            fc_view.budget_90_per_day_usd or 0.0,
+        )
+    else:
+        for b in getattr(fc, "budgets", None) or []:
+            tp = getattr(b, "target_percent", None)
+            dpd = float(getattr(b, "dollars_per_day", 0.0) or 0.0)
+            if tp == 100:
+                budgets["until_100pct"] = dpd
+            elif tp == 90:
+                budgets["until_90pct"] = dpd
     # avg / recent_24h: derive from dollars-per-percent × r_avg/r_recent.
     dpp = float(getattr(inputs, "dollars_per_percent", 0.0) or 0.0) if inputs else 0.0
     budgets["avg"] = dpp * r_avg * 24.0
@@ -2138,20 +2151,31 @@ def _build_block_detail(block: "Block",
     }
 
 
-def _dashboard_build_blocks_panel(conn: "sqlite3.Connection",
-                                   now_utc: "dt.datetime",
-                                   *,
-                                   week_start_at: "dt.datetime",
-                                   week_end_at: "dt.datetime",
-                                   skip_sync: bool = False,
-                                   display_tz: "ZoneInfo | None" = None) -> "list[BlocksPanelRow]":
-    """Activity blocks (`is_gap=False`) inside ``[week_start_at, week_end_at)``,
-    newest-first.
-
-    Mirrors the recorded-windows-widening trick used by ``cmd_blocks``: loads
-    recorded reset windows from ``[start - BLOCK_DURATION, end + BLOCK_DURATION]``
-    so a recorded reset just outside the visible window can still anchor
-    blocks inside it.
+def _dashboard_build_blocks_view(conn: "sqlite3.Connection",
+                                  now_utc: "dt.datetime",
+                                  *,
+                                  week_start_at: "dt.datetime",
+                                  week_end_at: "dt.datetime",
+                                  skip_sync: bool = False,
+                                  display_tz: "ZoneInfo | None" = None):
+    """Build a ``BlocksView`` for the dashboard Blocks panel window
+    ``[week_start_at, week_end_at)`` (issue #56).
+
+    Two-layer composition (mirrors `_dashboard_build_daily_panel`'s
+    pattern):
+
+    1. ``build_blocks_view`` (in ``bin/_lib_view_models.py``) is the
+       data plane — `_group_entries_into_blocks` plus per-block model
+       enrichment plus totals derivation.
+    2. This function is the presentation adapter — owns the
+       recorded-windows-widening trick (loads reset windows from
+       ``[start - BLOCK_DURATION, end + BLOCK_DURATION]`` so a recorded
+       reset just outside the visible window can still anchor blocks
+       inside it) and the strict-window entry filter.
+
+    Returning the full ``BlocksView`` (rows + totals) lets the sync
+    thread populate ``DataSnapshot.blocks_total_cost_usd`` /
+    ``blocks_total_tokens`` for the envelope without a second pass.
     """
     # Widen the entry window slightly so a recorded-reset window straddling
     # the boundary still picks up its entries.
@@ -2163,52 +2187,42 @@ def _dashboard_build_blocks_panel(conn: "sqlite3.Connection",
     recorded_windows, block_start_overrides = _load_recorded_five_hour_windows(
         fetch_start, fetch_end,
     )
-    blocks = _group_entries_into_blocks(
-        entries, mode="auto",
+    c = _cctally()
+    return c.build_blocks_view(
+        entries,
+        now_utc=now_utc,
         recorded_windows=recorded_windows,
         block_start_overrides=block_start_overrides,
-        now=now_utc,
+        range_start=week_start_at,
+        range_end=week_end_at,
+        display_tz=display_tz,
+        mode="auto",
     )
-    blocks = [b for b in blocks if not b.is_gap]
-    if not blocks:
-        return []
 
-    # Build per-block model-cost breakdown (matches _model_breakdowns_to_models
-    # input shape: dicts with `modelName` / `cost` keys, sorted desc by cost).
-    rows: list[BlocksPanelRow] = []
-    for b in blocks:
-        # Reaggregate the entries inside [b.start_time, b.end_time) for
-        # the model-split. _group_entries_into_blocks gives us total
-        # cost_usd per block but not per-model breakdown. Use
-        # `_calculate_entry_cost` (the single source-of-truth pricing
-        # path) so block per-model costs reconcile exactly with the
-        # block's own cost_usd.
-        per_model: dict[str, float] = {}
-        for e in entries:
-            if b.start_time <= e.timestamp < b.end_time:
-                cost = _calculate_entry_cost(
-                    e.model, e.usage, mode="auto", cost_usd=e.cost_usd,
-                )
-                per_model[e.model] = per_model.get(e.model, 0.0) + cost
-        model_breakdowns = [
-            {"modelName": name, "cost": cost}
-            for name, cost in sorted(per_model.items(), key=lambda kv: -kv[1])
-        ]
-        local_label = format_display_dt(
-            b.start_time, display_tz, fmt="%H:%M %b %d", suffix=True,
-        )
-        rows.append(BlocksPanelRow(
-            start_at=b.start_time.astimezone(dt.timezone.utc).isoformat(),
-            end_at=b.end_time.astimezone(dt.timezone.utc).isoformat(),
-            anchor=b.anchor,
-            is_active=bool(b.is_active and b.entries_count > 0),
-            cost_usd=b.cost_usd,
-            models=_model_breakdowns_to_models(model_breakdowns, b.cost_usd),
-            label=local_label,
-        ))
-
-    rows.sort(key=lambda r: r.start_at, reverse=True)
-    return rows
+
+def _dashboard_build_blocks_panel(conn: "sqlite3.Connection",
+                                   now_utc: "dt.datetime",
+                                   *,
+                                   week_start_at: "dt.datetime",
+                                   week_end_at: "dt.datetime",
+                                   skip_sync: bool = False,
+                                   display_tz: "ZoneInfo | None" = None) -> "list[BlocksPanelRow]":
+    """Activity blocks (`is_gap=False`) inside ``[week_start_at, week_end_at)``,
+    newest-first.
+
+    Thin presentation shim over ``_dashboard_build_blocks_view`` —
+    returns just ``view.rows`` so existing call sites (sync thread,
+    share-data override resolver, monkeypatch surfaces) keep their
+    ``list[BlocksPanelRow]`` contract.
+    """
+    view = _dashboard_build_blocks_view(
+        conn, now_utc,
+        week_start_at=week_start_at,
+        week_end_at=week_end_at,
+        skip_sync=skip_sync,
+        display_tz=display_tz,
+    )
+    return list(view.rows)
 
 
 def _dashboard_build_daily_panel(conn: "sqlite3.Connection",
@@ -2662,6 +2676,16 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     """
     cw = snap.current_week
     fc = snap.forecast
+    # Issue #57 — prefer ``snap.forecast_view`` (precomputed by the
+    # sync thread via ``build_forecast_view``) over re-deriving the
+    # projection / verdict / header-routing / budget fields inline.
+    # Falls back to the legacy inline routing below when
+    # ``forecast_view`` is missing — fixture modules that construct
+    # ``DataSnapshot`` positionally without the post-Bundle-1 fields
+    # leave it at ``None``, and their goldens predate the View so
+    # keeping the legacy path under that fallback preserves byte
+    # stability.
+    fc_view = getattr(snap, "forecast_view", None)
 
     # F1 fix: server-resolve the display tz to a CONCRETE IANA name and
     # surface it on the envelope so the browser never has to guess "local".
@@ -2690,19 +2714,35 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     five_hr  = getattr(cw, "five_hour_pct", None) if cw is not None else None
     dollar_pp = getattr(cw, "dollars_per_percent", None) if cw is not None else None
 
-    # Forecast fields: route each projection by method identity from
-    # r_avg / r_recent and inputs.{p_now, remaining_hours}. Don't use
-    # final_percent_{low,high} directly — those are numerical min/max of
-    # the two methods, which swaps the labels on decelerating weeks
-    # (r_recent < r_avg). Map defensively via getattr — the JS only
-    # needs the values, not the internal structure.
+    # Forecast field routing (issue #57). ``snap.forecast_view`` is the
+    # single source of truth: ``build_forecast_view`` runs the per-
+    # method projection / verdict / budget routing once and stashes
+    # the surface fields on the View. The legacy inline derivation
+    # remains as a fallback for fixture modules that construct
+    # ``DataSnapshot`` positionally without populating ``forecast_view``
+    # — their goldens predate the View, and the legacy block emits
+    # the same numbers so byte stability is preserved.
     fcast_pct: "float | None" = None
     recent_24h_pct: "float | None" = None
     verdict: "str | None" = None
     confidence: "str | None" = None
     budget_100: "float | None" = None
     budget_90: "float | None" = None
-    if fc is not None:
+    if fc_view is not None:
+        fcast_pct = fc_view.week_avg_projection_pct
+        recent_24h_pct = fc_view.recent_24h_projection_pct
+        # ForecastView.dashboard_verdict / .confidence default to
+        # ``"ok"`` / ``"unknown"`` even when ``output is None``; only
+        # surface non-None envelope values when there's an actual
+        # ForecastOutput backing them so the existing
+        # ``verdict / confidence is None when fc is None`` shape stays.
+        verdict = fc_view.dashboard_verdict if fc is not None else None
+        confidence = fc_view.confidence if fc is not None else None
+        budget_100 = fc_view.budget_100_per_day_usd
+        budget_90 = fc_view.budget_90_per_day_usd
+    elif fc is not None:
+        # Legacy inline routing — kept verbatim for positionally-
+        # constructed fixture snapshots that don't carry ``forecast_view``.
         inputs = getattr(fc, "inputs", None)
         if inputs is not None:
             confidence = getattr(inputs, "confidence", None)
@@ -2715,11 +2755,8 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         if (p_now is not None and rem_hrs is not None
                 and r_recent is not None):
             p_final_recent = p_now + r_recent * rem_hrs
-            # Only emit recent_24h when the two projections diverge — if
-            # r_recent equals r_avg the second method added no info.
             if fcast_pct is None or p_final_recent != fcast_pct:
                 recent_24h_pct = p_final_recent
-        # Verdict — simple mapping: "cap" if projected_cap, else "ok".
         if getattr(fc, "already_capped", False):
             verdict = "capped"
         elif getattr(fc, "projected_cap", False):
@@ -2773,20 +2810,23 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         reset_at_utc = we
 
     # Header forecast_pct should match the projection that drove the
-    # verdict pill next to it. When the verdict warns (projected to
-    # cap or already capped) and the recent-24h projection is higher
-    # than the week-average path, surface the pessimistic value so
-    # the number and the pill tell the same story. The Forecast panel
-    # still exposes both `week_avg_projection_pct` and
-    # `recent_24h_projection_pct` unchanged.
-    header_fcast_pct = fcast_pct
-    if (
-        verdict in ("cap", "capped")
-        and recent_24h_pct is not None
-        and fcast_pct is not None
-        and recent_24h_pct > fcast_pct
-    ):
-        header_fcast_pct = recent_24h_pct
+    # verdict pill next to it. The View (issue #57) carries the
+    # already-routed ``header_projection_pct``; the fallback path
+    # replays the legacy routing inline for fixture snapshots that
+    # don't populate ``forecast_view``. The Forecast panel still
+    # exposes both ``week_avg_projection_pct`` and
+    # ``recent_24h_projection_pct`` unchanged.
+    if fc_view is not None and fc is not None:
+        header_fcast_pct = fc_view.header_projection_pct
+    else:
+        header_fcast_pct = fcast_pct
+        if (
+            verdict in ("cap", "capped")
+            and recent_24h_pct is not None
+            and fcast_pct is not None
+            and recent_24h_pct > fcast_pct
+        ):
+            header_fcast_pct = recent_24h_pct
 
     # ---- weekly / monthly periods ---------------------------------
     def _weekly_row_to_dict(r: "WeeklyPeriodRow") -> dict:
@@ -2877,7 +2917,18 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         "total_tokens":   snap.monthly_total_tokens,
     }
 
-    blocks_env = {"rows": [_blocks_row_to_dict(r) for r in snap.blocks_panel]}
+    blocks_env = {
+        "rows": [_blocks_row_to_dict(r) for r in snap.blocks_panel],
+        # View-model unification follow-up (issue #56): additive scalars
+        # so the React BlocksPanel can stop running `rows.reduce(...)`
+        # in JS. Cost is summed-over-visible-rows in
+        # `_dashboard_build_blocks_view` (same structural invariant as
+        # daily/weekly/monthly footers); ``total_tokens`` is sourced
+        # from the same view since ``BlocksPanelRow`` doesn't carry
+        # token columns and we don't want to widen that shape.
+        "total_cost_usd": snap.blocks_total_cost_usd,
+        "total_tokens":   snap.blocks_total_tokens,
+    }
 
     # Re-run helper to derive thresholds; mutates rows[*].intensity_bucket
     # (no-op for builder-constructed rows since values match cost_usd).
@@ -3106,11 +3157,20 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
                     for w in (snap.weekly_history or [])
                 ],
                 # View-model unification (Bundle 1; spec §6.6): the
-                # pre-computed 3-sample $/% mean. TrendPanel can stop
-                # re-deriving the panel-average; TrendModal's median
-                # over trend.history is out of scope for this refactor
-                # (separate dataset, separate follow-up).
+                # pre-computed 3-sample $/% mean. TrendPanel reads this
+                # instead of re-deriving the panel-average.
                 "avg_dollars_per_pct": snap.trend_avg_dollars_per_pct,
+                # Issue #59 follow-up: pre-computed 4-week-median of
+                # non-current ``dollars_per_percent`` over the 12-row
+                # history. TrendModal.tsx's ``median4NonCurrent`` helper
+                # used to compute this client-side; pre-computing on
+                # ``build_trend_view`` keeps the rule
+                # (``sort(last 4 non-current dpps)``, midpoint
+                # ``(s[1]+s[2])/2``) in one place. ``None`` when fewer
+                # than 4 valid non-current samples — modal's client-side
+                # fallback handles the ``null`` case.
+                "history_median_dpp":
+                    getattr(snap, "trend_history_median_dpp", None),
             },
 
         "weekly":  weekly_env,

package/bin/_cctally_tui.py

@@ -329,6 +329,10 @@ def _dashboard_build_blocks_panel(*args, **kwargs):
     return sys.modules["cctally"]._dashboard_build_blocks_panel(*args, **kwargs)
 
 
+def _dashboard_build_blocks_view(*args, **kwargs):
+    return sys.modules["cctally"]._dashboard_build_blocks_view(*args, **kwargs)
+
+
 def _dashboard_build_daily_panel(*args, **kwargs):
     return sys.modules["cctally"]._dashboard_build_daily_panel(*args, **kwargs)
 
@@ -822,27 +826,15 @@ from _lib_view_models import (  # noqa: E402
 )
 
 
-@dataclass
-class BlocksPanelRow:
-    """One row of the dashboard's Blocks panel.
-
-    Subset of the `Block` dataclass — drops token counts (panel is
-    cost-driven; tokens belong to a future modal), drops `entries_count`
-    / `is_gap` / `burn_rate` / `projection` (panel doesn't render them),
-    and pre-formats `label` server-side for the local-tz "HH:MM MMM DD"
-    display.
-    """
-    start_at: str          # ISO-8601 UTC
-    end_at: str            # ISO-8601 UTC, start_at + 5h
-    anchor: str            # 'recorded' | 'heuristic'
-    is_active: bool        # now_utc < end_at AND entries_count > 0
-    cost_usd: float
-    models: list[dict[str, Any]]   # ModelCostRow shape, sorted desc by cost
-    label: str             # "HH:MM MMM DD" in local tz, e.g. "14:00 Apr 26"
-
-
-# DailyPanelRow + TuiSessionRow moved to bin/_lib_view_models.py — re-export.
-from _lib_view_models import DailyPanelRow, TuiSessionRow  # noqa: E402
+# BlocksPanelRow + DailyPanelRow + TuiSessionRow moved to
+# bin/_lib_view_models.py — re-exported here so historical
+# ``from _cctally_tui import BlocksPanelRow`` (or ``ns["BlocksPanelRow"]``
+# direct-dict reads in tests) keep resolving.
+from _lib_view_models import (  # noqa: E402
+    BlocksPanelRow,
+    DailyPanelRow,
+    TuiSessionRow,
+)
 
 
 @dataclass
@@ -1043,7 +1035,32 @@ class DataSnapshot:
     monthly_total_tokens: int = 0
     weekly_total_cost_usd: float = 0.0
     weekly_total_tokens: int = 0
+    # Blocks domain (issue #56). ``BlocksPanelRow`` doesn't carry token
+    # columns, so the cost total alone preserves the structural
+    # ``total === sum(visible rows).cost_usd`` invariant; ``blocks_total_tokens``
+    # is sourced from the same ``BlocksView`` build so both scalars
+    # come from a single typed pass.
+    blocks_total_cost_usd: float = 0.0
+    blocks_total_tokens: int = 0
     trend_avg_dollars_per_pct: float | None = None
+    # Trend modal median (issue #59). Sourced from
+    # ``build_trend_view``'s ``median_dpp_non_current_4w`` field — the
+    # last-4-non-current dpp median TrendModal.tsx used to compute
+    # client-side. Populated by the sync thread off the 12-row history
+    # build (NOT the 8-row panel build); the dashboard envelope adapter
+    # emits this as ``trend.history_median_dpp``. ``None`` for fixture
+    # modules that construct ``DataSnapshot`` positionally without
+    # going through ``_tui_build_snapshot``; the React modal keeps a
+    # client-side fallback for that case.
+    trend_history_median_dpp: float | None = None
+    # Forecast domain (issue #57). ``ForecastView`` wraps
+    # ``ForecastOutput`` and surfaces the per-method projection /
+    # verdict / header-routing / budget fields the dashboard envelope
+    # adapter used to re-derive inline. Field is ``None`` for fixture
+    # modules that construct ``DataSnapshot`` directly without going
+    # through ``_tui_build_snapshot``; the envelope adapter falls
+    # back to the legacy inline routing in that case.
+    forecast_view: Any | None = None
 
     @classmethod
     def synthesize_for_marketing(cls, *, as_of_iso: str) -> "DataSnapshot":
@@ -1426,11 +1443,32 @@ def _tui_build_forecast(
     *,
     skip_sync: bool = False,
 ):
-    """Call into existing forecast internals. Returns a ForecastOutput or None."""
-    inputs = _load_forecast_inputs(conn, now_utc, skip_sync=skip_sync)
-    if inputs is None:
-        return None
-    return _compute_forecast(inputs, [100, 90])
+    """Build the TUI/dashboard sync-thread forecast.
+
+    Issue #57: routes through ``build_forecast_view`` (the kernel-pattern
+    wrapper) and unwraps to a ``ForecastOutput`` for backward-compat with
+    every existing ``snap.forecast`` consumer (TUI panels, envelope
+    adapter, share builder). Use ``_tui_build_forecast_view`` when the
+    full view is needed (e.g. ``snap.forecast_view`` population).
+    """
+    view = _tui_build_forecast_view(conn, now_utc, skip_sync=skip_sync)
+    return view.output if view is not None else None
+
+
+def _tui_build_forecast_view(
+    conn: sqlite3.Connection,
+    now_utc: dt.datetime,
+    *,
+    skip_sync: bool = False,
+):
+    """Build the ``ForecastView`` (issue #57). Returns ``None`` only on
+    error in callers — the empty-state View is constructed by the
+    builder itself with ``output=None`` + ``verdict="LOW CONF"``.
+    """
+    c = _cctally()
+    return c.build_forecast_view(
+        conn, now_utc=now_utc, targets=(100, 90), skip_sync=skip_sync,
+    )
 
 
 def _tui_build_trend(
@@ -1470,9 +1508,46 @@ def _tui_build_weekly_history(
     than parameterising the call site keeps the snapshot fields
     semantically distinct (panel data vs. modal data) and avoids
     accidental cross-contamination.
+
+    Issue #59: list-returning shim kept for back-compat with the
+    public re-export at ``bin/cctally:13871``. New callers (the sync
+    thread populating ``snap.weekly_history`` + the modal-median
+    scalar) should prefer ``_tui_build_weekly_history_view`` so they
+    pick up the pre-computed ``median_dpp_non_current_4w`` scalar
+    without re-deriving.
+    """
+    return list(
+        _tui_build_weekly_history_view(
+            conn, now_utc, skip_sync=skip_sync, count=count,
+            display_tz=display_tz,
+        ).rows
+    )
+
+
+def _tui_build_weekly_history_view(
+    conn: sqlite3.Connection,
+    now_utc: dt.datetime,
+    *,
+    skip_sync: bool = False,                # noqa: ARG001 — unused today, kept for API symmetry
+    count: int = 12,
+    display_tz: "ZoneInfo | None" = None,
+):
+    """Build the full ``TrendView`` for the dashboard Trend modal
+    (issue #59).
+
+    Wraps ``build_trend_view`` with the 12-row default the modal
+    consumes. The returned ``TrendView`` carries the
+    ``median_dpp_non_current_4w`` pre-computed scalar so the sync
+    thread can populate ``DataSnapshot.trend_history_median_dpp``
+    without re-running the median derivation client-side. The 8-row
+    panel call (``_tui_build_trend``) goes through the same
+    ``build_trend_view`` kernel; both builds carry their own median
+    field but only the 12-row build's value reaches the envelope
+    (``trend.history_median_dpp``).
     """
-    return _tui_build_trend(
-        conn, now_utc, skip_sync=skip_sync, count=count, display_tz=display_tz,
+    c = _cctally()
+    return c.build_trend_view(
+        conn, now_utc=now_utc, n=max(1, count), display_tz=display_tz,
     )
 
 
@@ -1651,8 +1726,14 @@ def _tui_build_snapshot(
             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:
-            fc = _tui_build_forecast(conn, now_utc, skip_sync=skip_sync)
+            # 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)
+            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
@@ -1685,10 +1766,19 @@ def _tui_build_snapshot(
                 milestones = _tui_build_percent_milestones(conn)
         except Exception as exc:
             errors.append(f"milestones: {exc}")
+        history: list = []
+        history_median_dpp: "float | None" = None
         try:
-            history = _tui_build_weekly_history(
+            # 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,
             )
+            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 ----
@@ -1742,15 +1832,25 @@ def _tui_build_snapshot(
         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
+        # pass. ``_dashboard_build_blocks_view`` is the view-returning
+        # counterpart to ``_dashboard_build_blocks_panel`` (which is
+        # 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_panel = _dashboard_build_blocks_panel(
+                _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):
@@ -1818,7 +1918,11 @@ def _tui_build_snapshot(
             monthly_total_tokens=monthly_total_tokens,
             weekly_total_cost_usd=weekly_total_cost_usd,
             weekly_total_tokens=weekly_total_tokens,
+            blocks_total_cost_usd=blocks_total_cost_usd,
+            blocks_total_tokens=blocks_total_tokens,
             trend_avg_dollars_per_pct=trend_avg_dpp,
+            trend_history_median_dpp=history_median_dpp,
+            forecast_view=fc_view,
         )
     finally:
         conn.close()
@@ -2218,6 +2322,16 @@ class _TuiSyncThread:
                 self._ref.set(snap)
             except Exception as exc:
                 # Don't crash the thread on unexpected errors — surface in UI.
+                # Carry every additive view-model scalar through verbatim so
+                # the prior frame's panel rows and their envelope totals stay
+                # consistent. Bundle 1 / #56 / #57 / #59 each added envelope
+                # scalars the React panels now trust over a client-side
+                # ``rows.reduce``; without preserving them here, a sync crash
+                # leaves populated rows next to a ``$0.00`` footer (the
+                # dataclass defaults kick in for any field not explicitly
+                # passed). The structural-equality invariant
+                # ``total === sum(visible rows).cost_usd`` must survive a
+                # crash recovery, not just the happy path.
                 prev = self._ref.get()
                 self._ref.set(DataSnapshot(
                     current_week=prev.current_week,
@@ -2233,6 +2347,17 @@ class _TuiSyncThread:
                     monthly_periods=prev.monthly_periods,
                     blocks_panel=prev.blocks_panel,
                     daily_panel=prev.daily_panel,
+                    daily_total_cost_usd=prev.daily_total_cost_usd,
+                    daily_total_tokens=prev.daily_total_tokens,
+                    monthly_total_cost_usd=prev.monthly_total_cost_usd,
+                    monthly_total_tokens=prev.monthly_total_tokens,
+                    weekly_total_cost_usd=prev.weekly_total_cost_usd,
+                    weekly_total_tokens=prev.weekly_total_tokens,
+                    blocks_total_cost_usd=prev.blocks_total_cost_usd,
+                    blocks_total_tokens=prev.blocks_total_tokens,
+                    trend_avg_dollars_per_pct=prev.trend_avg_dollars_per_pct,
+                    trend_history_median_dpp=prev.trend_history_median_dpp,
+                    forecast_view=prev.forecast_view,
                 ))
             # Wait up to interval, or until forced.
             for _ in range(int(max(1, self._interval * 10))):