cctally 1.8.1 → 1.8.2

package/bin/_lib_view_models.py

@@ -28,6 +28,23 @@ Frozen ``*View`` dataclasses + builders:
 - ``TrendView`` + ``build_trend_view(conn, *, now_utc, n, display_tz)``
 - ``SessionsView`` + ``build_sessions_view(entries, *, now_utc, limit,
   display_tz)``
+- ``BlocksView`` + ``build_blocks_view(entries, *, now_utc,
+  recorded_windows, block_start_overrides, range_start, range_end,
+  display_tz, mode)`` — heuristic-aware (cmd_blocks + dashboard); and
+  ``build_blocks_view_from_table_rows(block_dicts, *, period_start,
+  period_end, display_tz)`` — API-anchored (cmd_five_hour_blocks
+  share). Issue #56.
+- ``ForecastView`` + ``build_forecast_view(conn, *, now_utc, targets,
+  skip_sync, display_tz)`` — wraps the existing math kernel
+  (``_load_forecast_inputs`` + ``_compute_forecast``) and surfaces the
+  per-method projection / verdict / header-routing / budget fields
+  consumers used to re-derive. Issue #57.
+- ``CodexDailyView`` / ``CodexMonthlyView`` / ``CodexWeeklyView`` /
+  ``CodexSessionView`` + ``build_codex_{daily,monthly,weekly,session}_view``
+  — wrap the existing ``_aggregate_codex_*`` kernel; preserve the
+  intentional divergences from upstream (LiteLLM token semantics,
+  duplicate-event dedup, ``codex-session`` descending-by-last-activity,
+  ``CODEX_LEGACY_FALLBACK_MODEL`` warning). Issue #58.
 
 Each ``*View`` carries ``rows`` (typed row tuple) plus a parallel
 ``aggregated`` ``BucketUsage`` tuple where CLI byte-stable JSON requires
@@ -166,6 +183,29 @@ class MonthlyPeriodRow:
     models: list[dict[str, Any]]
 
 
+@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.
+
+    Moved from ``bin/_cctally_tui.py`` alongside ``DailyPanelRow`` so
+    the BlocksView builder can construct rows without an import edge
+    back into the TUI module.
+    """
+    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"
+
+
 @dataclass
 class DailyPanelRow:
     """One row of the dashboard's Daily heatmap panel.
@@ -625,6 +665,16 @@ class TrendView:
     dashboard envelope adapter emits it as ``trend.avg_dollars_per_pct``
     so the React layer doesn't re-derive.
 
+    ``median_dpp_non_current_4w`` is the median of the last 4 non-current
+    ``dollars_per_percent`` values (``None`` when fewer than 4 valid
+    samples). Matches the rule TrendModal.tsx's ``median4NonCurrent``
+    helper used to compute client-side; pre-computed on the View so
+    the dashboard envelope can surface it as
+    ``trend.history_median_dpp`` (issue #59). The 8-row panel call also
+    populates the field — but the dashboard envelope only surfaces the
+    12-row history's median (panel modal vs panel-wide are different
+    summaries).
+
     Row ordering matches ``cmd_report`` / ``_tui_build_trend``:
     chronological (oldest first), suitable for the TUI sparkline left-
     to-right walk + cmd_report's `--json` trend list (which is then
@@ -632,6 +682,7 @@ class TrendView:
     """
     rows: "tuple[TuiTrendRow, ...]" = ()        # oldest-first
     avg_dollars_per_pct: "float | None" = None
+    median_dpp_non_current_4w: "float | None" = None
     period_start: "dt.datetime | None" = None
     period_end: "dt.datetime | None" = None
     display_tz_label: str = ""
@@ -865,9 +916,45 @@ def build_trend_view(conn, *, now_utc, n=8, display_tz=None):
                   if r.dollars_per_percent is not None]
     avg = (sum(valid_dpps) / len(valid_dpps)) if len(valid_dpps) >= 3 else None
 
+    # Issue #59 — pre-compute the 4-week-median-non-current dpp scalar
+    # the dashboard's Trend modal hero KV displays. Rule mirrors
+    # ``TrendModal.tsx::median4NonCurrent`` byte-for-byte:
+    #   * Drop EXACTLY ONE row by index — the same row
+    #     ``findCurrentIndex`` would pick: the FIRST ``is_current``
+    #     row, or ``rows.length - 1`` (the last row) when no row is
+    #     marked current. This matters when (a) the Bug D credited-
+    #     week split emits two rows with the same ``current_key``
+    #     (both ``is_current=True``; we drop only the first) and (b)
+    #     cost-only histories with no usage snapshot have every row
+    #     ``is_current=False`` (we still drop the last row).
+    #   * Keep only non-None / finite dpp values.
+    #   * Take the LAST 4 (chronological-last, since ``rows`` is
+    #     oldest-first); sort ascending; return the midpoint
+    #     ``(s[1] + s[2]) / 2``.
+    # Returns ``None`` when fewer than 4 non-current valid samples
+    # remain (matches the modal's empty-state). The 8-row panel call
+    # populates this too — harmless because the envelope only surfaces
+    # the 12-row history's value.
+    if rows:
+        cur_idx = next(
+            (i for i, r in enumerate(rows) if r.is_current),
+            len(rows) - 1,
+        )
+    else:
+        cur_idx = -1
+    non_cur_dpps = [r.dollars_per_percent
+                    for i, r in enumerate(rows)
+                    if i != cur_idx and r.dollars_per_percent is not None]
+    if len(non_cur_dpps) >= 4:
+        last4 = sorted(non_cur_dpps[-4:])
+        median_dpp_4w = (last4[1] + last4[2]) / 2
+    else:
+        median_dpp_4w = None
+
     return TrendView(
         rows=tuple(rows),
         avg_dollars_per_pct=avg,
+        median_dpp_non_current_4w=median_dpp_4w,
         period_start=None,
         period_end=now_utc,
         display_tz_label=_display_tz_label(display_tz),
@@ -991,3 +1078,700 @@ def build_sessions_view(entries, *, now_utc, limit=None, display_tz=None):
         period_end=now_utc,
         display_tz_label=_display_tz_label(display_tz),
     )
+
+
+# === BlocksView + build_blocks_view (Issue #56) ============================
+
+
+@dataclass(frozen=True)
+class BlocksView:
+    """Blocks domain view — covers two structurally distinct paths under
+    one dataclass.
+
+    1. **Heuristic-aware** (``cmd_blocks`` + dashboard Blocks panel):
+       built via ``build_blocks_view(entries, ...)``. Calls
+       ``_lib_blocks._group_entries_into_blocks`` and fills BOTH
+       ``rows`` (``tuple[BlocksPanelRow, ...]`` — non-gap, dashboard-
+       shape, newest-first) and ``aggregated`` (``tuple[Block, ...]``
+       — gaps included, CLI-shape, oldest-first per
+       ``_group_entries_into_blocks``'s contract). ``total_cost_usd``
+       / ``total_tokens`` are summed over non-gap blocks so the React
+       panel's footer ``total === sum(visible rows)`` invariant holds.
+
+    2. **API-anchored** (``cmd_five_hour_blocks`` + share snapshot):
+       built via ``build_blocks_view_from_table_rows(rows, ...)``.
+       Reads sqlite-Row-derived dicts from the ``five_hour_blocks``
+       TABLE; leaves ``rows`` empty (consumers read ``aggregated``
+       directly). Reset-aware (CLAUDE.md 5-hour gotcha block,
+       spec §3.2) — totals come from the table's per-block columns,
+       NOT recomputed from ``session_entries``.
+
+    Both builders return BlocksView; consumers branch on which field
+    they need. ``period_start`` / ``period_end`` carry time-window
+    bounds (used by the share path's ``PeriodSpec`` and by future
+    consumers that need a period label).
+    """
+    rows: "tuple[BlocksPanelRow, ...]" = ()
+    aggregated: tuple = ()                    # tuple[Block, ...] for heuristic; tuple[dict, ...] for API-anchored. Forward-ref kept untyped to avoid an import-time edge into _lib_blocks.
+    total_cost_usd: float = 0.0
+    total_tokens: int = 0
+    period_start: "dt.datetime | None" = None
+    period_end: "dt.datetime | None" = None
+    display_tz_label: str = ""
+
+
+def build_blocks_view(
+    entries,
+    *,
+    now_utc,
+    recorded_windows=None,
+    block_start_overrides=None,
+    range_start=None,
+    range_end=None,
+    display_tz=None,
+    mode="auto",
+    skip_rows: bool = False,
+):
+    """Build a ``BlocksView`` from raw ``UsageEntry`` list (heuristic-
+    aware path; spec §6 blocks follow-up).
+
+    ``aggregated`` carries the full Block list (gaps included), in
+    oldest-first order — consumed by ``cmd_blocks`` via
+    ``_blocks_to_json`` / ``_render_blocks_table``. ``rows`` carries
+    non-gap ``BlocksPanelRow`` entries (newest-first) — consumed by
+    ``_dashboard_build_blocks_panel`` and the dashboard envelope
+    serializer.
+
+    Per-row enrichment for the dashboard rows uses
+    ``_lib_pricing._calculate_entry_cost`` (single pricing source-of-
+    truth, mirrors the historical inline body of
+    ``_dashboard_build_blocks_panel``). ``label`` is pre-formatted via
+    ``format_display_dt`` ("HH:MM MMM DD" in display_tz).
+
+    Totals are summed over non-gap blocks (gaps contribute zero by
+    construction — they carry zero cost / tokens). Caller-supplied
+    ``range_start`` / ``range_end`` override the period metadata when
+    provided (the CLI ``cmd_blocks`` --since/--until path passes them
+    explicitly; the dashboard path passes the week window).
+
+    ``skip_rows=True`` skips the dashboard-row construction loop
+    entirely — leaves ``view.rows = ()`` while still populating
+    ``aggregated`` + totals. The per-block per-model enrichment scans
+    every entry for every non-gap block (O(B × N)); the CLI
+    ``cmd_blocks`` reads only ``view.aggregated`` and discards rows,
+    so it opts in to skip that work on large histories. Dashboard /
+    share callers leave the default (``False``) to keep their
+    consumers fed.
+    """
+    _lib_blocks = _load_lib("_lib_blocks")
+    _lib_pricing = _load_lib("_lib_pricing")
+    c = _cctally()
+    blocks = _lib_blocks._group_entries_into_blocks(
+        entries,
+        mode=mode,
+        recorded_windows=recorded_windows,
+        block_start_overrides=block_start_overrides,
+        now=now_utc,
+    )
+    rows: list = []
+    total_cost = 0.0
+    total_tok = 0
+    if blocks:
+        for b in blocks:
+            if b.is_gap:
+                continue
+            if not skip_rows:
+                # Per-block per-model breakdown for the dashboard row.
+                # Mirrors `_dashboard_build_blocks_panel`'s historical
+                # inline body — re-aggregates entries inside the block
+                # interval through the single pricing chokepoint so per-
+                # model costs reconcile exactly with `b.cost_usd`.
+                per_model: dict[str, float] = {}
+                for e in entries:
+                    if b.start_time <= e.timestamp < b.end_time:
+                        cost = _lib_pricing._calculate_entry_cost(
+                            e.model, e.usage, mode=mode, 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 = c.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_late(
+                        model_breakdowns, b.cost_usd,
+                    ),
+                    label=local_label,
+                ))
+            total_cost += b.cost_usd
+            total_tok += b.total_tokens
+    rows.sort(key=lambda r: r.start_at, reverse=True)
+
+    # Period defaults: caller-supplied range wins; otherwise fall back
+    # to block extent (first block's start) so the share builder /
+    # period-label paths get a sensible window.
+    period_start_dt = range_start
+    if period_start_dt is None and blocks:
+        period_start_dt = blocks[0].start_time
+    period_end_dt = range_end or now_utc
+
+    return BlocksView(
+        rows=tuple(rows),
+        aggregated=tuple(blocks),
+        total_cost_usd=total_cost,
+        total_tokens=total_tok,
+        period_start=period_start_dt,
+        period_end=period_end_dt,
+        display_tz_label=_display_tz_label(display_tz),
+    )
+
+
+def build_blocks_view_from_table_rows(
+    block_dicts,
+    *,
+    period_start=None,
+    period_end=None,
+    display_tz=None,
+):
+    """Build a ``BlocksView`` from API-anchored ``five_hour_blocks``
+    table rows (issue #56 — share path).
+
+    Reset-aware totals (CLAUDE.md 5-hour gotcha block, spec §3.2):
+    ``total_cost_usd`` is summed from each row's ``total_cost_usd``
+    column (already credit-aware at write time);
+    ``total_tokens`` is summed across the four token columns
+    (``total_input_tokens`` + ``total_output_tokens`` +
+    ``total_cache_create_tokens`` + ``total_cache_read_tokens``).
+    No recomputation from ``session_entries`` — preserves the
+    write-time invariant that ``five_hour_blocks.total_cost_usd``
+    is the authoritative per-block cost.
+
+    ``rows`` is left empty — the API-anchored consumers
+    (``_five_hour_blocks_to_json``, ``_render_five_hour_blocks_table``,
+    ``_build_five_hour_blocks_snapshot``) read ``aggregated`` (the
+    underlying dict list) directly. ``BlocksPanelRow`` doesn't carry
+    the API-anchored extras (``final_five_hour_percent``,
+    ``crossed_seven_day_reset``, ``credits``, ...) so synthesizing
+    rows on this path would lose data.
+
+    ``block_dicts`` is consumed as-is; the caller controls ordering
+    (``cmd_five_hour_blocks`` produces newest-first DESC).
+    """
+    rows_seq = list(block_dicts)
+    total_cost = sum(
+        float(d.get("total_cost_usd") or 0.0) for d in rows_seq
+    )
+    total_tok = sum(
+        int(d.get("total_input_tokens") or 0)
+        + int(d.get("total_output_tokens") or 0)
+        + int(d.get("total_cache_create_tokens") or 0)
+        + int(d.get("total_cache_read_tokens") or 0)
+        for d in rows_seq
+    )
+    return BlocksView(
+        rows=(),
+        aggregated=tuple(rows_seq),
+        total_cost_usd=total_cost,
+        total_tokens=total_tok,
+        period_start=period_start,
+        period_end=period_end,
+        display_tz_label=_display_tz_label(display_tz),
+    )
+
+
+# === ForecastView + build_forecast_view (Issue #57) ========================
+
+
+_FORECAST_VERDICT_GOOD = "GOOD"
+_FORECAST_VERDICT_WARN = "WARN"
+_FORECAST_VERDICT_OVER = "OVER"
+_FORECAST_VERDICT_LOW_CONF = "LOW CONF"
+
+
+@dataclass(frozen=True)
+class ForecastView:
+    """Forecast domain view — wraps the existing math kernel.
+
+    Unlike the rows-shaped domain views, ``ForecastView`` projects a
+    *singular* week into the future. The wrapped ``output`` carries the
+    full ``ForecastOutput`` math result (inputs + r_avg + r_recent +
+    final_percent_{low,high} + budgets[] + cap_at), and the View
+    additively surfaces fields that consumers used to re-derive:
+
+    * ``verdict`` — TUI design-language mapping ("GOOD" / "WARN" /
+      "OVER" / "LOW CONF"). Mirrors ``_tui_verdict_of``.
+    * ``dashboard_verdict`` — dashboard envelope's mapping ("ok" /
+      "cap" / "capped"). Mirrors the per-method routing in
+      ``snapshot_to_envelope``.
+    * ``week_avg_projection_pct`` / ``recent_24h_projection_pct`` —
+      per-method projections from ``r_avg`` / ``r_recent``. The
+      recent-24h value is ``None`` when ``r_recent`` is ``None`` or its
+      projection equals ``week_avg_projection_pct`` (no new info).
+      Routing labels stay correct on decelerating weeks where
+      ``r_recent < r_avg``.
+    * ``header_projection_pct`` — "pick pessimistic when verdict
+      warns" routing the dashboard header runs. Surfaced once on the
+      view so the header field and the verdict pill always tell the
+      same story.
+    * ``budget_100_per_day_usd`` / ``budget_90_per_day_usd`` — the
+      matching ``BudgetRow.dollars_per_day`` values, ``None`` when the
+      target is out of headroom.
+    * ``confidence`` / ``low_confidence`` / ``low_confidence_reasons`` —
+      mirrors ``inputs.confidence``. Surfaced separately so callers can
+      key on ``view.low_confidence`` without crawling
+      ``view.output.inputs``.
+
+    ``output`` is ``None`` when ``_load_forecast_inputs`` returned
+    ``None`` (no current-week snapshot). The View still constructs in
+    that case so consumers can render an empty-state from a uniformly-
+    shaped object; ``verdict`` is then ``"LOW CONF"`` and the projection
+    / budget fields are ``None``.
+
+    ``period_start`` / ``period_end`` carry the subscription-week
+    bounds (``inputs.week_start_at`` / ``inputs.week_end_at``), mirroring
+    the other domain views.
+    """
+    output: Any | None = None                  # ForecastOutput | None — forward-ref kept untyped to avoid an import-time edge into cctally's dataclasses.
+    verdict: str = _FORECAST_VERDICT_LOW_CONF
+    dashboard_verdict: str = "ok"
+    confidence: str = "unknown"
+    low_confidence: bool = False
+    low_confidence_reasons: tuple = ()
+    week_avg_projection_pct: "float | None" = None
+    recent_24h_projection_pct: "float | None" = None
+    header_projection_pct: "float | None" = None
+    budget_100_per_day_usd: "float | None" = None
+    budget_90_per_day_usd: "float | None" = None
+    period_start: "dt.datetime | None" = None
+    period_end: "dt.datetime | None" = None
+    display_tz_label: str = ""
+    targets: tuple = ()
+
+
+def _forecast_verdict_of(output) -> str:
+    """Design-language verdict for a ``ForecastOutput``. Mirrors
+    ``_tui_verdict_of`` but lives on the view-model layer so consumers
+    don't have to round-trip through ``_cctally_tui``.
+
+    None output OR low confidence → ``"LOW CONF"``. Otherwise threshold
+    on ``final_percent_high``: ≥100 → OVER, ≥90 → WARN, else GOOD.
+    """
+    if output is None:
+        return _FORECAST_VERDICT_LOW_CONF
+    inputs = getattr(output, "inputs", None)
+    if inputs is not None and getattr(inputs, "confidence", "high") == "low":
+        return _FORECAST_VERDICT_LOW_CONF
+    high = float(getattr(output, "final_percent_high", 0.0))
+    if high >= 100:
+        return _FORECAST_VERDICT_OVER
+    if high >= 90:
+        return _FORECAST_VERDICT_WARN
+    return _FORECAST_VERDICT_GOOD
+
+
+def _forecast_dashboard_verdict_of(output) -> str:
+    """Dashboard-envelope verdict ("ok"/"cap"/"capped"). Pure helper
+    used by ``snapshot_to_envelope`` and ``build_forecast_view``."""
+    if output is None:
+        return "ok"
+    if getattr(output, "already_capped", False):
+        return "capped"
+    if getattr(output, "projected_cap", False):
+        return "cap"
+    return "ok"
+
+
+def _forecast_projection_pcts(output) -> "tuple[float | None, float | None]":
+    """Return (week_avg_projection_pct, recent_24h_projection_pct).
+
+    Decomposes the dual-method projections from ``r_avg`` / ``r_recent``
+    + ``inputs.p_now`` + ``inputs.remaining_hours``. Mirrors the routing
+    in ``snapshot_to_envelope``: recent-24h is ``None`` when ``r_recent``
+    is ``None`` or its projection equals the week-avg projection (no
+    new info — a second method that agrees with the first contributes
+    nothing to the user-facing range).
+    """
+    if output is None:
+        return None, None
+    inputs = getattr(output, "inputs", None)
+    if inputs is None:
+        return None, None
+    p_now = getattr(inputs, "p_now", None)
+    rem = getattr(inputs, "remaining_hours", None)
+    r_avg = getattr(output, "r_avg", None)
+    r_recent = getattr(output, "r_recent", None)
+    week_avg_pct = None
+    if p_now is not None and rem is not None and r_avg is not None:
+        week_avg_pct = p_now + r_avg * rem
+    recent_pct = None
+    if p_now is not None and rem is not None and r_recent is not None:
+        candidate = p_now + r_recent * rem
+        # Suppress the second projection only when it adds no info.
+        if week_avg_pct is None or candidate != week_avg_pct:
+            recent_pct = candidate
+    return week_avg_pct, recent_pct
+
+
+def _forecast_header_projection_pct(
+    week_avg_pct: "float | None",
+    recent_24h_pct: "float | None",
+    dashboard_verdict: str,
+) -> "float | None":
+    """Header field routing: when the verdict warns ("cap"/"capped")
+    and recent-24h is the more pessimistic of the two, surface that
+    so the header number and the verdict pill agree. Otherwise the
+    week-avg projection wins (the historical default).
+    """
+    if (
+        dashboard_verdict in ("cap", "capped")
+        and recent_24h_pct is not None
+        and week_avg_pct is not None
+        and recent_24h_pct > week_avg_pct
+    ):
+        return recent_24h_pct
+    return week_avg_pct
+
+
+def _forecast_budgets(output) -> "tuple[float | None, float | None]":
+    """Pull the (100%, 90%) ``BudgetRow.dollars_per_day`` pair from a
+    ``ForecastOutput.budgets`` list. Either may be ``None`` when the
+    target is out of headroom (``BudgetRow.dollars_per_day is None``).
+    """
+    if output is None:
+        return None, None
+    b100 = None
+    b90 = None
+    for b in getattr(output, "budgets", None) or []:
+        tp = getattr(b, "target_percent", None)
+        dpd = getattr(b, "dollars_per_day", None)
+        if tp == 100:
+            b100 = dpd
+        elif tp == 90:
+            b90 = dpd
+    return b100, b90
+
+
+def build_forecast_view(
+    conn,
+    *,
+    now_utc,
+    targets=(100, 90),
+    skip_sync: bool = False,
+    display_tz=None,
+):
+    """Build a ``ForecastView`` (issue #57).
+
+    Wraps the existing math kernel (``_load_forecast_inputs`` +
+    ``_compute_forecast``) without duplicating logic. Always returns a
+    ``ForecastView`` — when ``_load_forecast_inputs`` returns ``None``
+    (no current-week snapshot), the View constructs with
+    ``output=None`` + ``verdict="LOW CONF"`` so empty-state callers
+    don't branch on the wrapper itself.
+
+    ``targets`` are the percent ceilings forwarded to
+    ``_compute_forecast`` (default ``(100, 90)`` — matches both
+    ``cmd_forecast``'s ``--targets`` default and the TUI sync thread's
+    hard-coded value). ``skip_sync`` honours
+    ``cctally forecast --no-sync`` (and the dashboard's sync-thread
+    refresh skip).
+    """
+    c = _cctally()
+    inputs = c._load_forecast_inputs(conn, now_utc, skip_sync=skip_sync)
+    if inputs is None:
+        return ForecastView(
+            output=None,
+            verdict=_FORECAST_VERDICT_LOW_CONF,
+            dashboard_verdict="ok",
+            confidence="unknown",
+            low_confidence=False,
+            low_confidence_reasons=(),
+            week_avg_projection_pct=None,
+            recent_24h_projection_pct=None,
+            header_projection_pct=None,
+            budget_100_per_day_usd=None,
+            budget_90_per_day_usd=None,
+            period_start=None,
+            period_end=None,
+            display_tz_label=_display_tz_label(display_tz),
+            targets=tuple(int(t) for t in targets),
+        )
+    output = c._compute_forecast(inputs, list(int(t) for t in targets))
+    verdict = _forecast_verdict_of(output)
+    dashboard_verdict = _forecast_dashboard_verdict_of(output)
+    week_avg_pct, recent_pct = _forecast_projection_pcts(output)
+    header_pct = _forecast_header_projection_pct(
+        week_avg_pct, recent_pct, dashboard_verdict,
+    )
+    b100, b90 = _forecast_budgets(output)
+    confidence = getattr(inputs, "confidence", "high")
+    return ForecastView(
+        output=output,
+        verdict=verdict,
+        dashboard_verdict=dashboard_verdict,
+        confidence=confidence,
+        low_confidence=(confidence == "low"),
+        low_confidence_reasons=tuple(
+            getattr(inputs, "low_confidence_reasons", None) or ()
+        ),
+        week_avg_projection_pct=week_avg_pct,
+        recent_24h_projection_pct=recent_pct,
+        header_projection_pct=header_pct,
+        budget_100_per_day_usd=b100,
+        budget_90_per_day_usd=b90,
+        period_start=getattr(inputs, "week_start_at", None),
+        period_end=getattr(inputs, "week_end_at", None),
+        display_tz_label=_display_tz_label(display_tz),
+        targets=tuple(int(t) for t in targets),
+    )
+
+
+# === Codex domain views + builders (Issue #58) =============================
+#
+# Codex domain is CLI-only — no dashboard panel, no share consumer. The
+# four views below wrap the existing ``_aggregate_codex_{daily,monthly,
+# weekly,sessions}`` math kernel without changing it, so the
+# intentional divergences from upstream documented in CLAUDE.md (LiteLLM
+# token semantics, duplicate-event dedup, descending-by-last-activity
+# session sort, ``CODEX_LEGACY_FALLBACK_MODEL`` warning) are preserved
+# end-to-end.
+#
+# Naming differences from the Claude views are deliberate:
+#
+# - The slot carrying the aggregator output is named ``rows`` (not
+#   ``aggregated``) — Codex has no parallel typed surface row dataclass
+#   to pair with, so the aggregator's typed output IS the surface (same
+#   precedent as ``TrendView.rows`` of typed ``TuiTrendRow``).
+# - ``display_tz_label`` is the already-resolved string label
+#   (``tz_name or _local_tz_name()``), not the ``zoneinfo.ZoneInfo.key``
+#   the Claude views emit via ``_display_tz_label(tzinfo)``. Codex
+#   commands plumb a string ``tz_name`` end-to-end (see
+#   ``_resolve_codex_tz_name``); the View carries the rendered label so
+#   ``cmd_codex_*`` can read it directly.
+#
+# Bucket ordering: ``_aggregate_codex_daily`` / ``_aggregate_codex_monthly``
+# / ``_aggregate_codex_weekly`` return ASC (earliest bucket first); the
+# View carries that order. ``cmd_codex_*`` reverses to DESC when
+# ``--order desc``.
+#
+# Session ordering: ``_aggregate_codex_sessions`` returns DESC
+# (most-recent last_activity first); the View carries that order.
+# ``cmd_codex_session`` reverses to ASC when ``--order asc``. The
+# upstream-parity DESC default matches ``ccusage-codex``'s session view.
+
+
+@dataclass(frozen=True)
+class CodexDailyView:
+    """Codex daily-bucket view (CLI-only).
+
+    ``rows`` is the parallel ``CodexBucketUsage`` tuple in ASC order
+    (earliest bucket first) — same as the aggregator's default.
+    ``cmd_codex_daily`` reverses for ``--order desc``.
+    """
+    rows: tuple = ()                    # tuple[CodexBucketUsage, ...]
+    total_cost_usd: float = 0.0
+    total_tokens: int = 0
+    period_start: "dt.datetime | None" = None
+    period_end: "dt.datetime | None" = None
+    display_tz_label: str = ""
+
+
+@dataclass(frozen=True)
+class CodexMonthlyView:
+    """Codex monthly-bucket view (CLI-only).
+
+    ``rows`` is the parallel ``CodexBucketUsage`` tuple in ASC order
+    (earliest bucket first). ``cmd_codex_monthly`` reverses for
+    ``--order desc``.
+    """
+    rows: tuple = ()                    # tuple[CodexBucketUsage, ...]
+    total_cost_usd: float = 0.0
+    total_tokens: int = 0
+    period_start: "dt.datetime | None" = None
+    period_end: "dt.datetime | None" = None
+    display_tz_label: str = ""
+
+
+@dataclass(frozen=True)
+class CodexWeeklyView:
+    """Codex weekly-bucket view (CLI-only).
+
+    ``rows`` is the parallel ``CodexBucketUsage`` tuple in ASC order
+    (earliest week-start first). ``cmd_codex_weekly`` reverses for
+    ``--order desc``. Week-start day is resolved by the caller
+    (``week_start_idx``) from config.json + ``WEEKDAY_MAP``.
+    """
+    rows: tuple = ()                    # tuple[CodexBucketUsage, ...]
+    total_cost_usd: float = 0.0
+    total_tokens: int = 0
+    period_start: "dt.datetime | None" = None
+    period_end: "dt.datetime | None" = None
+    display_tz_label: str = ""
+
+
+@dataclass(frozen=True)
+class CodexSessionView:
+    """Codex session view (CLI-only).
+
+    ``rows`` is the parallel ``CodexSessionUsage`` tuple in DESC order
+    (most-recent ``last_activity`` first) — matches upstream
+    ``ccusage-codex`` and the aggregator's default sort.
+    ``cmd_codex_session`` reverses for ``--order asc``.
+    """
+    rows: tuple = ()                    # tuple[CodexSessionUsage, ...]
+    total_sessions: int = 0
+    total_cost_usd: float = 0.0
+    total_tokens: int = 0
+    period_start: "dt.datetime | None" = None
+    period_end: "dt.datetime | None" = None
+    display_tz_label: str = ""
+
+
+def _codex_tz_label(tz_name: "str | None") -> str:
+    """Render the timezone label the way ``cmd_codex_*`` already does
+    (``tz_name or _local_tz_name()``). Centralized here so the four
+    builders share one chokepoint."""
+    if tz_name:
+        return tz_name
+    return _cctally()._local_tz_name()
+
+
+def _codex_bucket_totals(buckets) -> "tuple[float, int]":
+    """Sum ``cost_usd`` and ``total_tokens`` across a
+    ``CodexBucketUsage`` list."""
+    total_cost = 0.0
+    total_tok = 0
+    for b in buckets:
+        total_cost += b.cost_usd
+        total_tok += b.total_tokens
+    return total_cost, total_tok
+
+
+def _codex_period_start_from_date_bucket(buckets) -> "dt.datetime | None":
+    """Parse the earliest ``YYYY-MM-DD`` bucket key (daily / weekly)
+    into a UTC datetime at midnight. ``None`` when ``buckets`` is empty."""
+    if not buckets:
+        return None
+    try:
+        d = dt.date.fromisoformat(buckets[0].bucket)
+    except ValueError:
+        return None
+    return dt.datetime.combine(d, dt.time.min, tzinfo=dt.timezone.utc)
+
+
+def _codex_period_start_from_month_bucket(buckets) -> "dt.datetime | None":
+    """Parse the earliest ``YYYY-MM`` bucket key (monthly) into a UTC
+    datetime at the 1st-of-month midnight. ``None`` when ``buckets`` is
+    empty or the key is malformed."""
+    if not buckets:
+        return None
+    try:
+        yr, mo = buckets[0].bucket.split("-")
+        return dt.datetime(int(yr), int(mo), 1, tzinfo=dt.timezone.utc)
+    except (ValueError, IndexError):
+        return None
+
+
+def build_codex_daily_view(entries, *, now_utc, tz_name=None):
+    """Build a ``CodexDailyView`` from a list of ``CodexEntry`` (issue #58).
+
+    Delegates bucketing to ``_aggregate_codex_daily`` (LiteLLM-snapshot
+    pricing + Codex token semantics — see CLAUDE.md "Codex (OpenAI)
+    parity" gotcha block). ``tz_name`` plumbs through verbatim
+    (None → host-local fallback inside the aggregator).
+    """
+    _agg = _load_lib("_lib_aggregators")
+    buckets = _agg._aggregate_codex_daily(entries, tz_name=tz_name)
+    total_cost, total_tok = _codex_bucket_totals(buckets)
+    return CodexDailyView(
+        rows=tuple(buckets),
+        total_cost_usd=total_cost,
+        total_tokens=total_tok,
+        period_start=_codex_period_start_from_date_bucket(buckets),
+        period_end=now_utc,
+        display_tz_label=_codex_tz_label(tz_name),
+    )
+
+
+def build_codex_monthly_view(entries, *, now_utc, tz_name=None):
+    """Build a ``CodexMonthlyView`` from a list of ``CodexEntry`` (issue #58).
+
+    Same wrap-the-kernel posture as ``build_codex_daily_view``; bucket
+    key is ``YYYY-MM`` so ``period_start`` resolves to the 1st of the
+    earliest visible month at UTC midnight.
+    """
+    _agg = _load_lib("_lib_aggregators")
+    buckets = _agg._aggregate_codex_monthly(entries, tz_name=tz_name)
+    total_cost, total_tok = _codex_bucket_totals(buckets)
+    return CodexMonthlyView(
+        rows=tuple(buckets),
+        total_cost_usd=total_cost,
+        total_tokens=total_tok,
+        period_start=_codex_period_start_from_month_bucket(buckets),
+        period_end=now_utc,
+        display_tz_label=_codex_tz_label(tz_name),
+    )
+
+
+def build_codex_weekly_view(entries, *, now_utc, tz_name=None,
+                            week_start_idx=0):
+    """Build a ``CodexWeeklyView`` from a list of ``CodexEntry`` (issue #58).
+
+    ``week_start_idx`` is the resolved Mon=0..Sun=6 index the caller
+    pulls from config via ``get_week_start_name`` + ``WEEKDAY_MAP``.
+    Bucket key is the ISO date of the week's first day in the display
+    timezone (matches ``_aggregate_codex_weekly`` contract).
+    """
+    _agg = _load_lib("_lib_aggregators")
+    buckets = _agg._aggregate_codex_weekly(entries, tz_name, week_start_idx)
+    total_cost, total_tok = _codex_bucket_totals(buckets)
+    return CodexWeeklyView(
+        rows=tuple(buckets),
+        total_cost_usd=total_cost,
+        total_tokens=total_tok,
+        period_start=_codex_period_start_from_date_bucket(buckets),
+        period_end=now_utc,
+        display_tz_label=_codex_tz_label(tz_name),
+    )
+
+
+def build_codex_session_view(entries, *, now_utc, tz_name=None):
+    """Build a ``CodexSessionView`` from a list of ``CodexEntry`` (issue #58).
+
+    ``rows`` order mirrors the aggregator: descending by
+    ``last_activity`` (upstream parity).
+    ``cmd_codex_session`` reverses to ASC when ``--order asc``.
+
+    ``period_start`` is set to ``min(s.last_activity)`` across emitted
+    sessions when any exist — best-available approximation since
+    ``CodexSessionUsage`` doesn't carry a ``first_activity`` field (the
+    aggregator only tracks ``last`` per session). ``None`` on empty.
+    """
+    _agg = _load_lib("_lib_aggregators")
+    sessions = _agg._aggregate_codex_sessions(entries)
+    total_cost = 0.0
+    total_tok = 0
+    earliest = None
+    for s in sessions:
+        total_cost += s.cost_usd
+        total_tok += s.total_tokens
+        if earliest is None or s.last_activity < earliest:
+            earliest = s.last_activity
+    return CodexSessionView(
+        rows=tuple(sessions),
+        total_sessions=len(sessions),
+        total_cost_usd=total_cost,
+        total_tokens=total_tok,
+        period_start=earliest,
+        period_end=now_utc,
+        display_tz_label=_codex_tz_label(tz_name),
+    )