cctally 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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

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
 
@@ -76,6 +77,24 @@ _build_alert_payload_five_hour = _lib_alerts_payload._build_alert_payload_five_h
 _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 ===================================
 # Spec 2026-05-17 §3.3: kernel symbols import from _cctally_core.
@@ -103,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).
+
+    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.
 
-    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.
+    ``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``.
@@ -149,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 {}
@@ -181,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)
@@ -275,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

@@ -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",
@@ -414,6 +416,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`
@@ -505,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
@@ -532,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
@@ -653,6 +681,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
@@ -873,15 +971,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 +998,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

package/bin/_cctally_core.py

@@ -432,8 +432,14 @@ _ALERTS_CONFIG_VALID_KEYS = {
     "weekly_thresholds",
     "five_hour_thresholds",
     "projected_enabled",
+    "notifier",
+    "command_template",
 }
 
+# Dispatch backends (Phase B). "auto" picks a platform default; "command"
+# routes through alerts.command_template (which it then requires).
+_ALERTS_VALID_NOTIFIERS = ("auto", "osascript", "notify-send", "command", "none")
+
 
 def _validate_threshold_list(name: str, value: object) -> "list[int]":
     """Validate one of the alerts threshold lists.
@@ -513,11 +519,47 @@ def _get_alerts_config(cfg: "dict | None") -> dict:
             f"alerts.projected_enabled must be a JSON boolean, got "
             f"{type(projected_enabled).__name__}: {projected_enabled!r}"
         )
+    # Dispatch-global keys (Phase B). `notifier` selects the backend;
+    # `command_template` is an argv list for the `command` backend (and may be
+    # set ahead of switching the backend). The cross-field constraint
+    # (notifier='command' requires a template) is enforced last.
+    notifier = block.get("notifier", "auto")
+    if notifier not in _ALERTS_VALID_NOTIFIERS:
+        raise _AlertsConfigError(
+            f"alerts.notifier must be one of {list(_ALERTS_VALID_NOTIFIERS)}, "
+            f"got {notifier!r}"
+        )
+    command_template = block.get("command_template", None)
+    if command_template is not None:
+        if not isinstance(command_template, list) or not command_template:
+            raise _AlertsConfigError(
+                "alerts.command_template must be null or a non-empty list of strings"
+            )
+        for el in command_template:
+            if not isinstance(el, str):
+                raise _AlertsConfigError(
+                    f"alerts.command_template elements must be strings, "
+                    f"got {type(el).__name__}: {el!r}"
+                )
+            if "\x00" in el:
+                raise _AlertsConfigError(
+                    "alerts.command_template elements must not contain a NUL byte"
+                )
+        if not command_template[0].strip():
+            raise _AlertsConfigError(
+                "alerts.command_template[0] (the program) must not be empty/whitespace"
+            )
+    if notifier == "command" and command_template is None:
+        raise _AlertsConfigError(
+            "alerts.notifier='command' requires alerts.command_template to be set"
+        )
     return {
         "enabled": enabled,
         "weekly_thresholds": weekly,
         "five_hour_thresholds": five_hour,
         "projected_enabled": projected_enabled,
+        "notifier": notifier,
+        "command_template": command_template,
     }
 
 

package/bin/_cctally_dashboard.py

@@ -4687,6 +4687,12 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
             "weekly_thresholds": [],
             "five_hour_thresholds": [],
             "projected_enabled": False,
+            # Mirror the dispatch keys so the new alerts_settings lines
+            # (`notifier` / `command_configured`) don't KeyError on a
+            # corrupt config. Safe defaults: no notifier override, no
+            # configured command.
+            "notifier": "auto",
+            "command_template": None,
         }
     # Budget is its OWN config block (issue #19) — source budget fields
     # from ``_get_budget_config`` (the validated ``budget`` block), NOT
@@ -4708,6 +4714,15 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         # from the validated getters' ``projected_enabled`` (default False).
         "projected_weekly_enabled": bool(_alerts_cfg.get("projected_enabled")),
         "projected_budget_enabled": bool(_budget_cfg.get("projected_enabled")),
+        # Alert-dispatch notifier mirror (Phase B). `notifier` is the
+        # validated backend selector ("auto"/"command"/etc.). The raw
+        # `command_template` is NEVER mirrored — it routinely holds secrets
+        # (webhook URLs, bearer tokens) and the SSE snapshot is broadcast to
+        # every connected client. We expose only a boolean: is a custom
+        # command configured? (the CLI/config remains the sole writer of the
+        # template itself).
+        "notifier":           _alerts_cfg.get("notifier", "auto"),
+        "command_configured": _alerts_cfg.get("command_template") is not None,
     }
 
     # Mirror update-state.json + update-suppress.json into the envelope
@@ -5347,7 +5362,12 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         sent) is the full computed block from ``_compute_display_block``
         (preserves ``tz`` / ``resolved_tz`` / ``offset_label`` /
         ``offset_seconds`` shape consumers rely on). ``alerts`` (when
-        sent) is the full validated block from ``_get_alerts_config``.
+        sent) is the full validated block from ``_get_alerts_config``,
+        except the raw ``command_template`` is redacted to the boolean
+        ``command_configured`` (it routinely holds secrets — webhook URLs
+        / bearer tokens — and the echo is returned to the client; the
+        SSE ``alerts_settings`` mirror redacts identically). Do NOT
+        re-add the raw template to the echo.
         ``saved_at`` is included for backward compat.
         """
         if not self._check_origin_csrf():
@@ -5487,6 +5507,27 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     {"error": "alerts.projected_enabled must be a JSON boolean"},
                 )
                 return
+            # The dispatch command template is CLI/config-only — never
+            # settable via the dashboard (it routinely holds secrets and the
+            # dashboard echoes settings to the client). Reject it explicitly
+            # rather than silently dropping it.
+            if "command_template" in alerts_block:
+                self._respond_json(
+                    400,
+                    {"error": "alerts.command_template is CLI/config-only "
+                              "(not settable via the dashboard)"},
+                )
+                return
+            # `notifier` is settable (the backend selector). Structural type
+            # check only; the enum + cross-field rule (command needs a stored
+            # template) is enforced free by `_get_alerts_config(merged)` below.
+            if "notifier" in alerts_block and not isinstance(
+                alerts_block["notifier"], str
+            ):
+                self._respond_json(
+                    400, {"error": "alerts.notifier must be a string"}
+                )
+                return
 
         # Pre-validate budget shape (the structural type check; full
         # cross-key validation runs inside the lock via
@@ -5602,6 +5643,8 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     merged_alerts["projected_enabled"] = (
                         alerts_in["projected_enabled"]
                     )
+                if "notifier" in alerts_in:
+                    merged_alerts["notifier"] = alerts_in["notifier"]
                 merged["alerts"] = merged_alerts
                 # Final cross-field validation against the merged block.
                 # _AlertsConfigError → 400 (no partial write since
@@ -5703,7 +5746,14 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 merged, dt.datetime.now(dt.timezone.utc)
             )
         if "alerts" in payload:
-            out["alerts"] = _get_alerts_config(merged)
+            # Echo the full validated alerts block (defaults filled) so the
+            # SettingsOverlay can repaint without a follow-up GET — but
+            # redact the raw `command_template` (secrets) the same way the
+            # SSE snapshot mirror does: replace it with a boolean
+            # `command_configured`.
+            _a = dict(_get_alerts_config(merged))
+            _a["command_configured"] = _a.pop("command_template", None) is not None
+            out["alerts"] = _a
         if "budget" in payload:
             # Echo the full validated budget block (defaults filled) so the
             # SettingsOverlay can repaint without a follow-up GET.

package/bin/_lib_alert_axes.py

@@ -3,7 +3,7 @@
 Single source of truth for axis *metadata* — id, chip/title labels (kept
 byte-identical with dashboard/web/src/lib/alertAxis.ts), the milestone-table
 name used by the dashboard envelope, and the axis-uniform severity policy
-(amber <95 / red >=95). This kernel does NOT own the write/transaction path:
+(info <90 / warn 90-99 / critical >=100). This kernel does NOT own the write/transaction path:
 each axis keeps its own detect-and-arm code in bin/_cctally_record.py. The
 descriptor is the metadata/render contract, not the write engine.
 
@@ -14,14 +14,23 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
-# Severity boundary: thresholds at or above this render red, below it amber.
-# Mirrors the legacy hardcoded amber<95 / red>=95 split (axis-uniform v1).
-_SEVERITY_RED_FLOOR = 95
+# Severity bands (Phase B): info < warn floor <= warn < critical floor <= critical.
+# The top tier means "hit the ceiling" (100% weekly = rate-limited, budget 100% =
+# over). Maps onto notify-send's low/normal/critical urgency levels.
+_SEVERITY_WARN_FLOOR = 90
+_SEVERITY_CRITICAL_FLOOR = 100
 
 
 def severity_for(threshold: int) -> str:
-    """Map a crossed integer threshold to a severity color ('amber' | 'red')."""
-    return "red" if int(threshold) >= _SEVERITY_RED_FLOOR else "amber"
+    """Map a crossed integer threshold to a 3-tier severity
+    ('info' | 'warn' | 'critical'). Axis-uniform; the single authority kept
+    byte-identical with dashboard/web/src/lib/alertAxis.ts::alertSeverity."""
+    t = int(threshold)
+    if t >= _SEVERITY_CRITICAL_FLOOR:
+        return "critical"
+    if t >= _SEVERITY_WARN_FLOOR:
+        return "warn"
+    return "info"
 
 
 @dataclass(frozen=True)