cctally 1.22.3 → 1.23.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.23.0] - 2026-06-02
+
+### Added
+- **Projected-pace alerts: a new opt-in `projected` alert axis that warns you *before* you cross a ceiling, firing on your week-average pace rather than waiting for the actual crossing.** It tracks two metrics — `weekly_pct` (projected to reach 90% / 100% of your subscription cap by the week's reset) and `budget_usd` (projected to reach your `budget.alert_thresholds` of the weekly $ budget) — using the smooth week-average projection (`now + average-rate × time-remaining`), the same conservative number `forecast`/`budget` already display; it deliberately ignores the hotter trailing-24h estimate so a brief spike doesn't trigger a false alarm. Each level fires once per week (no re-fire, no recovery alert), is suppressed while the forecast is `LOW CONF` (too early in the week / too few samples), and re-anchors cleanly across a mid-week reset.
+- **Both projected toggles default OFF, gated behind their parent axis** — enable weekly-% projected alerts with `cctally config set alerts.projected_enabled true` (requires `alerts.enabled`) and budget-$ projected alerts with `cctally config set budget.projected_enabled true` (requires a configured `budget.weekly_usd` + `budget.alerts_enabled`); preview either without writing any data via `cctally alerts test --axis projected --metric weekly_pct` (or `--metric budget_usd`). The local web dashboard surfaces fired projected alerts with a dedicated **Projected** chip and forecast-aware context, and exposes both enable/disable toggles in its settings panel.
+- **`forecast --json` and `budget --json` now expose an additive `week_avg_projection_pct` / `week_avg_projection_usd` field** — the exact week-average end-of-week projection the projected-pace alert axis fires on, surfaced for scripting and reconciliation (additive only; no schema-version bump, existing keys unchanged).
+
+### Fixed
+- **The mid-week reset-to-zero detector now waits for a corroborating second reading before segmenting the week (#128).** When the Anthropic usage API reports a clean drop to ~0% against non-trivial prior usage (below the 25pp goodwill-credit threshold), `record-usage` no longer writes a `week_reset_events` row on the very first zero: it arms a one-tick debounce and fires only if the next reading stays low (at or below half the pre-zero level), treating a zero that bounces back toward the prior percentage as a transient API/replica glitch rather than a real reset. A genuine reset still surfaces — one status-line tick later — and the ≥25pp credit path, the boundary-advance path, and the 5-hour detector are unchanged. This is belt-and-suspenders hardening on the 2026-06-01 surprise-reset fix; the debounce is best-effort under concurrent `record-usage` runs (a race degrades to the previous single-zero behavior, never worse).
+- **Test-suite isolation (no shipped-code change): the `*_ns_patch.py` binding-regression tests no longer read the developer's real `~/.local/share/cctally` database (#127).** Their shared `cctally_mod` fixture loaded `bin/cctally` with a bespoke loader that only set `HOME` and relied on `_cctally_core`'s import-time path derivation — which silently no-ops once any earlier test has cached `_cctally_core` in `sys.modules` (every `load_script()` user does), so the handler under test fell back to the real prod DB. That stayed invisible until the prod DB happened to hold a `week_reset_events` row for the current week, at which point `test_percent_breakdown_md_reaches_all_accessors_via_ns` flipped to a failure that only reproduced under certain test orderings (it filters milestones by the DB's active segment, so the seeded fake milestone was dropped and the table never rendered). The five `*_ns_patch.py` fixtures now route through a shared `conftest.load_isolated_cctally_module()` helper built on `load_script()` + `redirect_paths()`, pinning `_cctally_core`'s path constants to the per-test tmp dir deterministically regardless of import order. A new order-independent regression (`test_ns_patch_loader_isolates_db_when_core_cached`) asserts the loader re-isolates `DB_PATH` even when `_cctally_core` is pre-cached pointing at a real prod path.
+
+## [1.22.4] - 2026-06-01
+
+### Fixed
+- **A surprise mid-week Anthropic usage reset is now reflected in the 7d percentage even when you were below ~25% usage.** When Anthropic zeroes the weekly counter mid-window (same reset timestamp, usage drops to ~0 — e.g. the 2026-06-01 incident), the reset detector previously only fired when the drop was at least 25 percentage points, so any account reset from a lower base (the observed 14% → 0%) slipped through: no `week_reset_events` row was written, the monotonic high-water-mark clamp kept reporting the stale pre-reset percentage across the statusline, `weekly`/`report`, and the dashboard, and post-reset 0% reads were silently dropped at the write site. The detector now ALSO fires on a reset-to-zero — when the post-reset value collapses to ~0 (≤ 1%) with at least a 3pp drop — independently of the 25pp magnitude gate, since a clean drop to zero is an unambiguous reset regardless of size (a lagging API replica reports a slightly-lower number, never a clean 0 against real usage), while the 3pp floor rejects 1%→0% replica jitter that would otherwise spuriously segment the week. The new discriminator is a single shared `_is_reset_drop()` helper wired into all four 7d detection sites (live + backfill, boundary-advance + in-place-credit branches) so they stay byte-identical; the 25pp partial-credit path and the separate 5h detector are unchanged. Regression: three new cases in `tests/test_in_place_credit_detection.py` (live reset-to-zero fires below 25pp, the 3pp floor rejects 1%→0% jitter, and backfill parity).
+
+### Changed
+- **Internal refactor (no user-facing change): extracted the shared formatting/color/table render primitives — the boxed-table renderer, the color/unicode capability detectors, the ANSI styling + display-width helpers, the integer/width-budget number formatters, the compact timestamp/week-window formatters, and the `_ANSI_ESC_RE` regex (plus the small `_parse_iso_datetime_optional` helper they depend on) — out of the `bin/cctally` single-file program into a new stdlib-only pure-function sibling module, `bin/_lib_fmt.py` (#126, the final tranche of the `bin/cctally` split).** This trims the main script by ~250 lines (2,969 → 2,715), and additionally converts the eight back-references these primitives had in `bin/_lib_render.py` and `bin/_lib_diff_kernel.py` from `cctally`-namespace shims into honest direct imports of the new kernel — with no change to any command's behavior, flags, output, or exit codes: every reporting/`diff`/`project`/`cache-report`/`forecast`/`blocks`/`percent-breakdown`/`five-hour-blocks` golden test is byte-identical and the full harness + pytest suite (1,329 checks) passes, a new `tests/test_lib_fmt_extraction_invariants.py` locks the extraction's import discipline, and the new module ships in the npm/brew/public packages (promoted to the mirror allowlist). Purely a maintainability / code-organization change; nothing to do on upgrade.
+
 ## [1.22.3] - 2026-06-01
 
 ### Changed

package/bin/_cctally_alerts.py

@@ -69,10 +69,12 @@ _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
+_alert_text_projected = _lib_alerts_payload._alert_text_projected
 _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
+_build_alert_payload_projected = _lib_alerts_payload._build_alert_payload_projected
 
 
 # === Honest imports from extracted homes ===================================
@@ -138,6 +140,8 @@ def _dispatch_alert_notification(
         title, subtitle, body = _alert_text_five_hour(payload, tz)
     elif axis == "budget":
         title, subtitle, body = _alert_text_budget(payload, tz)
+    elif axis == "projected":
+        title, subtitle, body = _alert_text_projected(payload, tz)
     else:
         title, subtitle, body = (
             "cctally - alert",
@@ -207,6 +211,8 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
         axis = "weekly"
     elif args.axis == "budget":
         axis = "budget"
+    elif args.axis == "projected":
+        axis = "projected"
     else:
         axis = "five_hour"
     threshold = int(args.threshold)
@@ -239,6 +245,27 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
             spent_usd=300.0 * threshold / 100.0,
             consumption_pct=float(threshold),
         )
+    elif axis == "projected":
+        # Synthetic projected-pace payload — NO DB writes (test/real divergence
+        # contract). The metric discriminator picks the wiring; projected_value
+        # is the threshold's denominator-relative value (so the body reads
+        # plausibly, e.g. weekly 100% → "~100% of cap", budget 100% → "$300 of
+        # $300"). denominator is the at-crossing target the row would carry
+        # (Codex P0-4): 100.0 for weekly_pct, $300 for budget_usd.
+        metric = getattr(args, "metric", "weekly_pct")
+        if metric == "budget_usd":
+            denominator = 300.0
+            projected_value = 300.0 * threshold / 100.0
+        else:  # weekly_pct
+            denominator = 100.0
+            projected_value = float(threshold)
+        payload = _build_alert_payload_projected(
+            metric=metric,
+            threshold=threshold,
+            projected_value=projected_value,
+            denominator=denominator,
+            week_start_at=dt.date.today().isoformat(),
+        )
     else:
         payload = _build_alert_payload_five_hour(
             threshold=threshold,

package/bin/_cctally_config.py

@@ -297,6 +297,7 @@ def save_config(data: dict[str, Any]) -> None:
 ALLOWED_CONFIG_KEYS = (
     "display.tz",
     "alerts.enabled",
+    "alerts.projected_enabled",
     "dashboard.bind",
     "update.check.enabled",
     "update.check.ttl_hours",
@@ -306,6 +307,7 @@ ALLOWED_CONFIG_KEYS = (
     "budget.weekly_usd",
     "budget.alerts_enabled",
     "budget.alert_thresholds",
+    "budget.projected_enabled",
 )
 
 
@@ -405,6 +407,13 @@ def _config_known_value(config: dict, key: str) -> "object":
         return c.get_display_tz_pref(config)
     if key == "alerts.enabled":
         return bool(_get_alerts_config(config)["enabled"])
+    if key == "alerts.projected_enabled":
+        # Validated boolean (defaults to False when unset). A corrupt alerts
+        # block surfaces the default — mirrors alerts.enabled.
+        try:
+            return bool(_get_alerts_config(config)["projected_enabled"])
+        except c._AlertsConfigError:
+            return False
     if key == "dashboard.bind":
         # Default semantic alias is 'loopback' (resolves to 127.0.0.1 at
         # bind time). LAN exposure is opt-in via `set dashboard.bind lan`
@@ -472,6 +481,7 @@ def _config_known_value(config: dict, key: str) -> "object":
         "budget.weekly_usd",
         "budget.alerts_enabled",
         "budget.alert_thresholds",
+        "budget.projected_enabled",
     ):
         inner = key.split(".", 1)[1]
         # Read the validated, defaults-filled block. A corrupt block falls
@@ -598,6 +608,51 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         else:
             print(f"alerts.enabled={'true' if normalized else 'false'}")
         return 0
+    if key == "alerts.projected_enabled":
+        # Projected-pace opt-in (#121). Same bool-normalizer + read-modify-write
+        # posture as alerts.enabled (preserves sibling alerts.* keys).
+        # _normalize_alerts_enabled_value hardcodes "alerts.enabled" in its
+        # ValueError text, so catch + re-message with the actual key name
+        # (mirrors _normalize_update_check_enabled_value's precedent) — the
+        # budget side already names its own key correctly.
+        try:
+            normalized = c._normalize_alerts_enabled_value(raw)
+        except ValueError:
+            print(
+                f"cctally: invalid boolean value for alerts.projected_enabled: "
+                f"{raw!r} (expected true|false|yes|no|1|0|on|off)",
+                file=sys.stderr,
+            )
+            return 2
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            existing_alerts = config.get("alerts")
+            if existing_alerts is not None and not isinstance(
+                existing_alerts, dict
+            ):
+                print(
+                    "cctally: alerts config error: alerts must be an object",
+                    file=sys.stderr,
+                )
+                return 2
+            alerts_block = dict(existing_alerts or {})
+            alerts_block["projected_enabled"] = normalized
+            try:
+                _get_alerts_config({**config, "alerts": alerts_block})
+            except _AlertsConfigError as exc:
+                print(f"cctally: alerts config error: {exc}", file=sys.stderr)
+                return 2
+            config["alerts"] = alerts_block
+            save_config(config)
+        if getattr(args, "emit_json", False):
+            print(
+                json.dumps({"alerts": {"projected_enabled": normalized}}, indent=2)
+            )
+        else:
+            print(
+                f"alerts.projected_enabled={'true' if normalized else 'false'}"
+            )
+        return 0
     if key == "dashboard.bind":
         # Validation rejects whitespace / empty / non-string up front;
         # write proceeds under config_writer_lock with _load_config_unlocked
@@ -715,6 +770,7 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         "budget.weekly_usd",
         "budget.alerts_enabled",
         "budget.alert_thresholds",
+        "budget.projected_enabled",
     ):
         inner_key = key.split(".", 1)[1]
         # Parse + normalize the raw value per key BEFORE acquiring the lock so
@@ -734,7 +790,7 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                         f"null, got {raw!r}"
                     )
                     return 2
-        elif inner_key == "alerts_enabled":
+        elif inner_key in ("alerts_enabled", "projected_enabled"):
             lo = raw.strip().lower()
             if lo in ("true", "yes", "on", "1"):
                 new_val = True
@@ -742,7 +798,7 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                 new_val = False
             else:
                 eprint(
-                    "cctally config: budget.alerts_enabled must be a boolean, "
+                    f"cctally config: budget.{inner_key} must be a boolean, "
                     f"got {raw!r}"
                 )
                 return 2
@@ -817,19 +873,21 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 save_config(config)
             # idempotent: silent on missing key
         return 0
-    if key == "alerts.enabled":
+    if key in ("alerts.enabled", "alerts.projected_enabled"):
         # Mirror the display.tz branch: writer-lock + _load_config_unlocked
         # (NOT load_config — fcntl.flock is per-fd so re-entry would
         # self-deadlock per the gotcha in CLAUDE.md). Unsetting just the
-        # `enabled` key preserves any user-customized threshold lists
-        # (`weekly_thresholds`, `five_hour_thresholds`); the read-time
-        # validator (`_get_alerts_config`) re-applies the canonical
-        # default of `enabled = False` for the missing key on next get.
+        # named key preserves any user-customized threshold lists
+        # (`weekly_thresholds`, `five_hour_thresholds`) and the sibling
+        # enabled/projected_enabled toggle; the read-time validator
+        # (`_get_alerts_config`) re-applies the canonical default of `False`
+        # for the missing key on next get.
+        inner_key = key.split(".", 1)[1]
         with config_writer_lock():
             config = _load_config_unlocked()
             block = config.get("alerts")
-            if isinstance(block, dict) and "enabled" in block:
-                del block["enabled"]
+            if isinstance(block, dict) and inner_key in block:
+                del block[inner_key]
                 if not block:
                     config.pop("alerts", None)
                 save_config(config)
@@ -889,6 +947,7 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
         "budget.weekly_usd",
         "budget.alerts_enabled",
         "budget.alert_thresholds",
+        "budget.projected_enabled",
     ):
         # Drop only the named leaf; preserve sibling budget.* keys (e.g.
         # unsetting weekly_usd keeps a customized alert_thresholds). If the

package/bin/_cctally_core.py

@@ -427,7 +427,12 @@ class _AlertsConfigError(ValueError):
     """Raised by _get_alerts_config on invalid alerts block."""
 
 
-_ALERTS_CONFIG_VALID_KEYS = {"enabled", "weekly_thresholds", "five_hour_thresholds"}
+_ALERTS_CONFIG_VALID_KEYS = {
+    "enabled",
+    "weekly_thresholds",
+    "five_hour_thresholds",
+    "projected_enabled",
+}
 
 
 def _validate_threshold_list(name: str, value: object) -> "list[int]":
@@ -499,10 +504,20 @@ def _get_alerts_config(cfg: "dict | None") -> dict:
     five_hour = _validate_threshold_list(
         "five_hour_thresholds", block.get("five_hour_thresholds", [90, 95])
     )
+    # projected-pace opt-in (#121); default OFF so upgrades fire no surprise
+    # notifications. Bool-validated (NOT coerced) so a non-bool is a config
+    # error, not silently truthy.
+    projected_enabled = block.get("projected_enabled", False)
+    if not isinstance(projected_enabled, bool):
+        raise _AlertsConfigError(
+            f"alerts.projected_enabled must be a JSON boolean, got "
+            f"{type(projected_enabled).__name__}: {projected_enabled!r}"
+        )
     return {
         "enabled": enabled,
         "weekly_thresholds": weekly,
         "five_hour_thresholds": five_hour,
+        "projected_enabled": projected_enabled,
     }
 
 
@@ -517,8 +532,14 @@ _BUDGET_DEFAULTS = {
     "weekly_usd": None,            # None = no budget (default)
     "alerts_enabled": True,        # "on when set"
     "alert_thresholds": [90, 100],
+    "projected_enabled": False,    # projected-pace opt-in (#121); default OFF
+}
+_BUDGET_CONFIG_VALID_KEYS = {
+    "weekly_usd",
+    "alerts_enabled",
+    "alert_thresholds",
+    "projected_enabled",
 }
-_BUDGET_CONFIG_VALID_KEYS = {"weekly_usd", "alerts_enabled", "alert_thresholds"}
 
 
 def _get_budget_config(cfg: dict) -> dict:
@@ -579,6 +600,12 @@ def _get_budget_config(cfg: dict) -> dict:
             cleaned.append(t)
         out["alert_thresholds"] = sorted(set(cleaned))  # empty list allowed (silenced)
 
+    if "projected_enabled" in block:
+        v = block["projected_enabled"]
+        if not isinstance(v, bool):
+            raise _BudgetConfigError("budget.projected_enabled must be a boolean")
+        out["projected_enabled"] = v
+
     return out
 
 
@@ -1027,6 +1054,37 @@ def open_db() -> sqlite3.Connection:
         """
     )
 
+    # ── projected_milestones (week-average-pace projection crossings — #121) ──
+    # Plain CREATE TABLE IF NOT EXISTS, NO migration handler / backfill — same
+    # posture as `budget_milestones` (write-once, forward-only, no
+    # `reset_event_id` segment column). Two metrics share the table, keyed by
+    # `metric` ('weekly_pct' | 'budget_usd'); a level fires once the
+    # WEEK-AVERAGE projection (not the displayed high-end verdict) crosses
+    # `threshold`. `denominator` snapshots the target AT crossing (target_usd
+    # for budget_usd, 100.0 for weekly_pct) so the dashboard envelope renders
+    # context "$312 of $300" / "102% of cap" from the ROW, not from live config
+    # that may have changed since (Codex P0-4). A mid-week reset re-anchors
+    # `week_start_at` (new window → fresh rows under the UNIQUE key), the
+    # budget-pattern reset handling — hence NO `reset_event_id` column.
+    # `alerted_at` is stamped BEFORE the osascript Popen (set-then-dispatch).
+    # Lives BEFORE the migration dispatcher: a plain CREATE on a
+    # framework-untracked table never touches `schema_migrations`.
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS projected_milestones (
+            id              INTEGER PRIMARY KEY AUTOINCREMENT,
+            week_start_at   TEXT    NOT NULL,
+            metric          TEXT    NOT NULL,   -- 'weekly_pct' | 'budget_usd'
+            threshold       INTEGER NOT NULL,   -- 90 | 100
+            projected_value REAL    NOT NULL,
+            denominator     REAL    NOT NULL,   -- target_usd (budget) | 100.0 (weekly)
+            crossed_at_utc  TEXT    NOT NULL,
+            alerted_at      TEXT,
+            UNIQUE(week_start_at, metric, 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