cctally 1.21.3 → 1.22.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.22.0] - 2026-05-29
+
+### Added
+- **`cctally budget` — a weekly equivalent-$ budget with a live pace projection.** Set a per-subscription-week target in dollars (`cctally budget set 300`, clear with `cctally budget unset`) and `cctally budget` shows spend-so-far, percent-of-budget consumed, remaining dollars, current daily pace, and a low/high end-of-week projection band (week-average pace vs. trailing-24h pace), with an `ok`/`warn`/`over` verdict and a `LOW CONF` note early in the week. Spend is computed live from your session data via the same path `weekly`/`forecast` use (so embedded-pricing edits take effect immediately), scoped to Claude only (the subscription week is an Anthropic concept). Supports `--json` (`schemaVersion: 1`) and the full shareable-output surface (`--format md|html|svg`, `--theme`, `--no-branding`, `--output`, `--copy`, `--open`; `--reveal-projects` is a no-op since budget has no per-project rows). `--config PATH` is read-only — `set`/`unset` always write the default config. See `docs/commands/budget.md`.
+- **Actual-spend budget alerts.** When live spend crosses a configured budget threshold (default 90% and 100% of the weekly target), cctally fires a desktop notification — recorded fire-once per `(week, threshold)` in a new `budget_milestones` table and dispatched set-then-dispatch like the existing weekly/5h percent alerts. Alerts are forward-only from the moment you set a budget (a back-set target reconciles existing crossings as already-alerted so it never floods you with retroactive popups), and a mid-week quota reset re-anchors the budget window so the new week's crossings fire fresh. `cctally alerts test --axis budget` previews the notification without writing to the DB.
+- **`budget` config block** (`budget.weekly_usd` / `budget.alerts_enabled` / `budget.alert_thresholds`) — its own validated config block (distinct from the `alerts` block), settable via `cctally config set budget.weekly_usd 300` / `config set budget.alert_thresholds 90,100` / `config set budget.alerts_enabled false` and readable via `config get`, with thresholds constrained to `[1, 100]` and a positive-finite weekly target (or `null` to clear). Alerts are "on when a budget is set" by default.
+- **Dashboard Recent-alerts gains a third `budget` axis.** Budget threshold crossings now surface in the existing Recent-alerts panel, modal, and toast alongside the weekly and 5h-block axes — a distinct `BUDGET` chip (green accent), an "$X of $Y budget" body line, a "Week of …" + "% of budget" context cell, and the actual-spend figure in the Cost column; the dashboard `alerts_settings` mirror now carries `budget_thresholds` + `budget_enabled` (sourced from the `budget` config block, not `alerts`), the Settings overlay shows the active budget thresholds, and `POST /api/settings` validates and persists an inbound `budget` block.
+- **`cctally pricing-check` — proactive detection of stale or missing embedded model pricing.** cctally prices every session locally from the embedded `CLAUDE_MODEL_PRICING` / `CODEX_MODEL_PRICING` tables, so an unrecognized Claude model silently contributes $0 (a silent undercount) and an unrecognized Codex model is only approximated via the `gpt-5` fallback; this command surfaces those gaps before anyone has to reconcile by hand. It runs three independently-degrading legs: **coverage** (offline, all-history — models in your cached session data cctally can't price exactly), **drift** (network, LiteLLM — embedded price values vs the LiteLLM snapshot, direction-aware so a model we price but LiteLLM lacks is never flagged, and suppressible via a non-vacuity-guarded `PRICING_DRIFT_ALLOWLIST`), and **existence** (network, Anthropic `/v1/models` — vendor models the API offers that our table lacks; Anthropic-only and maintainer-local since it needs an OAuth bearer). `--json` emits a `schemaVersion: 1` payload; `--offline` runs coverage only. Exit codes follow a strict precedence — any actionable finding exits 1 even when a network leg degraded (findings always win over degradation), a clean-or-degraded-but-no-findings run exits 0, and the orthogonal `"status"` field reports whether the check was complete. See `docs/commands/pricing-check.md`.
+- **`cctally doctor` now has a `pricing.coverage` check** that WARNs when your recent (trailing 30-day) session data contains a model cctally cannot price exactly — a Claude model resolving to $0 (`unpriced`) or a Codex model approximated via the `gpt-5` fallback (`fallback`) — listing each offending model ID with its entry count and token volume, with a remediation hint pointing at `cctally pricing-check` and the embedded pricing tables. It is OK when every observed model is priced (or when the cache is absent), the scan is strictly read-only (it never creates the data dir on a fresh HOME), and it rolls into the dashboard health chip/modal and the TUI for free as an ordinary doctor check. This is the offline, zero-network counterpart to `pricing-check`'s coverage leg.
+- **`PRICING_SNAPSHOT_DATE` constant** (alongside `PRICING_STALENESS_DAYS`, default 60) replaces the bare `# Captured:` provenance comments beside the pricing tables, so the staleness heuristic and the release pre-flight read structured data; bump it whenever the embedded pricing tables are synced against the vendor.
+
+### Changed
+- **A weekly `pricing-freshness` GitHub Action** now runs `cctally pricing-check --json` on a schedule and maintains exactly one auto-managed `pricing-drift`-labeled tracking issue — it opens or updates the issue (with a value-drift table, a missing-from-us list, and a remediation checklist) when the embedded pricing diverges from LiteLLM, and auto-closes it with a "resolved as of" note when the drift clears. The workflow runs only in the source repo (never on the public mirror), uses least-privilege permissions, pins Python 3.13, and captures the check's exit code so a drift run (exit 1) proceeds to issue management instead of failing the job; the create/update/close/noop decision is a pure unit-tested function. The maintainer's release pre-flight additionally surfaces a soft, overridable advisory at cut time if there is drift, a coverage gap, or a stale pricing snapshot. The zero-lag `/v1/models` existence signal is maintainer-local only (the cron has no OAuth and auto-degrades to LiteLLM drift), so the local coverage guard remains the day-0 backstop for new-model existence.
+
+### Documentation
+- Clarified why `cctally codex <cmd>` (`daily`/`monthly`/`weekly`/`session`) reports lower token totals and cost than upstream `ccusage-codex` on older sessions — and that **cctally, not `ccusage-codex`, is the accurate one.** Older Codex CLI versions re-emit duplicate `event_msg.token_count` records (identical `last_token_usage` while the cumulative `info.total_token_usage.total_tokens` ledger stays flat); `ccusage-codex` sums every emission (up to ~2× overcount on the oldest sessions) while cctally dedups by only counting events whose cumulative advances, exactly reconstructing the Codex CLI's own authoritative total. Recent sessions don't re-emit and match upstream byte-for-byte, so a per-month comparison trends from ~0.5× on old months toward ~1.0× on recent ones. The canonical divergence note in `docs/commands/codex-daily.md` now states which tool is correct and how to verify it per session, with a discoverability pointer added to the `codex` subgroup overview (`docs/commands/codex.md`). This reconciliation is now locked by a new `bin/cctally-reconcile-test` invariant `codex_dedup_eq_codex_ground_truth`: it asserts `codex-daily`'s reported `totalTokens` equals the sum of each fixture session's final `total_token_usage.total_tokens` (an independent raw-JSONL scan that shares no aggregation code with the CLI) and carries a non-vacuity guard requiring the naive all-events sum to strictly exceed the deduped ground truth, so a regression that silently disabled the dedup guard would fail the suite.
+
 ## [1.21.3] - 2026-05-29
 
 ### Fixed

package/bin/_cctally_alerts.py

@@ -68,9 +68,11 @@ def _load_lib(name: str):
 _lib_alerts_payload = _load_lib("_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
 
 
 # === Honest imports from extracted homes ===================================
@@ -134,6 +136,8 @@ def _dispatch_alert_notification(
         title, subtitle, body = _alert_text_weekly(payload, tz)
     elif axis == "five_hour":
         title, subtitle, body = _alert_text_five_hour(payload, tz)
+    elif axis == "budget":
+        title, subtitle, body = _alert_text_budget(payload, tz)
     else:
         title, subtitle, body = (
             "cctally - alert",
@@ -168,6 +172,7 @@ def _dispatch_alert_notification(
         window_key = (
             ctx.get("week_start_date")
             or ctx.get("five_hour_window_key")
+            or ctx.get("week_start_at")
             or ""
         )
         line = (
@@ -198,8 +203,16 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
       2  --threshold out of [1, 100] range
       3  other spawn error (PermissionError, OSError, ...)
     """
-    axis = "weekly" if args.axis == "weekly" else "five_hour"
+    if args.axis == "weekly":
+        axis = "weekly"
+    elif args.axis == "budget":
+        axis = "budget"
+    else:
+        axis = "five_hour"
     threshold = int(args.threshold)
+    # --threshold range stays [1, 100] (F5): the cap is axis-uniform with the
+    # existing weekly/5h thresholds. Over-budget tiers (>100%) are a v2
+    # deferral, not an oversight — see spec §2 (F5).
     if not (1 <= threshold <= 100):
         print(
             f"cctally: --threshold must be in [1, 100], got {threshold}",
@@ -214,6 +227,18 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
             cumulative_cost_usd=1.23,
             dollars_per_percent=0.01,
         )
+    elif axis == "budget":
+        # Synthetic budget payload — NO DB writes (test/real divergence
+        # contract). spent scaled to the threshold so the body line reads
+        # plausibly (e.g. 100% → $300 of $300).
+        payload = _build_alert_payload_budget(
+            threshold=threshold,
+            crossed_at_utc=now_utc_iso(),
+            week_start_at=dt.date.today().isoformat(),
+            budget_usd=300.0,
+            spent_usd=300.0 * threshold / 100.0,
+            consumption_pct=float(threshold),
+        )
     else:
         payload = _build_alert_payload_five_hour(
             threshold=threshold,

package/bin/_cctally_config.py

@@ -73,6 +73,8 @@ from _cctally_core import (
     DEFAULT_WEEK_START,
     _get_alerts_config,
     _AlertsConfigError,
+    _get_budget_config,
+    _BudgetConfigError,
 )
 from _lib_display_tz import normalize_display_tz_value
 
@@ -301,6 +303,9 @@ ALLOWED_CONFIG_KEYS = (
     "statusline.visual_burn_rate",
     "statusline.cost_source",
     "statusline.cctally_extensions",
+    "budget.weekly_usd",
+    "budget.alerts_enabled",
+    "budget.alert_thresholds",
 )
 
 
@@ -463,6 +468,25 @@ def _config_known_value(config: dict, key: str) -> "object":
         except ValueError:
             # Hand-edited junk: surface the default — mirrors dashboard.bind.
             return defaults[inner]
+    if key in (
+        "budget.weekly_usd",
+        "budget.alerts_enabled",
+        "budget.alert_thresholds",
+    ):
+        inner = key.split(".", 1)[1]
+        # Read the validated, defaults-filled block. A corrupt block falls
+        # back to the canonical default leaf (mirrors alerts.enabled /
+        # dashboard.bind, which surface the default on a hand-edited junk
+        # block rather than erroring out of a plain `config get`).
+        try:
+            return _get_budget_config(config)[inner]
+        except _BudgetConfigError:
+            from _cctally_core import _BUDGET_DEFAULTS
+
+            default = _BUDGET_DEFAULTS[inner]
+            if isinstance(default, list):
+                return list(default)
+            return default
     return None
 
 
@@ -500,6 +524,10 @@ def _cmd_config_get(args: argparse.Namespace, config: dict) -> int:
             # round-trips via `config set alerts.enabled <plain-text>` work.
             if isinstance(v, bool):
                 rendered = "true" if v else "false"
+            elif isinstance(v, list):
+                # Comma-joined so `config get budget.alert_thresholds` output
+                # round-trips through `config set budget.alert_thresholds`.
+                rendered = ",".join(str(x) for x in v)
             else:
                 rendered = str(v)
             print(f"{k}={rendered}")
@@ -683,6 +711,93 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                 rendered = str(normalized)
             print(f"{key}={rendered}")
         return 0
+    if key in (
+        "budget.weekly_usd",
+        "budget.alerts_enabled",
+        "budget.alert_thresholds",
+    ):
+        inner_key = key.split(".", 1)[1]
+        # Parse + normalize the raw value per key BEFORE acquiring the lock so
+        # rejection short-circuits. The whole merged block is re-validated via
+        # _get_budget_config under the lock so we never persist a config that
+        # fails subsequent reads. _load_config_unlocked is mandatory inside the
+        # writer lock (load_config would self-deadlock on the same fcntl fd).
+        if inner_key == "weekly_usd":
+            if raw.strip().lower() in {"null", "none", ""}:
+                new_val: object = None
+            else:
+                try:
+                    new_val = float(raw)
+                except ValueError:
+                    eprint(
+                        "cctally config: budget.weekly_usd must be a number or "
+                        f"null, got {raw!r}"
+                    )
+                    return 2
+        elif inner_key == "alerts_enabled":
+            lo = raw.strip().lower()
+            if lo in ("true", "yes", "on", "1"):
+                new_val = True
+            elif lo in ("false", "no", "off", "0"):
+                new_val = False
+            else:
+                eprint(
+                    "cctally config: budget.alerts_enabled must be a boolean, "
+                    f"got {raw!r}"
+                )
+                return 2
+        else:  # alert_thresholds — comma-separated int list (empty = silenced)
+            stripped = raw.strip()
+            parsed: "list[int]" = []
+            if stripped:
+                for part in stripped.split(","):
+                    tok = part.strip()
+                    try:
+                        parsed.append(int(tok))
+                    except ValueError:
+                        eprint(
+                            "cctally config: budget.alert_thresholds must be a "
+                            f"comma-separated list of integers, got {raw!r}"
+                        )
+                        return 2
+            new_val = parsed
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            existing = config.get("budget")
+            if existing is not None and not isinstance(existing, dict):
+                eprint("cctally config: budget must be an object")
+                return 2
+            block = dict(existing or {})
+            block[inner_key] = new_val
+            config["budget"] = block
+            try:
+                validated = _get_budget_config(config)
+            except _BudgetConfigError as exc:
+                eprint(f"cctally config: {exc}")
+                return 2
+            # Persist the canonicalized leaf (e.g. sorted/deduped thresholds,
+            # float-coerced weekly_usd) so config.json matches what reads apply.
+            block[inner_key] = validated[inner_key]
+            config["budget"] = block
+            save_config(config)
+        # Forward-only reconcile (mirrors `budget set`): enabling/raising a
+        # budget while already past a threshold must record the crossed
+        # thresholds as already-alerted so the next record-usage tick does NOT
+        # dispatch retroactive alerts. Runs OUTSIDE config_writer_lock — the
+        # helper opens stats.db and must not nest under the config lock
+        # (fcntl.flock is per-fd; the helper has its own open_db locking).
+        c = _cctally()
+        c._reconcile_budget_on_config_write(validated)
+        out_val = validated[inner_key]
+        if getattr(args, "emit_json", False):
+            print(json.dumps({"budget": {inner_key: out_val}}, indent=2))
+        else:
+            if isinstance(out_val, bool):
+                rendered = "true" if out_val else "false"
+            else:
+                rendered = str(out_val)
+            print(f"{key}={rendered}")
+        return 0
     return 2  # unreachable given the gate above
 
 
@@ -770,4 +885,24 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                     save_config(config)
             # idempotent: silent on missing key
         return 0
+    if key in (
+        "budget.weekly_usd",
+        "budget.alerts_enabled",
+        "budget.alert_thresholds",
+    ):
+        # Drop only the named leaf; preserve sibling budget.* keys (e.g.
+        # unsetting weekly_usd keeps a customized alert_thresholds). If the
+        # `budget` block ends up empty, drop the parent so config.json stays
+        # tidy. Mirrors the alerts.enabled / dashboard.bind unset branches.
+        inner_key = key.split(".", 1)[1]
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            block = config.get("budget")
+            if isinstance(block, dict) and inner_key in block:
+                del block[inner_key]
+                if not block:
+                    config.pop("budget", None)
+                save_config(config)
+            # idempotent: silent on missing key
+        return 0
     return 2  # unreachable given the gate above

package/bin/_cctally_core.py

@@ -12,6 +12,7 @@ below. See docs/superpowers/specs/2026-05-22-cctally-core-data-globals.md.
 """
 from __future__ import annotations
 import datetime as dt
+import math
 import os
 import pathlib
 import re
@@ -505,6 +506,89 @@ def _get_alerts_config(cfg: "dict | None") -> dict:
     }
 
 
+# === Budget validation cluster ======================================
+
+
+class _BudgetConfigError(ValueError):
+    """Raised by _get_budget_config on an invalid budget block."""
+
+
+_BUDGET_DEFAULTS = {
+    "weekly_usd": None,            # None = no budget (default)
+    "alerts_enabled": True,        # "on when set"
+    "alert_thresholds": [90, 100],
+}
+_BUDGET_CONFIG_VALID_KEYS = {"weekly_usd", "alerts_enabled", "alert_thresholds"}
+
+
+def _get_budget_config(cfg: dict) -> dict:
+    """Return the validated, defaults-filled budget block.
+
+    Raises _BudgetConfigError on invalid values. Unknown sub-keys emit a
+    one-line warn-and-ignore (mirrors _get_alerts_config / the display.tz
+    posture for forward compatibility).
+    """
+    out = dict(_BUDGET_DEFAULTS)
+    out["alert_thresholds"] = list(_BUDGET_DEFAULTS["alert_thresholds"])
+    block = cfg.get("budget") if isinstance(cfg, dict) else None
+    if block is None:
+        return out
+    if not isinstance(block, dict):
+        raise _BudgetConfigError(
+            f"budget must be an object, got {type(block).__name__}"
+        )
+    # warn-and-ignore unknown keys (forward compat; matches _get_alerts_config)
+    for k in block.keys():
+        if k not in _BUDGET_CONFIG_VALID_KEYS:
+            print(
+                f"warning: ignoring unknown budget config key: {k}",
+                file=sys.stderr,
+            )
+
+    if "weekly_usd" in block:
+        v = block["weekly_usd"]
+        if v is None:
+            out["weekly_usd"] = None
+        elif isinstance(v, bool) or not isinstance(v, (int, float)):
+            raise _BudgetConfigError("budget.weekly_usd must be a number or null")
+        elif not math.isfinite(float(v)) or float(v) <= 0:
+            raise _BudgetConfigError("budget.weekly_usd must be a finite number > 0")
+        else:
+            out["weekly_usd"] = float(v)
+
+    if "alerts_enabled" in block:
+        v = block["alerts_enabled"]
+        if not isinstance(v, bool):
+            raise _BudgetConfigError("budget.alerts_enabled must be a boolean")
+        out["alerts_enabled"] = v
+
+    if "alert_thresholds" in block:
+        v = block["alert_thresholds"]
+        if not isinstance(v, list):
+            raise _BudgetConfigError("budget.alert_thresholds must be a list of ints")
+        cleaned = []
+        for t in v:
+            if isinstance(t, bool) or not isinstance(t, int):
+                raise _BudgetConfigError(
+                    "budget.alert_thresholds entries must be integers"
+                )
+            if t < 1 or t > 100:
+                raise _BudgetConfigError(
+                    "budget.alert_thresholds entries must be in [1, 100]"
+                )
+            cleaned.append(t)
+        out["alert_thresholds"] = sorted(set(cleaned))  # empty list allowed (silenced)
+
+    return out
+
+
+def _budget_alerts_active(budget_cfg: dict) -> bool:
+    """True iff a budget is set AND alerts are enabled."""
+    return budget_cfg.get("weekly_usd") is not None and bool(
+        budget_cfg.get("alerts_enabled")
+    )
+
+
 # === DB primitive ===================================================
 
 
@@ -907,6 +991,42 @@ def open_db() -> sqlite3.Connection:
         """
     )
 
+    # ── budget_milestones (equiv-$ budget threshold crossings — issue #19) ──
+    # Plain CREATE TABLE IF NOT EXISTS, NO migration handler / backfill — the
+    # exact posture of `five_hour_milestones` (write-once, forward-only). A
+    # mid-week quota reset re-anchors `week_start_at` (see
+    # `_resolve_current_budget_window`), so the new window naturally gets
+    # fresh rows under UNIQUE(week_start_at, threshold) — no `reset_event_id`
+    # segment column needed (unlike the percent/5h tables). `week_start_at`
+    # stores the effective/re-anchored ISO string from the resolver
+    # (`isoformat(timespec="seconds")`); the resolver's `parse_iso_datetime`
+    # returns a HOST-LOCAL tz-aware datetime, so this dedup key carries the
+    # host's UTC offset (e.g. `…T07:00:00-07:00`) — host-consistent, NOT
+    # portable across hosts, same posture as `five_hour_blocks.block_start_at`.
+    # Firing + reconcile + the dashboard envelope all read/write the identical
+    # string on a given host, so the UNIQUE dedup is exact. `alerted_at` is stamped BEFORE the
+    # osascript Popen (set-then-dispatch invariant); NULL = "recorded without
+    # dispatch" (the forward-only-from-set reconcile path) OR "not yet
+    # dispatched", never "delivery failed". Lives BEFORE the migration
+    # dispatcher: a plain CREATE on a framework-untracked table never touches
+    # `schema_migrations`, so the dispatcher's fresh-install snapshot is
+    # unaffected.
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS budget_milestones (
+            id              INTEGER PRIMARY KEY AUTOINCREMENT,
+            week_start_at   TEXT    NOT NULL,
+            threshold       INTEGER NOT NULL,
+            budget_usd      REAL    NOT NULL,
+            spent_usd       REAL    NOT NULL,
+            consumption_pct REAL    NOT NULL,
+            crossed_at_utc  TEXT    NOT NULL,
+            alerted_at      TEXT,
+            UNIQUE(week_start_at, threshold)
+        )
+        """
+    )
+
     # Migration framework dispatcher. Replaces the prior inline gate stack
     # (has_blocks + _migration_done) with the framework's _run_pending_-
     # migrations entry point. See spec §2.3, §5.2 + the migration handlers