cctally 1.97.0 → 1.99.0

package/bin/_cctally_tui.py

@@ -193,6 +193,7 @@ import sqlite3
 import sys
 import threading
 import time
+from collections.abc import Mapping
 from dataclasses import dataclass, field
 from typing import Any, Sequence
 
@@ -264,6 +265,7 @@ _ensure_sibling_loaded("_cctally_dashboard_sources")
 from _cctally_dashboard_sources import (
     DashboardReadContext,
     _claude_accounts_wire,
+    _refresh_budget_status_clock,
     accounts_identity_digest,
     build_codex_source_state,
     codex_decision_deadline_passed,
@@ -281,6 +283,11 @@ from _lib_dashboard_sources import (
     SourceDashboardBundle,
     SourceDashboardState,
     SourceDashboardWarning,
+    aggregate_range,
+    aggregate_scope_failed,
+    aggregate_scope_identity,
+    build_aggregate_scope,
+    claude_stats_digest,
     codex_stats_digest,
     compose_all_state,
     dashboard_resource_key,
@@ -2311,7 +2318,12 @@ def _snapshot_data_version(sig) -> str:
     # in is what leaves the idle short-circuit so the source bundle is rebuilt
     # at all. Empty once the backlog has drained, so it is byte-neutral there.
     backlog = getattr(sig, "codex_ingest_backlog_sig", "")
-    return out if not backlog else f"{out}.b{backlog}"
+    out = out if not backlog else f"{out}.b{backlog}"
+    # #556 S3 §2.9: the Claude alert relations. A fired or armed Claude alert
+    # moves no numeric leg above, so without this the detail endpoints' change
+    # signal stays flat across a tick that added an alert row.
+    claude_digest = getattr(sig, "claude_stats_digest", "")
+    return out if not claude_digest else f"{out}.x{claude_digest}"
 
 
 def _tui_source_copy(value: object) -> object:
@@ -2342,6 +2354,38 @@ def _tui_claude_resource_row(
     return wire
 
 
+def alert_row_owner(
+    axis: object, vendor: object, metric: object,
+) -> str:
+    """Total ownership classifier for a legacy alert row (#556 S3 §3.4).
+
+    Raises on an unregistered axis, so adding a seventh axis without deciding
+    its owner fails a test instead of shipping a row invisible everywhere. The
+    predicate this replaced answered `False` for an unknown axis, which reads
+    as "Codex owns it" and is indistinguishable from a real Codex row.
+    """
+    if axis in {"weekly", "five_hour", "budget", "project_budget"}:
+        # An absent vendor is the established Claude meaning: the legacy rows
+        # predate the additive vendor field. An explicit non-Claude vendor is
+        # never relabelled — `project_budget` gained that check here, having
+        # previously claimed every row whatever its vendor said.
+        return "codex" if vendor == "codex" else "claude"
+    if axis == "projected":
+        # The metric is the owner here, and it is enumerated rather than
+        # defaulted. Defaulting an unrecognized metric to Claude would let a
+        # future Codex-side projected metric render in the Claude tab, and
+        # defaulting it to Codex would drop it from every surface without a
+        # word — the two failure modes this classifier exists to prevent.
+        if metric in {"weekly_pct", "budget_usd"}:
+            return "claude"
+        if metric == "codex_budget_usd":
+            return "codex"
+        raise ValueError(f"no ownership rule for projected metric {metric!r}")
+    if axis == "codex_budget":
+        return "codex"
+    raise ValueError(f"no ownership rule for alert axis {axis!r}")
+
+
 def _tui_project_claude_source_data(legacy_envelope: object) -> dict[str, object]:
     """Project one completed Claude legacy envelope without further DB reads.
 
@@ -2445,17 +2489,7 @@ def _tui_project_claude_source_data(legacy_envelope: object) -> dict[str, object
         axis = raw.get("axis")
         vendor = raw.get("vendor")
         metric = raw.get("metric")
-        owns_alert = (
-            (axis in {"weekly", "five_hour"} and vendor in {None, "claude"})
-            # Legacy top-level Claude budget rows predate the additive vendor
-            # field; the distinct Codex axis is ``codex_budget``.  Treat an
-            # absent vendor as that established Claude meaning, while an
-            # explicit non-Claude vendor must never be relabeled.
-            or (axis == "budget" and vendor in {None, "claude"})
-            or axis == "project_budget"
-            or (axis == "projected" and metric in {"weekly_pct", "budget_usd"})
-        )
-        if not owns_alert:
+        if alert_row_owner(axis, vendor, metric) != "claude":
             continue
         alert_rows.append(_tui_claude_resource_row(
             raw,
@@ -2572,6 +2606,54 @@ def _tui_claude_domain_freshness(
     return {"hero": accounting, "quota": quota, "sessions": "fresh"}
 
 
+def _refresh_claude_budget_clock(
+    state: SourceDashboardState,
+    *,
+    now_utc: dt.datetime,
+) -> SourceDashboardState:
+    """Re-run the pure pace kernel over Claude's frozen budget facts.
+
+    #556 S5 §3.7. Separate from ``_refresh_claude_source_clock`` because the two
+    are called from different places: that one runs ONLY on the pure-idle short
+    circuit and needs the legacy ``current_week`` object and the raw config,
+    neither of which the source-bundle builder holds. This one needs only the
+    published status and the server-private cost events, so it can be called
+    unconditionally after every build, reuse and degrade branch — which is what
+    §3.7 requires, because exact-version Claude reuse returns the prior object
+    unchanged and would otherwise republish a budget frozen at the instant it
+    was built.
+
+    Same-instant identity is preserved: the underlying kernel is deterministic
+    in ``now``, so a freshly built state reclocks to itself and the equality
+    guards below hand the caller the exact object it passed in.
+    """
+    if state.source != "claude" or not isinstance(state.data, Mapping):
+        return state
+    if now_utc.tzinfo is None or now_utc.utcoffset() is None:
+        raise ValueError("now_utc must be timezone-aware")
+    now_utc = now_utc.astimezone(dt.timezone.utc)
+    budget_domain = state.data.get("budget")
+    if not isinstance(budget_domain, Mapping):
+        return state
+    status = budget_domain.get("status")
+    if not isinstance(status, Mapping):
+        return state
+    refreshed = _refresh_budget_status_clock(
+        status,
+        now_utc,
+        cost_events=(
+            state.clock_data.get("claude_budget_cost_events", ())
+            if isinstance(state.clock_data, Mapping) else ()
+        ),
+    )
+    if refreshed is None or refreshed == status:
+        return state
+    data = dict(state.data)
+    data["budget"] = {**dict(budget_domain), "status": refreshed}
+    refreshed_state = dataclasses.replace(state, data=data)
+    return state if refreshed_state == state else refreshed_state
+
+
 def _refresh_claude_source_clock(
     state: SourceDashboardState,
     *,
@@ -2623,6 +2705,10 @@ def _refresh_claude_source_clock(
         state,
         domain_freshness=domain_freshness,
     )
+    # #556 S5 §3.7: the budget leg runs on the pure-idle path too. It is the
+    # SAME helper the bundle builder calls after every other branch, so the two
+    # paths cannot drift.
+    refreshed = _refresh_claude_budget_clock(refreshed, now_utc=now_utc)
     return state if refreshed == state else refreshed
 
 
@@ -2720,6 +2806,459 @@ def _tui_with_account_scope(
     return dataclasses.replace(state, account_scope=scope)
 
 
+_AGGREGATE_FOLD_FAILED = {"state": "failed", "code": "claude_fold_failed"}
+
+
+def _tui_build_claude_aggregates(
+    cache_conn,
+    *,
+    shared_start: dt.datetime,
+    shared_end_exclusive: dt.datetime,
+    now_utc: dt.datetime,
+    display_tz_name: str | None,
+    # NOT `legacy_project_labels`: that is the name of the public kernel
+    # function this receives the RESULT of (`c.legacy_project_labels`), and a
+    # parameter shadowing it inside a function that also calls it reads as a
+    # recursive reference.
+    legacy_labels: "dict[str, str] | None" = None,
+    max_entry_id: "int | None" = None,
+    entry_mutation_seq: "int | None" = None,
+    generation: int = 0,
+):
+    """Both All-only Claude legs, from ONE candidate read (spec §3.3, §3.4).
+
+    Returns ``(payload, outcomes)`` where ``payload`` holds the published rows
+    for whichever legs succeeded and ``outcomes`` names each leg's state.
+
+    Runs on the caller's PINNED cache connection, beside the Codex read and on
+    the same snapshot. Both legacy paths stay untouched: the attached-cache
+    block continues to serve ``env.projects`` and the Group-A read continues to
+    serve ``env.daily``, for the Claude tab.
+
+    Each fold has its OWN error boundary, so one failure cannot take the bundle
+    or the other leg down. A failure of the shared read itself fails both, since
+    neither leg has rows. A failure is a typed withheld outcome rather than an
+    escaped exception: today an exception inside this helper is caught by the
+    outer handler, which publishes the prior bundle or none at all, so a
+    cold-start fold failure could never become the outcome §3.7 promises.
+    """
+    from zoneinfo import ZoneInfo
+
+    c = _cctally()
+    display_tz = ZoneInfo(display_tz_name) if display_tz_name else None
+    payload: dict[str, object] = {}
+    outcomes: dict[str, object] = {
+        "projects": {"state": "ok"}, "daily": {"state": "ok"},
+    }
+    dashboard_module = sys.modules["_cctally_dashboard"]
+    cache_seams_unpatched = (
+        c.build_project_aggregate_rows
+        is dashboard_module.build_project_aggregate_rows
+        and c.build_daily_aggregate_rows
+        is dashboard_module.build_daily_aggregate_rows
+    )
+    if legacy_labels is not None and cache_seams_unpatched:
+        try:
+            return c.build_cached_claude_range_aggregates(
+                cache_conn,
+                shared_start=shared_start,
+                shared_end_exclusive=shared_end_exclusive,
+                now_utc=now_utc,
+                display_tz=display_tz,
+                legacy_labels=legacy_labels,
+                max_entry_id=max_entry_id,
+                entry_mutation_seq=entry_mutation_seq,
+                generation=generation,
+            ), outcomes
+        except Exception:
+            # The accumulator is only an optimization.  Its failure falls
+            # through to the original two independent fold boundaries below.
+            _lib_log.get_logger("dashboard").error(
+                "claude range aggregate cache failed", exc_info=True,
+            )
+    try:
+        rows = tuple(c.iter_shared_range_entries(
+            cache_conn, start=shared_start, end_exclusive=shared_end_exclusive,
+        ))
+    except Exception:
+        _lib_log.get_logger("dashboard").error(
+            "claude shared-range candidate read failed", exc_info=True,
+        )
+        return {}, {
+            "projects": dict(_AGGREGATE_FOLD_FAILED),
+            "daily": dict(_AGGREGATE_FOLD_FAILED),
+        }
+    prepared_daily_entries = None
+    if legacy_labels is None:
+        # No projects envelope was built this tick, so the routable population
+        # is unknown. Publishing anyway would relabel every row from the
+        # bounded population, mint different opaque keys, and hand them to a
+        # drill-down that resolves against an envelope it rebuilds for itself
+        # — the rows on screen and the rows the route can serve would be two
+        # different populations, and nothing would say so. Withholding states
+        # the failure instead, and `claude_fold_failed` also disqualifies the
+        # bundle from idle reuse, so the next tick's envelope gets a chance.
+        _lib_log.get_logger("dashboard").error(
+            "claude range projects fold has no projects envelope",
+        )
+        outcomes["projects"] = dict(_AGGREGATE_FOLD_FAILED)
+    else:
+        candidate_daily_entries = []
+        try:
+            payload["projects"] = c.build_project_aggregate_rows(
+                rows,
+                legacy_labels=legacy_labels,
+                prepared_daily_entries=candidate_daily_entries,
+            )
+            prepared_daily_entries = candidate_daily_entries
+        except Exception:
+            _lib_log.get_logger("dashboard").error(
+                "claude range projects fold failed", exc_info=True,
+            )
+            outcomes["projects"] = dict(_AGGREGATE_FOLD_FAILED)
+    try:
+        payload["daily"] = [
+            c.daily_panel_row_to_wire(row)
+            for row in c.build_daily_aggregate_rows(
+                rows,
+                now_utc=now_utc,
+                display_tz=display_tz,
+                prepared_entries=prepared_daily_entries,
+            )
+        ]
+    except Exception:
+        _lib_log.get_logger("dashboard").error(
+            "claude range daily fold failed", exc_info=True,
+        )
+        outcomes["daily"] = dict(_AGGREGATE_FOLD_FAILED)
+    return payload, outcomes
+
+
+def _tui_claude_data_with_aggregates(
+    claude_data: dict[str, object] | None,
+    payload: dict[str, object],
+    *,
+    fallback: dict[str, object],
+) -> dict[str, object]:
+    """Attach the rows-only siblings without mutating the caller's dict.
+
+    ``providers.claude.projects.aggregate`` and
+    ``providers.claude.periods.daily_aggregate`` are rows and nothing else — no
+    range, no outcome. Those live once, on the All source.
+    """
+    base = dict(claude_data) if claude_data is not None else dict(fallback)
+    if "projects" in payload:
+        projects = dict(base.get("projects") or {})
+        projects["aggregate"] = {"rows": payload["projects"]}
+        base["projects"] = projects
+    if "daily" in payload:
+        periods = dict(base.get("periods") or {})
+        periods["daily_aggregate"] = {"rows": payload["daily"]}
+        base["periods"] = periods
+    return base
+
+
+# #556 S5 §3.5 — the five dispositions, encoded on the wire. `status` published
+# means CONFIGURED AND COMPUTED. Everything else is an optional sibling that is
+# omitted when inapplicable, so the ordinary no-budget payload is byte-identical
+# to what shipped before this session:
+#
+#   provider_budget_unset  no key at all (the default the client assumes)
+#   account_budgets_only   `not_configured.disposition`
+#   period_unresolved      `status_unavailable.code`
+#   budget_compute_failed  `status_unavailable.code`
+#
+# The unavailable shape follows S1's `combined_unavailable` — {code, message,
+# provider} — so one client reader handles both.
+_CLAUDE_BUDGET_UNAVAILABLE_MESSAGES = {
+    "period_unresolved": (
+        "Claude's budget period could not be resolved, so no budget status "
+        "is published."
+    ),
+    "budget_compute_failed": (
+        "Claude's budget status could not be computed."
+    ),
+}
+
+
+def _tui_claude_budget_period(claude_budget: "Mapping[str, object] | None") -> str:
+    """The configured Claude budget period, defaulting to ``subscription-week``.
+
+    One reader for the capability record and the published status, so the two
+    can never name different periods.
+    """
+    config = claude_budget if isinstance(claude_budget, Mapping) else {}
+    return str(config.get("period") or "subscription-week")
+
+
+def _tui_claude_budget_window_identity(
+    claude_budget: "Mapping[str, object] | None",
+    *,
+    now_utc: dt.datetime,
+    display_tz_name: str | None,
+    week_start_name: str,
+) -> str:
+    """The configured CALENDAR budget window's end, as a version fragment.
+
+    #556 S5 Unit 1 review R5, kept as DEFENCE IN DEPTH — not a fix for a
+    shipped user-visible defect. `claude_version` carries
+    `_tui_claude_period_identity`, which reads the SUBSCRIPTION-WEEK bounds and
+    therefore tracks that period's boundary and no other. On a `calendar-week`
+    or `calendar-month` budget the fragment that already moved was S2's
+    aggregate-range fragment, and that one moves at DISPLAY-TIMEZONE midnight:
+    `resolve_shared_range` (`bin/_cctally_dashboard.py`) floors the earliest
+    day to midnight in the resolved display zone, and production passes ONE
+    resolved zone object to both legs — `_tui_build_snapshot` sets
+    `source_display_tz_name` from `_build_display_tz` and hands the same object
+    to `_tui_common_source_range_start`, while `_resolve_display_tz_obj` always
+    returns a `ZoneInfo`. A `calendar-week` or `calendar-month` boundary falls
+    at local midnight, so the aggregate fragment already moved with it.
+
+    The Unit 2 review corrected the Unit 1 claim that this reproduced a
+    production defect: the reproduction went red only because the test helper
+    paired `display_tz_name="America/New_York"` with a UTC range start, which
+    is a configuration production cannot construct. The fragment stays because
+    it makes the budget window's own boundary the thing that invalidates the
+    budget's own generation, rather than leaving that to a neighbouring
+    fragment that happens to move at the same instant.
+
+    Returns `""` for `subscription-week`, which `_tui_claude_period_identity`
+    already covers from the same bounds, and for an unconfigured budget — so an
+    install with no budget produces a byte-identical version string. Calendar
+    resolution is PURE (no database), which is what lets it run before the reuse
+    decision on every tick.
+
+    A resolution failure contributes `""` rather than raising: the same failure
+    reaches `_tui_claude_budget_domain`, which names `budget_compute_failed`.
+    """
+    config = claude_budget if isinstance(claude_budget, Mapping) else {}
+    if config.get("weekly_usd") is None:
+        return ""
+    period = _tui_claude_budget_period(config)
+    if period == "subscription-week":
+        return ""
+    try:
+        window = _tui_claude_budget_window(
+            None,
+            period=period,
+            now_utc=now_utc,
+            display_tz_name=display_tz_name,
+            week_start_name=week_start_name,
+        )
+    except Exception:
+        return ""
+    if window is None:
+        return ""
+    return window[1].isoformat()
+
+
+def _tui_claude_budget_unavailable(
+    code: str,
+    *,
+    budget_usd: float | None = None,
+    period: str | None = None,
+) -> dict[str, object]:
+    """The `{code, message, provider}` sibling, plus what the user configured.
+
+    #556 S5 Unit 2 review F5. §4.6 requires `period_unresolved` to render "the
+    configured amount with the window named as unresolved", and the client had
+    no amount to render: this payload carried the code, the message and the
+    provider, so the block printed the bare code and nothing else. Both codes
+    are reached ONLY from a configured budget, so both carry the configured
+    amount and period; they are additive and omitted when the caller has
+    nothing to state, which keeps every other consumer's shape unchanged.
+    """
+    payload: dict[str, object] = {
+        "code": code,
+        "message": _CLAUDE_BUDGET_UNAVAILABLE_MESSAGES[code],
+        "provider": "claude",
+    }
+    if budget_usd is not None:
+        try:
+            payload["budget_usd"] = float(budget_usd)
+        except (TypeError, ValueError):
+            # The `budget_compute_failed` caller runs INSIDE the only exception
+            # boundary the Claude build has, so a second raise here would take
+            # the whole bundle down. Omitting the amount degrades this one line.
+            pass
+    if period is not None:
+        payload["period"] = period
+    return payload
+
+
+def _tui_claude_budget_window(
+    stats_conn,
+    *,
+    period: str,
+    now_utc: dt.datetime,
+    display_tz_name: str | None,
+    week_start_name: str,
+):
+    """Resolve the Claude budget window, or ``None`` when it cannot be resolved.
+
+    #556 S5 §3.1: the IMPURE resolvers stay here and are injected into the pure
+    kernel. Subscription-week resolution reads ``weekly_usage_snapshots`` (and
+    returns ``None`` before the first snapshot lands, which the CLI reports as
+    ``status: "no_data"``); calendar resolution goes through the same DST-correct
+    `_resolve_calendar_window` the Codex side already uses, including its
+    per-instant `display.tz = local` path.
+    """
+    from zoneinfo import ZoneInfo
+
+    c = _cctally()
+    forecast = c._load_sibling("_cctally_forecast")
+    if period == "subscription-week":
+        window = forecast._resolve_current_budget_window(stats_conn, now_utc)
+        if window is None:
+            return None
+        start_at, end_at = window
+    else:
+        tz = ZoneInfo(display_tz_name) if display_tz_name else None
+        start_at, end_at = forecast._resolve_calendar_window(
+            period, now_utc, {"collector": {"week_start": week_start_name}}, tz,
+        )
+    return (
+        start_at.astimezone(dt.timezone.utc),
+        end_at.astimezone(dt.timezone.utc),
+    )
+
+
+def _tui_claude_budget_cost_events(
+    cache_conn, *, start_at: dt.datetime, end_at: dt.datetime,
+) -> tuple[tuple[dt.datetime, float], ...]:
+    """Freeze every configured-window Claude cost event for idle pace updates.
+
+    #556 S5 §3.7: trailing-24h spend CANNOT be derived from the status
+    aggregate — `_refresh_budget_status_clock` iterates individual events — so
+    the same per-event carrier Codex keeps in server-private `clock_data` is
+    built here for Claude. It runs on the caller's PINNED cache connection and
+    reuses `iter_shared_range_entries` plus `_shared_range_row_to_usage_entry`,
+    which route through the `claude_usage_dict` chokepoint and therefore price
+    the 1-hour cache-write portion correctly (#195).
+    """
+    c = _cctally()
+    events: list[tuple[dt.datetime, float]] = []
+    for row in c.iter_shared_range_entries(
+        cache_conn, start=start_at, end_exclusive=end_at,
+    ):
+        entry = c._shared_range_row_to_usage_entry(row)
+        timestamp = entry.timestamp
+        if timestamp.tzinfo is None or timestamp.utcoffset() is None:
+            timestamp = timestamp.replace(tzinfo=dt.timezone.utc)
+        events.append((
+            timestamp.astimezone(dt.timezone.utc),
+            c._calculate_entry_cost(
+                entry.model, entry.usage, mode="auto", cost_usd=entry.cost_usd,
+            ),
+        ))
+    return tuple(events)
+
+
+def _tui_claude_budget_domain(
+    cache_conn,
+    stats_conn,
+    *,
+    claude_budget: "Mapping[str, object] | None",
+    now_utc: dt.datetime,
+    display_tz_name: str | None,
+    week_start_name: str,
+) -> tuple[dict[str, object], tuple[tuple[dt.datetime, float], ...]]:
+    """Return ``(budget_domain_overlay, cost_events)`` for the Claude provider.
+
+    The status is VENDOR-WIDE (spec §3.4). A populated `budget.accounts` is NOT
+    consumed to simulate per-account scoping: Claude publishes no
+    `account_scopes` for such a map to describe, so an account-only
+    configuration is its own disposition rather than a fabricated status.
+
+    Every failure is caught HERE. The Claude build has no error boundary of its
+    own — unlike the Codex build at `_tui_build_source_bundle`'s
+    `source_build_failed` handler — so an escaping budget error would take the
+    whole bundle down, not merely the provider.
+    """
+    config = claude_budget if isinstance(claude_budget, Mapping) else {}
+    target = config.get("weekly_usd")
+    if target is None:
+        if config.get("accounts"):
+            return {"not_configured": {"disposition": "account_budgets_only"}}, ()
+        return {}, ()
+    # Resolved BEFORE the boundary so the `budget_compute_failed` payload can
+    # still name the configured period (#556 S5 Unit 2 review F5); the reader
+    # is a pure config lookup with no failure mode of its own.
+    period = _tui_claude_budget_period(config)
+    try:
+        c = _cctally()
+        window = _tui_claude_budget_window(
+            stats_conn,
+            period=period,
+            now_utc=now_utc,
+            display_tz_name=display_tz_name,
+            week_start_name=week_start_name,
+        )
+        if window is None:
+            return {
+                "status_unavailable": _tui_claude_budget_unavailable(
+                    "period_unresolved", budget_usd=target, period=period),
+            }, ()
+        start_at, end_at = window
+        events = _tui_claude_budget_cost_events(
+            cache_conn, start_at=start_at, end_at=end_at,
+        )
+        recent_start = max(start_at, now_utc - dt.timedelta(hours=24))
+        status = c.budget_status_payload(
+            period=period,
+            window_start_at=start_at,
+            window_end_at=end_at,
+            target_usd=target,
+            spent_usd=sum(
+                cost for timestamp, cost in events
+                if start_at <= timestamp < now_utc
+            ),
+            recent_24h_usd=sum(
+                cost for timestamp, cost in events
+                if recent_start <= timestamp < now_utc
+            ),
+            now=now_utc,
+            alert_thresholds=config["alert_thresholds"],
+        )
+    except Exception:
+        _lib_log.get_logger("dashboard").error(
+            "claude budget status could not be computed", exc_info=True,
+        )
+        return {
+            "status_unavailable": _tui_claude_budget_unavailable(
+                "budget_compute_failed", budget_usd=target, period=period),
+        }, ()
+    # #556 S5 Unit 1 review R4 — retain ONLY the events a later reclock can
+    # read. `_refresh_budget_status_clock` consults the carrier for exactly one
+    # quantity, `recent_24h_usd` over `[max(window_start, now - 24h), now)`, and
+    # `now` advances monotonically, so an event older than `now_utc - 24h` is
+    # unreadable for the life of this retained state. `spent_usd` above is
+    # already summed from the FULL set, so nothing published is lost — while a
+    # `calendar-month` budget would otherwise pin up to 31 days of Claude
+    # `session_entries` and make every reclock tick walk all of them.
+    reclock_floor = now_utc - dt.timedelta(hours=24)
+    retained = tuple(
+        (timestamp, cost) for timestamp, cost in events
+        if timestamp >= reclock_floor
+    )
+    return {"status": status}, retained
+
+
+def _tui_claude_data_with_budget(
+    base: dict[str, object], overlay: dict[str, object],
+) -> dict[str, object]:
+    """Merge the budget overlay without mutating the caller's dict.
+
+    An empty overlay returns the base unchanged, which is what keeps the
+    `provider_budget_unset` payload byte-identical.
+    """
+    if not overlay:
+        return base
+    merged = dict(base)
+    merged["budget"] = {**(merged.get("budget") or {}), **overlay}
+    return merged
+
+
 def _tui_build_source_bundle(
     *,
     stats_conn,
@@ -2733,6 +3272,7 @@ def _tui_build_source_bundle(
     claude_total_tokens: int,
     claude_data: dict[str, object] | None = None,
     common_range_start: dt.datetime | None = None,
+    projects_envelope: dict | None = None,
     prior_bundle: SourceDashboardBundle | None = None,
     raw_config: dict[str, object] | None = None,
 ) -> SourceDashboardBundle:
@@ -2758,10 +3298,48 @@ def _tui_build_source_bundle(
             cache_conn.execute("BEGIN")
             cache_read_tx = True
         if common_range_start is None:
-            common_range_start = now_utc - dt.timedelta(days=30)
+            # Resolved through the SAME helper the callers use, with no daily
+            # panel. A bare `now_utc - 30 days` here is a microsecond-precise
+            # instant that advances on every tick, and the resolved start is
+            # folded into both providers' version material at exactly the
+            # granularity `compose_all_aggregates` compares it — so a start
+            # that moves within a display day makes an unchanged provider's
+            # retained carrier disagree with a rebuilt one's, and both
+            # aggregates are then withheld as `retained_range_mismatch`
+            # permanently. Both production callers pass a resolved start, so
+            # this is the last producer that could reintroduce that shape.
+            #
+            # The zone lookup is guarded because this branch exists to be a
+            # SAFE fallback. An unresolvable `display_tz_name` raising out of
+            # it would take down the whole source build over the one path whose
+            # purpose is to keep going, so an unusable name degrades to UTC —
+            # which is what `resolve_shared_range` already does for `None`.
+            from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+            _fallback_tz = None
+            if display_tz_name:
+                try:
+                    _fallback_tz = ZoneInfo(display_tz_name)
+                except (ZoneInfoNotFoundError, ValueError, OSError):
+                    _fallback_tz = None
+            common_range_start, _fallback_end = c.resolve_shared_range(
+                None,
+                now_utc=now_utc,
+                display_tz=_fallback_tz,
+            )
         if common_range_start.tzinfo is None or common_range_start.utcoffset() is None:
             raise ValueError("common_range_start must be timezone-aware")
         common_range_start = common_range_start.astimezone(dt.timezone.utc)
+        # #556 S2 §3.2: ONE interval, resolved once and passed immutably to
+        # both Claude folds and to the Codex read. The exclusive upper bound is
+        # what the Codex projects read already applies, so the Codex tab stays
+        # byte-stable. The PUBLISHED `end_at` is `now_utc` itself.
+        shared_end_exclusive = now_utc.astimezone(
+            dt.timezone.utc,
+        ) + dt.timedelta(microseconds=1)
+        published_range = aggregate_range(
+            common_range_start.isoformat(),
+            now_utc.astimezone(dt.timezone.utc).isoformat(),
+        )
         semantics = resolve_dashboard_source_semantics(
             raw_config if raw_config is not None else c.load_config(),
             display_tz_name=display_tz_name,
@@ -2784,6 +3362,11 @@ def _tui_build_source_bundle(
         from _cctally_quota import assert_projection_readable
         assert_projection_readable(stats_conn)
         stats_digest = codex_stats_digest(stats_conn)
+        # #556 S3 §2.9: the Claude alert relations. Nothing else in the
+        # signature moves when a Claude alert fires or is armed, so without
+        # this the idle path can keep serving a prior bundle that predates the
+        # alert.
+        claude_digest = claude_stats_digest(stats_conn)
         # #341 finding 9: the account registry/active-identity digest. Empty for
         # every <=1-account install (byte-neutral — appended only when non-empty),
         # so single-account source versions stay byte-identical to today; a
@@ -2798,6 +3381,7 @@ def _tui_build_source_bundle(
             generation=c.current_generation(),
             codex_stats_digest=stats_digest,
             accounts_digest=accounts_digest,
+            claude_stats_digest=claude_digest,
         )
         _acct_suffix = f":a{accounts_digest}" if accounts_digest else ""
         # public #5: the hook's budgeted ingest can change what the Codex
@@ -2808,20 +3392,50 @@ def _tui_build_source_bundle(
         # wire. Empty (and so byte-neutral) once the backlog has drained.
         _backlog = getattr(signature, "codex_ingest_backlog_sig", "")
         _backlog_suffix = f":b{_backlog}" if _backlog else ""
+        # #556 S2 §3.6: the resolved range and the per-aggregate outcome enter
+        # BOTH providers' version material. Both, so a shared-start change (a
+        # display-day rollover) rebuilds them in lockstep and a coherent pair
+        # can never disagree about the interval their rows cover. The fragment
+        # below assumes SUCCESS, which is what makes it also the reuse gate: a
+        # prior generation whose fold failed carries a different fragment and
+        # therefore cannot be reused.
+        _aggregate_suffix = ":g" + aggregate_scope_identity(
+            build_aggregate_scope(published_range),
+        )
         codex_version = (
             f"codex:{signature.max_codex_id}:"
             f"{signature.codex_physical_mutation_seq}:{stats_digest}:"
             f"{semantics.codex_identity}{_acct_suffix}{_backlog_suffix}"
+            f"{_aggregate_suffix}"
         )
+        # #582: the dedicated accounting ledger is deliberately absent from
+        # the published version string (byte-stable API contract), but an
+        # id-stable token/account/project mutation still has to bypass exact
+        # provider reuse so the incremental path can consume it.
+        _codex_accounting_pending = c._load_sibling(
+            "_lib_snapshot_cache"
+        ).codex_accounting_cache_pending(cache_conn)
         # #556 S1 §3.6: normalized period identity, so a nominal week rollover
         # invalidates the generation even when no database signature moved.
         _period_identity = _tui_claude_period_identity(claude_data)
+        # #556 S5 (Unit 1 review R5) — the CONFIGURED budget period has its own
+        # boundary, and `_period_identity` above tracks only the subscription
+        # week. Empty for an unconfigured or subscription-week budget, so the
+        # version string is byte-identical on every install that had one before.
+        _budget_identity = _tui_claude_budget_window_identity(
+            semantics.claude_budget,
+            now_utc=now_utc,
+            display_tz_name=display_tz_name,
+            week_start_name=semantics.week_start_name,
+        )
+        _budget_suffix = f":b{_budget_identity}" if _budget_identity else ""
         claude_version = (
             f"claude:{signature.max_entry_id}:{signature.entry_mutation_seq}:"
             f"{signature.max_wus_id}:{signature.max_wcs_id}:"
             f"{signature.reset_sig[0]}:{signature.reset_sig[1]}:"
             f"{signature.generation}:{semantics.claude_identity}"
-            f":p{_period_identity}{_acct_suffix}"
+            f":p{_period_identity}{_budget_suffix}{_acct_suffix}"
+            f"{_aggregate_suffix}:x{claude_digest}"
         )
         prior_claude = (
             prior_bundle.sources.get("claude")
@@ -2853,6 +3467,14 @@ def _tui_build_source_bundle(
             claude = reuse_coherent_source_state(
                 prior_claude, data_version=claude_version,
             )
+            # #556 S2 §3.6, gate 2 of 2. The version fragment above already
+            # rejects a failed generation, but this gate is stated explicitly
+            # rather than left implicit in string arithmetic: exact-version
+            # provider reuse returns the PRIOR OBJECT unchanged, so a caught
+            # fold failure that survived reuse would withhold the aggregate for
+            # the life of the process. Gate 1 is the bundle-level idle guard.
+            if claude is not None and aggregate_scope_failed(claude):
+                claude = None
         if claude is None:
             claude_available = "ok" if (claude_cost_usd or claude_total_tokens) else "empty"
             # #341 Task 4 (Ruling C): the conditional per-account Claude wire,
@@ -2875,6 +3497,64 @@ def _tui_build_source_bundle(
                 # wire must never fail the whole dashboard tick — it just falls
                 # back to the byte-stable undecorated shape.
                 claude_accounts = []
+            # #556 S2 §3.3: both All-only Claude legs fold HERE, on the pinned
+            # cache connection, after BEGIN and beside the Codex read, so the
+            # two providers describe one snapshot. Folding them earlier — in
+            # the attached-cache block or through the Group-A daily read — runs
+            # against a different connection, and a cache commit in between
+            # would publish Claude generation A beside Codex generation B while
+            # the bundle's version names B.
+            aggregate_payload, aggregate_outcomes = _tui_build_claude_aggregates(
+                cache_conn,
+                shared_start=common_range_start,
+                shared_end_exclusive=shared_end_exclusive,
+                now_utc=now_utc,
+                display_tz_name=semantics.display_tz_name,
+                # The legacy display keys the drill-down route resolves
+                # against. Published rows adopt them wherever they exist, so
+                # the aggregate identity and the legacy one agree and the
+                # bounded rows stay routable. The raw envelope is required —
+                # `claude_data` has already replaced every legacy display key
+                # with an opaque key and dropped `bucket_path`, so the map
+                # cannot be recovered from it.
+                # `None` — not an empty map — when no envelope was built, so
+                # the fold can tell "the legacy population is empty" from "the
+                # legacy population is unknown" and withhold on the second.
+                legacy_labels=(
+                    c.legacy_project_labels(projects_envelope)
+                    if projects_envelope is not None else None
+                ),
+                max_entry_id=signature.max_entry_id,
+                entry_mutation_seq=signature.entry_mutation_seq,
+                generation=signature.generation,
+            )
+            # #556 S5 §3.2: the Claude budget fold runs HERE, on this
+            # function's own pinned cache snapshot — the same snapshot the S2
+            # folds and the Codex read use. That is the narrow, true claim: the
+            # legacy Claude envelope was constructed BEFORE this call, and
+            # stats.db deliberately stays in statement-scoped autocommit, so
+            # this is not coherence with every number in the envelope.
+            claude_budget_overlay, claude_budget_events = _tui_claude_budget_domain(
+                cache_conn,
+                stats_conn,
+                claude_budget=semantics.claude_budget,
+                now_utc=now_utc,
+                display_tz_name=semantics.display_tz_name,
+                week_start_name=semantics.week_start_name,
+            )
+            claude_aggregate_scope = build_aggregate_scope(
+                published_range, aggregate_outcomes,
+            )
+            if aggregate_scope_failed(claude_aggregate_scope):
+                # The published version must distinguish a failed fold from a
+                # successful one over the same signature and the same bounds;
+                # otherwise both would publish different rows under one
+                # `data_version`. It also makes the next tick's success-shaped
+                # candidate version mismatch, forcing the rebuild §3.6 requires.
+                claude_version = (
+                    f"{claude_version}:x"
+                    f"{aggregate_scope_identity(claude_aggregate_scope)}"
+                )
             claude = SourceDashboardState(
                 source="claude",
                 availability=claude_available,
@@ -2890,31 +3570,51 @@ def _tui_build_source_bundle(
                     "sessions": CapabilityRecord("supported", "legacy-session-rollup"),
                     "forensics": CapabilityRecord("supported", "legacy-projection"),
                     "quota": CapabilityRecord("supported", "subscription-week"),
-                    "budget": CapabilityRecord("supported", "subscription-week"),
+                    # #556 S5 §3.6: the CONFIGURED period, not a constant. This
+                    # record used to say `subscription-week` unconditionally
+                    # while Codex advertised `calendar-period`, and once the
+                    # published status beside it can carry `calendar-week` or
+                    # `calendar-month` the constant contradicts the very object
+                    # it describes. The default period IS `subscription-week`,
+                    # so an install with no budget configured advertises exactly
+                    # what it advertised before.
+                    "budget": CapabilityRecord(
+                        "supported", _tui_claude_budget_period(
+                            semantics.claude_budget),
+                    ),
                     "projects": CapabilityRecord("supported", "legacy-projection"),
                     "alerts": CapabilityRecord("supported", "provider-native"),
                 },
                 data={
-                    **(
-                        claude_data
-                        if claude_data is not None else {
-                            "hero": {
-                                "cost_usd": claude_cost_usd,
-                                "total_tokens": claude_total_tokens,
+                    **_tui_claude_data_with_budget(
+                        _tui_claude_data_with_aggregates(
+                            claude_data,
+                            aggregate_payload,
+                            fallback={
+                                "hero": {
+                                    "cost_usd": claude_cost_usd,
+                                    "total_tokens": claude_total_tokens,
+                                },
+                                "periods": {"daily": {"total_cost_usd": claude_cost_usd, "total_tokens": claude_total_tokens}},
+                                "sessions": {"rows": ()},
+                                "projects": {"rows": ()},
+                                "quota": {"blocks": (), "milestones": ()},
+                                "budget": {"label": "Claude subscription budget"},
+                                "alerts": {"rows": ()},
                             },
-                            "periods": {"daily": {"total_cost_usd": claude_cost_usd, "total_tokens": claude_total_tokens}},
-                            "sessions": {"rows": ()},
-                            "projects": {"rows": ()},
-                            "quota": {"blocks": (), "milestones": ()},
-                            "budget": {"label": "Claude subscription budget"},
-                            "alerts": {"rows": ()},
-                        }
+                        ),
+                        claude_budget_overlay,
                     ),
                     **({"accounts": claude_accounts} if claude_accounts else {}),
                 },
                 domain_freshness=_tui_claude_domain_freshness(
                     claude_data, now_utc=now_utc,
                 ),
+                # #556 S5 §3.7: server-private, NEVER published. The idle clock
+                # recomputes trailing-24h spend by iterating individual events,
+                # which the status aggregate cannot supply.
+                clock_data={"claude_budget_cost_events": claude_budget_events},
+                aggregate_scope=claude_aggregate_scope,
             )
         if codex_ingest_failed:
             warning = SourceDashboardWarning(
@@ -2949,7 +3649,8 @@ def _tui_build_source_bundle(
             # construction: one rebuild per crossing, not one per tick.
             codex = (
                 None if prior_codex is not None and (
-                    any(
+                    _codex_accounting_pending
+                    or any(
                         warning.code == "codex_projection_incoherent"
                         for warning in prior_codex.warnings
                     )
@@ -2958,6 +3659,13 @@ def _tui_build_source_bundle(
                     prior_codex, data_version=codex_version,
                 )
             )
+            # #556 S2 §3.6: symmetric with Claude. Codex's rows are already
+            # bounded by this same range, so its carrier records no fold of its
+            # own — but a retained failure state must never be reused, and the
+            # gate is stated on both providers so a future Codex-side fold
+            # inherits it.
+            if codex is not None and aggregate_scope_failed(codex):
+                codex = None
         if codex is None:
             try:
                 codex = build_codex_source_state(
@@ -2977,6 +3685,13 @@ def _tui_build_source_bundle(
                     ),
                     data_version=codex_version,
                 )
+                # Attached ONLY on a fresh build, never on the reuse or degrade
+                # paths: those carry rows this tick did not produce, and their
+                # own carrier already describes the range that bounds them.
+                codex = dataclasses.replace(
+                    codex,
+                    aggregate_scope=build_aggregate_scope(published_range),
+                )
             except Exception:
                 _lib_log.get_logger("dashboard").error(
                     "codex_read_model source build failed",
@@ -2995,9 +3710,18 @@ def _tui_build_source_bundle(
         # cycle's expiry invariant holds on EVERY path, including the reuse
         # path that returns the exact prior object (§2.5). Same-instant identity
         # is preserved by ``refresh_codex_source_clock``'s own data-equality
-        # guard, so a freshly built state is handed back unchanged. Claude is
-        # deliberately untouched.
+        # guard, so a freshly built state is handed back unchanged.
         codex = refresh_codex_source_clock(codex, now_utc=now_utc)
+        # #556 S5 §3.7: Claude is clocked here too, on the same terms and for
+        # the same reason. This comment used to say Claude was deliberately
+        # untouched, and that was correct only while Claude published nothing
+        # time-dependent. It now publishes a budget pace, and exact-version
+        # reuse returns the PRIOR OBJECT unchanged — so any tick another source
+        # forced would have republished a budget frozen at its build instant.
+        # Only the budget leg runs here: the two freshness axes need the legacy
+        # `current_week` object, which this builder does not hold, and they are
+        # already advanced by the pure-idle clock that does.
+        claude = _refresh_claude_budget_clock(claude, now_utc=now_utc)
         # #556 S1 §3.8: the decoration fact reaches composition as authoritative
         # server-only metadata. It is attached HERE, after every build / reuse /
         # degrade / clock branch, so no branch can publish a state without it.
@@ -3026,12 +3750,14 @@ def _tui_build_source_bundle(
             cache_read_tx = False
         post_stats_digest = codex_stats_digest(stats_conn)
         post_accounts_digest = accounts_identity_digest(stats_conn)
+        post_claude_digest = claude_stats_digest(stats_conn)
         post_signature = c.compute_signature(
             cache_conn,
             stats_conn,
             generation=c.current_generation(),
             codex_stats_digest=post_stats_digest,
             accounts_digest=post_accounts_digest,
+            claude_stats_digest=post_claude_digest,
         )
         stats_generation_moved = (
             post_signature.max_wus_id != signature.max_wus_id
@@ -3039,6 +3765,7 @@ def _tui_build_source_bundle(
             or post_signature.reset_sig != signature.reset_sig
             or post_stats_digest != stats_digest
             or post_accounts_digest != accounts_digest
+            or post_claude_digest != claude_digest
         )
         if stats_generation_moved:
             if prior_bundle is not None:
@@ -3111,6 +3838,14 @@ def _tui_source_bundle_can_idle(bundle: SourceDashboardBundle | None) -> bool:
                 or state.freshness != "fresh"
                 or state.data is None):
             return False
+        # #556 S2 §3.6, gate 1 of 2. A locally caught fold failure leaves an
+        # otherwise `ok` and `fresh` provider, so without this leg the bundle
+        # would qualify for idle reuse and one transient failure would withhold
+        # the aggregate for the life of the process. Falling through here routes
+        # to the bounded source-adapter rebuild, which re-folds — at most one
+        # rebuild per tick, so it creates no retry loop.
+        if aggregate_scope_failed(state):
+            return False
     return True
 
 
@@ -3120,18 +3855,18 @@ def _tui_common_source_range_start(
     now_utc: dt.datetime,
     display_tz: dt.tzinfo | None,
 ) -> dt.datetime:
-    """Return the shared provider interval from the already-built daily rows."""
-    if daily_panel:
-        earliest_day = dt.date.fromisoformat(daily_panel[-1].date)
-        if display_tz is not None:
-            return dt.datetime.combine(
-                earliest_day, dt.time.min, tzinfo=display_tz,
-            ).astimezone(dt.timezone.utc)
-        # internal fallback: host-local intentional
-        return dt.datetime.combine(
-            earliest_day, dt.time.min,
-        ).astimezone(dt.timezone.utc)
-    return now_utc - dt.timedelta(days=30)
+    """Return the shared provider interval from the already-built daily rows.
+
+    #556 S2 §3.2: the start bound is now resolved by
+    ``_cctally_dashboard.resolve_shared_range``, which also owns the exclusive
+    upper bound the Claude folds enforce. This wrapper stays because every
+    existing caller wants only the start, and because it is the monkeypatch
+    surface the source-invalidation tests already use.
+    """
+    start, _end_exclusive = _cctally().resolve_shared_range(
+        daily_panel, now_utc=now_utc, display_tz=display_tz,
+    )
+    return start
 
 
 def _tui_build_snapshot(
@@ -4058,30 +4793,37 @@ def _tui_build_snapshot_once(
                             "fingerprint": "source-projection",
                         },
                     )
-                legacy_envelope = _cctally().snapshot_to_envelope(
-                    source_snapshot,
-                    now_utc=now_utc,
-                    display_tz_pref_override=display_tz_pref_override,
-                    runtime_bind=runtime_bind,
-                )
-                source_bundle = _tui_build_source_bundle(
-                    stats_conn=conn,
-                    now_utc=now_utc,
-                    display_tz_name=(
-                        getattr(_build_display_tz, "key", None)
-                        if _build_display_tz is not None else None
-                    ),
-                    codex_ingest_contended=codex_ingest_contended,
-                    codex_ingest_failed=codex_ingest_failed,
-                    claude_ingest_contended=claude_ingest_contended,
-                    claude_ingest_failed=claude_ingest_failed,
-                    claude_cost_usd=daily_total_cost_usd,
-                    claude_total_tokens=daily_total_tokens,
-                    claude_data=_tui_project_claude_source_data(legacy_envelope),
-                    common_range_start=common_range_start,
-                    prior_bundle=prior_source_bundle,
-                    raw_config=raw_config,
-                )
+                # #566 §5.1 item 6: both calls carry their own phase. The two
+                # of them are the tail of the build and were the only region
+                # the trace never entered, so a slow store attributed 79% of
+                # its build to the root's unnamed remainder.
+                with _perf.phase("envelope.legacy_projection"):
+                    legacy_envelope = _cctally().snapshot_to_envelope(
+                        source_snapshot,
+                        now_utc=now_utc,
+                        display_tz_pref_override=display_tz_pref_override,
+                        runtime_bind=runtime_bind,
+                    )
+                with _perf.phase("build.source_bundle"):
+                    source_bundle = _tui_build_source_bundle(
+                        stats_conn=conn,
+                        now_utc=now_utc,
+                        display_tz_name=(
+                            getattr(_build_display_tz, "key", None)
+                            if _build_display_tz is not None else None
+                        ),
+                        codex_ingest_contended=codex_ingest_contended,
+                        codex_ingest_failed=codex_ingest_failed,
+                        claude_ingest_contended=claude_ingest_contended,
+                        claude_ingest_failed=claude_ingest_failed,
+                        claude_cost_usd=daily_total_cost_usd,
+                        claude_total_tokens=daily_total_tokens,
+                        claude_data=_tui_project_claude_source_data(legacy_envelope),
+                        common_range_start=common_range_start,
+                        projects_envelope=projects_envelope_block,
+                        prior_bundle=prior_source_bundle,
+                        raw_config=raw_config,
+                    )
                 if source_bundle is None:
                     raise RuntimeError("source bundle builder returned no bundle")
             except QuotaProjectionIncomplete as exc:
@@ -4232,6 +4974,7 @@ def _tui_compute_dispatch_signature(stats_conn):
             generation=sc.current_generation(),
             codex_stats_digest=codex_stats_digest(stats_conn),
             accounts_digest=accounts_identity_digest(stats_conn),
+            claude_stats_digest=claude_stats_digest(stats_conn),
         )
     finally:
         cache_conn.close()
@@ -4409,6 +5152,7 @@ def _tui_build_idle_snapshot(prior, *, now_utc, precompute_envelope,
                         now_utc=now_utc,
                         display_tz=source_display_tz,
                     ),
+                    projects_envelope=prior.projects_envelope,
                     prior_bundle=source_bundle,
                     raw_config=raw_config,
                 )