cctally 1.27.0 → 1.28.0

package/bin/_cctally_config.py

@@ -301,6 +301,7 @@ ALLOWED_CONFIG_KEYS = (
     "alerts.notifier",
     "alerts.command_template",
     "dashboard.bind",
+    "dashboard.expose_transcripts",
     "update.check.enabled",
     "update.check.ttl_hours",
     "statusline.visual_burn_rate",
@@ -310,8 +311,10 @@ ALLOWED_CONFIG_KEYS = (
     "budget.alerts_enabled",
     "budget.alert_thresholds",
     "budget.projected_enabled",
+    "budget.period",
     "budget.projects",
     "budget.project_alerts_enabled",
+    "budget.codex",
 )
 
 
@@ -449,6 +452,32 @@ def _config_known_value(config: dict, key: str) -> "object":
             # Hand-edited junk: surface the default rather than the bad value;
             # `cmd_dashboard` warns at server-start when it hits the same path.
             return "loopback"
+    if key == "dashboard.expose_transcripts":
+        # Boolean opt-in (Plan 2, spec §5). Default False — transcript
+        # endpoints are served only over loopback unless this is true (LAN
+        # exposure). A hand-edited junk value surfaces the default, mirroring
+        # dashboard.bind.
+        block = config.get("dashboard") if isinstance(config, dict) else None
+        if not isinstance(block, dict):
+            block = {}
+        stored = block.get("expose_transcripts")
+        if stored is None:
+            return False
+        # Config stores a JSON bool; the shared string-normalizer
+        # (_normalize_alerts_enabled_value) only tolerates str spellings,
+        # so short-circuit a real bool here rather than re-forking it.
+        if isinstance(stored, bool):
+            return stored
+        # Only str spellings are normalizable. Any other JSON scalar/container
+        # (int/float/list/dict) must surface the default — NOT crash: the shared
+        # normalizer does ``(raw or "").strip()``, which raises AttributeError
+        # (uncaught by ``except ValueError``) on e.g. a hand-edited bare ``1``.
+        if isinstance(stored, str):
+            try:
+                return c._normalize_alerts_enabled_value(stored)
+            except ValueError:
+                return False
+        return False
     if key in ("update.check.enabled", "update.check.ttl_hours"):
         # Defaults mirror `_is_update_check_due` (True / 24 hours).
         # Hand-edited junk surfaces as the default — matches dashboard.bind.
@@ -501,8 +530,10 @@ def _config_known_value(config: dict, key: str) -> "object":
         "budget.alerts_enabled",
         "budget.alert_thresholds",
         "budget.projected_enabled",
+        "budget.period",
         "budget.projects",
         "budget.project_alerts_enabled",
+        "budget.codex",
     ):
         inner = key.split(".", 1)[1]
         # Read the validated, defaults-filled block. A corrupt block falls
@@ -533,7 +564,7 @@ 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"):
+        if k in ("alerts.command_template", "budget.projects", "budget.codex"):
             return v
         return v if v is not None else ""
 
@@ -562,11 +593,14 @@ def _cmd_config_get(args: argparse.Namespace, config: dict) -> int:
         for k, v in pairs:
             # 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"):
+            if k in (
+                "alerts.command_template", "budget.projects", "budget.codex"
+            ):
                 # JSON-encoded so `config get` output round-trips through the
                 # matching `config set` branch (both JSON-parse their value).
                 # `alerts.command_template` is a list-of-strings|null;
-                # `budget.projects` is an object {git-root: usd}.
+                # `budget.projects` is an object {git-root: usd};
+                # `budget.codex` is an object|null (the no-budget sentinel).
                 rendered = json.dumps(v)
             elif isinstance(v, bool):
                 rendered = "true" if v else "false"
@@ -787,6 +821,49 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         else:
             print(f"dashboard.bind={canonical}")
         return 0
+    if key == "dashboard.expose_transcripts":
+        # Same read-modify-write posture as dashboard.bind: validate first,
+        # then write under config_writer_lock with _load_config_unlocked
+        # (calling load_config inside the writer-lock self-deadlocks per the
+        # CLAUDE.md gotcha — fcntl.flock is per-fd, not per-process). Preserves
+        # a sibling dashboard.bind in the same parent block.
+        # Reuse the shared bool-normalizer (DRY with alerts.enabled); it
+        # hardcodes "alerts.enabled" in its ValueError text, so catch +
+        # re-message with the actual key name (mirrors alerts.projected_enabled).
+        try:
+            canonical = c._normalize_alerts_enabled_value(raw)
+        except ValueError:
+            print(
+                f"cctally: invalid boolean value for dashboard.expose_transcripts: "
+                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 = config.get("dashboard")
+            if existing is not None and not isinstance(existing, dict):
+                print(
+                    "cctally: dashboard config error: dashboard must be an object",
+                    file=sys.stderr,
+                )
+                return 2
+            block = dict(existing or {})
+            block["expose_transcripts"] = canonical
+            config["dashboard"] = block
+            save_config(config)
+        if getattr(args, "emit_json", False):
+            print(
+                json.dumps(
+                    {"dashboard": {"expose_transcripts": canonical}}, indent=2
+                )
+            )
+        else:
+            print(
+                f"dashboard.expose_transcripts="
+                f"{'true' if canonical else 'false'}"
+            )
+        return 0
     if key in (
         "statusline.visual_burn_rate",
         "statusline.cost_source",
@@ -877,8 +954,10 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         "budget.alerts_enabled",
         "budget.alert_thresholds",
         "budget.projected_enabled",
+        "budget.period",
         "budget.projects",
         "budget.project_alerts_enabled",
+        "budget.codex",
     ):
         inner_key = key.split(".", 1)[1]
         # Parse + normalize the raw value per key BEFORE acquiring the lock so
@@ -912,6 +991,36 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                     f"got {raw!r}"
                 )
                 return 2
+        elif inner_key == "period":
+            # `budget.period` is a plain string leaf. The enum check lives in
+            # _get_budget_config under the lock below (so a bad value is a
+            # clean exit-2 with the canonical message); here we just pass the
+            # raw token through.
+            new_val = raw.strip()
+        elif inner_key == "codex":
+            # `budget.codex` is a nested object (or null = no Codex budget),
+            # which the plain leaves can't round-trip — JSON-parse it (mirrors
+            # the budget.projects branch). The shape/period/amount rules are
+            # enforced by _get_budget_config under the lock below; here we only
+            # reject non-JSON and coerce the null sentinel.
+            if raw.strip().lower() in {"null", "none"}:
+                new_val = None
+            else:
+                try:
+                    parsed_codex = json.loads(raw)
+                except (json.JSONDecodeError, ValueError):
+                    eprint(
+                        "cctally config: budget.codex must be a JSON object or "
+                        f"null, got {raw!r}"
+                    )
+                    return 2
+                if parsed_codex is not None and not isinstance(parsed_codex, dict):
+                    eprint(
+                        "cctally config: budget.codex must be a JSON object or "
+                        "null"
+                    )
+                    return 2
+                new_val = parsed_codex
         elif inner_key == "projects":
             # `budget.projects` is a dict {git-root: usd}, which the plain
             # number/bool/list leaves can't round-trip — JSON-parse it (mirrors
@@ -995,25 +1104,41 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         # on `budget.weekly_usd` — would latch a currently-over-but-not-yet-
         # dispatched threshold as already-alerted, permanently suppressing the
         # next record-usage tick's dispatch. The global axis feeds on
-        # weekly_usd/alerts_enabled/alert_thresholds; the per-project axis on
-        # projects/project_alerts_enabled/alert_thresholds (alert_thresholds is
-        # shared; projected_enabled belongs to neither reconcile). Both run
-        # OUTSIDE config_writer_lock (each helper has its own open_db lock).
-        if inner_key in ("weekly_usd", "alerts_enabled", "alert_thresholds"):
+        # weekly_usd/alerts_enabled/alert_thresholds/period; the per-project axis
+        # on projects/project_alerts_enabled/alert_thresholds (alert_thresholds
+        # is shared; projected_enabled belongs to neither reconcile). `period` is
+        # in the global set because changing it re-keys the milestone window
+        # (calendar period-start instant vs subscription-week); without the
+        # reconcile, switching period while already over a threshold would
+        # instant-popup on the next record-usage tick — the exact case the
+        # forward-only-from-set reconcile prevents (`budget set --period` already
+        # reconciles via the same helper). Both run OUTSIDE config_writer_lock
+        # (each helper has its own open_db lock).
+        if inner_key in (
+            "weekly_usd", "alerts_enabled", "alert_thresholds", "period"
+        ):
             c._reconcile_budget_on_config_write(validated)
         if inner_key in (
             "projects", "project_alerts_enabled", "alert_thresholds"
         ):
             c._reconcile_project_budget_milestones_on_write(validated)
+        # Codex budget axis (spec §6): the nested budget.codex block is set
+        # wholesale via `config set budget.codex '<json>'`, so the only key that
+        # touches it is `codex` itself. Gated on the codex block carrying
+        # alerts_enabled + thresholds (the helper re-checks); records nothing
+        # otherwise.
+        if inner_key == "codex":
+            c._reconcile_codex_budget_on_config_write(validated)
         out_val = validated[inner_key]
         if getattr(args, "emit_json", False):
             print(json.dumps({"budget": {inner_key: out_val}}, indent=2))
         else:
             if isinstance(out_val, bool):
                 rendered = "true" if out_val else "false"
-            elif inner_key == "projects":
-                # JSON so `config get budget.projects` round-trips back through
-                # this branch (str(dict) is not valid JSON).
+            elif inner_key in ("projects", "codex"):
+                # JSON so `config get budget.{projects,codex}` round-trips back
+                # through this branch (str(dict)/None is not valid JSON; the
+                # codex no-budget sentinel renders as `null`).
                 rendered = json.dumps(out_val)
             else:
                 rendered = str(out_val)
@@ -1096,6 +1221,21 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 save_config(config)
             # idempotent: silent on missing key
         return 0
+    if key == "dashboard.expose_transcripts":
+        # Mirror the dashboard.bind unset branch: drop only the
+        # expose_transcripts leaf; if the dashboard block ends up empty, drop
+        # the parent too so config.json stays tidy. A sibling dashboard.bind
+        # survives.
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            block = config.get("dashboard")
+            if isinstance(block, dict) and "expose_transcripts" in block:
+                del block["expose_transcripts"]
+                if not block:
+                    config.pop("dashboard", None)
+                save_config(config)
+            # idempotent: silent on missing key
+        return 0
     if key in (
         "statusline.visual_burn_rate",
         "statusline.cost_source",
@@ -1137,8 +1277,10 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
         "budget.alerts_enabled",
         "budget.alert_thresholds",
         "budget.projected_enabled",
+        "budget.period",
         "budget.projects",
         "budget.project_alerts_enabled",
+        "budget.codex",
     ):
         # 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

@@ -160,6 +160,24 @@ def _is_dev_checkout() -> bool:
     return (_repo_root() / ".git").exists()
 
 
+def _real_prod_data_dir() -> pathlib.Path:
+    """The REAL user's prod data dir (~/.local/share/cctally), resolved from
+    the password database rather than $HOME so it is immune to a faked HOME.
+
+    The prod-migration guard (bin/_cctally_db.py, issue #142) compares the
+    connection's DB directory against this to tell a fake-HOME test 'prod'
+    (e.g. a golden harness's /tmp/scratch/.local/share/cctally) apart from
+    the actual prod dir. Monkeypatchable seam: tests point it at a tmp dir to
+    exercise the guard's fire path without touching real prod. Falls back to
+    Path.home() only if `pwd` is unavailable (cctally targets Unix only)."""
+    try:
+        import pwd
+        home = pathlib.Path(pwd.getpwuid(os.getuid()).pw_dir)
+    except Exception:
+        home = pathlib.Path.home()
+    return home / ".local" / "share" / "cctally"
+
+
 _init_paths_from_env()
 
 
@@ -570,21 +588,49 @@ class _BudgetConfigError(ValueError):
     """Raised by _get_budget_config on an invalid budget block."""
 
 
+def _validate_positive_budget_amount(v: object, label: str) -> float:
+    """Validate a budget *amount* value: a non-bool finite number > 0.
+
+    Single-sources the rule shared by ``budget.weekly_usd``,
+    ``budget.codex.amount_usd``, and each ``budget.projects`` value (code-review
+    #5). ``bool`` is an ``int`` subclass, so it's rejected explicitly. ``label``
+    is the human field name used in the raised message (e.g.
+    ``"budget.weekly_usd"``). Null handling stays at the call site — this helper
+    only validates a value the caller has already decided must be a number.
+    """
+    if isinstance(v, bool) or not isinstance(v, (int, float)):
+        raise _BudgetConfigError(f"{label} must be a number")
+    if not math.isfinite(float(v)) or float(v) <= 0:
+        raise _BudgetConfigError(f"{label} must be a finite number > 0")
+    return float(v)
+
+
+# Per-vendor budget period enums (calendar-period + Codex budgets feature).
+# Claude budgets may use any of the three (default subscription-week, the
+# existing reset-aware behavior); Codex budgets may NOT use subscription-week
+# (it's an Anthropic-only concept), so Codex defaults to calendar-month. These
+# 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")
 _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
+    "period": "subscription-week",  # Claude period; default = existing behavior
     "projects": {},               # per-project weekly $ budgets, keyed by git-root
     "project_alerts_enabled": False,  # per-project alerts opt-in (#19/#121); default OFF
+    "codex": None,                # None = no Codex budget (nested block when set)
 }
 _BUDGET_CONFIG_VALID_KEYS = {
     "weekly_usd",
     "alerts_enabled",
     "alert_thresholds",
     "projected_enabled",
+    "period",
     "projects",
     "project_alerts_enabled",
+    "codex",
 }
 
 
@@ -631,21 +677,18 @@ def _get_budget_config(cfg: dict) -> dict:
         out["alerts_enabled"] = v
 
     if "alert_thresholds" in block:
-        v = block["alert_thresholds"]
-        if not isinstance(v, list):
-            raise _BudgetConfigError("budget.alert_thresholds must be a list of ints")
-        cleaned = []
-        for t in v:
-            if isinstance(t, bool) or not isinstance(t, int):
-                raise _BudgetConfigError(
-                    "budget.alert_thresholds entries must be integers"
-                )
-            if t < 1 or t > 100:
-                raise _BudgetConfigError(
-                    "budget.alert_thresholds entries must be in [1, 100]"
-                )
-            cleaned.append(t)
-        out["alert_thresholds"] = sorted(set(cleaned))  # empty list allowed (silenced)
+        out["alert_thresholds"] = _validate_budget_thresholds(
+            block["alert_thresholds"], "budget.alert_thresholds"
+        )
+
+    if "period" in block:
+        v = block["period"]
+        if not isinstance(v, str) or v not in BUDGET_PERIODS:
+            raise _BudgetConfigError(
+                "budget.period must be one of "
+                f"{', '.join(BUDGET_PERIODS)}, got {v!r}"
+            )
+        out["period"] = v
 
     if "projected_enabled" in block:
         v = block["projected_enabled"]
@@ -688,6 +731,107 @@ def _get_budget_config(cfg: dict) -> dict:
             )
         out["project_alerts_enabled"] = v
 
+    if "codex" in block:
+        out["codex"] = _validate_codex_budget_block(block["codex"])
+
+    return out
+
+
+def _validate_budget_thresholds(v: object, label: str) -> "list[int]":
+    """Validate + canonicalize a budget alert-thresholds list.
+
+    Shared by the top-level ``budget.alert_thresholds`` and the nested
+    ``budget.codex.alert_thresholds`` leaves. Entries must be ints in [1, 100]
+    (bool is an int subclass and is rejected). Returns a sorted, deduped list;
+    an empty list is allowed (alerts silenced).
+    """
+    if not isinstance(v, list):
+        raise _BudgetConfigError(f"{label} must be a list of ints")
+    cleaned: "list[int]" = []
+    for t in v:
+        if isinstance(t, bool) or not isinstance(t, int):
+            raise _BudgetConfigError(f"{label} entries must be integers")
+        if t < 1 or t > 100:
+            raise _BudgetConfigError(f"{label} entries must be in [1, 100]")
+        cleaned.append(t)
+    return sorted(set(cleaned))  # empty list allowed (silenced)
+
+
+def _validate_codex_budget_block(v: object) -> "dict | None":
+    """Validate the nested ``budget.codex`` block (Codex per-vendor budget).
+
+    ``None`` is the no-Codex-budget sentinel. When set, it's an object with a
+    finite ``amount_usd`` > 0, a ``period`` in CODEX_BUDGET_PERIODS (NOT
+    subscription-week — Anthropic-only), ``alerts_enabled`` bool (default
+    False — opt-in, like every alert axis), ``alert_thresholds`` validated like
+    the top-level budget thresholds (default [90, 100]), and
+    ``projected_enabled`` bool (default False). Returns a defaults-filled copy.
+    """
+    if v is None:
+        return None
+    if not isinstance(v, dict):
+        raise _BudgetConfigError(
+            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:
+            print(
+                f"warning: ignoring unknown budget.codex config key: {k}",
+                file=sys.stderr,
+            )
+    out: "dict" = {
+        "amount_usd": None,
+        "period": "calendar-month",     # Codex default (NO subscription-week)
+        "alerts_enabled": False,        # opt-in, like every alert axis
+        "alert_thresholds": [90, 100],
+        "projected_enabled": False,
+    }
+    # amount_usd — required (a Codex block must define a budget) finite > 0.
+    # Shares the positive-amount rule with weekly_usd / projects via the helper;
+    # the message form ("must be a number" / "must be a finite number > 0") is
+    # byte-identical to the prior inline checks (code-review #5).
+    if "amount_usd" not in v:
+        raise _BudgetConfigError("budget.codex.amount_usd is required")
+    out["amount_usd"] = _validate_positive_budget_amount(
+        v["amount_usd"], "budget.codex.amount_usd"
+    )
+
+    if "period" in v:
+        p = v["period"]
+        if not isinstance(p, str) or p not in CODEX_BUDGET_PERIODS:
+            raise _BudgetConfigError(
+                "budget.codex.period must be one of "
+                f"{', '.join(CODEX_BUDGET_PERIODS)} (NOT subscription-week), "
+                f"got {p!r}"
+            )
+        out["period"] = p
+
+    if "alerts_enabled" in v:
+        ae = v["alerts_enabled"]
+        if not isinstance(ae, bool):
+            raise _BudgetConfigError(
+                "budget.codex.alerts_enabled must be a boolean"
+            )
+        out["alerts_enabled"] = ae
+
+    if "alert_thresholds" in v:
+        out["alert_thresholds"] = _validate_budget_thresholds(
+            v["alert_thresholds"], "budget.codex.alert_thresholds"
+        )
+
+    if "projected_enabled" in v:
+        pe = v["projected_enabled"]
+        if not isinstance(pe, bool):
+            raise _BudgetConfigError(
+                "budget.codex.projected_enabled must be a boolean"
+            )
+        out["projected_enabled"] = pe
+
     return out
 
 
@@ -1101,44 +1245,47 @@ def open_db() -> sqlite3.Connection:
     )
 
     # ── budget_milestones (equiv-$ budget threshold crossings — issue #19) ──
-    # Plain CREATE TABLE IF NOT EXISTS, NO migration handler / backfill — the
-    # exact posture of `five_hour_milestones` (write-once, forward-only). A
+    # Write-once, forward-only (the exact posture of `five_hour_milestones`). A
     # mid-week quota reset re-anchors `week_start_at` (see
     # `_resolve_current_budget_window`), so the new window naturally gets
-    # fresh rows under UNIQUE(week_start_at, threshold) — no `reset_event_id`
-    # segment column needed (unlike the percent/5h tables). `week_start_at`
-    # stores the effective/re-anchored ISO string from the resolver
-    # (`isoformat(timespec="seconds")`); the resolver's `parse_iso_datetime`
-    # returns a HOST-LOCAL tz-aware datetime, so this dedup key carries the
-    # host's UTC offset (e.g. `…T07:00:00-07:00`) — host-consistent, NOT
-    # portable across hosts, same posture as `five_hour_blocks.block_start_at`.
-    # Firing + reconcile + the dashboard envelope all read/write the identical
-    # string on a given host, so the UNIQUE dedup is exact. `alerted_at` is stamped BEFORE the
-    # osascript Popen (set-then-dispatch invariant); NULL = "recorded without
-    # dispatch" (the forward-only-from-set reconcile path) OR "not yet
-    # dispatched", never "delivery failed". Lives BEFORE the migration
-    # dispatcher: a plain CREATE on a framework-untracked table never touches
-    # `schema_migrations`, so the dispatcher's fresh-install snapshot is
-    # unaffected.
+    # fresh rows under UNIQUE(week_start_at, period, threshold) — no
+    # `reset_event_id` segment column needed (unlike the percent/5h tables).
+    # `week_start_at` stores the effective/re-anchored ISO string from the
+    # resolver (`isoformat(timespec="seconds")`); the resolver's
+    # `parse_iso_datetime` returns a HOST-LOCAL tz-aware datetime, so this
+    # dedup key carries the host's UTC offset (e.g. `…T07:00:00-07:00`) —
+    # host-consistent, NOT portable across hosts, same posture as
+    # `five_hour_blocks.block_start_at`. Firing + reconcile + the dashboard
+    # envelope all read/write the identical string on a given host, so the
+    # UNIQUE dedup is exact. `alerted_at` is stamped BEFORE the osascript Popen
+    # (set-then-dispatch invariant); NULL = "recorded without dispatch" (the
+    # forward-only-from-set reconcile path) OR "not yet dispatched", never
+    # "delivery failed".
+    # Schema owned by migration 011_budget_milestone_period_keys (the `period`
+    # column + the period-inclusive UNIQUE; see _cctally_db.py). The live CREATE
+    # below makes the new shape on fresh installs (dispatcher fast-stamps 011);
+    # pre-011 DBs trip the migration's rename-recreate-copy. `period` is the
+    # configured period noun at crossing ('calendar-week'|'calendar-month'|
+    # 'subscription-week'); NULL = pre-011 unknown.
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS budget_milestones (
             id              INTEGER PRIMARY KEY AUTOINCREMENT,
             week_start_at   TEXT    NOT NULL,
+            period          TEXT,                 -- configured period at crossing; NULL = pre-011 unknown (migration 011)
             threshold       INTEGER NOT NULL,
             budget_usd      REAL    NOT NULL,
             spent_usd       REAL    NOT NULL,
             consumption_pct REAL    NOT NULL,
             crossed_at_utc  TEXT    NOT NULL,
             alerted_at      TEXT,
-            UNIQUE(week_start_at, threshold)
+            UNIQUE(week_start_at, period, threshold)
         )
         """
     )
 
     # ── 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
+    # Write-once, forward-only — same posture as `budget_milestones` (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
@@ -1149,20 +1296,22 @@ def open_db() -> sqlite3.Connection:
     # `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`.
+    # Schema owned by migration 011_budget_milestone_period_keys (the `period`
+    # column + the period-inclusive UNIQUE; see _cctally_db.py). `period` is
+    # NULL for pre-011 rows.
     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'
+            week_start_at   TEXT    NOT NULL,   -- period-start instant (subscription-week OR calendar period-start; back-compat name)
+            period          TEXT,               -- configured period at crossing; NULL = pre-011 unknown (migration 011)
+            metric          TEXT    NOT NULL,   -- 'weekly_pct' | 'budget_usd' | 'codex_budget_usd'
             threshold       INTEGER NOT NULL,   -- 90 | 100
             projected_value REAL    NOT NULL,
-            denominator     REAL    NOT NULL,   -- target_usd (budget) | 100.0 (weekly)
+            denominator     REAL    NOT NULL,   -- target_usd (budget / codex_budget) | 100.0 (weekly)
             crossed_at_utc  TEXT    NOT NULL,
             alerted_at      TEXT,
-            UNIQUE(week_start_at, metric, threshold)
+            UNIQUE(week_start_at, period, metric, threshold)
         )
         """
     )
@@ -1203,6 +1352,46 @@ def open_db() -> sqlite3.Connection:
         """
     )
 
+    # ── codex_budget_milestones (per-vendor Codex budget crossings) ──────────
+    # Plain CREATE TABLE IF NOT EXISTS, NO migration handler / backfill — the
+    # same posture as `budget_milestones` / `projected_milestones` /
+    # `project_budget_milestones` (write-once, forward-only, framework-untracked;
+    # calendar-period-codex-budgets feature, spec §6). The dedup key is keyed on
+    # `period_start_at` — the resolved period-window START instant stored as the
+    # `isoformat(timespec="seconds")` `+00:00` offset form (NOT a `Z` suffix),
+    # e.g. calendar-month June → `2026-06-01T00:00:00+00:00` — NOT a subscription
+    # week:
+    # Codex has no Anthropic week, so the budget runs over a calendar period
+    # (calendar-week / calendar-month). Rolling to the next period yields a fresh
+    # `period_start_at` → fresh crossings under UNIQUE(period_start_at, period,
+    # threshold) (the budget-pattern reset handling — hence NO `reset_event_id`
+    # segment column). `budget_usd` snapshots the Codex target AT crossing so the
+    # dashboard renders "$210 of $200" from the ROW, not from live config that
+    # may have changed since (the Codex P0-4 lesson, baked into the sibling
+    # tables). `alerted_at` is stamped BEFORE the osascript Popen (set-then-
+    # dispatch invariant); NULL = "recorded without dispatch" (the forward-only-
+    # from-set reconcile path) OR "not yet dispatched", never "delivery failed".
+    # Schema owned by migration 011_budget_milestone_period_keys (the `period`
+    # column + the period-inclusive UNIQUE; see _cctally_db.py). `period` is the
+    # configured Codex period noun at crossing ('calendar-week'|'calendar-
+    # month'); NULL = pre-011 unknown.
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS codex_budget_milestones (
+            id              INTEGER PRIMARY KEY AUTOINCREMENT,
+            period_start_at TEXT    NOT NULL,   -- resolved period-window start instant (+00:00 offset form, NOT Z)
+            period          TEXT,               -- configured period at crossing; NULL = pre-011 unknown (migration 011)
+            threshold       INTEGER NOT NULL,
+            budget_usd      REAL    NOT NULL,   -- Codex target snapshotted AT crossing
+            spent_usd       REAL    NOT NULL,
+            consumption_pct REAL    NOT NULL,
+            crossed_at_utc  TEXT    NOT NULL,
+            alerted_at      TEXT,
+            UNIQUE(period_start_at, period, 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