cctally 1.102.0 → 1.104.0

package/README.md

@@ -34,9 +34,9 @@ Your Claude Code plan meters you with a percentage that creeps up all week. ccta
 
 Highlights from the `v1.95.5` to `v1.101.0` stable upgrade:
 
-- Dashboard refreshes now release their coherent `cache.db` snapshot before constructing provider views, cutting the measured median read hold from 3.40 seconds to 1.04 seconds while preserving the exact published payload (#617).
-- Every dashboard warning state now offers the explanation for its own window. A row in Recent alerts, an alert toast, a warn or over budget block, and a capped forecast each carry a button that opens the surface explaining that warning: a weekly crossing opens the current week, a five-hour crossing opens that block, a calendar-month budget opens that month, a project-budget crossing opens that project's drill-down, and a projected-pace crossing opens the forecast. The window is checked before anything opens, a warning about a week the dashboard is no longer showing states that its window has closed and opens nothing at all, rather than quietly showing you the current week instead. A five-hour block still opens however old it is, as long as the alert recorded which block it was; an alert that recorded no block start says so and opens nothing. On Codex the button says `Open this cycle` rather than `Open this week`, because a Codex quota cycle is what it opens. A project-budget crossing on a machine with more than one account is recorded across all of them, so it states that it cannot be narrowed to one account's projects rather than picking one. Every button is an ordinary control reachable by Tab and activated by Enter or Space, and no keyboard shortcut is claimed (#620).
-- The dashboard's Projects table now writes out what its two percentages mean, under the week selector rather than only in a tooltip, a tooltip never appears on a phone. The `Used pp` column is relabelled `Used pp (sum)` and the caption states that it adds each week's attributed usage percentage across the selected window, so it is a sum of percentage points rather than a share of any one week; the caption also names the denominator of the `Cost share` column as total project spend in that same window. No column is added or removed. On an installation with more than one Claude account, both the Projects panel and the Projects table now also state that accounts are folded into one ranking and that their weekly quota percentages are never added together. That sentence appears on the Claude and All views only, because the Codex view ranks Codex projects and folds no Claude accounts at all (#620).
+- Dashboard refreshes release their read lock on `cache.db` sooner, cutting the measured median hold from 3.40 seconds to 1.04. The published data is unchanged.
+- Every dashboard warning carries a button that opens the surface explaining it, the week, the five-hour block, the month, the project, or the forecast. A warning whose window has closed says so and opens nothing.
+- The dashboard's Projects table writes out what its two percentages mean under the week selector, where a phone can read it. `Used pp` is relabelled `Used pp (sum)`, and the caption names the denominator of `Cost share`.
 
 [See every change in this stable upgrade](https://github.com/omrikais/cctally/releases/tag/v1.101.0)
 <!-- cctally:latest-stable:end -->

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_cache.py

@@ -7327,6 +7327,20 @@ def sync_codex_cache(
                 model=initial_model,
                 total_tokens=initial_total_tokens,
             )
+            if start_offset > 0 and not truncated and not requalified:
+                prior_accounting = conn.execute(
+                    "SELECT MAX(timestamp_utc),MAX(line_offset) "
+                    "FROM codex_session_entries "
+                    "WHERE source_path=? AND line_offset<? ",
+                    (path_str, start_offset),
+                ).fetchone()
+                if prior_accounting is not None and prior_accounting[0] is not None:
+                    iter_state.last_accounting_timestamp = _parse_anchor_iso(
+                        prior_accounting[0])
+                if prior_accounting is not None and prior_accounting[1] is not None:
+                    iter_state.generation_transition_pending = (
+                        _lib_jsonl._codex_generation_transition_between(
+                            path_str, int(prior_accounting[1]), start_offset))
             if (
                 prev is not None and not truncated and not requalified
                 and prev_native_thread_id is not None
@@ -11223,6 +11237,23 @@ def sync_codex_conversations(
                 model=initial_model,
                 total_tokens=initial_total_tokens,
             )
+            if start_offset > 0 and not reset_file:
+                try:
+                    prior_accounting = conn.execute(
+                        "SELECT MAX(timestamp_utc),MAX(line_offset) FROM "
+                        "cache_db.codex_session_entries "
+                        "WHERE source_path=? AND line_offset<? ",
+                        (path_str, start_offset),
+                    ).fetchone()
+                except sqlite3.OperationalError:
+                    prior_accounting = None
+                if prior_accounting is not None and prior_accounting[0] is not None:
+                    state.last_accounting_timestamp = _parse_anchor_iso(
+                        prior_accounting[0])
+                if prior_accounting is not None and prior_accounting[1] is not None:
+                    state.generation_transition_pending = (
+                        _lib_jsonl._codex_generation_transition_between(
+                            path_str, int(prior_accounting[1]), start_offset))
             if initial_native and initial_root:
                 state.thread = _lib_jsonl.CodexThreadMetadata(
                     source_root_key=discovered.source_root_key,

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