cctally 1.68.0 → 1.69.0

package/bin/_cctally_config.py

@@ -75,6 +75,8 @@ from _cctally_core import (
     _AlertsConfigError,
     _get_budget_config,
     _BudgetConfigError,
+    _validate_codex_budget_block,
+    CODEX_BUDGET_LEAVES,
 )
 from _lib_display_tz import normalize_display_tz_value
 
@@ -300,6 +302,7 @@ ALLOWED_CONFIG_KEYS = (
     "alerts.projected_enabled",
     "alerts.notifier",
     "alerts.command_template",
+    "alerts.quota",
     "dashboard.bind",
     "dashboard.expose_transcripts",
     "dashboard.cache_failure_markers",
@@ -318,10 +321,236 @@ ALLOWED_CONFIG_KEYS = (
     "budget.projects",
     "budget.project_alerts_enabled",
     "budget.codex",
+    "budget.codex.amount_usd",
+    "budget.codex.period",
+    "budget.codex.alerts_enabled",
+    "budget.codex.alert_thresholds",
+    "budget.codex.projected_enabled",
     "telemetry.enabled",
 )
 
 
+_CODEX_BUDGET_LEAF_PREFIX = "budget.codex."
+
+
+def _config_codex_leaf_value(config: dict, key: str) -> object:
+    """Read one nested Codex budget leaf with its public default.
+
+    ``config get`` is deliberately forgiving of a hand-edited corrupt block,
+    just like the existing whole-object ``budget.codex`` read: it reports the
+    defaults without repairing the file. Mutations use the strict setter below.
+    """
+    if not key.startswith(_CODEX_BUDGET_LEAF_PREFIX):
+        raise ValueError(f"not a Codex budget leaf: {key!r}")
+    leaf = key.removeprefix(_CODEX_BUDGET_LEAF_PREFIX)
+    if leaf not in CODEX_BUDGET_LEAVES:
+        raise ValueError(f"unknown Codex budget leaf: {key!r}")
+    try:
+        block = _get_budget_config(config)["codex"]
+    except _BudgetConfigError:
+        block = None
+    if block is None:
+        defaults = {
+            "amount_usd": None,
+            "period": "calendar-month",
+            "alerts_enabled": False,
+            "alert_thresholds": [90, 100],
+            "projected_enabled": False,
+        }
+        value = defaults[leaf]
+    else:
+        value = block[leaf]
+    return list(value) if isinstance(value, list) else value
+
+
+def _parse_codex_budget_leaf_value(leaf: str, raw_value: str) -> object:
+    """Parse exactly the command-line wire format for one Codex leaf."""
+    if leaf == "amount_usd":
+        try:
+            return float(raw_value)
+        except ValueError as exc:
+            raise _BudgetConfigError(
+                "budget.codex.amount_usd must be a finite number > 0"
+            ) from exc
+    if leaf == "period":
+        return raw_value.strip()
+    if leaf in {"alerts_enabled", "projected_enabled"}:
+        normalized = raw_value.strip().lower()
+        if normalized in {"true", "yes", "on", "1"}:
+            return True
+        if normalized in {"false", "no", "off", "0"}:
+            return False
+        raise _BudgetConfigError(f"budget.codex.{leaf} must be a boolean")
+    if leaf == "alert_thresholds":
+        if not raw_value.strip():
+            return []
+        parsed: list[int] = []
+        for part in raw_value.split(","):
+            try:
+                parsed.append(int(part.strip(), 10))
+            except ValueError as exc:
+                raise _BudgetConfigError(
+                    "budget.codex.alert_thresholds must be a comma-separated "
+                    "list of integers"
+                ) from exc
+        return parsed
+    raise _BudgetConfigError(f"unknown Codex budget leaf {leaf!r}")
+
+
+def _set_codex_budget_leaf(config: dict, key: str, raw_value: str) -> dict:
+    """Return the canonical prospective nested Codex budget block.
+
+    The caller owns the writer lock and persistence. This pure merge helper
+    validates existing state before mutating it, so malformed user state never
+    becomes a partially repaired write.
+    """
+    if not key.startswith(_CODEX_BUDGET_LEAF_PREFIX):
+        raise _BudgetConfigError(f"unknown Codex budget leaf {key!r}")
+    leaf = key.removeprefix(_CODEX_BUDGET_LEAF_PREFIX)
+    if leaf not in CODEX_BUDGET_LEAVES:
+        raise _BudgetConfigError(f"unknown Codex budget leaf {key!r}")
+    budget = config.get("budget")
+    if budget is not None and not isinstance(budget, dict):
+        raise _BudgetConfigError("budget must be an object")
+    existing = (budget or {}).get("codex")
+    if existing is None:
+        if leaf != "amount_usd":
+            raise _BudgetConfigError(
+                "budget.codex.amount_usd must be configured before setting "
+                f"budget.codex.{leaf}"
+            )
+        prospective: dict = {}
+    else:
+        if not isinstance(existing, dict):
+            raise _BudgetConfigError(
+                f"budget.codex must be an object or null, got {type(existing).__name__}"
+            )
+        # Strictly validate first: malformed existing data must abort without
+        # mutation, while valid unknown siblings retain the validator's
+        # existing warn-and-drop behavior when the prospective block is built.
+        validated_existing = _validate_codex_budget_block(existing)
+        assert validated_existing is not None
+        prospective = dict(validated_existing)
+    prospective[leaf] = _parse_codex_budget_leaf_value(leaf, raw_value)
+    validated = _validate_codex_budget_block(prospective)
+    assert validated is not None
+    return validated
+
+
+# ``alerts.quota`` is an additive nested object owned by the provider-neutral
+# quota projection. Keep the existing core alert reader byte-compatible for
+# Claude axes while making this now-known child exempt from its unknown-key
+# warning path.
+_cctally_core._ALERTS_CONFIG_VALID_KEYS.add("quota")
+
+_QUOTA_ALERT_KEYS = {
+    "enabled", "actual_thresholds", "projected_thresholds", "rules",
+}
+_QUOTA_RULE_KEYS = {
+    "source", "source_root_key", "logical_limit_key",
+    "actual_thresholds", "projected_thresholds",
+}
+
+
+def _quota_alert_error(message: str) -> None:
+    raise _cctally_core._AlertsConfigError(message)
+
+
+def _validate_quota_thresholds(name: str, value: object) -> list[int]:
+    """Validate a quota list; unlike legacy axis lists, [] deliberately silences."""
+    if not isinstance(value, list):
+        _quota_alert_error(f"alerts.quota.{name} must be a list of integers")
+    result: list[int] = []
+    prior = 0
+    for item in value:
+        if not isinstance(item, int) or isinstance(item, bool):
+            _quota_alert_error(
+                f"alerts.quota.{name} items must be integers, got "
+                f"{type(item).__name__}: {item!r}"
+            )
+        if not 1 <= item <= 100:
+            _quota_alert_error(
+                f"alerts.quota.{name} items must be in [1, 100], got {item}"
+            )
+        if item <= prior:
+            _quota_alert_error(f"alerts.quota.{name} must be strictly increasing")
+        result.append(item)
+        prior = item
+    return result
+
+
+def _get_quota_alerts_config(cfg: "dict | None") -> dict:
+    """Return the strict, defaults-filled ``alerts.quota`` configuration."""
+    alerts = (cfg or {}).get("alerts", {})
+    if alerts is None:
+        alerts = {}
+    if not isinstance(alerts, dict):
+        _quota_alert_error("alerts must be an object")
+    quota = alerts.get("quota", {})
+    if quota is None or not isinstance(quota, dict):
+        _quota_alert_error("alerts.quota must be an object")
+    for key in quota:
+        if key not in _QUOTA_ALERT_KEYS:
+            print(
+                f"warning: ignoring unknown alerts.quota config key: {key}",
+                file=sys.stderr,
+            )
+    enabled = quota.get("enabled", False)
+    if not isinstance(enabled, bool):
+        _quota_alert_error(
+            "alerts.quota.enabled must be a JSON boolean, got "
+            f"{type(enabled).__name__}: {enabled!r}"
+        )
+    actual = _validate_quota_thresholds(
+        "actual_thresholds", quota.get("actual_thresholds", [90, 95])
+    )
+    projected = _validate_quota_thresholds(
+        "projected_thresholds", quota.get("projected_thresholds", [])
+    )
+    raw_rules = quota.get("rules", [])
+    if not isinstance(raw_rules, list):
+        _quota_alert_error("alerts.quota.rules must be a list")
+    rules: list[dict] = []
+    seen: set[tuple[str, str, str]] = set()
+    for index, raw_rule in enumerate(raw_rules):
+        prefix = f"alerts.quota.rules[{index}]"
+        if not isinstance(raw_rule, dict):
+            _quota_alert_error(f"{prefix} must be an object")
+        if set(raw_rule) != _QUOTA_RULE_KEYS:
+            _quota_alert_error(
+                f"{prefix} must contain exactly {sorted(_QUOTA_RULE_KEYS)}"
+            )
+        normalized: dict[str, object] = {}
+        for key in ("source", "source_root_key", "logical_limit_key"):
+            value = raw_rule[key]
+            if not isinstance(value, str) or not value:
+                _quota_alert_error(f"{prefix}.{key} must be a non-empty string")
+            normalized[key] = value
+        normalized["actual_thresholds"] = _validate_quota_thresholds(
+            f"rules[{index}].actual_thresholds", raw_rule["actual_thresholds"]
+        )
+        normalized["projected_thresholds"] = _validate_quota_thresholds(
+            f"rules[{index}].projected_thresholds", raw_rule["projected_thresholds"]
+        )
+        identity = (
+            str(normalized["source"]), str(normalized["source_root_key"]),
+            str(normalized["logical_limit_key"]),
+        )
+        if identity in seen:
+            _quota_alert_error(
+                "alerts.quota.rules must be unique by source, source_root_key, "
+                "and logical_limit_key"
+            )
+        seen.add(identity)
+        rules.append(normalized)
+    return {
+        "enabled": enabled,
+        "actual_thresholds": actual,
+        "projected_thresholds": projected,
+        "rules": rules,
+    }
+
+
 # === statusline config validators (issue #86 Session G) ===================
 
 _STATUSLINE_VBR_VALUES = ("off", "emoji", "text", "emoji-text")
@@ -459,6 +688,11 @@ def _config_known_value(config: dict, key: str) -> "object":
             return _get_alerts_config(config)["command_template"]
         except c._AlertsConfigError:
             return None
+    if key == "alerts.quota":
+        try:
+            return _get_quota_alerts_config(config)
+        except c._AlertsConfigError:
+            return _get_quota_alerts_config({})
     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`
@@ -580,6 +814,8 @@ def _config_known_value(config: dict, key: str) -> "object":
             return c._validate_update_check_ttl_hours_value(stored)
         except ValueError:
             return c.UPDATE_DEFAULT_TTL_HOURS
+    if key.startswith(_CODEX_BUDGET_LEAF_PREFIX):
+        return _config_codex_leaf_value(config, key)
     if key in (
         "statusline.visual_burn_rate",
         "statusline.cost_source",
@@ -649,7 +885,10 @@ def _cmd_config_get(args: argparse.Namespace, config: dict) -> int:
     # (including None) must survive into the render layer — the generic
     # None->"" coercion below would break the JSON shape / round-trip.
     def _coerce(k: str, v: "object") -> "object":
-        if k in ("alerts.command_template", "budget.projects", "budget.codex"):
+        if k in (
+            "alerts.command_template", "alerts.quota", "budget.projects",
+            "budget.codex",
+        ) or k.startswith(_CODEX_BUDGET_LEAF_PREFIX):
             return v
         return v if v is not None else ""
 
@@ -667,7 +906,19 @@ def _cmd_config_get(args: argparse.Namespace, config: dict) -> int:
         # a flat tail (`{"update": {"check.enabled": ...}}`) and
         # diverged from `config set --json` / on-disk shape.
         out: "dict[str, object]" = {}
+        nested_parents = {
+            candidate
+            for candidate, _value in pairs
+            if any(child.startswith(candidate + ".") for child, _value in pairs)
+        }
         for k, v in pairs:
+            # A bulk read includes both `budget.codex` (null when not
+            # configured) and its additive `budget.codex.*` leaves.  A scalar
+            # parent cannot coexist with those children in JSON, so let the
+            # specific leaves build their object.  Direct `config get
+            # budget.codex --json` has no descendant pair and remains null.
+            if k in nested_parents and not isinstance(v, dict):
+                continue
             segments = k.split(".")
             node: dict = out
             for seg in segments[:-1]:
@@ -679,7 +930,8 @@ def _cmd_config_get(args: argparse.Namespace, config: dict) -> int:
             # Preserve canonical bool stringification (true/false) so
             # round-trips via `config set alerts.enabled <plain-text>` work.
             if k in (
-                "alerts.command_template", "budget.projects", "budget.codex"
+                "alerts.command_template", "alerts.quota", "budget.projects",
+                "budget.codex",
             ):
                 # JSON-encoded so `config get` output round-trips through the
                 # matching `config set` branch (both JSON-parse their value).
@@ -687,6 +939,8 @@ def _cmd_config_get(args: argparse.Namespace, config: dict) -> int:
                 # `budget.projects` is an object {git-root: usd};
                 # `budget.codex` is an object|null (the no-budget sentinel).
                 rendered = json.dumps(v)
+            elif k.startswith(_CODEX_BUDGET_LEAF_PREFIX) and v is None:
+                rendered = "null"
             elif isinstance(v, bool):
                 rendered = "true" if v else "false"
             elif isinstance(v, list):
@@ -705,6 +959,36 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
     if key not in ALLOWED_CONFIG_KEYS:
         eprint(f"cctally config: unknown config key {key!r}")
         return 2
+    if key.startswith(_CODEX_BUDGET_LEAF_PREFIX):
+        try:
+            with config_writer_lock():
+                config = _load_config_unlocked()
+                configured = _set_codex_budget_leaf(config, key, raw)
+                budget = config.get("budget")
+                if budget is not None and not isinstance(budget, dict):
+                    raise _BudgetConfigError("budget must be an object")
+                block = dict(budget or {})
+                block["codex"] = configured
+                config["budget"] = block
+                save_config(config)
+        except _BudgetConfigError as exc:
+            eprint(f"cctally config: {exc}")
+            return 2
+        # Deliberately outside the config lock: this helper opens and locks DBs.
+        c._reconcile_codex_budget_on_config_write({"codex": configured})
+        leaf = key.removeprefix(_CODEX_BUDGET_LEAF_PREFIX)
+        value = configured[leaf]
+        if getattr(args, "emit_json", False):
+            print(json.dumps({"budget": {"codex": {leaf: value}}}, indent=2))
+        else:
+            if isinstance(value, bool):
+                rendered = "true" if value else "false"
+            elif isinstance(value, list):
+                rendered = ",".join(str(item) for item in value)
+            else:
+                rendered = str(value)
+            print(f"{key}={rendered}")
+        return 0
     if key == "display.tz":
         try:
             canonical = normalize_display_tz_value(raw)
@@ -878,6 +1162,44 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         else:
             print(f"alerts.command_template={json.dumps(parsed)}")
         return 0
+    if key == "alerts.quota":
+        try:
+            parsed = json.loads(raw)
+        except (ValueError, TypeError) as exc:
+            print(
+                f"cctally: alerts.quota must be a JSON object: {exc}",
+                file=sys.stderr,
+            )
+            return 2
+        if not isinstance(parsed, dict):
+            print("cctally: alerts.quota must be a JSON object", 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["quota"] = parsed
+            candidate = {**config, "alerts": alerts_block}
+            try:
+                _get_alerts_config(candidate)
+                normalized = _get_quota_alerts_config(candidate)
+            except _AlertsConfigError as exc:
+                print(f"cctally: alerts config error: {exc}", file=sys.stderr)
+                return 2
+            alerts_block["quota"] = normalized
+            config["alerts"] = alerts_block
+            save_config(config)
+        if getattr(args, "emit_json", False):
+            print(json.dumps({"alerts": {"quota": normalized}}, indent=2))
+        else:
+            print(f"alerts.quota={json.dumps(normalized)}")
+        return 0
     if key == "dashboard.bind":
         # Validation rejects whitespace / empty / non-string up front;
         # write proceeds under config_writer_lock with _load_config_unlocked
@@ -1350,6 +1672,49 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
     if key not in ALLOWED_CONFIG_KEYS:
         eprint(f"cctally config: unknown config key {key!r}")
         return 2
+    if key.startswith(_CODEX_BUDGET_LEAF_PREFIX):
+        c = _cctally()
+        configured: dict | None = None
+        try:
+            with config_writer_lock():
+                config = _load_config_unlocked()
+                budget = config.get("budget")
+                if budget is not None and not isinstance(budget, dict):
+                    raise _BudgetConfigError("budget must be an object")
+                existing = (budget or {}).get("codex")
+                if existing is None:
+                    return 0
+                if not isinstance(existing, dict):
+                    raise _BudgetConfigError(
+                        f"budget.codex must be an object or null, got {type(existing).__name__}"
+                    )
+                validated_existing = _validate_codex_budget_block(existing)
+                assert validated_existing is not None
+                leaf = key.removeprefix(_CODEX_BUDGET_LEAF_PREFIX)
+                block = dict(budget or {})
+                if leaf == "amount_usd":
+                    block.pop("codex", None)
+                    if block:
+                        config["budget"] = block
+                    else:
+                        config.pop("budget", None)
+                    save_config(config)
+                    return 0
+                prospective = dict(validated_existing)
+                prospective.pop(leaf, None)
+                configured = _validate_codex_budget_block(prospective)
+                assert configured is not None
+                block["codex"] = configured
+                config["budget"] = block
+                save_config(config)
+        except _BudgetConfigError as exc:
+            eprint(f"cctally config: {exc}")
+            return 2
+        # An optional leaf leaves a configured block, even when it already
+        # held its default; the forward-only state must be reconciled once.
+        assert configured is not None
+        c._reconcile_codex_budget_on_config_write({"codex": configured})
+        return 0
     if key == "display.tz":
         with config_writer_lock():
             config = _load_config_unlocked()
@@ -1366,6 +1731,7 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
         "alerts.projected_enabled",
         "alerts.notifier",
         "alerts.command_template",
+        "alerts.quota",
     ):
         # Mirror the display.tz branch: writer-lock + _load_config_unlocked
         # (NOT load_config — fcntl.flock is per-fd so re-entry would

package/bin/_cctally_core.py

@@ -65,6 +65,8 @@ def _init_paths_from_env() -> None:
     global CONFIG_PATH, MIGRATION_ERROR_LOG_PATH, CHANGELOG_PATH
     global HOOK_TICK_LOG_DIR, HOOK_TICK_LOG_PATH, HOOK_TICK_LOG_ROTATED_PATH
     global HOOK_TICK_THROTTLE_PATH, HOOK_TICK_THROTTLE_LOCK_PATH
+    global STATUSLINE_OBSERVE_MARKER_PATH, STATUSLINE_PERSIST_LOCK_PATH
+    global OAUTH_BACKOFF_MARKER_PATH, OAUTH_BACKOFF_COUNT_PATH
     global UPDATE_STATE_PATH, UPDATE_SUPPRESS_PATH
     global UPDATE_LOCK_PATH, UPDATE_LOG_PATH, UPDATE_LOG_ROTATED_PATH
     global UPDATE_CHECK_LAST_FETCH_PATH, CLAUDE_SETTINGS_PATH
@@ -119,6 +121,31 @@ def _init_paths_from_env() -> None:
     HOOK_TICK_THROTTLE_PATH = APP_DIR / "hook-tick.last-fetch"
     HOOK_TICK_THROTTLE_LOCK_PATH = APP_DIR / "hook-tick.last-fetch.lock"
 
+    # Statusline usage-persistence markers + lock (spec 2026-07-17
+    # usage-statusline-fallback). The statusline is the PRIMARY automatic
+    # writer of weekly/5h usage snapshots; these gate it.
+    #   - STATUSLINE_OBSERVE_MARKER_PATH: liveness marker (mtime-based,
+    #     like HOOK_TICK_THROTTLE_PATH) — touched after every statusline
+    #     persist that fed valid 7d input through cmd_record_usage, INCLUDING
+    #     a dedup no-op. Represents "the statusline is alive and feeding".
+    #     The statusline persist throttle AND the OAuth backfill gate both
+    #     key off this, NOT snapshot age (cmd_record_usage dedups unchanged
+    #     percentages without refreshing captured_at, so snapshot age keeps
+    #     growing while the statusline is actively feeding).
+    #   - STATUSLINE_PERSIST_LOCK_PATH: cross-process flock serializing the
+    #     detached persist feeder so a multi-session render herd yields at
+    #     most one snapshot per throttle window.
+    #   - OAUTH_BACKOFF_MARKER_PATH: shared 429 cooldown. Stores an ABSOLUTE
+    #     epoch deadline in the file CONTENT (never the mtime — future-dating
+    #     an mtime would corrupt HOOK_TICK_THROTTLE_PATH's age reading).
+    STATUSLINE_OBSERVE_MARKER_PATH = APP_DIR / "statusline-observe.last"
+    STATUSLINE_PERSIST_LOCK_PATH = APP_DIR / "statusline-persist.lock"
+    OAUTH_BACKOFF_MARKER_PATH = APP_DIR / "oauth-backoff.until"
+    # Consecutive-429 counter (text int) driving the headerless exponential
+    # backoff (base * 2**count). Separate from the deadline marker so the
+    # deadline file stays a single parseable float.
+    OAUTH_BACKOFF_COUNT_PATH = APP_DIR / "oauth-backoff.count"
+
     UPDATE_STATE_PATH = APP_DIR / "update-state.json"
     UPDATE_SUPPRESS_PATH = APP_DIR / "update-suppress.json"
     UPDATE_LOCK_PATH = APP_DIR / "update.lock"
@@ -210,6 +237,24 @@ def _real_prod_data_dir() -> pathlib.Path:
     return home / ".local" / "share" / "cctally"
 
 
+# === Statusline-persist / OAuth-backfill tunables ==========================
+# Internal (no config UI — YAGNI, spec §Out of scope); test injection only.
+# Spec 2026-07-17-usage-statusline-fallback-design.
+#
+# STATUSLINE_PERSIST_THROTTLE_SECONDS: min seconds between statusline
+#   persist attempts (keyed off STATUSLINE_OBSERVE_MARKER_PATH liveness).
+# OAUTH_BACKFILL_STALE_SECONDS: the OAuth poll only backfills once the
+#   observation marker is at least this stale (i.e. the statusline has
+#   NOT fed recently). Strictly greater than the persist throttle so the
+#   statusline is the primary writer and OAuth only covers its absence.
+# OAUTH_BACKOFF_BASE_SECONDS / OAUTH_BACKOFF_CAP_SECONDS: the headerless
+#   exponential 429 backoff (base * 2**consecutive_429, capped).
+STATUSLINE_PERSIST_THROTTLE_SECONDS = 60.0
+OAUTH_BACKFILL_STALE_SECONDS = 300.0
+OAUTH_BACKOFF_BASE_SECONDS = 60.0
+OAUTH_BACKOFF_CAP_SECONDS = 3600.0
+
+
 _init_paths_from_env()
 
 
@@ -681,6 +726,10 @@ def _validate_positive_budget_amount(v: object, label: str) -> float:
 # are reused by the parser (`--period` choices) and the config layer.
 BUDGET_PERIODS = ("subscription-week", "calendar-week", "calendar-month")
 CODEX_BUDGET_PERIODS = ("calendar-week", "calendar-month")
+CODEX_BUDGET_LEAVES = (
+    "amount_usd", "period", "alerts_enabled", "alert_thresholds",
+    "projected_enabled",
+)
 _BUDGET_DEFAULTS = {
     "weekly_usd": None,            # None = no budget (default)
     "alerts_enabled": True,        # "on when set"
@@ -843,12 +892,8 @@ def _validate_codex_budget_block(v: object) -> "dict | None":
             f"budget.codex must be an object or null, got {type(v).__name__}"
         )
     # warn-and-ignore unknown sub-keys (forward compat, like the parent block)
-    _codex_valid = {
-        "amount_usd", "period", "alerts_enabled", "alert_thresholds",
-        "projected_enabled",
-    }
     for k in v.keys():
-        if k not in _codex_valid:
+        if k not in CODEX_BUDGET_LEAVES:
             print(
                 f"warning: ignoring unknown budget.codex config key: {k}",
                 file=sys.stderr,
@@ -914,6 +959,118 @@ def _budget_alerts_active(budget_cfg: dict) -> bool:
 # === DB primitive ===================================================
 
 
+def _apply_quota_projection_schema(conn: sqlite3.Connection) -> None:
+    """Create the current durable provider-neutral quota projection schema.
+
+    The physical observations remain in cache.db.  These tables are the
+    idempotent interpreted index consumed by the Codex quota adapter; migration
+    013 calls this same helper for old databases while ``open_db`` calls it for
+    fresh installs before the migration dispatcher stamps the migration.
+    """
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS quota_window_blocks (
+            id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+            source                TEXT    NOT NULL,
+            source_root_key       TEXT    NOT NULL,
+            logical_limit_key     TEXT    NOT NULL,
+            observed_slot         TEXT    NOT NULL,
+            window_minutes        INTEGER NOT NULL CHECK(window_minutes > 0),
+            limit_id              TEXT,
+            limit_name            TEXT,
+            resets_at_utc         TEXT    NOT NULL,
+            nominal_start_at_utc  TEXT    NOT NULL,
+            first_observed_at_utc TEXT    NOT NULL,
+            last_observed_at_utc  TEXT    NOT NULL,
+            first_percent         REAL    NOT NULL,
+            current_percent       REAL    NOT NULL,
+            last_source_path      TEXT    NOT NULL,
+            last_line_offset      INTEGER NOT NULL,
+            generation            TEXT    NOT NULL,
+            orphaned_at           TEXT,
+            UNIQUE(source, source_root_key, logical_limit_key, observed_slot,
+                   window_minutes, resets_at_utc)
+        );
+        CREATE INDEX IF NOT EXISTS idx_quota_blocks_active
+            ON quota_window_blocks(source, source_root_key, orphaned_at,
+                                   logical_limit_key, observed_slot,
+                                   window_minutes, resets_at_utc);
+
+        CREATE TABLE IF NOT EXISTS quota_percent_milestones (
+            id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+            source                TEXT    NOT NULL,
+            source_root_key       TEXT    NOT NULL,
+            logical_limit_key     TEXT    NOT NULL,
+            observed_slot         TEXT    NOT NULL,
+            window_minutes        INTEGER NOT NULL CHECK(window_minutes > 0),
+            resets_at_utc         TEXT    NOT NULL,
+            percent_threshold     INTEGER NOT NULL CHECK(percent_threshold BETWEEN 1 AND 100),
+            captured_at_utc       TEXT    NOT NULL,
+            source_path           TEXT    NOT NULL,
+            line_offset           INTEGER NOT NULL,
+            high_water_percent    INTEGER NOT NULL CHECK(high_water_percent BETWEEN 1 AND 100),
+            generation            TEXT    NOT NULL,
+            orphaned_at           TEXT,
+            UNIQUE(source, source_root_key, logical_limit_key, observed_slot,
+                   window_minutes, resets_at_utc, percent_threshold)
+        );
+        CREATE INDEX IF NOT EXISTS idx_quota_milestones_active
+            ON quota_percent_milestones(source, source_root_key, orphaned_at,
+                                        logical_limit_key, observed_slot,
+                                        window_minutes, resets_at_utc,
+                                        percent_threshold);
+
+        CREATE TABLE IF NOT EXISTS quota_threshold_events (
+            id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+            source                TEXT    NOT NULL,
+            source_root_key       TEXT    NOT NULL,
+            logical_limit_key     TEXT    NOT NULL,
+            observed_slot         TEXT    NOT NULL,
+            window_minutes        INTEGER NOT NULL CHECK(window_minutes > 0),
+            resets_at_utc         TEXT    NOT NULL,
+            threshold             INTEGER NOT NULL CHECK(threshold BETWEEN 1 AND 100),
+            qualifying_kind       TEXT    NOT NULL CHECK(qualifying_kind IN ('actual','projected')),
+            qualifying_percent    REAL,
+            projected_percent     REAL,
+            severity              TEXT    NOT NULL,
+            created_at_utc        TEXT    NOT NULL,
+            disposition           TEXT    NOT NULL CHECK(disposition IN ('alerted','suppressed_backfill')),
+            alerted_at             TEXT,
+            suppressed_at          TEXT,
+            orphaned_at            TEXT,
+            CHECK((disposition = 'alerted' AND alerted_at IS NOT NULL AND suppressed_at IS NULL)
+               OR (disposition = 'suppressed_backfill' AND suppressed_at IS NOT NULL AND alerted_at IS NULL)),
+            UNIQUE(source, source_root_key, logical_limit_key, observed_slot,
+                   window_minutes, resets_at_utc, threshold)
+        );
+        CREATE INDEX IF NOT EXISTS idx_quota_threshold_events_active
+            ON quota_threshold_events(source, source_root_key, orphaned_at,
+                                      logical_limit_key, observed_slot,
+                                      window_minutes, resets_at_utc, threshold);
+
+        CREATE TABLE IF NOT EXISTS quota_projection_state (
+            source_root_key    TEXT PRIMARY KEY,
+            generation         TEXT NOT NULL,
+            physical_signature TEXT NOT NULL,
+            completed_at_utc   TEXT NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS quota_alert_arming (
+            id                INTEGER PRIMARY KEY AUTOINCREMENT,
+            source            TEXT NOT NULL,
+            source_root_key   TEXT NOT NULL,
+            logical_limit_key TEXT NOT NULL,
+            observed_slot     TEXT NOT NULL,
+            window_minutes    INTEGER NOT NULL CHECK(window_minutes > 0),
+            rule_fingerprint  TEXT NOT NULL,
+            activated_at_utc  TEXT NOT NULL,
+            UNIQUE(source, source_root_key, logical_limit_key, observed_slot,
+                   window_minutes)
+        );
+        """
+    )
+
+
 def open_db() -> sqlite3.Connection:
     c = _cctally()
     # Spec §2.6 carve-out: open_db reaches the migration framework
@@ -1474,6 +1631,12 @@ def open_db() -> sqlite3.Connection:
         """
     )
 
+    # Stats migration 013 owns durable quota interpretation.  Keep the current
+    # schema in the fresh-install path before the dispatcher, exactly like the
+    # existing live CREATE tables; its handler calls this same idempotent helper
+    # for an older stats.db and the dispatcher central-stamps on clean return.
+    _apply_quota_projection_schema(conn)
+
     # 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