cctally 1.24.0 → 1.26.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.26.0] - 2026-06-03
+
+### Added
+- **`cctally budget set --project` now hints the correct argument order when you put the amount after the flag.** Writing the flag-first form `cctally budget set --project 25` binds `25` to the `--project` value (argparse `nargs='?'`) and leaves the amount unset; instead of the generic "`set --project` requires an amount" error, cctally now points you at the supported `cctally budget set 25 --project` ordering. A bare numeric value that names a real directory (e.g. a repo literally called `2025`) is treated as a project path rather than a misplaced amount, so the hint never misfires on a numeric-named repo. The exit code is unchanged (2, a safe no-write failure) and valid invocations are unaffected.
+
+### Changed
+- **Internal refactor (no user-facing change): consolidated the per-project budget label-disambiguation and threshold-crossing arithmetic onto two shared helpers (`_project_budget_labels`, `_project_crossings`), used by the budget table, the alert firing path, the config-write reconcile, and the dashboard SSE envelope, and replaced the share-ranking hidden-`MoneyCell` hack with an explicit `ProjectCell.rank_cost` field.** The firing-path label resolution is now lazy (resolved only when a crossing actually dispatches, off the common no-dispatch tick). Output is byte-identical — the per-project budget reconcile invariants (61/61), the budget/share goldens (26/26), and the full pytest suite are unchanged; nothing to do on upgrade.
+
+## [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

package/bin/_cctally_alerts.py

@@ -70,11 +70,13 @@ _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
@@ -171,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:
@@ -279,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:
@@ -313,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

package/bin/_cctally_config.py

@@ -310,6 +310,8 @@ ALLOWED_CONFIG_KEYS = (
     "budget.alerts_enabled",
     "budget.alert_thresholds",
     "budget.projected_enabled",
+    "budget.projects",
+    "budget.project_alerts_enabled",
 )
 
 
@@ -499,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
@@ -513,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
 
@@ -522,11 +528,12 @@ 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.
+    # `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 == "alerts.command_template":
+        if k in ("alerts.command_template", "budget.projects"):
             return v
         return v if v is not None else ""
 
@@ -555,10 +562,11 @@ def _cmd_config_get(args: argparse.Namespace, config: dict) -> int:
         for k, v in pairs:
             # Preserve canonical bool stringification (true/false) so
             # round-trips via `config set alerts.enabled <plain-text>` work.
-            if k == "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).
+            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"
@@ -869,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
@@ -888,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
@@ -900,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]" = []
@@ -941,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}")
@@ -1070,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

package/bin/_cctally_core.py

@@ -575,12 +575,16 @@ _BUDGET_DEFAULTS = {
     "alerts_enabled": True,        # "on when set"
     "alert_thresholds": [90, 100],
     "projected_enabled": False,    # projected-pace opt-in (#121); default OFF
+    "projects": {},               # per-project weekly $ budgets, keyed by git-root
+    "project_alerts_enabled": False,  # per-project alerts opt-in (#19/#121); default OFF
 }
 _BUDGET_CONFIG_VALID_KEYS = {
     "weekly_usd",
     "alerts_enabled",
     "alert_thresholds",
     "projected_enabled",
+    "projects",
+    "project_alerts_enabled",
 }
 
 
@@ -593,6 +597,7 @@ def _get_budget_config(cfg: dict) -> dict:
     """
     out = dict(_BUDGET_DEFAULTS)
     out["alert_thresholds"] = list(_BUDGET_DEFAULTS["alert_thresholds"])
+    out["projects"] = dict(_BUDGET_DEFAULTS["projects"])
     block = cfg.get("budget") if isinstance(cfg, dict) else None
     if block is None:
         return out
@@ -648,6 +653,41 @@ def _get_budget_config(cfg: dict) -> dict:
             raise _BudgetConfigError("budget.projected_enabled must be a boolean")
         out["projected_enabled"] = v
 
+    if "projects" in block:
+        v = block["projects"]
+        if not isinstance(v, dict):
+            raise _BudgetConfigError(
+                f"budget.projects must be an object, got {type(v).__name__}"
+            )
+        cleaned: "dict[str, float]" = {}
+        for proj_key, proj_val in v.items():
+            if not isinstance(proj_key, str):
+                raise _BudgetConfigError(
+                    "budget.projects keys must be strings (canonical git-root paths)"
+                )
+            # Reuse the weekly_usd numeric rule per value: a non-bool finite
+            # number > 0 (bool is an int subclass, so reject it explicitly).
+            if isinstance(proj_val, bool) or not isinstance(proj_val, (int, float)):
+                raise _BudgetConfigError(
+                    f"budget.projects values must be numbers, "
+                    f"got {type(proj_val).__name__} for key {proj_key!r}"
+                )
+            if not math.isfinite(float(proj_val)) or float(proj_val) <= 0:
+                raise _BudgetConfigError(
+                    f"budget.projects values must be finite numbers > 0, "
+                    f"got {proj_val!r} for key {proj_key!r}"
+                )
+            cleaned[proj_key] = float(proj_val)
+        out["projects"] = cleaned
+
+    if "project_alerts_enabled" in block:
+        v = block["project_alerts_enabled"]
+        if not isinstance(v, bool):
+            raise _BudgetConfigError(
+                "budget.project_alerts_enabled must be a boolean"
+            )
+        out["project_alerts_enabled"] = v
+
     return out
 
 
@@ -1127,6 +1167,42 @@ def open_db() -> sqlite3.Connection:
         """
     )
 
+    # ── project_budget_milestones (per-project equiv-$ budget crossings) ──────
+    # Plain CREATE TABLE IF NOT EXISTS, NO migration handler / backfill — the
+    # same posture as `budget_milestones` / `projected_milestones` (write-once,
+    # forward-only, framework-untracked). `project_key` is the NEW dimension in
+    # the UNIQUE key: each project crosses each threshold once per week,
+    # independently of every other project (issue #19 / #121, spec §5.1). It
+    # stores the canonical git-root (`ProjectKey.bucket_path`), matched by string
+    # equality against each session entry's resolved git-root. `budget_usd`
+    # snapshots the project's target AT crossing time so the dashboard renders
+    # "$26 of $25" from the ROW, not from live config that may have changed since
+    # (the Codex P0-4 lesson, already baked into `budget_milestones` /
+    # `projected_milestones`). A mid-week quota reset re-anchors `week_start_at`
+    # (new window → fresh rows under the UNIQUE key) — budget-pattern reset
+    # handling, hence NO `reset_event_id` segment column. `alerted_at` is stamped
+    # BEFORE dispatch (set-then-dispatch invariant); NULL = "recorded without
+    # dispatch" (forward-only-from-set reconcile) OR "not yet dispatched", never
+    # "delivery failed". Lives BEFORE the migration dispatcher: a plain CREATE on
+    # a framework-untracked table never touches `schema_migrations`, so the
+    # dispatcher's fresh-install snapshot is unaffected.
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS project_budget_milestones (
+            id              INTEGER PRIMARY KEY AUTOINCREMENT,
+            week_start_at   TEXT    NOT NULL,
+            project_key     TEXT    NOT NULL,   -- canonical git-root (bucket_path)
+            threshold       INTEGER NOT NULL,
+            budget_usd      REAL    NOT NULL,   -- project's target snapshotted AT crossing
+            spent_usd       REAL    NOT NULL,
+            consumption_pct REAL    NOT NULL,
+            crossed_at_utc  TEXT    NOT NULL,
+            alerted_at      TEXT,
+            UNIQUE(week_start_at, project_key, threshold)
+        )
+        """
+    )
+
     # Migration framework dispatcher. Replaces the prior inline gate stack
     # (has_blocks + _migration_done) with the framework's _run_pending_-
     # migrations entry point. See spec §2.3, §5.2 + the migration handlers

package/bin/_cctally_dashboard.py

@@ -340,6 +340,12 @@ def _build_alert_payload_projected(*args, **kwargs):
     return sys.modules["cctally"]._build_alert_payload_projected(*args, **kwargs)
 
 
+def _build_alert_payload_project_budget(*args, **kwargs):
+    return sys.modules["cctally"]._build_alert_payload_project_budget(
+        *args, **kwargs
+    )
+
+
 def _dispatch_alert_notification(*args, **kwargs):
     return sys.modules["cctally"]._dispatch_alert_notification(*args, **kwargs)
 
@@ -4252,6 +4258,66 @@ def _envelope_rows_projected(conn, descriptor, limit, severity_for) -> list[dict
     return out
 
 
+def _envelope_rows_project_budget(conn, descriptor, limit, severity_for) -> list[dict]:
+    # Fifth axis (issue #19 / #121): PER-PROJECT equiv-$ budget threshold
+    # crossings. Like the global budget axis, project-budget alerts re-anchor
+    # ``week_start_at`` on a mid-week reset, so there is NO ``reset_event_id``
+    # segment — the new window gets fresh rows under
+    # ``UNIQUE(week_start_at, project_key, threshold)``. ``project_key`` is the
+    # canonical git-root (``ProjectKey.bucket_path``); the human-readable chip
+    # context carries the project BASENAME, resolved through the production
+    # ``_resolve_project_key`` (git-root mode) so a moved/deleted repo still
+    # renders its basename from the snapshotted path (no FS dependency on a
+    # live ``.git``). ``budget_usd`` / ``spent_usd`` / ``consumption_pct`` are
+    # rendered FROM THE ROW (snapshotted at crossing), never live config that
+    # may have changed since (Codex P0-4). The envelope id mirrors the dispatch
+    # payload's ``project_budget:<week_start_at>:<project_key>:<threshold>``
+    # shape (``_build_alert_payload_project_budget``).
+    rows = conn.execute(
+        f"""
+        SELECT week_start_at, project_key, threshold, budget_usd, spent_usd,
+               consumption_pct, crossed_at_utc, alerted_at
+        FROM {descriptor.milestone_table}
+        WHERE alerted_at IS NOT NULL
+        ORDER BY alerted_at DESC
+        LIMIT ?
+        """,
+        (limit,),
+    ).fetchall()
+    c = _cctally()
+    # Collision-aware labels via the shared primitive (#130), disambiguated
+    # across the alerted ROWS (NOT live config) to preserve the
+    # render-from-the-snapshotted-row invariant above — so a deleted/renamed
+    # config key still renders. This is intentionally a different feed than the
+    # table/notification (full config); see spec §1 Goals (Codex F1).
+    label_by_key = c._project_budget_labels(
+        sorted({r["project_key"] for r in rows})
+    )
+    out: list[dict] = []
+    for r in rows:
+        threshold = int(r["threshold"])
+        project_key = r["project_key"]
+        out.append({
+            "id": (
+                f"project_budget:{r['week_start_at']}:{project_key}:{threshold}"
+            ),
+            "axis":       descriptor.id,
+            "threshold":  threshold,
+            "severity":   severity_for(threshold),
+            "crossed_at": r["crossed_at_utc"],
+            "alerted_at": r["alerted_at"],
+            "context": {
+                "week_start_at":   r["week_start_at"],
+                "project":         label_by_key.get(project_key, project_key),
+                "project_key":     project_key,
+                "budget_usd":      float(r["budget_usd"]),
+                "spent_usd":       float(r["spent_usd"]),
+                "consumption_pct": float(r["consumption_pct"]),
+            },
+        })
+    return out
+
+
 # Keyed by ``AlertAxisDescriptor.id`` — the registry decides which axes run,
 # in what order; this table supplies the bespoke heterogeneous row-mapper.
 _ENVELOPE_AXIS_MAPPERS = {
@@ -4259,6 +4325,7 @@ _ENVELOPE_AXIS_MAPPERS = {
     "five_hour": _envelope_rows_five_hour,
     "budget": _envelope_rows_budget,
     "projected": _envelope_rows_projected,
+    "project_budget": _envelope_rows_project_budget,
 }
 
 
@@ -4269,19 +4336,20 @@ def _build_alerts_envelope_array(
     """Return the ``alerts`` array for the SSE snapshot envelope.
 
     Union of ``percent_milestones``, ``five_hour_milestones``,
-    ``budget_milestones``, and ``projected_milestones`` rows with
-    ``alerted_at IS NOT NULL``, ordered newest-first by ``alerted_at``,
-    capped at ``limit`` (default 100). Single source of truth for both the
-    dashboard panel (slices to 10 client-side) and the modal (renders all
-    100). Forward-only semantics: only rows the alert-dispatch path stamped
-    get included; pre-deploy crossings stay NULL and are intentionally
-    invisible (spec §4.3).
-
-    All four axes share the same envelope schema; the ``axis`` field
-    (``weekly`` / ``five_hour`` / ``budget`` / ``projected``) discriminates.
-    The ``projected`` axis additionally carries a top-level ``metric``
-    (``weekly_pct`` | ``budget_usd``) so the frontend can pick its
-    metric-aware context renderer.
+    ``budget_milestones``, ``projected_milestones``, and
+    ``project_budget_milestones`` rows with ``alerted_at IS NOT NULL``,
+    ordered newest-first by ``alerted_at``, capped at ``limit`` (default 100).
+    Single source of truth for both the dashboard panel (slices to 10
+    client-side) and the modal (renders all 100). Forward-only semantics: only
+    rows the alert-dispatch path stamped get included; pre-deploy crossings
+    stay NULL and are intentionally invisible (spec §4.3).
+
+    All five axes share the same envelope schema; the ``axis`` field
+    (``weekly`` / ``five_hour`` / ``budget`` / ``projected`` /
+    ``project_budget``) discriminates. The ``projected`` axis additionally
+    carries a top-level ``metric`` (``weekly_pct`` | ``budget_usd``) so the
+    frontend can pick its metric-aware context renderer; ``project_budget``
+    carries the project basename + ``$spent of $budget`` in its context.
 
     Per-axis ``LIMIT`` is applied at the SQL level (each query may yield
     up to ``limit``) and the union is re-sorted + sliced — important for
@@ -4702,7 +4770,8 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         _budget_cfg = _get_budget_config(_cfg_for_alerts)
     except _BudgetConfigError:
         _budget_cfg = {"weekly_usd": None, "alerts_enabled": True,
-                       "alert_thresholds": [], "projected_enabled": False}
+                       "alert_thresholds": [], "projected_enabled": False,
+                       "projects": {}, "project_alerts_enabled": False}
     alerts_settings = {
         "enabled":              _alerts_cfg["enabled"],
         "weekly_thresholds":    list(_alerts_cfg["weekly_thresholds"]),
@@ -4714,6 +4783,12 @@ 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")),
+        # Per-project budget alerts opt-in mirror (issue #19 / #121). Gates the
+        # ``project_budget`` axis dispatch only (the display section always
+        # renders configured projects). Sourced from the validated budget
+        # getter's ``project_alerts_enabled`` (default False) — the frontend
+        # SettingsOverlay seeds a single on/off toggle from it.
+        "project_alerts_enabled": bool(_budget_cfg.get("project_alerts_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
@@ -5673,7 +5748,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 budget_in = payload["budget"]
                 for leaf in (
                     "weekly_usd", "alerts_enabled", "alert_thresholds",
-                    "projected_enabled",
+                    "projected_enabled", "project_alerts_enabled",
                 ):
                     if leaf in budget_in:
                         merged_budget[leaf] = budget_in[leaf]
@@ -5766,7 +5841,23 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             # Runs AFTER save_config (config persisted first); best-effort —
             # never breaks the 200 response. Config write already left the
             # config_writer_lock, so the helper's open_db never nests.
-            _cctally()._reconcile_budget_on_config_write(validated_budget)
+            #
+            # Gate each axis on the touched leaves (parity with `config set`):
+            # running on an unrelated leaf would latch a currently-over-but-
+            # not-yet-dispatched threshold, permanently suppressing the next
+            # tick's dispatch. The dashboard accepts no `projects` leaf (the
+            # map is CLI-only), so the per-project axis keys on
+            # project_alerts_enabled/alert_thresholds.
+            budget_in = payload["budget"]
+            touched = (
+                set(budget_in.keys()) if isinstance(budget_in, dict) else set()
+            )
+            if touched & {"weekly_usd", "alerts_enabled", "alert_thresholds"}:
+                _cctally()._reconcile_budget_on_config_write(validated_budget)
+            if touched & {"project_alerts_enabled", "alert_thresholds"}:
+                _cctally()._reconcile_project_budget_milestones_on_write(
+                    validated_budget
+                )
         if update_check_validated is not None:
             # Echo the full merged check block (cooked defaults included)
             # so the SettingsOverlay can repaint without a follow-up GET.
@@ -5818,11 +5909,13 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         dispatch status string in the JSON response.
 
         Body (all fields optional): ``{"axis":
-        "weekly"|"five_hour"|"budget"|"projected", "threshold": 1..100,
-        "metric": "weekly_pct"|"budget_usd"}``. Defaults: axis="weekly",
-        threshold=90, metric="weekly_pct". ``metric`` is only consulted for
-        the ``projected`` axis (mirrors the CLI ``alerts test --axis
-        projected --metric`` surface); it is ignored for the other axes.
+        "weekly"|"five_hour"|"budget"|"projected"|"project_budget",
+        "threshold": 1..100, "metric": "weekly_pct"|"budget_usd"}``. Defaults:
+        axis="weekly", threshold=90, metric="weekly_pct". ``metric`` is only
+        consulted for the ``projected`` axis (mirrors the CLI ``alerts test
+        --axis projected --metric`` surface); it is ignored for the other
+        axes. The ``project_budget`` axis dispatches a synthetic example
+        project ($26 of $25) — no real ``budget.projects`` entry required.
 
         IMPORTANT: ``axis`` uses the underscore form (``"five_hour"``)
         in the JSON API to match the dispatch payload's internal axis
@@ -5861,12 +5954,14 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 return
 
         axis = body.get("axis", "weekly")
-        if axis not in ("weekly", "five_hour", "budget", "projected"):
+        if axis not in (
+            "weekly", "five_hour", "budget", "projected", "project_budget",
+        ):
             self._respond_json(
                 400,
                 {"error": (
-                    "axis must be 'weekly', 'five_hour', 'budget' or "
-                    f"'projected', got {axis!r}"
+                    "axis must be 'weekly', 'five_hour', 'budget', "
+                    f"'projected' or 'project_budget', got {axis!r}"
                 )},
             )
             return
@@ -5917,6 +6012,22 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 spent_usd=300.0 * threshold / 100.0,
                 consumption_pct=float(threshold),
             )
+        elif axis == "project_budget":
+            # Synthetic per-project budget payload — mirrors the CLI
+            # ``alerts test --axis project_budget`` branch (NO DB writes,
+            # test/real divergence contract). Uses a fixed example project
+            # ($26 of $25 = 104%) so no real ``budget.projects`` entry is
+            # required; ``project_key`` is a placeholder canonical path.
+            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 — mirrors the CLI
             # cmd_alerts_test projected branch (NO DB writes, test/real