cctally 1.23.0 → 1.25.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.25.0] - 2026-06-03
+
+### Added
+- **Per-project weekly budgets with their own actual-spend alerts (a new `project_budget` alert axis).** Set a dollar budget for any repo with `cctally budget set 25 --project` (resolves the current directory's git-root) or `--project /abs/path`, clear it with `cctally budget unset --project`, and `cctally budget` now renders a per-project section below the global status (budget / spent / used% / verdict / `LOW CONF`, sorted by used% desc) — present even when no global `budget.weekly_usd` is set, additive in `--json` (a `projects[]` array, no schema bump) and in share-output (names anonymized unless `--reveal-projects`). Turn on push alerts (opt-in, default off) with `cctally config set budget.project_alerts_enabled true`: when a project crosses one of your `budget.alert_thresholds` of its own budget, `record-usage` fires one cross-platform notification per `(project, threshold)` per week with project-specific text (e.g. *"Project foo - $26.00 of $25.00 (104% of budget)"*), severity from the shared 3-tier model. Setting a project budget mid-week when you're already over a threshold records that crossing silently (no retroactive popup) and only later crossings fire, and a mid-week budget change never re-alerts an already-fired threshold. Preview the notification without any real config via `cctally alerts test --axis project-budget --threshold 100`. Thresholds reuse the global `budget.alert_thresholds`; projects are keyed by canonical git-root so same-basename repos stay distinct. In the local web dashboard, fired project alerts now show in the existing "Recent alerts" panel/modal with a distinct **PROJECT** chip (vs the global **BUDGET** chip) and the project basename + `$spent of $budget` context, the Settings overlay gains a **Per-project budget alerts** on/off toggle that persists `budget.project_alerts_enabled` (enabling it mid-week when already over latches the crossed thresholds without storming retroactive popups), and the Settings "Send test alert" picker can fire the synthetic project-budget example end-to-end; editing per-project budget *amounts* stays CLI-only.
+
+## [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

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,13 +70,33 @@ _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_project_budget = _lib_alerts_payload._alert_text_project_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_project_budget = _lib_alerts_payload._build_alert_payload_project_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 ===================================
 # Spec 2026-05-17 §3.3: kernel symbols import from _cctally_core.
@@ -103,14 +124,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``.
@@ -140,6 +173,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 == "project_budget":
+        title, subtitle, body = _alert_text_project_budget(payload, tz)
     elif axis == "projected":
         title, subtitle, body = _alert_text_projected(payload, tz)
     else:
@@ -149,27 +184,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 {}
@@ -181,7 +253,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)
@@ -211,6 +283,8 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
         axis = "weekly"
     elif args.axis == "budget":
         axis = "budget"
+    elif args.axis == "project-budget":
+        axis = "project_budget"
     elif args.axis == "projected":
         axis = "projected"
     else:
@@ -245,6 +319,22 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
             spent_usd=300.0 * threshold / 100.0,
             consumption_pct=float(threshold),
         )
+    elif axis == "project_budget":
+        # Synthetic per-project budget payload — NO DB writes (test/real
+        # divergence contract), NO real budget.projects entry required. A small
+        # $25 budget at $26 spent (104%) reads plausibly regardless of the
+        # --threshold (the body line shows the at-crossing snapshot the dashboard
+        # would render).
+        payload = _build_alert_payload_project_budget(
+            threshold=threshold,
+            crossed_at_utc=now_utc_iso(),
+            week_start_at=dt.date.today().isoformat(),
+            project="example-project",
+            project_key="/example/repos/example-project",
+            budget_usd=25.0,
+            spent_usd=26.0,
+            consumption_pct=104.0,
+        )
     elif axis == "projected":
         # Synthetic projected-pace payload — NO DB writes (test/real divergence
         # contract). The metric discriminator picks the wiring; projected_value
@@ -275,6 +365,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

@@ -298,6 +298,8 @@ ALLOWED_CONFIG_KEYS = (
     "display.tz",
     "alerts.enabled",
     "alerts.projected_enabled",
+    "alerts.notifier",
+    "alerts.command_template",
     "dashboard.bind",
     "update.check.enabled",
     "update.check.ttl_hours",
@@ -308,6 +310,8 @@ ALLOWED_CONFIG_KEYS = (
     "budget.alerts_enabled",
     "budget.alert_thresholds",
     "budget.projected_enabled",
+    "budget.projects",
+    "budget.project_alerts_enabled",
 )
 
 
@@ -414,6 +418,21 @@ def _config_known_value(config: dict, key: str) -> "object":
             return bool(_get_alerts_config(config)["projected_enabled"])
         except c._AlertsConfigError:
             return False
+    if key == "alerts.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`
@@ -482,6 +501,8 @@ def _config_known_value(config: dict, key: str) -> "object":
         "budget.alerts_enabled",
         "budget.alert_thresholds",
         "budget.projected_enabled",
+        "budget.projects",
+        "budget.project_alerts_enabled",
     ):
         inner = key.split(".", 1)[1]
         # Read the validated, defaults-filled block. A corrupt block falls
@@ -496,6 +517,8 @@ def _config_known_value(config: dict, key: str) -> "object":
             default = _BUDGET_DEFAULTS[inner]
             if isinstance(default, list):
                 return list(default)
+            if isinstance(default, dict):
+                return dict(default)
             return default
     return None
 
@@ -505,14 +528,21 @@ 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), and
+    # `budget.projects` is JSON-shaped (an object), so their real values
+    # (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"):
+            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
@@ -532,7 +562,13 @@ 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 in ("alerts.command_template", "budget.projects"):
+                # 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}.
+                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
@@ -653,6 +689,76 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                 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
@@ -771,6 +877,8 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         "budget.alerts_enabled",
         "budget.alert_thresholds",
         "budget.projected_enabled",
+        "budget.projects",
+        "budget.project_alerts_enabled",
     ):
         inner_key = key.split(".", 1)[1]
         # Parse + normalize the raw value per key BEFORE acquiring the lock so
@@ -790,7 +898,9 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                         f"null, got {raw!r}"
                     )
                     return 2
-        elif inner_key in ("alerts_enabled", "projected_enabled"):
+        elif inner_key in (
+            "alerts_enabled", "projected_enabled", "project_alerts_enabled"
+        ):
             lo = raw.strip().lower()
             if lo in ("true", "yes", "on", "1"):
                 new_val = True
@@ -802,6 +912,42 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                     f"got {raw!r}"
                 )
                 return 2
+        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
+            # the alerts.command_template branch). The per-value numeric rule is
+            # enforced by _get_budget_config under the lock below; here we only
+            # reject non-JSON / non-object shape.
+            try:
+                parsed_obj = json.loads(raw)
+            except (json.JSONDecodeError, ValueError):
+                eprint(
+                    "cctally config: budget.projects must be a JSON object, "
+                    f"got {raw!r}"
+                )
+                return 2
+            if not isinstance(parsed_obj, dict):
+                eprint("cctally config: budget.projects must be a JSON object")
+                return 2
+            # Canonicalize each project key to its resolved git-root, mirroring
+            # the `budget set --project` CLI path (`_resolve_project_budget_-
+            # target`). `_sum_cost_by_project` buckets spend under the realpath'd
+            # `ProjectKey.bucket_path`, so a `~`/relative/sub-dir/trailing-slash
+            # key stored verbatim would NEVER match → a permanent $0 row that
+            # silently never alerts. Resolving here makes the JSON-object surface
+            # match the per-project CLI surface. Non-string keys (impossible from
+            # json.loads, defensive) and the `__CWD__`-non-git None case fall
+            # back to the raw key for `_get_budget_config` to handle.
+            c = _cctally()
+            new_val = {
+                (
+                    c._resolve_project_budget_target(pk)
+                    if isinstance(pk, str)
+                    else pk
+                )
+                or pk: pv
+                for pk, pv in parsed_obj.items()
+            }
         else:  # alert_thresholds — comma-separated int list (empty = silenced)
             stripped = raw.strip()
             parsed: "list[int]" = []
@@ -843,13 +989,32 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         # helper opens stats.db and must not nest under the config lock
         # (fcntl.flock is per-fd; the helper has its own open_db locking).
         c = _cctally()
-        c._reconcile_budget_on_config_write(validated)
+        # Gate each forward-only reconcile (spec §6.8) on the keys it actually
+        # consumes. Running unconditionally on an UNRELATED write — e.g. the
+        # global axis on `config set budget.projects`, or the per-project axis
+        # 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"):
+            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)
         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).
+                rendered = json.dumps(out_val)
             else:
                 rendered = str(out_val)
             print(f"{key}={rendered}")
@@ -873,15 +1038,25 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 save_config(config)
             # idempotent: silent on missing key
         return 0
-    if key in ("alerts.enabled", "alerts.projected_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
         # named key preserves any user-customized threshold lists
         # (`weekly_thresholds`, `five_hour_thresholds`) and the sibling
-        # enabled/projected_enabled toggle; the read-time validator
-        # (`_get_alerts_config`) re-applies the canonical default of `False`
-        # for the missing key on next get.
+        # 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()
@@ -890,6 +1065,20 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 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
@@ -948,6 +1137,8 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
         "budget.alerts_enabled",
         "budget.alert_thresholds",
         "budget.projected_enabled",
+        "budget.projects",
+        "budget.project_alerts_enabled",
     ):
         # Drop only the named leaf; preserve sibling budget.* keys (e.g.
         # unsetting weekly_usd keeps a customized alert_thresholds). If the