cctally 1.103.0 → 1.104.0

package/CHANGELOG.md

@@ -5,6 +5,62 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.104.0] - 2026-08-29
+
+### Added
+- `cctally quota` reports how much of your weekly quota your usage consumes and whether Anthropic has changed the metering rate, from a budget fitted to your own history rather than a shipped constant. See `docs/commands/quota.md`.
+- `cctally quota --json` publishes the fit, the current week's consumption and projection, the composition support radii and the detector's own bound under `schemaVersion` 1.
+- `cctally quota --reset-calibration` discards the stored calibration for one account, and `--since` and `--watch-from` narrow or override the window the analysis uses.
+- `bin/cctally-preflight` compiles every Python file in the repository, not only the ones beside it, so a syntax error anywhere in the tree now blocks a test run instead of surfacing during one.
+- `cctally forecast --json` states the reading its arithmetic used and where its projection came from, through `weekly_percent_corrected`, `right_censored`, `projection_basis`, `projection_code` and `calibration_code`.
+- `cctally forecast --json` moves to `schemaVersion` 2: its three projection fields can now be null, and they are measured from a different reading than before.
+- `cctally project --json` moves to `schemaVersion` 2. `attributedUsedPercent` and `costPerPercent` keep their spelling and change their meaning, from a share of the window's cost to modelled weekly quota.
+- `cctally project` reports each project's `Used %` as modelled quota units rather than as its share of the window's dollars, so a cache-heavy project no longer reads high and an output-heavy Opus one no longer reads low.
+- `cctally doctor` reports a new Quota category: whether Anthropic changed your weekly metering rate, and whether the stored calibration is usable. Neither check can fail, so neither changes doctor's exit code.
+- `cctally quota` records a durable event when it confirms a metering-rate change, so it and `doctor` report the change with no configuration. The desktop notification stays off until you set `alerts.rate_change_enabled`.
+- `cctally project` states its four modelled-quota figures under the table — window total, listed-row total, filtered or unmodelled, and the meter's reading minus the modelled total — where before they were in `--json` only.
+- The status line's 7d slot shows where the week is heading and which measurement said so, as `7d 42% (2d 3h) → 58% meter`, plus a `Δrate` marker while a metering-rate change is in force.
+- The dashboard's Forecast panel names the basis its projection came from and shows a `Δ rate` chip while a metering-rate change is in force.
+- The dashboard's Forecast modal adds the modelled consumption, the headroom, what the meter reading covers, and the meter's reading minus the modelled total.
+- The dashboard's Recent Alerts modal lists metering-rate changes in their own section, with the size and direction of the change and the instant it took effect, and a rate change now raises its own toast.
+- `alerts.rate_change_enabled` is settable with `cctally config set` and from the dashboard's Settings overlay, so turning the notification on no longer means editing `config.json` by hand.
+- `bin/cctally-test-all` refuses to start when the recorded test estate disagrees with what this tree collects, when a recorded test disappeared without a declaration authorizing it, or when it cannot derive the estate at all.
+- `bin/cctally-test-all --with-estate-check` runs that check on a `--harness` subset, which otherwise skips it to keep a targeted run fast.
+
+### Changed
+- `cctally forecast`, the TUI and the dashboard measure your pace from what you consumed rather than from the rounded-up meter reading, so rates and projections read about half a point lower and daily budgets a little larger.
+- At a displayed 100% the forecast shows no projection, no time-to-cap and no daily budget, because a capped meter says only that you are past 99%. `cctally quota` still models consumption there, from tokens.
+- The projected-pace weekly alert stays quiet once `cctally quota` has fitted your budget, rather than firing on a pace the forecast no longer shows you.
+- `cctally forecast`'s trailing four-week dollar rate divides each prior week's cost by the meter movement that week realized, not by its post-credit high-water mark, which priced one measured week at $355 per point against a true $25.
+- A prior week whose realized movement cannot be established is left out of the forecast's four-week median rather than guessed at, and so is a week whose meter reached 100%.
+- `cctally project` withholds its meter-versus-modelled difference when the requested range slices a subscription week, instead of stating a whole-week difference beside a three-day range.
+- `cctally forecast` names its dollar rate's source in words — `trailing 4wk median (drift-reduced confidence)` rather than the bare code — and says when the comparability test behind that rate could not run.
+- `rates.week_average_pct_per_hour` in `cctally forecast --json` is null at a reading of 100% or more, because a capped meter supplies no rate to average.
+- `cctally quota` refuses to predict from a metering rate it has only just detected. It says so, and the forecast, the TUI and the dashboard fall back to the meter and state the reason, rather than projecting from a three-day fit.
+- `bin/cctally-preflight` lists the repository once instead of once per check, so widening the Python check to the whole tree costs one pass rather than two.
+- `docs/commands/report.md` states that `$ / 1%` falls when the provider charges more points for the same tokens, so a drop can read as improved efficiency, and points at `cctally quota` as the detector. The metric itself is unchanged.
+- `cctally project` names the absent operand when it withholds the meter-versus-modelled difference — a modelled week with no snapshot, or a window that modelled no week — instead of reporting either as a misaligned population.
+- `bin/cctally-test-all` builds both of its pytest phases from one recorded declaration rather than from hard-coded file names, and refuses at startup when a named target no longer exists.
+- `bin/cctally-test-all` removes `PYTEST_ADDOPTS` and `PYTEST_PLUGINS` from both pytest phases so neither can narrow a run; set `CCTALLY_PYTEST_DURATIONS=1` for per-test timings instead.
+
+### Fixed
+- The dashboard keeps the full account-count value visible in the `All` hero at tablet widths instead of clipping it mid-word.
+- A shared forecast artifact writes a ceiling more than 30 days out as `>30d` instead of printing the literal figure, which on a barely-used week read `1166.8`.
+- The terminal forecast's explain modal says why it shows no daily budgets at a capped meter, instead of printing the heading over nothing.
+- `bin/cctally-preflight` bounds every command it runs, including the harness-ownership check, and reports a hung system bash version probe rather than silently skipping the bash 3.2 floor check.
+- `bin/cctally-preflight` stops its shell syntax sweep and reports what went unchecked when an interpreter hangs, rather than spending its full per-file timeout on every remaining file.
+- `cctally project` withholds modelled quota on a multi-account install whose account registry cannot be read, instead of falling back to a cost share under the `Used %` column.
+- `cctally forecast` leaves a prior week out of its four-week median when the recorded credit or reset rows for that week cannot be read, instead of summing the week as if the credit had zeroed the meter.
+- `cctally forecast` keeps prior weeks from before a metering-rate change out of its four-week median even when it cannot read the entry cache, instead of admitting every one of them after a single failed read.
+- The dashboard hero shows no week-over-week `$ / 1%` comparison when it has no `$ / 1%` to compare, instead of printing a change beside a dash.
+- The dashboard's Forecast panel keeps its pace bar visible and its content inside the card when the source reports a degradation, where the bar collapsed to nothing and the panel overflowed.
+- The dashboard's Forecast modal says when a published `$ / 1%` rate was measured over a reduced or unverified population, where before the qualification was only visible in `--json`.
+- A metering-rate change desktop notification shows the effective date in your own timezone rather than in UTC.
+- Interrupting `cctally quota` with Ctrl-C while it records a metering-rate change stops the command, rather than printing a recording failure and carrying on.
+- `cctally quota` carries on when it cannot read your stored calibration file, rather than stopping with a Python traceback.
+- The status line's 7d slot shows no projection once the stored reset instant has passed, rather than projecting over a week that has already ended.
+- The dashboard's Forecast panel puts its verdict, status and `Δ rate` chips on one line instead of stacking them, giving the card back a row of height. The Forecast modal's Quota model heading is now tinted like every other section heading.
+
 ## [1.103.0] - 2026-08-26
 
 ### Added

package/bin/_cctally_alerts.py

@@ -140,6 +140,56 @@ def _alert_text_quota(payload: dict, _tz) -> tuple[str, str, str]:
     # dashboard alert envelope, so the CLI line is the only routing it gets.
     return title, subtitle, _with_next_step(body, payload, _tz)
 
+
+def _alert_text_meter_rate_change(payload: dict, tz) -> tuple[str, str, str]:
+    """#661 S2 §6.1: the non-threshold family's own copy.
+
+    It states the direction and the size of the change, and it states them as
+    a rate the provider sets rather than as anything cctally can act on. There
+    is no threshold to name, which is the whole reason this family is not an
+    `AXIS_REGISTRY` member.
+
+    Two DELIBERATE divergences from the threshold builders, both recorded in
+    `docs/alerts-gotchas.md` (#661 S2 Stage C review, F7b):
+
+    * The body does not end with `_with_next_step`. That helper derives its
+      affordance through `alert_next_step_command`, which branches on
+      `AXIS_REGISTRY` axes; this family is deliberately not one, so it has no
+      window to scope and no branch to reach. The affordance is stated
+      directly instead.
+    * This builder and `_alert_text_quota` above it live in this glue module
+      rather than in the pure `_lib_alerts_payload` kernel, which holds the
+      other five. That is the placement both non-registry families use.
+
+    `effective_from` IS routed through `format_display_dt`. It is a clock
+    instant, not a calendar day, so the carve-out `_alert_text_weekly`
+    documents for `week_start_date` does not apply: slicing its first ten
+    characters showed a user at UTC+13 or UTC-8 a date one day away from
+    their own.
+    """
+    previous = float(payload.get("previous_units_per_point") or 0.0)
+    new = float(payload.get("new_units_per_point") or 0.0)
+    provider = str(payload.get("provider") or "claude").capitalize()
+    if previous > 0.0 and new > 0.0:
+        change = (new - previous) / previous * 100.0
+        direction = "less" if change < 0 else "more"
+        subtitle = (
+            f"each meter point now covers {abs(change):.0f}% {direction} usage")
+    else:
+        subtitle = "the rate this account is metered at changed"
+    raw = str(payload.get("effective_from") or "")
+    try:
+        effective = _lib_alerts_payload.format_display_dt(
+            raw, tz, fmt="%Y-%m-%d", suffix=False) if raw else ""
+    except ValueError:
+        effective = ""
+    body = (
+        f"Effective {effective}. Run `cctally quota` for the fitted budget "
+        f"and its evidence." if effective else
+        "Run `cctally quota` for the fitted budget and its evidence.")
+    return f"cctally - {provider} metering rate changed", subtitle, body
+
+
 # Phase B: severity policy + the cross-platform dispatch kernel. The kernel is
 # pure (parameterized on platform + which_on_path); this module is the I/O glue
 # that injects the real sys.platform / shutil.which and spawns with shell=False.
@@ -293,6 +343,8 @@ def _dispatch_alert_notification(
         title, subtitle, body = _alert_text_projected(payload, tz)
     elif axis == "quota":
         title, subtitle, body = _alert_text_quota(payload, tz)
+    elif axis == "meter_rate_change":
+        title, subtitle, body = _alert_text_meter_rate_change(payload, tz)
     else:
         title, subtitle, body = (
             "cctally - alert",
@@ -310,10 +362,19 @@ def _dispatch_alert_notification(
     # trailing log column. A missing threshold (defensive — shouldn't happen for
     # a real crossing) floors at "info".
     threshold = payload.get("threshold")
-    try:
-        severity = severity_for(int(threshold)) if threshold is not None else "info"
-    except (TypeError, ValueError):
-        severity = "info"
+    if axis == "meter_rate_change":
+        # #661 S2 §6.1: this family carries an EXPLICIT severity, because a
+        # rate transition has no percentage threshold for `severity_for` to
+        # map. Reading it verbatim is what keeps the three tiers meaningful
+        # here; falling through would floor every transition at `info`.
+        severity = str(payload.get("severity") or "info")
+        if severity not in ("info", "warn", "alarm"):
+            severity = "info"
+    else:
+        try:
+            severity = severity_for(int(threshold)) if threshold is not None else "info"
+        except (TypeError, ValueError):
+            severity = "info"
     urgency = severity_to_urgency(severity)
 
     if platform is None:

package/bin/_cctally_config.py

@@ -300,6 +300,7 @@ ALLOWED_CONFIG_KEYS = (
     "display.tz",
     "alerts.enabled",
     "alerts.projected_enabled",
+    "alerts.rate_change_enabled",
     "alerts.notifier",
     "alerts.command_template",
     "alerts.quota",
@@ -1006,6 +1007,16 @@ def _config_known_value(config: dict, key: str) -> "object":
             return bool(_get_alerts_config(config)["projected_enabled"])
         except c._AlertsConfigError:
             return False
+    if key == "alerts.rate_change_enabled":
+        # #661 S2 section 6.2's PUSH gate. Recording a metering-rate change is
+        # unconditional; this key gates only the notification. Same posture as
+        # alerts.projected_enabled — validated boolean, default False, and a
+        # corrupt alerts block surfaces the default rather than erroring out of
+        # a plain `config get`.
+        try:
+            return bool(_get_alerts_config(config)["rate_change_enabled"])
+        except c._AlertsConfigError:
+            return False
     if key == "alerts.notifier":
         # Validated dispatch backend (defaults to 'auto' when unset). A corrupt
         # alerts block surfaces the default — mirrors alerts.enabled.
@@ -1468,6 +1479,53 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                 f"alerts.projected_enabled={'true' if normalized else 'false'}"
             )
         return 0
+    if key == "alerts.rate_change_enabled":
+        # #661 S2 section 6.2. Identical posture to alerts.projected_enabled
+        # above, including the re-message: _normalize_alerts_enabled_value
+        # hardcodes "alerts.enabled" in its ValueError text, so the branch
+        # names the key the user actually typed.
+        try:
+            normalized = c._normalize_alerts_enabled_value(raw)
+        except ValueError:
+            print(
+                f"cctally: invalid boolean value for "
+                f"alerts.rate_change_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["rate_change_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": {"rate_change_enabled": normalized}}, indent=2
+                )
+            )
+        else:
+            print(
+                f"alerts.rate_change_enabled="
+                f"{'true' if normalized else 'false'}"
+            )
+        return 0
     if key == "alerts.notifier":
         # Dispatch backend (Phase B). Plain string; the enum constraint is
         # enforced by the pre-persist _get_alerts_config validation (so we never
@@ -2296,6 +2354,7 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
     if key in (
         "alerts.enabled",
         "alerts.projected_enabled",
+        "alerts.rate_change_enabled",
         "alerts.notifier",
         "alerts.command_template",
         "alerts.quota",
@@ -2305,8 +2364,9 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
         # self-deadlock per the gotcha in CLAUDE.md). Unsetting just the
         # named key preserves any user-customized threshold lists
         # (`weekly_thresholds`, `five_hour_thresholds`) and the sibling
-        # enabled/projected_enabled/notifier/command_template keys. For
-        # enabled/projected_enabled/notifier the read-time validator
+        # enabled/projected_enabled/rate_change_enabled/notifier/
+        # command_template keys. For enabled/projected_enabled/
+        # rate_change_enabled/notifier the read-time validator
         # (`_get_alerts_config`) re-applies the canonical default
         # (`False` / `"auto"`) for the missing key on next get. NOT so for
         # command_template when notifier == "command": the cross-field

package/bin/_cctally_core.py

@@ -400,7 +400,17 @@ _init_paths_from_env()
 # removing the shared-memory WAL page map implicated by the retained corruption
 # bundles. The one-time rebuild is the mode transition; no stats migration is
 # added and cache/conversations remain WAL/NORMAL.
-STATS_INDEX_EPOCH = 1010
+# 1010 -> 1011 (#661 S2 §6.4): the meter-rate-change event family. Adds
+# `meter_rate_change_events`, a durable forward-only record that one provider
+# metering-rate transition was observed, keyed
+# `(provider, account_key, effective_from)`. It is an epoch bump and NOT a
+# stats migration for the two reasons every bump since 1005 carries: the
+# 13-entry registry is frozen, AND an epoch-current open returns before any
+# schema work, so a `@stats_migration` handler would never run on an upgraded
+# install and the table would simply never appear. `quota_alert_arming` is the
+# precedent the family follows — a journaled STATE record whose boundary
+# survives a rebuild, so history cannot re-fire.
+STATS_INDEX_EPOCH = 1011
 LEGACY_STATS_HEAD = 13
 
 #: #496 S1 F1. A NEW branch, for a state that cannot occur before the
@@ -965,6 +975,12 @@ _ALERTS_CONFIG_VALID_KEYS = {
     "weekly_thresholds",
     "five_hour_thresholds",
     "projected_enabled",
+    # #661 S2 §6.2. The metering-rate-change family's PUSH toggle, and only
+    # its push toggle: events are recorded from the first upgrade whatever
+    # this says, so every pull surface shows the state with no configuration.
+    # It defaults OFF like every other alert toggle, so an upgrade never
+    # produces a surprise notification.
+    "rate_change_enabled",
     "notifier",
     "command_template",
 }
@@ -1062,6 +1078,17 @@ def _get_alerts_config(cfg: "dict | None") -> dict:
             f"{type(projected_enabled).__name__}: {projected_enabled!r}",
             field="alerts.projected_enabled",
         )
+    # #661 S2 §6.2: the rate-change PUSH toggle, default OFF. Recording is
+    # unconditional and does not consult this — the split is what lets a user
+    # learn that the rate changed without opting in while nothing arrives
+    # unbidden. Bool-validated rather than coerced, like `projected_enabled`.
+    rate_change_enabled = block.get("rate_change_enabled", False)
+    if not isinstance(rate_change_enabled, bool):
+        raise _AlertsConfigError(
+            f"alerts.rate_change_enabled must be a JSON boolean, got "
+            f"{type(rate_change_enabled).__name__}: {rate_change_enabled!r}",
+            field="alerts.rate_change_enabled",
+        )
     # Dispatch-global keys (Phase B). `notifier` selects the backend;
     # `command_template` is an argv list for the `command` backend (and may be
     # set ahead of switching the backend). The cross-field constraint
@@ -1109,6 +1136,7 @@ def _get_alerts_config(cfg: "dict | None") -> dict:
         "weekly_thresholds": weekly,
         "five_hour_thresholds": five_hour,
         "projected_enabled": projected_enabled,
+        "rate_change_enabled": rate_change_enabled,
         "notifier": notifier,
         "command_template": command_template,
     }
@@ -1637,6 +1665,39 @@ def _apply_quota_projection_schema(conn: sqlite3.Connection) -> None:
             PRIMARY KEY(source)
         );
 
+        -- #661 S2 §6: a provider metering-rate transition, recorded from the
+        -- first upgrade whether or not notification is enabled (§6.2). The
+        -- row is the durable forward-only latch: its presence is what stops
+        -- the same transition alerting twice, and it survives a stats.db
+        -- rebuild because the journal event that created it carries a
+        -- self-sufficient payload (§6.5).
+        --
+        -- The identity is `(provider, account_key, effective_from)` and the
+        -- promise is stated at exactly that precision — once per exact key,
+        -- not "once per provider regime". `reduce_state` closes and
+        -- re-creates regimes on a fingerprint change and a revised detector
+        -- can select a different `effective_from` for the same underlying
+        -- transition; separately, R8 can turn a formerly merged identity into
+        -- a real account key. Both produce a new key for a transition a human
+        -- would call the same one. The FINGERPRINT stays out of the key
+        -- deliberately: including it would re-alert on our own algorithm
+        -- revisions.
+        CREATE TABLE IF NOT EXISTS meter_rate_change_events (
+            id                       INTEGER PRIMARY KEY AUTOINCREMENT,
+            provider                 TEXT    NOT NULL,
+            account_key              TEXT    NOT NULL DEFAULT 'unattributed',
+            effective_from           TEXT    NOT NULL,
+            previous_units_per_point REAL    NOT NULL,
+            new_units_per_point      REAL    NOT NULL,
+            severity                 TEXT    NOT NULL,
+            detected_at_utc          TEXT    NOT NULL,
+            created_at_utc           TEXT    NOT NULL,
+            notified_at              TEXT,
+            UNIQUE(provider, account_key, effective_from)
+        );
+        CREATE INDEX IF NOT EXISTS idx_meter_rate_change_events_key
+            ON meter_rate_change_events(provider, account_key, effective_from);
+
         CREATE TABLE IF NOT EXISTS quota_alert_arming (
             id                INTEGER PRIMARY KEY AUTOINCREMENT,
             source            TEXT NOT NULL,

package/bin/_cctally_dashboard.py

@@ -581,6 +581,7 @@ from _cctally_dashboard_envelope import (
     _envelope_rows_project_budget,
     _ENVELOPE_AXIS_MAPPERS,
     _build_alerts_envelope_array,
+    _build_meter_rate_change_array,
     _model_breakdowns_to_models,
 )
 
@@ -8282,6 +8283,16 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     merged_alerts["projected_enabled"] = (
                         alerts_in["projected_enabled"]
                     )
+                # #661 S2 section 6.2's PUSH gate. Assigned VERBATIM, like
+                # every sibling here: the boolean rule lives in
+                # `_get_alerts_config`, which runs against the merged block
+                # below, so a `bool()` here would coerce "yes" to True and
+                # destroy the evidence before the canonical validator could
+                # refuse it.
+                if "rate_change_enabled" in alerts_in:
+                    merged_alerts["rate_change_enabled"] = (
+                        alerts_in["rate_change_enabled"]
+                    )
                 if "notifier" in alerts_in:
                     merged_alerts["notifier"] = alerts_in["notifier"]
                 merged["alerts"] = merged_alerts