cctally 1.21.3 → 1.22.0

package/bin/cctally

@@ -204,6 +204,11 @@ _AlertsConfigError = _cctally_core._AlertsConfigError
 _ALERTS_CONFIG_VALID_KEYS = _cctally_core._ALERTS_CONFIG_VALID_KEYS
 _validate_threshold_list = _cctally_core._validate_threshold_list
 _get_alerts_config = _cctally_core._get_alerts_config
+_BudgetConfigError = _cctally_core._BudgetConfigError
+_BUDGET_DEFAULTS = _cctally_core._BUDGET_DEFAULTS
+_BUDGET_CONFIG_VALID_KEYS = _cctally_core._BUDGET_CONFIG_VALID_KEYS
+_get_budget_config = _cctally_core._get_budget_config
+_budget_alerts_active = _cctally_core._budget_alerts_active
 open_db = _cctally_core.open_db
 WeekRef = _cctally_core.WeekRef
 _canonicalize_optional_iso = _cctally_core._canonicalize_optional_iso
@@ -275,6 +280,35 @@ CODEX_FAST_MULTIPLIER_FALLBACK = _lib_pricing.CODEX_FAST_MULTIPLIER_FALLBACK
 _codex_config_requests_fast_service_tier = _lib_pricing._codex_config_requests_fast_service_tier
 _short_model_name = _lib_pricing._short_model_name
 
+# Pricing-freshness check (spec 2026-05-29): pure-fn kernel re-exported here
+# like the other _lib_* kernels. The kernel takes the pricing predicates +
+# tables + observed rows as injected args; the I/O glue (cache scan, HTTP
+# fetchers, the doctor coverage wiring) lives in bin/cctally.
+_lib_pricing_check = _load_sibling("_lib_pricing_check")
+classify_coverage = _lib_pricing_check.classify_coverage
+scope_litellm = _lib_pricing_check.scope_litellm
+diff_pricing = _lib_pricing_check.diff_pricing
+stale_allowlist_entries = _lib_pricing_check.stale_allowlist_entries
+check_table_shapes = _lib_pricing_check.check_table_shapes
+pricing_issue_action = _lib_pricing_check.pricing_issue_action
+CoverageGap = _lib_pricing_check.CoverageGap
+DriftRow = _lib_pricing_check.DriftRow
+DriftResult = _lib_pricing_check.DriftResult
+PRICING_SNAPSHOT_DATE = _lib_pricing.PRICING_SNAPSHOT_DATE
+PRICING_STALENESS_DAYS = _lib_pricing.PRICING_STALENESS_DAYS
+PRICING_DRIFT_ALLOWLIST = _lib_pricing.PRICING_DRIFT_ALLOWLIST
+LITELLM_PRICES_URL = _lib_pricing.LITELLM_PRICES_URL
+
+# Budget kernel (spec 2026-05-29): pure-fn kernel re-exported here like the
+# other _lib_* kernels. `project_linear` is the shared projection primitive
+# (forecast routes its EOW % projection through it too — spec F1). The I/O
+# glue (spend gather, the `budget` subcommand) lives in bin/cctally.
+_lib_budget = _load_sibling("_lib_budget")
+BudgetInputs = _lib_budget.BudgetInputs
+BudgetStatus = _lib_budget.BudgetStatus
+compute_budget_status = _lib_budget.compute_budget_status
+project_linear = _lib_budget.project_linear
+
 # Per-model context window (used by `cctally statusline` segment 4).
 # Keep in sync with Anthropic's docs:
 #   https://docs.anthropic.com/en/docs/about-claude/models
@@ -337,9 +371,11 @@ def _nonneg_int(raw: str) -> int:
 _lib_alerts_payload = _load_sibling("_lib_alerts_payload")
 _alert_text_weekly = _lib_alerts_payload._alert_text_weekly
 _alert_text_five_hour = _lib_alerts_payload._alert_text_five_hour
+_alert_text_budget = _lib_alerts_payload._alert_text_budget
 _escape_applescript_string = _lib_alerts_payload._escape_applescript_string
 _build_alert_payload_weekly = _lib_alerts_payload._build_alert_payload_weekly
 _build_alert_payload_five_hour = _lib_alerts_payload._build_alert_payload_five_hour
+_build_alert_payload_budget = _lib_alerts_payload._build_alert_payload_budget
 
 _lib_five_hour = _load_sibling("_lib_five_hour")
 _FIVE_HOUR_JITTER_FLOOR_SECONDS = _lib_five_hour._FIVE_HOUR_JITTER_FLOOR_SECONDS
@@ -692,6 +728,7 @@ _cctally_record = _load_sibling("_cctally_record")
 _PERCENT_NORMALIZE_DECIMALS = _cctally_record._PERCENT_NORMALIZE_DECIMALS
 _normalize_percent = _cctally_record._normalize_percent
 maybe_record_milestone = _cctally_record.maybe_record_milestone
+maybe_record_budget_milestone = _cctally_record.maybe_record_budget_milestone
 _compute_block_totals = _cctally_record._compute_block_totals
 maybe_update_five_hour_block = _cctally_record.maybe_update_five_hour_block
 cmd_record_usage = _cctally_record.cmd_record_usage
@@ -2066,6 +2103,22 @@ def _warn_alerts_bad_config_once(exc: Exception) -> None:
     eprint(f"[alerts] invalid config, skipping dispatch: {exc}")
 
 
+_BUDGET_BAD_CONFIG_WARNED = False  # one-shot warn flag for malformed budget block
+
+
+def _warn_budget_bad_config_once(exc: Exception) -> None:
+    """Emit a single stderr warning per process when the budget config block
+    is malformed, so a hand-edited bad block becomes a quiet no-op on the
+    record-usage hot path instead of unthrottled per-tick stderr. Mirrors
+    `_warn_alerts_bad_config_once`.
+    """
+    global _BUDGET_BAD_CONFIG_WARNED
+    if _BUDGET_BAD_CONFIG_WARNED:
+        return
+    _BUDGET_BAD_CONFIG_WARNED = True
+    eprint(f"[budget] invalid config, skipping dispatch: {exc}")
+
+
 # === Update subsystem main body (state/lock/log, install-method
 # detection, version-check pipeline, install execution, dashboard
 # UpdateWorker + _DashboardUpdateCheckThread, cmd_update,
@@ -3510,6 +3563,110 @@ def insert_percent_milestone(
     return int(cur.rowcount)
 
 
+def insert_budget_milestone(
+    conn: sqlite3.Connection,
+    *,
+    week_start_at: str,
+    threshold: int,
+    budget_usd: float,
+    spent_usd: float,
+    consumption_pct: float,
+    commit: bool = True,
+) -> int:
+    """INSERT OR IGNORE a budget threshold crossing. Returns ``cur.rowcount``
+    (1 = genuinely new crossing, 0 = INSERT OR IGNORE no-op on a pre-existing
+    ``(week_start_at, threshold)`` row).
+
+    Mirrors :func:`insert_percent_milestone`'s rowcount contract so the
+    alert-fire predicate (`if inserted == 1`) is race-safe without a
+    follow-up SELECT. ``alerted_at`` is left NULL — the caller stamps it in
+    the SAME transaction BEFORE dispatching (set-then-dispatch invariant,
+    CLAUDE.md Alerts gotcha). ``commit=False`` lets the caller bundle the
+    INSERT with the follow-up ``alerted_at`` UPDATE in one transaction so a
+    crash between them can't strand ``alerted_at`` NULL forever.
+    """
+    cur = conn.execute(
+        "INSERT OR IGNORE INTO budget_milestones "
+        "(week_start_at, threshold, budget_usd, spent_usd, consumption_pct, "
+        " crossed_at_utc) "
+        "VALUES (?, ?, ?, ?, ?, ?)",
+        (
+            week_start_at,
+            int(threshold),
+            float(budget_usd),
+            float(spent_usd),
+            float(consumption_pct),
+            now_utc_iso(),
+        ),
+    )
+    if commit:
+        conn.commit()
+    return int(cur.rowcount)
+
+
+def _reconcile_budget_milestones_on_set(conn, *, target, thresholds, now_utc):
+    """Forward-only-from-set reconcile (spec §5): on `budget set`, every
+    threshold ALREADY crossed for the current week is recorded with
+    ``alerted_at`` SET but WITHOUT dispatch — so setting a budget when you're
+    already at 95% does NOT instant-popup. Thresholds not yet crossed get NO
+    row, so they fire later via :func:`maybe_record_budget_milestone`.
+
+    A mid-week target change re-runs this; thresholds already alerted stay
+    deduped via UNIQUE(week_start_at, threshold) + the ``alerted_at IS NULL``
+    guard on the UPDATE (so an existing alerted row is never re-stamped).
+    """
+    window = _resolve_current_budget_window(conn, now_utc)
+    if window is None:
+        return
+    week_start_at, _week_end_at = window
+    week_key = week_start_at.isoformat(timespec="seconds")
+    spent = _sum_cost_for_range(week_start_at, now_utc, mode="auto")
+    # target > 0 guaranteed by the caller (_cmd_budget_set passes the validated
+    # weekly_usd); the else is belt-and-suspenders.
+    consumption_pct = (spent / target * 100.0) if target > 0 else 0.0
+    for t in sorted(thresholds):
+        if consumption_pct + 1e-9 >= t:
+            insert_budget_milestone(
+                conn,
+                week_start_at=week_key,
+                threshold=t,
+                budget_usd=target,
+                spent_usd=spent,
+                consumption_pct=consumption_pct,
+                commit=False,
+            )
+            conn.execute(
+                "UPDATE budget_milestones SET alerted_at = ? "
+                "WHERE week_start_at = ? AND threshold = ? AND alerted_at IS NULL",
+                (now_utc_iso(), week_key, t),
+            )
+    conn.commit()
+
+
+def _reconcile_budget_on_config_write(validated_budget):
+    """Forward-only reconcile shared by all three budget-config write
+    paths (`budget set`, `config set budget.*`, dashboard POST
+    /api/settings). Gated + best-effort: a budget with alerts off or no
+    thresholds records nothing; a stats.db failure never fails the write.
+    Runs OUTSIDE any config_writer_lock (open_db has its own locking)."""
+    thresholds = validated_budget.get("alert_thresholds") or []
+    if not (_budget_alerts_active(validated_budget) and thresholds):
+        return
+    try:
+        conn = open_db()
+        try:
+            _reconcile_budget_milestones_on_set(
+                conn,
+                target=validated_budget["weekly_usd"],
+                thresholds=thresholds,
+                now_utc=_command_as_of(),
+            )
+        finally:
+            conn.close()
+    except Exception as exc:  # best-effort; never fail the write
+        eprint(f"[budget-milestone] reconcile on set failed: {exc}")
+
+
 def _backfill_five_hour_blocks(conn: sqlite3.Connection) -> int:
     """One-shot historical backfill of five_hour_blocks from existing
     weekly_usage_snapshots data. Idempotent via UNIQUE(five_hour_window_key)
@@ -7643,6 +7800,67 @@ def _apply_midweek_reset_override(
     return week_start_at, samples
 
 
+def _resolve_current_budget_window(conn, now_utc):
+    """Return ``(effective_week_start_dt, week_end_dt)`` for the subscription
+    week containing ``now_utc``, honoring a mid-week reset re-anchor; or
+    ``None`` if no snapshot exists yet.
+
+    Reuses the SAME reset-aware resolution forecast/weekly use
+    (``_fetch_current_week_snapshots`` + ``_apply_midweek_reset_override``)
+    so the budget display window and the alert-firing window (Task 3) agree.
+    Unlike forecast's ``_load_forecast_inputs``, this does NOT short-circuit
+    on an empty samples list — budget computes live spend from
+    ``session_entries`` regardless of whether a usage snapshot landed inside
+    the window, so the worst case is ``spent_usd = 0`` (spec §6), not a
+    no-window outcome.
+    """
+    fetched = _fetch_current_week_snapshots(conn, now_utc)
+    if fetched is None:
+        return None
+    week_start_at, week_end_at, samples = fetched
+    week_start_at, _samples = _apply_midweek_reset_override(
+        conn, week_start_at, week_end_at, samples
+    )
+    return (week_start_at, week_end_at)
+
+
+def _build_budget_status_inputs(conn, *, target_usd, now_utc, alert_thresholds):
+    """Gather live spend over the current subscription week and build a
+    :class:`BudgetInputs`. Returns ``None`` when no week window resolves.
+
+    Spend is recomputed live via ``_sum_cost_for_range(..., mode="auto")``
+    (the same path ``weekly`` / ``forecast`` use — pricing edits take effect
+    immediately; F3's reconcile invariant is pinned here, NOT to snapshot
+    ``report``). ``recent_24h_usd`` is a second trailing-24h call that is NOT
+    display-only: in ``_lib_budget.compute_budget_status`` it feeds
+    ``rate_recent → rate_high → projected_high → projected``, which drives the
+    ok/warn/over verdict. It is therefore clamped to the current budget week
+    (``max(week_start_at, now - 24h)``) so a heavy spend just before reset
+    can't leak last week's dollars into a fresh week's verdict (false
+    WARN/OVER).
+    """
+    window = _resolve_current_budget_window(conn, now_utc)
+    if window is None:
+        return None
+    week_start_at, week_end_at = window
+    spent = _sum_cost_for_range(week_start_at, now_utc, mode="auto")
+    # Clamp the recent-rate window at the week start: both bounds are tz-aware
+    # so max() is well-defined. Without this, a brand-new week (now < week
+    # start + 24h) would pull pre-reset spend into rate_recent and flip a
+    # fresh verdict to warn/over.
+    recent_start = max(week_start_at, now_utc - dt.timedelta(hours=24))
+    recent_24h = _sum_cost_for_range(recent_start, now_utc, mode="auto")
+    return BudgetInputs(
+        target_usd=float(target_usd),
+        spent_usd=float(spent),
+        recent_24h_usd=float(recent_24h),
+        week_start_at=week_start_at,
+        week_end_at=week_end_at,
+        now=now_utc,
+        alert_thresholds=tuple(alert_thresholds),
+    )
+
+
 def _select_dollars_per_percent(
     conn: sqlite3.Connection,
     now_utc: dt.datetime,
@@ -7851,15 +8069,17 @@ def _compute_forecast(inputs: ForecastInputs, targets: list[int]) -> ForecastOut
     else:
         r_recent = None
 
-    # Projected final %
+    # Projected final % — routed through the shared project_linear primitive
+    # (spec F1). r_recent is None ⇒ collapse to the average projection.
     if r_recent is None:
-        p_final_avg = inputs.p_now + r_avg * inputs.remaining_hours
-        final_low = final_high = p_final_avg
+        final_low, final_high = project_linear(
+            inputs.p_now, inputs.remaining_hours, r_avg, r_avg
+        )
     else:
-        p_final_avg = inputs.p_now + r_avg * inputs.remaining_hours
-        p_final_recent = inputs.p_now + r_recent * inputs.remaining_hours
-        final_low = min(p_final_avg, p_final_recent)
-        final_high = max(p_final_avg, p_final_recent)
+        a, b = project_linear(
+            inputs.p_now, inputs.remaining_hours, r_avg, r_recent
+        )
+        final_low, final_high = min(a, b), max(a, b)
 
     already_capped = inputs.p_now >= 100.0
     projected_cap = already_capped or final_high >= 100.0
@@ -8858,6 +9078,448 @@ def cmd_forecast(args: argparse.Namespace) -> int:
     return 0
 
 
+# ── budget ──────────────────────────────────────────────────────────────
+# `cctally budget` — weekly equivalent-$ budget + pace + spend alerts.
+# cctally-original (NOT a ccusage drop-in) → flat surface only, no
+# claude/codex subgroup. Status reads live spend; `set`/`unset` write the
+# DEFAULT config (F4 — the path the alert firing in Task 3 reads). See
+# docs/commands/budget.md + spec §4/§6.
+
+_BUDGET_JSON_SCHEMA_VERSION = 1
+
+
+def cmd_budget(args: argparse.Namespace) -> int:
+    """Dispatch `cctally budget [set AMOUNT | unset]`. See docs/commands/budget.md."""
+    action = getattr(args, "action", None)
+
+    # F4: mutations always target the DEFAULT config; --config is read-only.
+    # --format is a status-only render surface — reject it on set/unset.
+    if action in {"set", "unset"} and getattr(args, "config", None):
+        eprint(
+            "cctally budget: --config is read-only; "
+            "set/unset always write the default config"
+        )
+        return 2
+    if action in {"set", "unset"} and getattr(args, "format", None):
+        eprint("cctally budget: --format is not valid with set/unset")
+        return 2
+
+    if action == "set":
+        return _cmd_budget_set(args)
+    if action == "unset":
+        return _cmd_budget_unset(args)
+
+    # ── bare status ──
+    # Early reject of bad share-flag combos BEFORE any DB/sync work
+    # (mirrors cmd_forecast; calls sys.exit(2) directly inside).
+    _share_validate_args(args)
+    config = _load_claude_config_for_args(args)  # honors --config read-only
+    args._resolved_tz = resolve_display_tz(args, config)
+    try:
+        budget_cfg = _get_budget_config(config)
+    except _BudgetConfigError as exc:
+        eprint(f"cctally budget: {exc}")
+        return 2
+    target = budget_cfg["weekly_usd"]
+    if target is None:
+        return _budget_render_unset(args)  # exit 0, friendly message
+
+    now_utc = _command_as_of()  # honors the CCTALLY_AS_OF testing hook
+    conn = open_db()
+    inputs = _build_budget_status_inputs(
+        conn,
+        target_usd=target,
+        now_utc=now_utc,
+        alert_thresholds=budget_cfg["alert_thresholds"],
+    )
+    if inputs is None:
+        # No usage snapshot yet → no resolvable week window (spec §6 worst case).
+        if getattr(args, "format", None):
+            snap = _build_budget_no_data_snapshot(args, budget_cfg, now_utc)
+            _share_render_and_emit(snap, args)
+            return 0
+        if getattr(args, "json", False):
+            print(json.dumps({
+                "schemaVersion": _BUDGET_JSON_SCHEMA_VERSION,
+                "status": "no_data",
+                "weekly_usd": target,
+            }))
+            return 0
+        print(f"Weekly budget: ${target:,.2f} — no usage data yet this week.")
+        return 0
+
+    status = compute_budget_status(inputs)
+    if getattr(args, "format", None):
+        snap = _build_budget_snapshot(args, budget_cfg, inputs, status)
+        _share_render_and_emit(snap, args)
+        return 0
+    if getattr(args, "json", False):
+        return _budget_emit_json(budget_cfg, inputs, status)
+    return _budget_render_terminal(args, budget_cfg, inputs, status)
+
+
+def _cmd_budget_set(args: argparse.Namespace) -> int:
+    """`cctally budget set AMOUNT` — write `budget.weekly_usd`, preserving the
+    other budget keys. Writes the DEFAULT config (F4). Task 3 appends the
+    forward-only milestone reconcile here."""
+    raw = getattr(args, "amount", None)
+    if raw is None:
+        eprint("cctally budget: `set` requires an amount, e.g. cctally budget set 300")
+        return 2
+    try:
+        amount = float(raw)
+    except (TypeError, ValueError):
+        eprint(f"cctally budget: amount must be a positive number, got {raw!r}")
+        return 2
+    if not math.isfinite(amount) or amount <= 0:
+        eprint(f"cctally budget: amount must be a positive finite number, got {raw!r}")
+        return 2
+
+    # Read-modify-write under config_writer_lock + _load_config_unlocked
+    # (load_config inside the lock self-deadlocks — fcntl.flock is per-fd).
+    # Re-validate the merged block via _get_budget_config before persisting.
+    with config_writer_lock():
+        config = _load_config_unlocked()
+        existing = config.get("budget")
+        if existing is not None and not isinstance(existing, dict):
+            eprint("cctally budget: budget config must be an object")
+            return 2
+        block = dict(existing or {})
+        block["weekly_usd"] = amount
+        config["budget"] = block
+        try:
+            validated = _get_budget_config(config)
+        except _BudgetConfigError as exc:
+            eprint(f"cctally budget: {exc}")
+            return 2
+        block["weekly_usd"] = validated["weekly_usd"]
+        config["budget"] = block
+        save_config(config)
+
+    weekly_usd = validated["weekly_usd"]
+    alerts_enabled = validated["alerts_enabled"]
+    thresholds = validated["alert_thresholds"]
+
+    # Forward-only-from-set reconcile (Task 3, spec §5): record thresholds
+    # ALREADY crossed with alerted_at set but WITHOUT dispatch, so setting a
+    # budget mid-week doesn't instant-popup; only LATER crossings fire. Runs
+    # OUTSIDE the config_writer_lock (open_db has its own locking; reusing the
+    # config lock here would needlessly serialize a stats.db write behind it).
+    # Shared with `config set budget.*` + dashboard POST /api/settings via
+    # _reconcile_budget_on_config_write (gated on _budget_alerts_active — a
+    # budget with alerts off or no thresholds records nothing).
+    _reconcile_budget_on_config_write(validated)
+    if getattr(args, "json", False):
+        print(json.dumps({
+            "status": "set",
+            "weekly_usd": weekly_usd,
+            "alerts_enabled": alerts_enabled,
+            "alert_thresholds": list(thresholds),
+        }))
+        return 0
+    alerts_part = "alerts on" if alerts_enabled else "alerts off"
+    if thresholds:
+        thr_part = " · thresholds " + " ".join(f"{t}%" for t in thresholds)
+    else:
+        thr_part = " · no thresholds"
+    print(f"Weekly budget set to ${weekly_usd:,.2f} · {alerts_part}{thr_part}")
+    return 0
+
+
+def _cmd_budget_unset(args: argparse.Namespace) -> int:
+    """`cctally budget unset` — clear `budget.weekly_usd` (preserve
+    alerts_enabled / alert_thresholds). Idempotent."""
+    with config_writer_lock():
+        config = _load_config_unlocked()
+        existing = config.get("budget")
+        if existing is not None and not isinstance(existing, dict):
+            eprint("cctally budget: budget config must be an object")
+            return 2
+        block = dict(existing or {})
+        block["weekly_usd"] = None
+        config["budget"] = block
+        save_config(config)
+
+    if getattr(args, "json", False):
+        print(json.dumps({"status": "unset", "weekly_usd": None}))
+        return 0
+    print("Weekly budget cleared")
+    return 0
+
+
+def _budget_render_unset(args: argparse.Namespace) -> int:
+    """No budget set → friendly stdout message, exit 0 (NOT an error)."""
+    if getattr(args, "format", None):
+        snap = _build_budget_no_budget_snapshot(args)
+        _share_render_and_emit(snap, args)
+        return 0
+    if getattr(args, "json", False):
+        print(json.dumps({
+            "schemaVersion": _BUDGET_JSON_SCHEMA_VERSION,
+            "status": "unset",
+            "weekly_usd": None,
+        }))
+        return 0
+    print("No weekly budget set. Set one with: cctally budget set <amount>.")
+    return 0
+
+
+def _budget_verdict_ansi_code(verdict: str) -> str:
+    """ANSI color code for a budget verdict: ok→green, warn→amber, over→red."""
+    return {"ok": "32", "warn": "33", "over": "31"}.get(verdict, "32")
+
+
+def _budget_render_terminal(args, budget_cfg, inputs, status) -> int:
+    """Render the §4 status block to stdout. Datetimes via format_display_dt
+    (honors display.tz). Verdict color ok→green / warn→amber / over→red."""
+    color = _supports_color_stdout()
+    tz_render = getattr(args, "_resolved_tz", None)
+
+    total_seconds = (inputs.week_end_at - inputs.week_start_at).total_seconds()
+    elapsed_days = status.elapsed_fraction * total_seconds / 86400.0
+    remaining_days = max(
+        0.0, total_seconds * (1.0 - status.elapsed_fraction) / 86400.0
+    )
+
+    ws = format_display_dt(inputs.week_start_at, tz_render, fmt="%Y-%m-%d", suffix=False)
+    we = format_display_dt(inputs.week_end_at, tz_render, fmt="%Y-%m-%d", suffix=False)
+
+    lines = []
+    lines.append(
+        f"Weekly budget: ${inputs.target_usd:,.2f}   "
+        f"(subscription week {ws} → {we})"
+    )
+    lines.append("")
+    lines.append(
+        f"  Spent so far    ${status.spent_usd:,.2f}    "
+        f"{status.consumption_pct:.1f}% of budget"
+    )
+    lines.append(f"  Remaining       ${status.remaining_usd:,.2f}")
+    lines.append(
+        f"  Pace            ${status.daily_pace_usd:,.2f}/day  ·  "
+        f"{elapsed_days:.1f} d elapsed"
+    )
+    lines.append(
+        f"  Daily budget    ${status.daily_budget_remaining_usd:,.2f}/day for the "
+        f"{remaining_days:.1f} d left to stay under"
+    )
+    verdict_label = {"ok": "OK", "warn": "WARN", "over": "OVER"}.get(
+        status.verdict, status.verdict.upper()
+    )
+    verdict_glyph = {"ok": "✓", "warn": "⚠", "over": "✗"}.get(status.verdict, "")
+    verdict_text = _style_ansi(
+        f"{verdict_glyph} {verdict_label}".strip(),
+        _budget_verdict_ansi_code(status.verdict),
+        color,
+    )
+    proj_line = (
+        f"  Projected EOW   ${status.projected_eow_low_usd:,.0f}"
+        f"–${status.projected_eow_high_usd:,.0f}   →   {verdict_text}"
+    )
+    if status.low_confidence:
+        proj_line += "   (LOW CONF — early in week)"
+    lines.append(proj_line)
+    lines.append("")
+    lines.append(_budget_alerts_line(budget_cfg, status))
+
+    print("\n".join(lines))
+    return 0
+
+
+def _budget_alerts_line(budget_cfg, status) -> str:
+    """Render the "Alerts: ..." footer line: on/off + thresholds + crossed."""
+    enabled = budget_cfg["alerts_enabled"]
+    thresholds = budget_cfg["alert_thresholds"]
+    if not enabled:
+        return "  Alerts: off"
+    if not thresholds:
+        return "  Alerts: on · no thresholds configured"
+    thr_str = " · ".join(f"{t}%" for t in thresholds)
+    crossed = status.crossed_thresholds
+    if crossed:
+        crossed_str = ", ".join(f"{t}%" for t in crossed)
+        tail = f"({crossed_str} crossed)"
+    else:
+        tail = "(none crossed yet)"
+    return f"  Alerts: on · thresholds {thr_str} · {tail}"
+
+
+def _budget_emit_json(budget_cfg, inputs, status) -> int:
+    """Emit the full BudgetStatus + config echo + window as JSON (schemaVersion 1).
+    Window timestamps are `…Z`, ignoring display.tz (every --json is UTC)."""
+    payload = {
+        "schemaVersion": _BUDGET_JSON_SCHEMA_VERSION,
+        "status": "ok",
+        "weekly_usd": inputs.target_usd,
+        "alerts_enabled": budget_cfg["alerts_enabled"],
+        "alert_thresholds": list(budget_cfg["alert_thresholds"]),
+        "week_start_at": _iso_z(inputs.week_start_at),
+        "week_end_at": _iso_z(inputs.week_end_at),
+        "as_of": _iso_z(inputs.now),
+        "spent_usd": status.spent_usd,
+        "remaining_usd": status.remaining_usd,
+        "consumption_pct": status.consumption_pct,
+        "elapsed_fraction": status.elapsed_fraction,
+        "projected_eow_low_usd": status.projected_eow_low_usd,
+        "projected_eow_high_usd": status.projected_eow_high_usd,
+        "daily_pace_usd": status.daily_pace_usd,
+        "daily_budget_remaining_usd": status.daily_budget_remaining_usd,
+        "verdict": status.verdict,
+        "low_confidence": status.low_confidence,
+        "crossed_thresholds": list(status.crossed_thresholds),
+    }
+    print(json.dumps(payload))
+    return 0
+
+
+def _build_budget_snapshot(args, budget_cfg, inputs, status):
+    """Build a `_lib_share.ShareSnapshot` (cmd="budget") for `--format` output.
+
+    `--reveal-projects` is inert for budget — there are no ProjectCells, so
+    `_scrub` returns the snapshot unchanged. No parallel renderer; the gate
+    calls `_share_render_and_emit(snap, args)`."""
+    _lib_share = _share_load_lib()
+    tz_label = _share_display_tz_label(getattr(args, "_resolved_tz", None))
+    period_label = _share_period_label(
+        inputs.week_start_at, inputs.week_end_at, tz_label
+    )
+    period = _lib_share.PeriodSpec(
+        start=inputs.week_start_at, end=inputs.week_end_at,
+        display_tz=tz_label, label=period_label,
+    )
+    columns = (
+        _lib_share.ColumnSpec(key="metric", label="Metric", align="left"),
+        _lib_share.ColumnSpec(key="value", label="Value", align="right",
+                              emphasis=True),
+    )
+    rows = (
+        _lib_share.Row(cells={"metric": _lib_share.TextCell("Spent so far"),
+                              "value": _lib_share.MoneyCell(status.spent_usd)}),
+        _lib_share.Row(cells={"metric": _lib_share.TextCell("Consumption"),
+                              "value": _lib_share.PercentCell(status.consumption_pct)}),
+        _lib_share.Row(cells={"metric": _lib_share.TextCell("Remaining"),
+                              "value": _lib_share.MoneyCell(status.remaining_usd)}),
+        _lib_share.Row(cells={"metric": _lib_share.TextCell("Daily pace"),
+                              "value": _lib_share.MoneyCell(status.daily_pace_usd)}),
+        _lib_share.Row(cells={"metric": _lib_share.TextCell("Projected EOW (low)"),
+                              "value": _lib_share.MoneyCell(status.projected_eow_low_usd)}),
+        _lib_share.Row(cells={"metric": _lib_share.TextCell("Projected EOW (high)"),
+                              "value": _lib_share.MoneyCell(status.projected_eow_high_usd)}),
+    )
+    notes = ("LOW CONF — early in week",) if status.low_confidence else ()
+    subtitle = " · ".join([
+        period_label,
+        args.theme,
+        "real projects" if args.reveal_projects else "projects anonymized",
+    ])
+    return _lib_share.ShareSnapshot(
+        cmd="budget",
+        title=f"Budget — week of {inputs.week_start_at.strftime('%b %d')}",
+        subtitle=subtitle,
+        period=period,
+        columns=columns,
+        rows=rows,
+        chart=None,
+        totals=(
+            _lib_share.Totalled(label="Verdict", value=status.verdict.upper()),
+            _lib_share.Totalled(label="Budget", value=f"${inputs.target_usd:,.2f}"),
+        ),
+        notes=notes,
+        generated_at=_share_now_utc(),
+        version=_share_resolve_version(),
+    )
+
+
+def _build_budget_no_data_snapshot(args, budget_cfg, now_utc):
+    """Share snapshot for "budget set but no usage data yet this week" — a
+    uniformly-shaped artifact rather than free-form text. Computes the real
+    subscription-week boundaries from config so the period label is meaningful."""
+    _lib_share = _share_load_lib()
+    config = _load_claude_config_for_args(args)
+    tz = getattr(args, "_resolved_tz", None)
+    tz_label = _share_display_tz_label(tz)
+    week_start_name = get_week_start_name(
+        config, getattr(args, "week_start_name", None)
+    )
+    ws_date, we_date = compute_week_bounds(now_utc, week_start_name)
+    # internal fallback: host-local intentional
+    local_tz = dt.datetime.now().astimezone().tzinfo
+    week_start_dt = dt.datetime.combine(ws_date, dt.time.min, tzinfo=local_tz)
+    week_end_dt = dt.datetime.combine(
+        we_date + dt.timedelta(days=1), dt.time.min, tzinfo=local_tz
+    )
+    period_label = _share_period_label(week_start_dt, week_end_dt, tz_label)
+    target = budget_cfg["weekly_usd"]
+    subtitle = " · ".join([
+        period_label, args.theme,
+        "real projects" if args.reveal_projects else "projects anonymized",
+    ])
+    return _lib_share.ShareSnapshot(
+        cmd="budget",
+        title=f"Budget — week of {week_start_dt.strftime('%b %d')}",
+        subtitle=subtitle,
+        period=_lib_share.PeriodSpec(
+            start=week_start_dt, end=week_end_dt,
+            display_tz=tz_label, label=period_label,
+        ),
+        columns=(
+            _lib_share.ColumnSpec(key="metric", label="Metric", align="left"),
+            _lib_share.ColumnSpec(key="value", label="Value", align="right",
+                                  emphasis=True),
+        ),
+        rows=(
+            _lib_share.Row(cells={
+                "metric": _lib_share.TextCell("Weekly budget"),
+                "value": _lib_share.MoneyCell(float(target)),
+            }),
+        ),
+        chart=None,
+        totals=(),
+        notes=("No usage data recorded for this week yet — run "
+               "cctally record-usage to populate.",),
+        generated_at=_share_now_utc(),
+        version=_share_resolve_version(),
+    )
+
+
+def _build_budget_no_budget_snapshot(args):
+    """Share snapshot for the "no budget set" status — a uniform artifact."""
+    _lib_share = _share_load_lib()
+    now_utc = _command_as_of()
+    tz = getattr(args, "_resolved_tz", None)
+    if tz is None:
+        # Purely defensive: the sole caller (_budget_render_unset) already
+        # resolves args._resolved_tz before dispatch, so this rarely fires —
+        # resolve here anyway so the artifact always carries a tz label.
+        config = _load_claude_config_for_args(args)
+        tz = resolve_display_tz(args, config)
+    tz_label = _share_display_tz_label(tz)
+    period_label = _share_period_label(now_utc, now_utc, tz_label)
+    subtitle = " · ".join([
+        period_label, args.theme,
+        "real projects" if args.reveal_projects else "projects anonymized",
+    ])
+    return _lib_share.ShareSnapshot(
+        cmd="budget",
+        title="Budget — no budget set",
+        subtitle=subtitle,
+        period=_lib_share.PeriodSpec(
+            start=now_utc, end=now_utc, display_tz=tz_label, label=period_label,
+        ),
+        columns=(
+            _lib_share.ColumnSpec(key="metric", label="Metric", align="left"),
+            _lib_share.ColumnSpec(key="value", label="Value", align="right",
+                                  emphasis=True),
+        ),
+        rows=(),
+        chart=None,
+        totals=(),
+        notes=("No weekly budget set. Set one with: cctally budget set <amount>.",),
+        generated_at=_share_now_utc(),
+        version=_share_resolve_version(),
+    )
+
+
 def cmd_percent_breakdown(args: argparse.Namespace) -> int:
     config = load_config()
     tz = resolve_display_tz(args, config)
@@ -10381,6 +11043,355 @@ _LEGACY_BACKUP_DIR_PREFIX = "cctally-legacy-hook-backup-"
 _LEGACY_POLLER_SIGTERM_GRACE_S = 0.250
 
 
+# Private sentinel so `_pricing_observed_models` can tell "default 30-day
+# window" apart from an explicit `since=None` all-history scan.
+_PRICING_SCAN_DEFAULT_WINDOW = object()
+
+
+def _pricing_observed_models(now_utc, *, since=_PRICING_SCAN_DEFAULT_WINDOW):
+    """Read-only scan of the session-entry cache for observed models.
+
+    Returns a list of ``(provider, model, entry_count, token_total)`` tuples,
+    one per DISTINCT model seen in ``cache.db`` (Claude ``session_entries`` +
+    Codex ``codex_session_entries``). By default it scans the trailing 30-day
+    window relative to ``now_utc`` (the `doctor` coverage signal — recent =
+    actionable). Pass ``since=<datetime>`` to widen/narrow the window, or
+    ``since=None`` explicitly for an all-history scan (used by `pricing-check`).
+
+    Read-only / no-mutation contract (spec §5.1): mirrors the freshness read
+    in this same function — guard on ``CACHE_DB_PATH.exists()``, raw
+    ``sqlite3.connect`` (NEVER ``open_cache_db()`` / ``sync_cache()`` /
+    ``load_config()`` / ``ensure_dirs()``), and treat a missing table/column as
+    "no observed models" rather than crashing. ``doctor --json`` on a virgin
+    HOME must not create ``APP_DIR`` — regression
+    ``test_pricing_observed_models_no_mutation_on_fresh_home``.
+    """
+    out: list = []
+    if not _cctally_core.CACHE_DB_PATH.exists():
+        return out
+    # Sentinel: the 30-day window is the default; `since=False` is not a
+    # supported value, so distinguish "caller wants all-history" (None) from
+    # "caller did not pass since" via a private marker.
+    if since is _PRICING_SCAN_DEFAULT_WINDOW:
+        cutoff_iso = (now_utc - dt.timedelta(days=30)).isoformat()
+    elif since is None:
+        cutoff_iso = None  # all-history
+    else:
+        cutoff_iso = since.isoformat()
+    try:
+        conn = sqlite3.connect(str(_cctally_core.CACHE_DB_PATH))
+    except sqlite3.Error:
+        return out
+    try:
+        # Token-sum expressions use the ACTUAL cache column names from
+        # bin/_cctally_db.py::_apply_cache_schema (verified — Claude uses
+        # cache_create_tokens, NOT cache_creation_tokens; Codex carries a
+        # materialized total_tokens covering input/cache/output/reasoning).
+        for provider, table, tok_expr in (
+            ("claude", "session_entries",
+             "COALESCE(input_tokens,0)+COALESCE(output_tokens,0)+"
+             "COALESCE(cache_create_tokens,0)+COALESCE(cache_read_tokens,0)"),
+            ("codex", "codex_session_entries",
+             "COALESCE(total_tokens,0)"),
+        ):
+            where = "model IS NOT NULL"
+            params: tuple = ()
+            if cutoff_iso is not None:
+                where = "timestamp_utc >= ? AND " + where
+                params = (cutoff_iso,)
+            try:
+                rows = conn.execute(
+                    f"SELECT model, COUNT(*), SUM({tok_expr}) FROM {table} "
+                    f"WHERE {where} GROUP BY model",
+                    params,
+                ).fetchall()
+            except sqlite3.OperationalError:
+                rows = []  # table/column missing — treat as none
+            for model, cnt, toks in rows:
+                out.append((provider, model, int(cnt or 0), int(toks or 0)))
+    finally:
+        conn.close()
+    return out
+
+
+# ── pricing-check network legs (spec §5.2) ──────────────────────────────
+#
+# Hidden dev hooks (like `project`'s CCTALLY_AS_OF): read at call time, NOT
+# import time, so a test/harness can set them in the child process env. They
+# are deliberately absent from `--help` — they only exist to make the
+# network legs deterministic in tests (invariant #4: no test hits the
+# network). When set to a path, the corresponding fetcher reads that local
+# JSON instead of issuing an HTTP request.
+_ENV_PRICING_LITELLM_FILE = "CCTALLY_PRICING_LITELLM_FILE"
+_ENV_PRICING_MODELS_FILE = "CCTALLY_PRICING_MODELS_FILE"
+
+
+def _fetch_litellm_prices() -> "tuple[dict, bool]":
+    """Fetch the LiteLLM model_prices map. Returns ``(data, ok)``.
+
+    NEVER raises to the caller: on any failure (bad inject file, network
+    error, non-JSON, non-dict body) returns ``({}, False)`` so the drift
+    leg degrades gracefully (spec invariant #1). Honors the hidden
+    ``CCTALLY_PRICING_LITELLM_FILE`` env hook for deterministic tests.
+    """
+    inject = os.environ.get(_ENV_PRICING_LITELLM_FILE, "").strip()
+    if inject:
+        try:
+            data = json.loads(pathlib.Path(inject).read_text())
+            return (data, True) if isinstance(data, dict) else ({}, False)
+        except Exception:
+            return {}, False
+    try:
+        # UA can be plain here — LiteLLM is a raw GitHub JSON blob, not the
+        # Anthropic rate-limited surface that requires `claude-code/*`.
+        req = urllib.request.Request(
+            LITELLM_PRICES_URL, headers={"User-Agent": "cctally"},
+        )
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+        return (data, True) if isinstance(data, dict) else ({}, False)
+    except Exception as exc:
+        eprint(f"[pricing-check] LiteLLM fetch failed: {exc}")
+        return {}, False
+
+
+def _fetch_anthropic_models_or_none() -> "dict | None":
+    """GET https://api.anthropic.com/v1/models with the Claude OAuth bearer.
+
+    Returns the parsed JSON object on success, or ``None`` on ANY failure
+    (no token, 401/403, network error, non-JSON, non-dict body) so the
+    existence leg degrades to ``status: degraded``. NEVER raises to the
+    caller — wrapped in a broad try/except.
+
+    C0 DE-RISK SPIKE STATUS — UNVERIFIED LIVE REACHABILITY: this code path
+    was authored WITHOUT a live `/v1/models` call (the sandbox has no real
+    OAuth token). It is UNKNOWN whether the Claude Code OAuth bearer
+    authorizes `GET /v1/models`; if the endpoint 401/403s, this function
+    returns None and the existence leg reports `status: degraded` (the
+    feature still stands on LiteLLM drift + the local coverage guard). The
+    maintainer must run `cctally pricing-check` on a machine with a real
+    OAuth token to confirm the leg actually reaches `status: ok`. The whole
+    leg is fully exercisable offline via `CCTALLY_PRICING_MODELS_FILE`.
+    """
+    try:
+        token = _resolve_oauth_token()
+        if not token:
+            return None
+        # Mirror the OAuth-usage UA discipline: Anthropic rate-limits
+        # per-UA, so use `claude-code/<version>` (NOT Python-urllib).
+        # RAW config read (NOT load_config / _load_config_unlocked — both
+        # call ensure_dirs() and would mutate a fresh HOME, violating the
+        # read-only contract). Honors an `oauth_usage.user_agent` override
+        # when config.json exists; otherwise the default `claude-code/<v>`.
+        raw_cfg = {}
+        try:
+            if _cctally_core.CONFIG_PATH.exists():
+                parsed = json.loads(
+                    _cctally_core.CONFIG_PATH.read_text(encoding="utf-8"))
+                if isinstance(parsed, dict):
+                    raw_cfg = parsed
+        except (json.JSONDecodeError, OSError):
+            raw_cfg = {}
+        cfg = _get_oauth_usage_config(raw_cfg)
+        user_agent = _resolve_oauth_usage_user_agent(cfg)
+        req = urllib.request.Request(
+            "https://api.anthropic.com/v1/models",
+            headers={
+                "Authorization": f"Bearer {token}",
+                "anthropic-beta": "oauth-2025-04-20",
+                "anthropic-version": "2023-06-01",
+                "User-Agent": user_agent,
+            },
+        )
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+        return data if isinstance(data, dict) else None
+    except Exception as exc:
+        eprint(f"[pricing-check] /v1/models fetch failed: {exc}")
+        return None
+
+
+def _pricing_existence_check() -> dict:
+    """Anthropic-only vendor `/v1/models` coverage gap.
+
+    Returns ``{"status": "ok"|"degraded"|"skipped", "unpriced_vendor_models":
+    [...]}``. ``ok`` = the vendor list was obtained; the gap is the IDs the
+    vendor offers that ``_resolve_model_pricing`` cannot price. ``degraded``
+    = the fetch failed (no token / 401 / network / non-JSON). Honors the
+    hidden ``CCTALLY_PRICING_MODELS_FILE`` env hook.
+
+    Codex existence is intentionally out of scope (no OpenAI credentials —
+    spec §4 non-goals); the payload's existence block is Anthropic-only.
+    """
+    inject = os.environ.get(_ENV_PRICING_MODELS_FILE, "").strip()
+    if inject:
+        try:
+            raw = json.loads(pathlib.Path(inject).read_text())
+        except Exception:
+            return {"status": "degraded", "unpriced_vendor_models": []}
+    else:
+        raw = _fetch_anthropic_models_or_none()
+        if raw is None:
+            return {"status": "degraded", "unpriced_vendor_models": []}
+    if not isinstance(raw, dict):
+        return {"status": "degraded", "unpriced_vendor_models": []}
+    ids = [m.get("id") for m in raw.get("data", []) if isinstance(m, dict) and m.get("id")]
+    # Detection-only: warn=False so a vendor model we don't price doesn't
+    # fire the cost-engine's one-shot stderr warning.
+    gap = sorted(i for i in ids if _resolve_model_pricing(i, warn=False) is None)
+    return {"status": "ok", "unpriced_vendor_models": gap}
+
+
+def cmd_pricing_check(args: argparse.Namespace) -> int:
+    """`cctally pricing-check` — detect stale/missing embedded pricing.
+
+    Three independently-degrading legs (spec §5.2):
+      1. coverage (offline, ALL-HISTORY) — models in cache.db we can't price.
+      2. drift (network, LiteLLM) — embedded value vs LiteLLM (direction-aware
+         + allowlist-suppressed).
+      3. existence (network, Anthropic `/v1/models`) — vendor models absent
+         from our table.
+
+    Exit-code precedence (spec invariant #1, §5.2):
+      1 — ANY actionable finding (coverage gap OR value_drift OR
+          missing_from_us OR an existence gap), EVEN IF a network leg
+          degraded. Findings always win over degradation.
+      0 — NO actionable findings (fully clean OR partially/fully degraded
+          but nothing actionable). JSON still carries status=degraded.
+      2 — argument/usage error (argparse handles before we run).
+
+    ``status`` (ok|degraded) reports check COMPLETENESS; the exit code
+    reports whether the operator must ACT. They are orthogonal: a degraded
+    leg never masks a finding and never fabricates one.
+    """
+    now_utc = _command_as_of()
+    status = "ok"
+    degraded: list[str] = []
+
+    # 1. Coverage — offline, all-history (since=None). Read-only scan; any
+    #    failure degrades to [] (the scan itself swallows DB errors).
+    try:
+        observed = _pricing_observed_models(now_utc, since=None)
+        coverage = classify_coverage(
+            observed,
+            lambda m: _resolve_model_pricing(m, warn=False),
+            _is_codex_fallback,
+        )
+    except Exception:
+        coverage = []
+
+    drift = {"value_drift": [], "missing_from_us": [], "ahead_of_litellm": []}
+    existence = {"status": "skipped", "unpriced_vendor_models": []}
+
+    if not args.offline:
+        litellm, ok = _fetch_litellm_prices()
+        if ok:
+            scoped = scope_litellm(litellm)
+            res = diff_pricing(
+                CLAUDE_MODEL_PRICING, CODEX_MODEL_PRICING,
+                scoped, PRICING_DRIFT_ALLOWLIST,
+            )
+            drift = {
+                "value_drift": [dataclasses.asdict(r) for r in res.value_drift],
+                "missing_from_us": list(res.missing_from_us),
+                "ahead_of_litellm": list(res.ahead_of_litellm),
+            }
+        else:
+            status = "degraded"
+            degraded.append("litellm")
+        existence = _pricing_existence_check()
+        if existence["status"] == "degraded":
+            status = "degraded"
+            degraded.append("models_api")
+
+    # Actionable = any finding on a leg that ran. `ahead_of_litellm` is
+    # NEVER actionable (invariant #2). A degraded leg contributes no finding.
+    actionable = (
+        bool(coverage)
+        or bool(drift["value_drift"])
+        or bool(drift["missing_from_us"])
+        or bool(existence["unpriced_vendor_models"])
+    )
+
+    payload = {
+        "schemaVersion": 1,
+        "status": status,
+        "degraded_components": degraded,
+        "snapshotDate": PRICING_SNAPSHOT_DATE,
+        "coverage": [dataclasses.asdict(g) for g in coverage],
+        "drift": drift,
+        "existence": existence,
+        "litellmSource": LITELLM_PRICES_URL,
+    }
+
+    if getattr(args, "json", False):
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        _render_pricing_check_text(payload, offline=args.offline, actionable=actionable)
+
+    return 1 if actionable else 0
+
+
+def _render_pricing_check_text(payload: dict, *, offline: bool, actionable: bool) -> None:
+    """Human-readable render of the pricing-check payload. JSON is the
+    machine contract; this is a readable summary for interactive use."""
+    out = sys.stdout.write
+    status = payload["status"]
+    out(f"pricing-check  (snapshot {payload['snapshotDate']})\n")
+    if status == "degraded":
+        out(f"  status: degraded — incomplete check "
+            f"({', '.join(payload['degraded_components'])} unavailable)\n")
+    else:
+        out("  status: ok\n")
+
+    cov = payload["coverage"]
+    if cov:
+        out(f"\n  Coverage gaps ({len(cov)} model(s) we cannot price exactly):\n")
+        for g in cov:
+            kind = ("unpriced ($0)" if g["kind"] == "unpriced"
+                    else "approximated via gpt-5")
+            entries = g["entry_count"]
+            noun = "entry" if entries == 1 else "entries"
+            out(f"    • {g['model']} ({g['provider']}): {entries} "
+                f"{noun} / {g['token_total']} tokens — {kind}\n")
+    else:
+        out("\n  Coverage: all observed models priced.\n")
+
+    if offline:
+        out("\n  (offline — network drift + existence legs skipped)\n")
+    else:
+        vd = payload["drift"]["value_drift"]
+        mu = payload["drift"]["missing_from_us"]
+        if vd:
+            out(f"\n  Value drift vs LiteLLM ({len(vd)} field(s)):\n")
+            for d in vd:
+                out(f"    • {d['model']}.{d['field']}: ours={d['ours']} "
+                    f"litellm={d['theirs']}\n")
+        if mu:
+            out(f"\n  Models LiteLLM prices but we don't ({len(mu)}):\n")
+            for m in mu:
+                out(f"    • {m}\n")
+        if not vd and not mu and "litellm" not in payload["degraded_components"]:
+            out("\n  Drift: embedded pricing matches LiteLLM.\n")
+        ex = payload["existence"]
+        if ex["status"] == "ok":
+            gap = ex["unpriced_vendor_models"]
+            if gap:
+                out(f"\n  Vendor models not in our table ({len(gap)}):\n")
+                for m in gap:
+                    out(f"    • {m}\n")
+            else:
+                out("\n  Existence: all vendor models priced.\n")
+        elif ex["status"] == "degraded":
+            out("\n  Existence: /v1/models unavailable (skipped).\n")
+
+    # Single-sourced from cmd_pricing_check's exit-code predicate (don't
+    # recompute the four-clause boolean here — it would drift).
+    if actionable:
+        out("\n  Action: review CLAUDE_MODEL_PRICING / CODEX_MODEL_PRICING; "
+            "bump PRICING_SNAPSHOT_DATE on sync.\n")
+
+
 def doctor_gather_state(
     *,
     now_utc: "dt.datetime | None" = None,
@@ -10714,6 +11725,26 @@ def doctor_gather_state(
         _compute_effective_update_available(update_state, update_suppress, now_utc)
     )
 
+    # ── Pricing coverage (spec §5.1) ─────────────────────────────────
+    # Read-only trailing-30d scan + classification via the pure-fn kernel.
+    # Any failure degrades to None so the check renders OK (never FAIL) and
+    # the rest of the report is unaffected — same posture as the cache reads
+    # above. `_pricing_observed_models` honors the no-mutation contract.
+    pricing_coverage = None
+    try:
+        observed = _pricing_observed_models(now_utc)
+        # Detection-only: pass warn=False so finding an unpriced model here does
+        # NOT fire the cost-engine's `[cost] unknown model` stderr warning (this
+        # is a read-only diagnostic, and the warning would also poison the
+        # dedup set, suppressing a later genuine cost-path warning).
+        pricing_coverage = classify_coverage(
+            observed,
+            lambda m: _resolve_model_pricing(m, warn=False),
+            _is_codex_fallback,
+        )
+    except Exception:
+        pricing_coverage = None
+
     # ── Meta ─────────────────────────────────────────────────────────
     cctally_version_tuple = _lib_changelog._read_latest_changelog_version()
     cctally_version = (
@@ -10759,6 +11790,8 @@ def doctor_gather_state(
         dev_mode=_cctally_core.DEV_MODE,
         app_dir=str(_cctally_core.APP_DIR),
         is_dev_checkout=_cctally_core._is_dev_checkout(),
+        # Pricing-freshness check (spec §5.1): trailing-30d coverage gaps.
+        pricing_coverage=pricing_coverage,
     )
 
 
@@ -11980,6 +13013,51 @@ def build_parser() -> argparse.ArgumentParser:
     _add_share_args(fc, has_status_line=True)
     fc.set_defaults(func=cmd_forecast)
 
+    # budget — cctally-original (NOT a ccusage drop-in), so flat surface only;
+    # no claude/codex subgroup. `--config` is honored read-only on bare status
+    # but rejected on set/unset (F4). `--reveal-projects` is accepted for share
+    # surface parity but inert (no per-project axis). `--tz` follows the sibling
+    # reporting commands' precedence.
+    bg = sub.add_parser(
+        "budget",
+        help="Weekly equivalent-$ budget + pace + spend alerts",
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Track Claude equivalent-$ spend for the current subscription week
+            against a weekly budget. Shows spend, pace, projected end-of-week,
+            and a verdict (ok / warn / over). `budget set <amount>` and
+            `budget unset` manage the budget; spend-crossing alerts fire from
+            record-usage (see `cctally alerts`).
+            """
+        ),
+        epilog=textwrap.dedent(
+            """\
+            Examples:
+              cctally budget
+              cctally budget set 300
+              cctally budget unset
+              cctally budget --json
+              cctally budget --format md
+            """
+        ),
+    )
+    bg.add_argument("action", nargs="?", choices=["set", "unset"], default=None,
+                    help="`set <amount>` to set the weekly budget, `unset` to clear it.")
+    bg.add_argument("amount", nargs="?", default=None,
+                    help="Target USD for `budget set` (e.g. 300).")
+    bg.add_argument("--config", default=None,
+                    help="Read status from this config file (read-only; "
+                         "rejected on set/unset).")
+    bg.add_argument("--reveal-projects", action="store_true", dest="reveal_projects",
+                    help="Accepted for --format surface parity; inert for budget "
+                         "(no per-project axis).")
+    bg.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
+                    help="Display timezone: local, utc, or IANA name. "
+                         "Overrides config display.tz for this call.")
+    _add_share_args(bg)
+    bg.set_defaults(func=cmd_budget)
+
     pb = sub.add_parser(
         "percent-breakdown",
         help="Show per-percent cost milestones for a week",
@@ -12871,14 +13949,15 @@ def build_parser() -> argparse.ArgumentParser:
             Examples:
               cctally alerts test
               cctally alerts test --axis five-hour --threshold 95
+              cctally alerts test --axis budget --threshold 100
         """),
     )
     p_alerts_test.add_argument(
         "--axis",
-        choices=["weekly", "five-hour"],
+        choices=["weekly", "five-hour", "budget"],
         default="weekly",
-        help="Alert axis to simulate: weekly subscription window or 5h block "
-             "(default: weekly).",
+        help="Alert axis to simulate: weekly subscription window, 5h block, "
+             "or equiv-$ budget (default: weekly).",
     )
     p_alerts_test.add_argument(
         "--threshold",
@@ -13041,6 +14120,51 @@ def build_parser() -> argparse.ArgumentParser:
     )
     doctor_p.set_defaults(func=cmd_doctor)
 
+    # ---- pricing-check (standalone diagnostic — NOT under claude/codex) ----
+    pc_p = sub.add_parser(
+        "pricing-check",
+        help="Detect stale or missing embedded model pricing",
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Check whether cctally's embedded model pricing is stale or
+            missing, across three independently-degrading legs:
+
+              • coverage  (offline, all-history) — models in your cached
+                session data that cctally cannot price (Claude $0) or only
+                approximates (Codex gpt-5 fallback).
+              • drift     (network, LiteLLM) — embedded price values vs the
+                LiteLLM snapshot (direction-aware; allowlist-suppressed).
+              • existence (network, Anthropic /v1/models) — vendor models the
+                API offers that our table lacks. Maintainer-local (needs
+                OAuth); degrades to skipped/degraded otherwise.
+
+            Exit codes:
+              0 — no actionable findings (fully clean, OR partially/fully
+                  network-degraded but nothing actionable; --json still
+                  carries "status":"degraded").
+              1 — any actionable finding (a coverage gap, value drift,
+                  missing-from-us, or an existence gap) — EVEN IF a network
+                  leg degraded. Findings always win over degradation.
+              2 — argument/usage error.
+
+            "status" (ok|degraded) reports check completeness; the exit code
+            reports whether you must act. They are orthogonal.
+
+            See docs/commands/pricing-check.md for the JSON schema.
+            """
+        ),
+    )
+    pc_p.add_argument(
+        "--json", action="store_true",
+        help="Emit machine-readable JSON to stdout (schemaVersion: 1)",
+    )
+    pc_p.add_argument(
+        "--offline", action="store_true",
+        help="Coverage only — skip both network legs (LiteLLM + /v1/models)",
+    )
+    pc_p.set_defaults(func=cmd_pricing_check)
+
     # `release` is its own standalone entry-point (bin/cctally-release);
     # no `release` subparser is registered on the main `cctally` CLI.
     # See docs/RELEASE.md.
@@ -15095,6 +16219,13 @@ def _post_command_update_hooks(command: str | None, args) -> None:
         return
     if command == "doctor":
         return
+    if command == "pricing-check":
+        # Read-only diagnostic (same rationale as doctor): load_config() would
+        # call ensure_dirs() and write a stub config.json on a fresh HOME, and
+        # _spawn_background_update_check would write update-state.json/log. The
+        # no-mutation contract (test_pricing_check_offline_does_not_mutate_
+        # fresh_home) requires skipping the whole hook.
+        return
     if command == "repair-symlinks":
         return
     # Self-heal: reconcile current_version with the running binary's