cctally 1.100.0 → 1.102.0

package/bin/_lib_forecast.py

@@ -20,10 +20,60 @@ from __future__ import annotations
 
 import datetime as dt
 from dataclasses import dataclass
+from enum import Enum
 
 from _lib_budget import project_linear
 
 
+class ForecastConfidenceCause(str, Enum):
+    """The closed set of reasons a forecast is low-confidence.
+
+    The four values are a wire contract `--json` consumers read, so they are
+    the exact strings `_assess_forecast_confidence` has always emitted.
+    """
+
+    ELAPSED_HOURS = "elapsed_hours<24"
+    PERCENT = "percent<2"
+    SNAPSHOTS = "snapshots<3"
+    NO_SAMPLE_GE_24H = "no_sample_ge_24h"
+
+
+@dataclass(frozen=True)
+class ForecastConfidenceAssessment:
+    confidence: str                 # "high" | "low"
+    reasons: tuple[str, ...]
+
+
+def assess_forecast_confidence(
+    elapsed_hours: float,
+    percent: float,
+    snapshot_count: int,
+    *,
+    has_sample_ge_24h: bool,
+) -> ForecastConfidenceAssessment:
+    """The complete confidence predicate, including the fourth trigger.
+
+    `no_sample_ge_24h` used to be appended by `_load_forecast_inputs` after
+    it called the three-trigger predicate, which meant glue could add reasons
+    the predicate did not know about (#620 S2 E3, closes F19). Reason order
+    is `elapsed_hours<24`, `percent<2`, `snapshots<3`, `no_sample_ge_24h` —
+    the order the old call-plus-append produced.
+    """
+    reasons: list[str] = []
+    if elapsed_hours < 24:
+        reasons.append(ForecastConfidenceCause.ELAPSED_HOURS.value)
+    if percent < 2:
+        reasons.append(ForecastConfidenceCause.PERCENT.value)
+    if snapshot_count < 3:
+        reasons.append(ForecastConfidenceCause.SNAPSHOTS.value)
+    if not has_sample_ge_24h:
+        reasons.append(ForecastConfidenceCause.NO_SAMPLE_GE_24H.value)
+    return ForecastConfidenceAssessment(
+        confidence="low" if reasons else "high",
+        reasons=tuple(reasons),
+    )
+
+
 @dataclass
 class ForecastInputs:
     now_utc: dt.datetime
@@ -42,9 +92,11 @@ class ForecastInputs:
     # Rate inputs
     p_24h_ago: float | None
     t_24h_actual_hours: float | None
-    # $/1% selection
-    dollars_per_percent: float
-    dollars_per_percent_source: str  # "this_week" | "trailing_4wk_median" | "this_week_sparse"
+    # $/1% selection. `None` when no usage has been observed (#620 S1 D5) —
+    # every dollar-derived output is then unavailable rather than zero, and
+    # `dollars_per_percent_source` carries the cause.
+    dollars_per_percent: "float | None"
+    dollars_per_percent_source: str  # "this_week" | "trailing_4wk_median" | "this_week_sparse" | "no_usage_observed"
     # Confidence
     confidence: str  # "high" | "low"
     low_confidence_reasons: list[str]
@@ -121,7 +173,13 @@ def _compute_forecast(inputs: ForecastInputs, targets: list[int]) -> ForecastOut
                 budgets.append(BudgetRow(target_percent=t, pct_headroom=None,
                                          dollars_per_day=None, percent_per_day=None))
                 continue
-            dollars_day = (headroom * inputs.dollars_per_percent) / inputs.remaining_days
+            # #620 S1 D5: with no observed usage there is no rate, so the
+            # dollar budget is unavailable. The percent budget does not
+            # depend on the rate and is still published.
+            dollars_day = (
+                None if inputs.dollars_per_percent is None
+                else (headroom * inputs.dollars_per_percent) / inputs.remaining_days
+            )
             pct_day = headroom / inputs.remaining_days
             budgets.append(BudgetRow(
                 target_percent=t,

package/bin/_lib_perf.py

@@ -244,6 +244,18 @@ def current_root():
     return getattr(_tls, "root", None)
 
 
+def in_phase() -> bool:
+    """Whether a phase is currently OPEN on this thread.
+
+    `current_root()` answers a different question — it names the last root
+    that CLOSED — so a caller deciding whether to open a root of its own
+    cannot use it. A pure fold that opens child phases needs this one: with no
+    root open its children would be emitted into whatever phase happens to be
+    on the stack, or into none at all.
+    """
+    return bool(_stack())
+
+
 def reset_thread():
     """Start a fresh root scope on this thread, capturing the armed state.
 

package/bin/_lib_pricing.py

@@ -736,15 +736,16 @@ _unknown_codex_model_warnings: set[str] = set()
 # directly comparable.
 CODEX_LEGACY_FALLBACK_MODEL = "gpt-5"
 
-# OpenAI's model catalog describes ``codex-auto-review`` as the hidden model
-# used by the Guardian approval-review subagent, not as a public billable model
-# with its own rate card.  The canonical ccusage Codex adapter resolves that
-# identifier to the model current when it appeared; its 2026-04-23-and-later
-# mapping is gpt-5.5, which covers every retained auto-review event observed for
-# issue #535.  Keep this as a normalization map rather than a duplicate pricing
-# row so pricing drift continues to have one source of truth per rate card.
+# Runtime identifiers without their own rate card normalize here so pricing
+# drift retains one source of truth per card. OpenAI's live pricing page states
+# that ``daybreak-blue-latest`` currently points to ``gpt-5.6-sol`` and inherits
+# the underlying model's pricing; Codex emits the prefixed runtime identifier
+# retained below. ``codex-auto-review`` is the hidden Guardian model and maps to
+# the model current when it appeared, covering every retained event observed
+# for issue #535.
 CODEX_MODEL_ALIASES: dict[str, str] = {
     "codex-auto-review": "gpt-5.5",
+    "gpt-daybreak-blue-latest": "gpt-5.6-sol",
 }
 
 # Per-model fast-tier price multipliers, ported from ryoppippi/ccusage

package/bin/_lib_readme_refresh.py

@@ -8,7 +8,9 @@ implementation:
 1. ``extract_highlights`` — pull up to N lint-clean highlight bullets from a
    specific ``## [X.Y.Z] - YYYY-MM-DD`` CHANGELOG section (exact version match,
    Added > Changed > Fixed priority, multiline flattening, terminal issue-ref
-   stripping, fenced-code skipping).
+   stripping, fenced-code skipping). ``render_latest_stable_block`` keeps that
+   compact target-section sample honest by naming and linking the complete
+   previous-stable-to-target upgrade span.
 2. ``normalize_highlight`` — deterministically rewrite a bullet so it satisfies
    the copy lint by construction (em/en dashes with surrounding spaces become
    ``, ``; doubled separators collapse; leading/trailing separators trim).
@@ -297,14 +299,33 @@ def extract_highlights(
 
 
 def render_latest_stable_block(
-    version: str, date: str, bullets: "list[str]"
+    version: str,
+    date: str,
+    bullets: "list[str]",
+    *,
+    previous_stable: "str | None" = None,
+    release_url: "str | None" = None,
 ) -> str:
     """Render the auto-maintained latest-stable block (no trailing newline
-    after the last bullet; version+date only when *bullets* is empty)."""
+    after the last line; initial baselines retain the single-release shape)."""
     base = f"**Latest stable: v{version}** ({date})\n"
+    if previous_stable is None:
+        if bullets:
+            return base + "\n" + "\n".join(f"- {b}" for b in bullets)
+        return base
+    if release_url is None:
+        raise ValueError("stable-span README block requires a release URL")
+    blocks = [
+        base.rstrip("\n"),
+        f"Highlights from the `v{previous_stable}` to `v{version}` "
+        "stable upgrade:",
+    ]
     if bullets:
-        return base + "\n" + "\n".join(f"- {b}" for b in bullets)
-    return base
+        blocks.append("\n".join(f"- {b}" for b in bullets))
+    blocks.append(
+        f"[See every change in this stable upgrade]({release_url})"
+    )
+    return "\n\n".join(blocks)
 
 
 # --------------------------------------------------------------------------

package/bin/_lib_render.py

@@ -2795,7 +2795,8 @@ def _render_project_table(
     """Render project rollup as a ccusage-style ANSI table.
 
     Columns: Project | Sessions | First Seen | Last Seen | Input |
-             Cache Create | Cache Read | Output | Cost (USD) | Used % | $/1%
+             Cache Create | Cache Read | Output | Cost (USD) |
+             Cost Share | Used % | $/1%
 
     Parent rows show all columns; breakdown child rows show per-model
     aggregates with blank Sessions/Used%/$/1% cells (those only make
@@ -2822,12 +2823,12 @@ def _render_project_table(
     headers = [
         "Project", "Sessions", "First Seen", "Last Seen",
         "Input", "Cache Create", "Cache Read", "Output",
-        "Cost (USD)", "Used %", "$/1%",
+        "Cost (USD)", "Cost Share", "Used %", "$/1%",
     ]
     aligns = [
         "left", "right", "left", "left",
         "right", "right", "right", "right",
-        "right", "right", "right",
+        "right", "right", "right", "right",
     ]
     num_cols = len(headers)
 
@@ -2891,6 +2892,19 @@ def _render_project_table(
             return ("\u2014", _gray)
         return (f"${cpp:.2f}", None)
 
+    # #620 S1 D13 (CLI half): each project's share of the cost of the
+    # projects this table lists. That denominator is NOT the quota
+    # percentage `Used %` reports, so the two columns are independent and
+    # the footer below names this one explicitly — the terminal has no
+    # hover, so the disclosure the dashboard makes in a tooltip has to be a
+    # rendered line here.
+    cost_share_total = stable_sum(float(r["cost_usd"]) for r in rows)
+
+    def _cost_share_cell(cost_usd: float) -> tuple[str, Any]:
+        if cost_share_total <= 0:
+            return ("\u2014", _gray)
+        return (f"{100.0 * float(cost_usd) / cost_share_total:.1f}%", None)
+
     arrow = "  \u2514\u2500" if unicode_ok else "  |_"
 
     ROW_DATA, ROW_BREAKDOWN = "data", "breakdown"
@@ -2910,6 +2924,7 @@ def _render_project_table(
             (_fmt_num(r["cache_read"]), None),
             (_fmt_num(r["output"]), None),
             (f"${r['cost_usd']:.2f}", None),
+            _cost_share_cell(r["cost_usd"]),
             (used_text, used_cfn),
             (cpp_text, cpp_cfn),
         ]
@@ -2928,6 +2943,10 @@ def _render_project_table(
                     (_fmt_num(mb["cache_read"]), _gray),
                     (_fmt_num(mb["output"]), _gray),
                     (f"${mb['cost_usd']:.2f}", _gray),
+                    # Cost Share is blank on a model row for the same reason
+                    # Used % and $/1% are: a model's share of its project is a
+                    # different denominator from the one the column names.
+                    ("", None),
                     ("", None),
                     ("", None),
                 ]
@@ -3062,6 +3081,15 @@ def _render_project_table(
             )
         )
 
+    project_plural = "s" if len(rows) != 1 else ""
+    out.append(
+        _dim(
+            f"Cost Share: each project's share of ${cost_share_total:,.2f} "
+            f"\u2014 the total cost of the {len(rows)} "
+            f"project{project_plural} listed."
+        )
+    )
+
     return "\n".join(out)
 
 

package/bin/_lib_share_templates.py

@@ -199,6 +199,108 @@ def _kpi_strip(*items: tuple[str, str]) -> tuple:
     return tuple(_LS.Totalled(label=lbl, value=val) for lbl, val in items)
 
 
+def _optional_money(value, spec: str = ".2f") -> str:
+    """A dollar figure, or `n/a` when the value was withheld.
+
+    #620 S1 D5/A5. A KPI strip renders through an f-string, so a `None`
+    raises and a substituted zero prints `$0.000` — which is the fabrication
+    the contract removes. `n/a` is the same word `_build_forecast_snapshot`
+    already uses for an absent $/1%, so the two share surfaces say the same
+    thing about the same absence.
+    """
+    if value is None:
+        return "n/a"
+    return f"${value:{spec}}"
+
+
+def _optional_money_cell(value):
+    """A `MoneyCell`, or a `TextCell` reading `n/a` when the value was
+    withheld.
+
+    #620 S1 D5/A5, table half. `_optional_money` covers the KPI strip, which
+    is already a string; a table cell is a tagged-union member, and
+    `MoneyCell` takes a float. Forcing a withheld figure through `float(...)`
+    raises `TypeError`, and the dashboard share handler catches that and
+    returns a share FAILURE — so the coercion turned a fabricated `$0.000`
+    into no artifact at all. `n/a` is the word `_optional_money` and
+    `_build_forecast_snapshot` already use for the same absence.
+    """
+    if value is None:
+        return _LS.TextCell("n/a")
+    return _LS.MoneyCell(float(value))
+
+
+def _optional_pct(value, *, scale: float = 100.0, spec: str = ".1f") -> str:
+    """A percentage, or `n/a` when the value was withheld.
+
+    #620 S1. `TuiTrendRow.used_pct` and `WeeklyPeriodRow.used_pct` are both
+    `float | None` — `None` when the week carries a cost snapshot but no
+    usage snapshot. A KPI strip formats through an f-string, so a `None`
+    raises and the zero it replaced printed `0.0%`, which a reader cannot
+    tell from a week that really used nothing. `n/a` is the word the money
+    helpers above already use for the same absence.
+    """
+    if value is None:
+        return "n/a"
+    return f"{float(value) * scale:{spec}}%"
+
+
+def _optional_pct_cell(value, *, scale: float = 100.0):
+    """A `PercentCell`, or a `TextCell` reading `n/a` when withheld.
+
+    The table half of `_optional_pct`, mirroring `_optional_money_cell`:
+    `PercentCell` takes a float, so forcing a withheld percentage through
+    `float(...)` raises `TypeError`, which the dashboard share handler turns
+    into a share FAILURE rather than an artifact.
+    """
+    if value is None:
+        return _LS.TextCell("n/a")
+    return _LS.PercentCell(float(value) * scale)
+
+
+def _optional_days(value, spec: str = ".1f") -> str:
+    """A number of days, or `n/a` when the distance is not defined.
+
+    #620 S1. `days_to_90pct` / `days_to_100pct` are withheld when no rate was
+    observed, because a ceiling is not reachable on any timeline the data
+    describes. `float(... or 0.0)` printed `0.0`, which says the ceiling has
+    already been reached — the opposite fact.
+    """
+    if value is None:
+        return "n/a"
+    return f"{float(value):{spec}}"
+
+
+def _optional_signed_pct(value) -> str:
+    """A signed percentage change, or `n/a` when it could not be computed."""
+    if value is None:
+        return "n/a"
+    return f"{float(value) * 100:+.1f}%"
+
+
+def _optional_signed_money(value) -> str:
+    """A signed dollar change, or `n/a` when it could not be computed."""
+    if value is None:
+        return "n/a"
+    return f"${float(value):+,.2f}"
+
+
+def _optional_chart_points(items, *, x_label_key, y_key):
+    """Chart points for `items`, omitting any whose `y_key` was withheld.
+
+    A withheld value plotted at zero draws a cliff to the axis that reads as
+    a measured collapse. The x position stays the item's original index, so
+    the remaining points keep their spacing and the gap sits where the
+    missing week actually is.
+    """
+    return tuple(
+        _LS.ChartPoint(x_label=item[x_label_key], x_value=float(i),
+                       y_value=float(item[y_key]))
+        for i, item in enumerate(items)
+        if item.get(y_key) is not None
+    )
+
+
 def _top_projects_rows(top_projects, cap: int) -> tuple:
     """Build `Row` tuple with ProjectCell + MoneyCell from a list of
     `(project_path, cost_usd)` pairs.
@@ -499,8 +601,8 @@ def _build_weekly_recap(*, panel_data, options):
             "weeks": [
                 {"start_date": "YYYY-MM-DD",      # ISO date string
                  "cost_usd":    float,
-                 "pct_used":    float,            # fraction 0..1
-                 "dollar_per_pct": float,
+                 "pct_used":    float | None,      # fraction 0..1; None = withheld
+                 "dollar_per_pct": float | None,   # None = withheld
                  "top_projects":  [(path, cost), ...]},
                 ... up to 8 weeks, chronological ...
             ],
@@ -530,8 +632,8 @@ def _build_weekly_recap(*, panel_data, options):
         ),
         totals=_kpi_strip(
             ("$ spent",      f"${w['cost_usd']:.2f}"),
-            ("% used",       f"{w['pct_used']*100:.1f}%"),
-            ("$/% rate",     f"${w['dollar_per_pct']:.3f}"),
+            ("% used",       _optional_pct(w['pct_used'])),
+            ("$/% rate",     _optional_money(w['dollar_per_pct'], ".3f")),
         ),
         notes=(),
         generated_at=_utc_now(),
@@ -549,7 +651,7 @@ def _build_current_week_recap(*, panel_data, options):
         {
             "kpi_cost_usd":       float,
             "kpi_pct_used":      float,   # fraction 0..1
-            "kpi_dollar_per_pct": float,
+            "kpi_dollar_per_pct": float | None,   # None = withheld
             "kpi_days_remaining": float,
             "daily_progression":  [{"date": "YYYY-MM-DD",
                                      "cost_usd": float}, ...],   # ≤7
@@ -583,7 +685,8 @@ def _build_current_week_recap(*, panel_data, options):
         totals=_kpi_strip(
             ("$ spent",        f"${panel_data['kpi_cost_usd']:.2f}"),
             ("% used",         f"{panel_data['kpi_pct_used']*100:.1f}%"),
-            ("$/% rate",       f"${panel_data['kpi_dollar_per_pct']:.3f}"),
+            ("$/% rate",       _optional_money(
+                panel_data.get("kpi_dollar_per_pct"), ".3f")),
             ("Days remaining", f"{panel_data['kpi_days_remaining']:.1f}"),
         ),
         notes=(),
@@ -602,8 +705,8 @@ def _build_trend_recap(*, panel_data, options):
             "weeks": [
                 {"start_date": "YYYY-MM-DD",
                  "cost_usd":      float,
-                 "pct_used":      float,
-                 "dollar_per_pct": float}, ... 8 entries, chronological ...
+                 "pct_used":      float | None,   # None = withheld
+                 "dollar_per_pct": float | None}, ... 8 entries, chronological ...
             ],
             "delta_3_weeks": {
                 "dpp_change_pct": float,   # +ve = $/% trending up
@@ -631,24 +734,21 @@ def _build_trend_recap(*, panel_data, options):
         rows=tuple(
             _LS.Row(cells={
                 "week": _LS.TextCell(w["start_date"]),
-                "cost": _LS.MoneyCell(float(w["cost_usd"])),
-                "pct":  _LS.PercentCell(float(w["pct_used"]) * 100.0),
-                "dpp":  _LS.MoneyCell(float(w["dollar_per_pct"])),
+                "cost": _optional_money_cell(w["cost_usd"]),
+                "pct":  _optional_pct_cell(w["pct_used"]),
+                "dpp":  _optional_money_cell(w["dollar_per_pct"]),
             })
             for w in weeks
         ),
         chart=_LS.LineChart(
-            points=tuple(
-                _LS.ChartPoint(x_label=w["start_date"], x_value=float(i),
-                               y_value=float(w["dollar_per_pct"]))
-                for i, w in enumerate(weeks)
-            ),
+            points=_optional_chart_points(
+                weeks, x_label_key="start_date", y_key="dollar_per_pct"),
             y_label="$ / 1%",
             reference_lines=(),
         ) if weeks else None,
         totals=_kpi_strip(
-            ("Δ $/% (3wk)", f"{float(delta.get('dpp_change_pct') or 0.0)*100:+.1f}%"),
-            ("Δ $ (3wk)",   f"${float(delta.get('cost_change_usd') or 0.0):+,.2f}"),
+            ("Δ $/% (3wk)", _optional_signed_pct(delta.get('dpp_change_pct'))),
+            ("Δ $ (3wk)",   _optional_signed_money(delta.get('cost_change_usd'))),
         ),
         notes=(),
         generated_at=_utc_now(),
@@ -813,8 +913,8 @@ def _build_forecast_recap(*, panel_data, options):
     Expected panel_data shape:
         {
             "projected_end_pct":  float,   # fraction 0..1+
-            "days_to_100pct":     float,
-            "days_to_90pct":      float,
+            "days_to_100pct":     float | None,   # None = no rate observed
+            "days_to_90pct":      float | None,   # None = no rate observed
             "daily_budgets": {
                 "avg":           float,   # $/day to-date
                 "recent_24h":    float,
@@ -846,13 +946,13 @@ def _build_forecast_recap(*, panel_data, options):
         ),
         rows=(
             _LS.Row(cells={"metric": _LS.TextCell("Avg to-date"),
-                           "value":  _LS.MoneyCell(float(budgets.get("avg") or 0.0))}),
+                           "value":  _optional_money_cell(budgets.get("avg"))}),
             _LS.Row(cells={"metric": _LS.TextCell("Recent 24h"),
-                           "value":  _LS.MoneyCell(float(budgets.get("recent_24h") or 0.0))}),
+                           "value":  _optional_money_cell(budgets.get("recent_24h"))}),
             _LS.Row(cells={"metric": _LS.TextCell("Budget to 90%"),
-                           "value":  _LS.MoneyCell(float(budgets.get("until_90pct") or 0.0))}),
+                           "value":  _optional_money_cell(budgets.get("until_90pct"))}),
             _LS.Row(cells={"metric": _LS.TextCell("Budget to 100%"),
-                           "value":  _LS.MoneyCell(float(budgets.get("until_100pct") or 0.0))}),
+                           "value":  _optional_money_cell(budgets.get("until_100pct"))}),
         ),
         chart=_LS.LineChart(
             points=tuple(
@@ -867,8 +967,8 @@ def _build_forecast_recap(*, panel_data, options):
             ),
         ) if curve else None,
         totals=_kpi_strip(
-            ("Days→90%",  f"{float(panel_data.get('days_to_90pct') or 0.0):.1f}"),
-            ("Days→100%", f"{float(panel_data.get('days_to_100pct') or 0.0):.1f}"),
+            ("Days→90%",  _optional_days(panel_data.get('days_to_90pct'))),
+            ("Days→100%", _optional_days(panel_data.get('days_to_100pct'))),
             ("End %",     f"{float(panel_data.get('projected_end_pct') or 0.0)*100:.1f}%"),
         ),
         notes=notes,
@@ -978,7 +1078,7 @@ def _build_weekly_visual(*, panel_data, options):
         ),
         totals=_kpi_strip(
             ("$ spent",  f"${w['cost_usd']:.2f}"),
-            ("% used",   f"{w['pct_used']*100:.1f}%"),
+            ("% used",   _optional_pct(w['pct_used'])),
         ),
         notes=(),
         generated_at=_utc_now(),
@@ -1043,8 +1143,8 @@ def _build_weekly_detail(*, panel_data, options):
         ),
         totals=_kpi_strip(
             ("$ spent",      f"${w['cost_usd']:.2f}"),
-            ("% used",       f"{w['pct_used']*100:.1f}%"),
-            ("$/% rate",     f"${w['dollar_per_pct']:.3f}"),
+            ("% used",       _optional_pct(w['pct_used'])),
+            ("$/% rate",     _optional_money(w['dollar_per_pct'], ".3f")),
         ),
         notes=(),
         generated_at=_utc_now(),
@@ -1112,7 +1212,8 @@ def _build_current_week_detail(*, panel_data, options):
         totals=_kpi_strip(
             ("$ spent",        f"${panel_data['kpi_cost_usd']:.2f}"),
             ("% used",         f"{panel_data['kpi_pct_used']*100:.1f}%"),
-            ("$/% rate",       f"${panel_data['kpi_dollar_per_pct']:.3f}"),
+            ("$/% rate",       _optional_money(
+                panel_data.get("kpi_dollar_per_pct"), ".3f")),
             ("Days remaining", f"{panel_data['kpi_days_remaining']:.1f}"),
         ),
         notes=(),
@@ -1137,17 +1238,14 @@ def _build_trend_visual(*, panel_data, options):
         columns=(),
         rows=(),
         chart=_LS.LineChart(
-            points=tuple(
-                _LS.ChartPoint(x_label=w["start_date"], x_value=float(i),
-                               y_value=float(w["dollar_per_pct"]))
-                for i, w in enumerate(weeks)
-            ),
+            points=_optional_chart_points(
+                weeks, x_label_key="start_date", y_key="dollar_per_pct"),
             y_label="$ / 1%",
             reference_lines=(),
         ) if weeks else None,
         totals=_kpi_strip(
-            ("Δ $/% (3wk)", f"{float(delta.get('dpp_change_pct') or 0.0)*100:+.1f}%"),
-            ("Δ $ (3wk)",   f"${float(delta.get('cost_change_usd') or 0.0):+,.2f}"),
+            ("Δ $/% (3wk)", _optional_signed_pct(delta.get('dpp_change_pct'))),
+            ("Δ $ (3wk)",   _optional_signed_money(delta.get('cost_change_usd'))),
         ),
         notes=(),
         generated_at=_utc_now(),
@@ -1177,24 +1275,21 @@ def _build_trend_detail(*, panel_data, options):
         rows=tuple(
             _LS.Row(cells={
                 "week": _LS.TextCell(w["start_date"]),
-                "cost": _LS.MoneyCell(float(w["cost_usd"])),
-                "pct":  _LS.PercentCell(float(w["pct_used"]) * 100.0),
-                "dpp":  _LS.MoneyCell(float(w["dollar_per_pct"])),
+                "cost": _optional_money_cell(w["cost_usd"]),
+                "pct":  _optional_pct_cell(w["pct_used"]),
+                "dpp":  _optional_money_cell(w["dollar_per_pct"]),
             })
             for w in weeks
         ),
         chart=_LS.LineChart(
-            points=tuple(
-                _LS.ChartPoint(x_label=w["start_date"], x_value=float(i),
-                               y_value=float(w["dollar_per_pct"]))
-                for i, w in enumerate(weeks)
-            ),
+            points=_optional_chart_points(
+                weeks, x_label_key="start_date", y_key="dollar_per_pct"),
             y_label="$ / 1%",
             reference_lines=(),
         ) if weeks else None,
         totals=_kpi_strip(
-            ("Δ $/% (3wk)", f"{float(delta.get('dpp_change_pct') or 0.0)*100:+.1f}%"),
-            ("Δ $ (3wk)",   f"${float(delta.get('cost_change_usd') or 0.0):+,.2f}"),
+            ("Δ $/% (3wk)", _optional_signed_pct(delta.get('dpp_change_pct'))),
+            ("Δ $ (3wk)",   _optional_signed_money(delta.get('cost_change_usd'))),
         ),
         notes=(),
         generated_at=_utc_now(),
@@ -1529,8 +1624,8 @@ def _build_forecast_visual(*, panel_data, options):
             ),
         ) if curve else None,
         totals=_kpi_strip(
-            ("Days→90%",  f"{float(panel_data.get('days_to_90pct') or 0.0):.1f}"),
-            ("Days→100%", f"{float(panel_data.get('days_to_100pct') or 0.0):.1f}"),
+            ("Days→90%",  _optional_days(panel_data.get('days_to_90pct'))),
+            ("Days→100%", _optional_days(panel_data.get('days_to_100pct'))),
             ("End %",     f"{float(panel_data.get('projected_end_pct') or 0.0)*100:.1f}%"),
         ),
         notes=notes,
@@ -1557,13 +1652,13 @@ def _build_forecast_detail(*, panel_data, options):
     # Budget metric rows + per-day projection rows, capped at top_n total.
     budget_rows = (
         _LS.Row(cells={"metric": _LS.TextCell("Avg to-date"),
-                       "value":  _LS.MoneyCell(float(budgets.get("avg") or 0.0))}),
+                       "value":  _optional_money_cell(budgets.get("avg"))}),
         _LS.Row(cells={"metric": _LS.TextCell("Recent 24h"),
-                       "value":  _LS.MoneyCell(float(budgets.get("recent_24h") or 0.0))}),
+                       "value":  _optional_money_cell(budgets.get("recent_24h"))}),
         _LS.Row(cells={"metric": _LS.TextCell("Budget to 90%"),
-                       "value":  _LS.MoneyCell(float(budgets.get("until_90pct") or 0.0))}),
+                       "value":  _optional_money_cell(budgets.get("until_90pct"))}),
         _LS.Row(cells={"metric": _LS.TextCell("Budget to 100%"),
-                       "value":  _LS.MoneyCell(float(budgets.get("until_100pct") or 0.0))}),
+                       "value":  _optional_money_cell(budgets.get("until_100pct"))}),
     )
     day_rows = tuple(
         _LS.Row(cells={
@@ -1597,8 +1692,8 @@ def _build_forecast_detail(*, panel_data, options):
             ),
         ) if curve else None,
         totals=_kpi_strip(
-            ("Days→90%",  f"{float(panel_data.get('days_to_90pct') or 0.0):.1f}"),
-            ("Days→100%", f"{float(panel_data.get('days_to_100pct') or 0.0):.1f}"),
+            ("Days→90%",  _optional_days(panel_data.get('days_to_90pct'))),
+            ("Days→100%", _optional_days(panel_data.get('days_to_100pct'))),
             ("End %",     f"{float(panel_data.get('projected_end_pct') or 0.0)*100:.1f}%"),
         ),
         notes=notes,