cctally 1.22.4 → 1.24.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.24.0] - 2026-06-02
+
+### Added
+- **Threshold alerts now dispatch cross-platform, not just on macOS.** Alongside the existing macOS `osascript` Notification Center popup, alerts can now fire via Linux `notify-send` (with the severity mapped to a `-u low|normal|critical` urgency token and a `--` end-of-options guard against option-injection) or via a fully custom command you configure — so Windows / WSL / headless setups can finally wire up a real popup. The backend is picked automatically per host (`auto`: a custom command if you've set one, else `osascript` on macOS, else `notify-send` on Linux, else no popup), and `cctally alerts test` now prints a `notifier: <resolved>` line so you can see exactly which backend will fire before relying on a real crossing. The dispatch decision lives in a new pure, fully-unit-tested kernel (`bin/_lib_alert_dispatch.py`) and every spawn is `shell=False` with the arg-list form, so alert text containing `$(...)`, `;`, or `&&` is passed as one literal argument and can never inject a shell command.
+- **A new `alerts.command_template` config key lets you run any command on an alert.** Set it to a JSON argv list — e.g. `cctally config set alerts.command_template '["notify-send","-u","{urgency}","{title}","{body}"]'` — and cctally spawns that command (shell-free) on every crossing, substituting the documented `{title}`/`{subtitle}`/`{body}`/`{severity}`/`{urgency}`/`{axis}`/`{threshold}`/`{metric}` tokens (unmatched braces stay literal; a missing value substitutes as empty). This is trusted local execution (you own your config), and under the default `auto` notifier a set template takes over dispatch on every OS, so you can route alerts to a webhook, a logger, a phone push, or any tool you like. The companion `alerts.notifier` key (`auto` / `osascript` / `notify-send` / `command` / `none`) pins the backend explicitly when you don't want auto-detection, and both keys are editable from the dashboard Settings overlay (notifier dropdown) as well as `cctally config set`.
+
+### Changed
+- **Alert severity is now a 3-tier model (info / warn / critical) instead of the previous two-color split.** A crossed threshold below 90% is `info` (indigo), 90–99% is `warn` (amber), and 100%+ is `critical` (red); this single mapping drives the dashboard toast color, the "Recent alerts" panel chip, and the Linux `notify-send` urgency token, and it is kept byte-identical between the Python authority (`bin/_lib_alert_axes.py::severity_for`) and the dashboard (`alertSeverity` in `dashboard/web/src/lib/alertAxis.ts`), with legacy `amber`/`red` tokens from an older backend normalizing to `warn`/`critical` on read. The `alerts.log` audit file gains a 7th tab-delimited column carrying this severity on every dispatch line. No action needed on upgrade; existing alert config and thresholds are unchanged.
+
+## [1.23.0] - 2026-06-02
+
+### Added
+- **Projected-pace alerts: a new opt-in `projected` alert axis that warns you *before* you cross a ceiling, firing on your week-average pace rather than waiting for the actual crossing.** It tracks two metrics — `weekly_pct` (projected to reach 90% / 100% of your subscription cap by the week's reset) and `budget_usd` (projected to reach your `budget.alert_thresholds` of the weekly $ budget) — using the smooth week-average projection (`now + average-rate × time-remaining`), the same conservative number `forecast`/`budget` already display; it deliberately ignores the hotter trailing-24h estimate so a brief spike doesn't trigger a false alarm. Each level fires once per week (no re-fire, no recovery alert), is suppressed while the forecast is `LOW CONF` (too early in the week / too few samples), and re-anchors cleanly across a mid-week reset.
+- **Both projected toggles default OFF, gated behind their parent axis** — enable weekly-% projected alerts with `cctally config set alerts.projected_enabled true` (requires `alerts.enabled`) and budget-$ projected alerts with `cctally config set budget.projected_enabled true` (requires a configured `budget.weekly_usd` + `budget.alerts_enabled`); preview either without writing any data via `cctally alerts test --axis projected --metric weekly_pct` (or `--metric budget_usd`). The local web dashboard surfaces fired projected alerts with a dedicated **Projected** chip and forecast-aware context, and exposes both enable/disable toggles in its settings panel.
+- **`forecast --json` and `budget --json` now expose an additive `week_avg_projection_pct` / `week_avg_projection_usd` field** — the exact week-average end-of-week projection the projected-pace alert axis fires on, surfaced for scripting and reconciliation (additive only; no schema-version bump, existing keys unchanged).
+
+### Fixed
+- **The mid-week reset-to-zero detector now waits for a corroborating second reading before segmenting the week (#128).** When the Anthropic usage API reports a clean drop to ~0% against non-trivial prior usage (below the 25pp goodwill-credit threshold), `record-usage` no longer writes a `week_reset_events` row on the very first zero: it arms a one-tick debounce and fires only if the next reading stays low (at or below half the pre-zero level), treating a zero that bounces back toward the prior percentage as a transient API/replica glitch rather than a real reset. A genuine reset still surfaces — one status-line tick later — and the ≥25pp credit path, the boundary-advance path, and the 5-hour detector are unchanged. This is belt-and-suspenders hardening on the 2026-06-01 surprise-reset fix; the debounce is best-effort under concurrent `record-usage` runs (a race degrades to the previous single-zero behavior, never worse).
+- **Test-suite isolation (no shipped-code change): the `*_ns_patch.py` binding-regression tests no longer read the developer's real `~/.local/share/cctally` database (#127).** Their shared `cctally_mod` fixture loaded `bin/cctally` with a bespoke loader that only set `HOME` and relied on `_cctally_core`'s import-time path derivation — which silently no-ops once any earlier test has cached `_cctally_core` in `sys.modules` (every `load_script()` user does), so the handler under test fell back to the real prod DB. That stayed invisible until the prod DB happened to hold a `week_reset_events` row for the current week, at which point `test_percent_breakdown_md_reaches_all_accessors_via_ns` flipped to a failure that only reproduced under certain test orderings (it filters milestones by the DB's active segment, so the seeded fake milestone was dropped and the table never rendered). The five `*_ns_patch.py` fixtures now route through a shared `conftest.load_isolated_cctally_module()` helper built on `load_script()` + `redirect_paths()`, pinning `_cctally_core`'s path constants to the per-test tmp dir deterministically regardless of import order. A new order-independent regression (`test_ns_patch_loader_isolates_db_when_core_cached`) asserts the loader re-isolates `DB_PATH` even when `_cctally_core` is pre-cached pointing at a real prod path.
+
 ## [1.22.4] - 2026-06-01
 
 ### Fixed

package/bin/_cctally_alerts.py

@@ -47,6 +47,7 @@ import datetime as dt
 import importlib.util as _ilu
 import os
 import pathlib
+import shutil
 import subprocess
 import sys
 
@@ -69,10 +70,30 @@ _lib_alerts_payload = _load_lib("_lib_alerts_payload")
 _alert_text_weekly = _lib_alerts_payload._alert_text_weekly
 _alert_text_five_hour = _lib_alerts_payload._alert_text_five_hour
 _alert_text_budget = _lib_alerts_payload._alert_text_budget
+_alert_text_projected = _lib_alerts_payload._alert_text_projected
 _escape_applescript_string = _lib_alerts_payload._escape_applescript_string
 _build_alert_payload_weekly = _lib_alerts_payload._build_alert_payload_weekly
 _build_alert_payload_five_hour = _lib_alerts_payload._build_alert_payload_five_hour
 _build_alert_payload_budget = _lib_alerts_payload._build_alert_payload_budget
+_build_alert_payload_projected = _lib_alerts_payload._build_alert_payload_projected
+
+# 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.
+_lib_alert_axes = _load_lib("_lib_alert_axes")
+severity_for = _lib_alert_axes.severity_for
+_lib_alert_dispatch = _load_lib("_lib_alert_dispatch")
+resolve_notifier = _lib_alert_dispatch.resolve_notifier
+build_command = _lib_alert_dispatch.build_command
+severity_to_urgency = _lib_alert_dispatch.severity_to_urgency
+
+
+# `load_config` STAYS a shim that bounces through cctally's namespace (mirrors
+# bin/_cctally_record.py): production monkeypatches `cctally.load_config`, and
+# the dispatch tests patch this module-level name directly. Its natural home is
+# _cctally_config; a direct import would silently bypass those patches.
+def load_config(*args, **kwargs):
+    return sys.modules["cctally"].load_config(*args, **kwargs)
 
 
 # === Honest imports from extracted homes ===================================
@@ -101,14 +122,26 @@ def _dispatch_alert_notification(
     popen_factory=subprocess.Popen,
     mode: str = "real",
     tz: "object | None" = None,
+    platform: "str | None" = None,
+    which_on_path=None,
 ) -> str:
-    """Spawn osascript to display a macOS notification (non-blocking, best-effort).
+    """Dispatch a notification for a crossed threshold (non-blocking, best-effort).
 
-    Returns ``"queued"`` on successful Popen, ``"spawn_error: <ExcType>: <msg>"``
-    on failure. Writes EXACTLY ONE line to ``alerts.log`` with the terminal
-    status (no contradictory pre-/post-Popen log pair). Never raises:
-    Popen-spawn failures and log-write failures are both swallowed so the
-    dispatch contract stays independent of the OS / FS state.
+    Picks the active notifier (osascript / notify-send / a config-driven
+    command_template / none) via the pure ``_lib_alert_dispatch`` kernel, builds
+    its exact arg-list, and spawns it with ``shell=False``. Returns one of:
+      ``"queued"``                  Popen succeeded
+      ``"no_notifier:none"``        auto/none resolved to no popup on this host
+      ``"no_notifier:unavailable"`` an explicit osascript/notify-send is missing
+      ``"spawn_error: <ExcType>: <msg>"`` Popen raised
+    Writes EXACTLY ONE line to ``alerts.log`` with the terminal status PLUS the
+    crossing's 3-tier severity as a trailing column. Never raises: the config
+    read, Popen-spawn failures, and log-write failures are all swallowed so the
+    dispatch contract stays independent of the OS / FS / user-config state.
+
+    ``platform`` (sys.platform-style) and ``which_on_path`` (name -> bool) are
+    injectable so every OS branch + the no-notifier paths are testable from any
+    host; both default to the real ``sys.platform`` / ``shutil.which``.
 
     Production callers ignore the return value (fire-and-forget); test
     callers assert on it via an injected ``popen_factory``.
@@ -138,6 +171,8 @@ def _dispatch_alert_notification(
         title, subtitle, body = _alert_text_five_hour(payload, tz)
     elif axis == "budget":
         title, subtitle, body = _alert_text_budget(payload, tz)
+    elif axis == "projected":
+        title, subtitle, body = _alert_text_projected(payload, tz)
     else:
         title, subtitle, body = (
             "cctally - alert",
@@ -145,27 +180,64 @@ def _dispatch_alert_notification(
             f"axis={axis} threshold={payload.get('threshold')}",
         )
 
-    script = (
-        f'display notification "{_escape_applescript_string(body)}"'
-        f' with title "{_escape_applescript_string(title)}"'
-        f' subtitle "{_escape_applescript_string(subtitle)}"'
+    # Severity (3-tier) drives both the notify-send urgency token and the
+    # 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"
+    urgency = severity_to_urgency(severity)
+
+    if platform is None:
+        platform = sys.platform
+    if which_on_path is None:
+        which_on_path = lambda name: shutil.which(name) is not None
+
+    # Guarded so a malformed user config (or a load_config raise) never breaks
+    # the never-raise contract: fall back to auto-detect / no custom command.
+    try:
+        alerts_cfg = _cctally_core._get_alerts_config(load_config())
+    except Exception:
+        alerts_cfg = {"notifier": "auto", "command_template": None}
+
+    notifier = resolve_notifier(
+        alerts_cfg, platform=platform, which_on_path=which_on_path
+    )
+    args = build_command(
+        notifier,
+        title=title,
+        subtitle=subtitle,
+        body=body,
+        severity=severity,
+        urgency=urgency,
+        payload=payload,
+        command_template=alerts_cfg.get("command_template"),
     )
 
     status: str
-    try:
-        popen_factory(
-            ["osascript", "-e", script],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            close_fds=True,
-            start_new_session=True,
-        )
-        status = "queued"
-    except (FileNotFoundError, PermissionError, OSError) as exc:
-        status = f"spawn_error: {exc.__class__.__name__}: {exc}"
+    if args is None:
+        # 'none' (auto resolved to no popup, or notifier='none') vs an
+        # explicitly-selected native backend that is unavailable on this host.
+        selector = alerts_cfg.get("notifier", "auto")
+        reason = "unavailable" if selector in ("osascript", "notify-send") else "none"
+        status = f"no_notifier:{reason}"
+    else:
+        try:
+            popen_factory(
+                args,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                close_fds=True,
+                start_new_session=True,
+            )
+            status = "queued"
+        except (FileNotFoundError, PermissionError, OSError) as exc:
+            status = f"spawn_error: {exc.__class__.__name__}: {exc}"
 
-    # SINGLE log line per dispatch attempt (Codex P1#2 fix: no
-    # contradictory "queued" + "spawn_error" pair for the same call).
+    # SINGLE log line per dispatch attempt (Codex P1#2 fix: no contradictory
+    # "queued" + "spawn_error" pair). Severity is appended as the 7th column.
     try:
         log_path = _alerts_log_path()
         ctx = payload.get("context") or {}
@@ -177,7 +249,7 @@ def _dispatch_alert_notification(
         )
         line = (
             f"{now_utc_iso()}\t{axis}\t{payload.get('threshold')}\t{window_key}"
-            f"\t{mode}\t{status}\n"
+            f"\t{mode}\t{status}\t{severity}\n"
         )
         with open(log_path, "a") as f:
             f.write(line)
@@ -207,6 +279,8 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
         axis = "weekly"
     elif args.axis == "budget":
         axis = "budget"
+    elif args.axis == "projected":
+        axis = "projected"
     else:
         axis = "five_hour"
     threshold = int(args.threshold)
@@ -239,6 +313,27 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
             spent_usd=300.0 * threshold / 100.0,
             consumption_pct=float(threshold),
         )
+    elif axis == "projected":
+        # Synthetic projected-pace payload — NO DB writes (test/real divergence
+        # contract). The metric discriminator picks the wiring; projected_value
+        # is the threshold's denominator-relative value (so the body reads
+        # plausibly, e.g. weekly 100% → "~100% of cap", budget 100% → "$300 of
+        # $300"). denominator is the at-crossing target the row would carry
+        # (Codex P0-4): 100.0 for weekly_pct, $300 for budget_usd.
+        metric = getattr(args, "metric", "weekly_pct")
+        if metric == "budget_usd":
+            denominator = 300.0
+            projected_value = 300.0 * threshold / 100.0
+        else:  # weekly_pct
+            denominator = 100.0
+            projected_value = float(threshold)
+        payload = _build_alert_payload_projected(
+            metric=metric,
+            threshold=threshold,
+            projected_value=projected_value,
+            denominator=denominator,
+            week_start_at=dt.date.today().isoformat(),
+        )
     else:
         payload = _build_alert_payload_five_hour(
             threshold=threshold,
@@ -248,6 +343,20 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
             block_cost_usd=1.23,
             primary_model="claude-sonnet-4-6",
         )
+    # Resolve and report the active notifier for display BEFORE dispatch — the
+    # config read is guarded the same way `_dispatch_alert_notification` guards
+    # its own (so a malformed config never crashes `alerts test`). This is
+    # purely informational; the dispatch path re-resolves independently.
+    try:
+        alerts_cfg = _cctally_core._get_alerts_config(load_config())
+    except Exception:
+        alerts_cfg = {"notifier": "auto", "command_template": None}
+    notifier = resolve_notifier(
+        alerts_cfg,
+        platform=sys.platform,
+        which_on_path=lambda name: shutil.which(name) is not None,
+    )
+    print(f"notifier: {notifier}")
     status = _dispatch_alert_notification(payload, mode="test")
     if status == "queued":
         print("Test alert dispatched (mode=test). Check Notification Center.")

package/bin/_cctally_config.py

@@ -297,6 +297,9 @@ def save_config(data: dict[str, Any]) -> None:
 ALLOWED_CONFIG_KEYS = (
     "display.tz",
     "alerts.enabled",
+    "alerts.projected_enabled",
+    "alerts.notifier",
+    "alerts.command_template",
     "dashboard.bind",
     "update.check.enabled",
     "update.check.ttl_hours",
@@ -306,6 +309,7 @@ ALLOWED_CONFIG_KEYS = (
     "budget.weekly_usd",
     "budget.alerts_enabled",
     "budget.alert_thresholds",
+    "budget.projected_enabled",
 )
 
 
@@ -405,6 +409,28 @@ def _config_known_value(config: dict, key: str) -> "object":
         return c.get_display_tz_pref(config)
     if key == "alerts.enabled":
         return bool(_get_alerts_config(config)["enabled"])
+    if key == "alerts.projected_enabled":
+        # Validated boolean (defaults to False when unset). A corrupt alerts
+        # block surfaces the default — mirrors alerts.enabled.
+        try:
+            return bool(_get_alerts_config(config)["projected_enabled"])
+        except c._AlertsConfigError:
+            return False
+    if key == "alerts.notifier":
+        # Validated dispatch backend (defaults to 'auto' when unset). A corrupt
+        # alerts block surfaces the default — mirrors alerts.enabled.
+        try:
+            return _get_alerts_config(config)["notifier"]
+        except c._AlertsConfigError:
+            return "auto"
+    if key == "alerts.command_template":
+        # Validated argv list or None (defaults to None when unset). A corrupt
+        # alerts block surfaces the default. The plain-text render path JSON-
+        # encodes this so `config get` round-trips through `config set`.
+        try:
+            return _get_alerts_config(config)["command_template"]
+        except c._AlertsConfigError:
+            return None
     if key == "dashboard.bind":
         # Default semantic alias is 'loopback' (resolves to 127.0.0.1 at
         # bind time). LAN exposure is opt-in via `set dashboard.bind lan`
@@ -472,6 +498,7 @@ def _config_known_value(config: dict, key: str) -> "object":
         "budget.weekly_usd",
         "budget.alerts_enabled",
         "budget.alert_thresholds",
+        "budget.projected_enabled",
     ):
         inner = key.split(".", 1)[1]
         # Read the validated, defaults-filled block. A corrupt block falls
@@ -495,14 +522,20 @@ def _cmd_config_get(args: argparse.Namespace, config: dict) -> int:
     if key is not None and key not in ALLOWED_CONFIG_KEYS:
         eprint(f"cctally config: unknown config key {key!r}")
         return 2
+    # `alerts.command_template` is JSON-shaped (a list of strings or null), so
+    # its real value (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 == "alerts.command_template":
+            return v
+        return v if v is not None else ""
+
     pairs: "list[tuple[str, object]]" = []
     if key is None:
         for k in ALLOWED_CONFIG_KEYS:
-            v = _config_known_value(config, k)
-            pairs.append((k, v if v is not None else ""))
+            pairs.append((k, _coerce(k, _config_known_value(config, k))))
     else:
-        v = _config_known_value(config, key)
-        pairs.append((key, v if v is not None else ""))
+        pairs.append((key, _coerce(key, _config_known_value(config, key))))
 
     if getattr(args, "emit_json", False):
         # Walk every dot-delimited segment so keys deeper than two
@@ -522,7 +555,12 @@ 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 isinstance(v, bool):
+            if k == "alerts.command_template":
+                # JSON-encoded (list of strings or null) so `config get` output
+                # round-trips through `config set alerts.command_template`
+                # (which JSON-parses its value).
+                rendered = json.dumps(v)
+            elif isinstance(v, bool):
                 rendered = "true" if v else "false"
             elif isinstance(v, list):
                 # Comma-joined so `config get budget.alert_thresholds` output
@@ -598,6 +636,121 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         else:
             print(f"alerts.enabled={'true' if normalized else 'false'}")
         return 0
+    if key == "alerts.projected_enabled":
+        # Projected-pace opt-in (#121). Same bool-normalizer + read-modify-write
+        # posture as alerts.enabled (preserves sibling alerts.* keys).
+        # _normalize_alerts_enabled_value hardcodes "alerts.enabled" in its
+        # ValueError text, so catch + re-message with the actual key name
+        # (mirrors _normalize_update_check_enabled_value's precedent) — the
+        # budget side already names its own key correctly.
+        try:
+            normalized = c._normalize_alerts_enabled_value(raw)
+        except ValueError:
+            print(
+                f"cctally: invalid boolean value for alerts.projected_enabled: "
+                f"{raw!r} (expected true|false|yes|no|1|0|on|off)",
+                file=sys.stderr,
+            )
+            return 2
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            existing_alerts = config.get("alerts")
+            if existing_alerts is not None and not isinstance(
+                existing_alerts, dict
+            ):
+                print(
+                    "cctally: alerts config error: alerts must be an object",
+                    file=sys.stderr,
+                )
+                return 2
+            alerts_block = dict(existing_alerts or {})
+            alerts_block["projected_enabled"] = normalized
+            try:
+                _get_alerts_config({**config, "alerts": alerts_block})
+            except _AlertsConfigError as exc:
+                print(f"cctally: alerts config error: {exc}", file=sys.stderr)
+                return 2
+            config["alerts"] = alerts_block
+            save_config(config)
+        if getattr(args, "emit_json", False):
+            print(
+                json.dumps({"alerts": {"projected_enabled": normalized}}, indent=2)
+            )
+        else:
+            print(
+                f"alerts.projected_enabled={'true' if normalized else 'false'}"
+            )
+        return 0
+    if key == "alerts.notifier":
+        # Dispatch backend (Phase B). Plain string; the enum constraint is
+        # enforced by the pre-persist _get_alerts_config validation (so we never
+        # write a config that fails subsequent reads). Same read-modify-write
+        # posture as alerts.enabled (preserves sibling alerts.* keys).
+        normalized = raw.strip()
+        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["notifier"] = 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": {"notifier": normalized}}, indent=2))
+        else:
+            print(f"alerts.notifier={normalized}")
+        return 0
+    if key == "alerts.command_template":
+        # Dispatch argv template (Phase B). JSON-parsed value (a list of strings
+        # or null to clear it); the shape + cross-field constraints are enforced
+        # by the pre-persist _get_alerts_config validation. Same read-modify-
+        # write posture as alerts.enabled (preserves sibling alerts.* keys).
+        try:
+            parsed = json.loads(raw)
+        except (ValueError, TypeError) as exc:
+            print(
+                f"cctally: alerts.command_template must be JSON (a list of "
+                f"strings or null): {exc}",
+                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["command_template"] = parsed
+            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": {"command_template": parsed}}, indent=2))
+        else:
+            print(f"alerts.command_template={json.dumps(parsed)}")
+        return 0
     if key == "dashboard.bind":
         # Validation rejects whitespace / empty / non-string up front;
         # write proceeds under config_writer_lock with _load_config_unlocked
@@ -715,6 +868,7 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         "budget.weekly_usd",
         "budget.alerts_enabled",
         "budget.alert_thresholds",
+        "budget.projected_enabled",
     ):
         inner_key = key.split(".", 1)[1]
         # Parse + normalize the raw value per key BEFORE acquiring the lock so
@@ -734,7 +888,7 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                         f"null, got {raw!r}"
                     )
                     return 2
-        elif inner_key == "alerts_enabled":
+        elif inner_key in ("alerts_enabled", "projected_enabled"):
             lo = raw.strip().lower()
             if lo in ("true", "yes", "on", "1"):
                 new_val = True
@@ -742,7 +896,7 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                 new_val = False
             else:
                 eprint(
-                    "cctally config: budget.alerts_enabled must be a boolean, "
+                    f"cctally config: budget.{inner_key} must be a boolean, "
                     f"got {raw!r}"
                 )
                 return 2
@@ -817,21 +971,47 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 save_config(config)
             # idempotent: silent on missing key
         return 0
-    if key == "alerts.enabled":
+    if key in (
+        "alerts.enabled",
+        "alerts.projected_enabled",
+        "alerts.notifier",
+        "alerts.command_template",
+    ):
         # Mirror the display.tz branch: writer-lock + _load_config_unlocked
         # (NOT load_config — fcntl.flock is per-fd so re-entry would
         # self-deadlock per the gotcha in CLAUDE.md). Unsetting just the
-        # `enabled` key preserves any user-customized threshold lists
-        # (`weekly_thresholds`, `five_hour_thresholds`); the read-time
-        # validator (`_get_alerts_config`) re-applies the canonical
-        # default of `enabled = False` for the missing key on next get.
+        # named key preserves any user-customized threshold lists
+        # (`weekly_thresholds`, `five_hour_thresholds`) and the sibling
+        # enabled/projected_enabled/notifier/command_template keys. For
+        # enabled/projected_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
+        # constraint makes notifier="command" REQUIRE a template, so dropping
+        # the template would leave a config that _get_alerts_config REJECTS on
+        # the next read. The pre-persist guard below catches exactly that case.
+        inner_key = key.split(".", 1)[1]
         with config_writer_lock():
             config = _load_config_unlocked()
             block = config.get("alerts")
-            if isinstance(block, dict) and "enabled" in block:
-                del block["enabled"]
+            if isinstance(block, dict) and inner_key in block:
+                del block[inner_key]
                 if not block:
                     config.pop("alerts", None)
+                # Pre-persist guard (mirrors the set branches): unsetting a key
+                # that participates in a cross-field constraint
+                # (alerts.command_template while alerts.notifier == "command")
+                # would leave a config that _get_alerts_config rejects on the
+                # next read. Validate the TOP-LEVEL config (so a pruned/empty
+                # alerts block correctly validates to defaults) and refuse
+                # rather than persist an unreadable config.
+                try:
+                    _get_alerts_config(config)
+                except _AlertsConfigError as exc:
+                    print(
+                        f"cctally: alerts config error: {exc}", file=sys.stderr
+                    )
+                    return 2
                 save_config(config)
             # idempotent: silent on missing key
         return 0
@@ -889,6 +1069,7 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
         "budget.weekly_usd",
         "budget.alerts_enabled",
         "budget.alert_thresholds",
+        "budget.projected_enabled",
     ):
         # Drop only the named leaf; preserve sibling budget.* keys (e.g.
         # unsetting weekly_usd keeps a customized alert_thresholds). If the