cctally 1.23.0 → 1.25.0

package/bin/_cctally_milestones.py

@@ -369,6 +369,52 @@ def insert_budget_milestone(
     return int(cur.rowcount)
 
 
+def insert_project_budget_milestone(
+    conn: sqlite3.Connection,
+    *,
+    week_start_at: str,
+    project_key: str,
+    threshold: int,
+    budget_usd: float,
+    spent_usd: float,
+    consumption_pct: float,
+    commit: bool = True,
+) -> int:
+    """INSERT OR IGNORE a per-project budget threshold crossing. Returns
+    ``cur.rowcount`` (1 = genuinely new crossing, 0 = INSERT OR IGNORE no-op on a
+    pre-existing ``(week_start_at, project_key, threshold)`` row).
+
+    Mirrors :func:`insert_budget_milestone` EXACTLY, with ``project_key`` added
+    as the per-project dimension of the UNIQUE dedup key (spec §5.1) — each
+    project crosses each threshold once per week, independently. The rowcount
+    contract matches :func:`insert_percent_milestone` so the alert-fire predicate
+    (`if inserted == 1`) is race-safe without a follow-up SELECT. ``alerted_at``
+    is left NULL — the caller stamps it in the SAME transaction BEFORE
+    dispatching (set-then-dispatch invariant, CLAUDE.md Alerts gotcha).
+    ``commit=False`` lets the caller bundle the INSERT with the follow-up
+    ``alerted_at`` UPDATE in one transaction so a crash between them can't strand
+    ``alerted_at`` NULL forever.
+    """
+    cur = conn.execute(
+        "INSERT OR IGNORE INTO project_budget_milestones "
+        "(week_start_at, project_key, threshold, budget_usd, spent_usd, "
+        " consumption_pct, crossed_at_utc) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?)",
+        (
+            week_start_at,
+            str(project_key),
+            int(threshold),
+            float(budget_usd),
+            float(spent_usd),
+            float(consumption_pct),
+            now_utc_iso(),
+        ),
+    )
+    if commit:
+        conn.commit()
+    return int(cur.rowcount)
+
+
 def insert_projected_milestone(
     conn: sqlite3.Connection,
     *,
@@ -499,3 +545,103 @@ def _reconcile_budget_on_config_write(validated_budget):
             conn.close()
     except Exception as exc:  # best-effort; never fail the write
         eprint(f"[budget-milestone] reconcile on set failed: {exc}")
+
+
+def _reconcile_project_budget_milestones_on_write(
+    validated_budget, touched_projects=None
+):
+    """Forward-only-from-write reconcile for PER-PROJECT budgets (spec §6.8).
+
+    Shared by all four per-project write surfaces: ``budget set --project`` /
+    ``unset --project`` (call sites in ``_cmd_budget_set_project`` /
+    ``_cmd_budget_unset_project``), ``config set budget.projects`` /
+    ``config set budget.project_alerts_enabled`` (call site in
+    ``_cmd_config_set``), and the dashboard ``project_alerts_enabled`` toggle
+    (POST /api/settings, Task 4). Mirrors :func:`_reconcile_budget_on_config_write`.
+
+    Mechanic: for each configured project, compute current-week spend (the
+    shared ``_sum_cost_by_project`` scan), and for each ALREADY-crossed
+    ``(project, threshold)`` ``INSERT OR IGNORE`` a milestone with ``alerted_at``
+    stamped and **NO dispatch** — so setting a project budget mid-week (already
+    over) records the crossed thresholds as already-alerted without an
+    instant-popup; only LATER crossings fire via
+    :func:`maybe_record_project_budget_milestone`.
+
+    Dedup via ``UNIQUE(week_start_at, project_key, threshold)`` + the
+    ``alerted_at IS NULL`` UPDATE guard, so a mid-week TARGET change never
+    re-stamps an already-alerted row (mirrors the global reconcile's
+    target-change semantics).
+
+    Gated: runs ONLY when per-project alerts are active (``projects`` non-empty
+    **and** ``project_alerts_enabled`` **and** ``alert_thresholds`` non-empty);
+    else records nothing. Best-effort — a stats.db failure never fails the config
+    write. Runs OUTSIDE any ``config_writer_lock`` (``open_db`` has its own
+    locking).
+
+    ``touched_projects``: when not ``None``, reconcile ONLY these project keys.
+    The single-project CLI writes (``budget set/unset --project``) pass
+    ``{root}`` so touching project A never latches a sibling project B's
+    already-crossed-but-not-yet-dispatched threshold — which would permanently
+    suppress B's real alert. ``None`` (config-set / dashboard toggle / wholesale
+    ``budget.projects`` set) reconciles every configured project: the intended
+    "axis enabled / map redefined → suppress the retroactive storm for all
+    currently-over projects" semantics.
+    """
+    projects = (validated_budget or {}).get("projects") or {}
+    thresholds = validated_budget.get("alert_thresholds") or []
+    if not (
+        projects
+        and validated_budget.get("project_alerts_enabled")
+        and thresholds
+    ):
+        return
+    c = _cctally()
+    try:
+        conn = open_db()
+        try:
+            now_utc = _command_as_of()
+            window = c._resolve_current_budget_window(conn, now_utc)
+            if window is None:
+                return
+            week_start_at, _week_end_at = window
+            week_key = week_start_at.isoformat(timespec="seconds")
+            by_proj = c._sum_cost_by_project(week_start_at, now_utc, mode="auto")
+            items = (
+                projects.items()
+                if touched_projects is None
+                else [
+                    (k, v) for k, v in projects.items()
+                    if k in touched_projects
+                ]
+            )
+            for project_key, target in items:
+                spent = float(by_proj.get(project_key, 0.0))
+                target = float(target)
+                consumption_pct = (
+                    (spent / target * 100.0) if target > 0 else 0.0
+                )
+                for t in sorted(thresholds):
+                    if consumption_pct + 1e-9 >= t:
+                        insert_project_budget_milestone(
+                            conn,
+                            week_start_at=week_key,
+                            project_key=project_key,
+                            threshold=t,
+                            budget_usd=target,
+                            spent_usd=spent,
+                            consumption_pct=consumption_pct,
+                            commit=False,
+                        )
+                        conn.execute(
+                            "UPDATE project_budget_milestones SET alerted_at = ? "
+                            "WHERE week_start_at = ? AND project_key = ? "
+                            "  AND threshold = ? AND alerted_at IS NULL",
+                            (now_utc_iso(), week_key, project_key, t),
+                        )
+            conn.commit()
+        finally:
+            conn.close()
+    except Exception as exc:  # best-effort; never fail the write
+        eprint(
+            f"[project-budget-milestone] reconcile on write failed: {exc}"
+        )

package/bin/_cctally_parser.py

@@ -1273,6 +1273,7 @@ def build_parser() -> argparse.ArgumentParser:
               cctally budget
               cctally budget set 300
               cctally budget unset
+              cctally budget set 25 --project
               cctally budget --json
               cctally budget --format md
             """
@@ -1285,9 +1286,13 @@ def build_parser() -> argparse.ArgumentParser:
     bg.add_argument("--config", default=None,
                     help="Read status from this config file (read-only; "
                          "rejected on set/unset).")
+    bg.add_argument(
+        "--project", nargs="?", const="__CWD__", default=None,
+        help="Set/unset a per-project budget for this git repo "
+             "(bare = current directory's git-root; or pass a path).")
     bg.add_argument("--reveal-projects", action="store_true", dest="reveal_projects",
-                    help="Accepted for --format surface parity; inert for budget "
-                         "(no per-project axis).")
+                    help="Show real project basenames in the per-project section "
+                         "of --format output (default anonymizes to project-1/…).")
     bg.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
                     help="Display timezone: local, utc, or IANA name. "
                          "Overrides config display.tz for this call.")
@@ -2186,15 +2191,17 @@ def build_parser() -> argparse.ArgumentParser:
               cctally alerts test
               cctally alerts test --axis five-hour --threshold 95
               cctally alerts test --axis budget --threshold 100
+              cctally alerts test --axis project-budget --threshold 100
               cctally alerts test --axis projected --metric budget_usd
         """),
     )
     p_alerts_test.add_argument(
         "--axis",
-        choices=["weekly", "five-hour", "budget", "projected"],
+        choices=["weekly", "five-hour", "budget", "project-budget", "projected"],
         default="weekly",
         help="Alert axis to simulate: weekly subscription window, 5h block, "
-             "equiv-$ budget, or projected-pace (default: weekly).",
+             "equiv-$ budget, per-project equiv-$ budget, or projected-pace "
+             "(default: weekly).",
     )
     p_alerts_test.add_argument(
         "--threshold",

package/bin/_cctally_project.py

@@ -81,6 +81,57 @@ def _load_week_snapshots(
         conn.close()
 
 
+def _sum_cost_by_project(
+    start: dt.datetime,
+    now: dt.datetime,
+    mode: str = "auto",
+    skip_sync: bool = False,
+) -> dict[str, float]:
+    """Return ``{canonical_git_root: spent_usd}`` over ``[start, now]``.
+
+    ONE scan over the joined session entries (the same iterator
+    ``cmd_project`` walks), bucketed in Python by each entry's resolved
+    git-root (``_resolve_project_key`` — a filesystem ``.git`` walk, NOT a
+    SQL ``GROUP BY``), with per-entry cost computed via the same
+    ``_calculate_entry_cost(model, usage, mode=...)`` path ``cmd_project``
+    uses (so pricing edits flow through uniformly). Keys are the resolved
+    ``ProjectKey.bucket_path`` (the canonical git-root when a ``.git`` is
+    found, else the normalized path) — identical to how ``cmd_project``
+    keys its rows, so configured ``budget.projects`` keys match by string
+    equality.
+
+    Synthetic entries (Claude Code internal markers) are skipped, mirroring
+    ``cmd_project`` / the other ``_JoinedClaudeEntry`` aggregators. A
+    configured project with no in-range entry simply never appears in the
+    returned map (the caller renders it as a ``$0`` row — spec §7.2).
+
+    Shared by the per-project budget display (§7.2, ``cmd_budget``) and the
+    alert-firing path (§6.4); ``skip_sync`` threads through to
+    ``get_claude_session_entries`` so the record-tick caller can reuse a
+    cache already warmed earlier in the same tick.
+    """
+    c = _cctally()
+    resolver_cache: dict[str, ProjectKey] = {}
+    out: dict[str, float] = {}
+    for entry in c.get_claude_session_entries(start, now, skip_sync=skip_sync):
+        if entry.model == "<synthetic>":
+            continue
+        cost = c._calculate_entry_cost(
+            entry.model,
+            {
+                "input_tokens": entry.input_tokens,
+                "output_tokens": entry.output_tokens,
+                "cache_creation_input_tokens": entry.cache_creation_tokens,
+                "cache_read_input_tokens": entry.cache_read_tokens,
+            },
+            mode=mode,
+            cost_usd=entry.cost_usd,
+        )
+        key = c._resolve_project_key(entry.project_path, "git-root", resolver_cache)
+        out[key.bucket_path] = out.get(key.bucket_path, 0.0) + cost
+    return out
+
+
 def _accumulate_entry_into_bucket(
     b: dict,
     entry: "_JoinedClaudeEntry",

package/bin/_cctally_record.py

@@ -265,6 +265,26 @@ def _build_alert_payload_budget(*args, **kwargs):
     return sys.modules["cctally"]._build_alert_payload_budget(*args, **kwargs)
 
 
+def _build_alert_payload_project_budget(*args, **kwargs):
+    return sys.modules["cctally"]._build_alert_payload_project_budget(*args, **kwargs)
+
+
+def _sum_cost_by_project(*args, **kwargs):
+    return sys.modules["cctally"]._sum_cost_by_project(*args, **kwargs)
+
+
+def insert_project_budget_milestone(*args, **kwargs):
+    return sys.modules["cctally"].insert_project_budget_milestone(*args, **kwargs)
+
+
+def _resolve_project_key(*args, **kwargs):
+    return sys.modules["cctally"]._resolve_project_key(*args, **kwargs)
+
+
+def _project_disambiguate_labels(*args, **kwargs):
+    return sys.modules["cctally"]._project_disambiguate_labels(*args, **kwargs)
+
+
 def _get_budget_config(*args, **kwargs):
     return sys.modules["cctally"]._get_budget_config(*args, **kwargs)
 
@@ -820,6 +840,180 @@ def maybe_record_budget_milestone(saved: dict[str, Any]) -> None:
             eprint(f"[budget-alerts] dispatch failed: {dispatch_exc}")
 
 
+def maybe_record_project_budget_milestone(saved: dict[str, Any]) -> None:
+    """Fire PER-PROJECT equiv-$ budget alerts on ACTUAL-spend threshold
+    crossings (spec §6 — called from ``cmd_record_usage`` alongside the
+    weekly-% / 5h-% / budget / projected milestone helpers). An independent
+    helper (its own ``load_config()`` / ``open_db()``), matching the existing
+    per-axis structure — NOT fused into ``maybe_record_budget_milestone``.
+
+    Gated, hot-path-cheap, pre-probed, set-then-dispatch, fire-once. Errors are
+    logged, not raised (the caller also wraps).
+
+    ``saved`` is accepted for call-site symmetry with the sibling helpers but is
+    unused: each project's live spend is resolved from ``session_entries`` via
+    the shared ``_sum_cost_by_project`` scan, independent of the just-recorded
+    7d-% snapshot.
+
+    Invariants preserved byte-for-byte with the global budget path: gate-first,
+    pre-probe-before-the-cost-scan, ``rowcount==1`` race guard, set-then-dispatch.
+    The cost source is ``_sum_cost_by_project`` (NOT ``_sum_cost_for_range``): it
+    skips ``<synthetic>`` entries + buckets by canonical git-root, matching
+    ``cmd_project`` and the per-project DISPLAY — so the firing path reconciles
+    exactly with the displayed ``consumption_pct``.
+    """
+    # Gate FIRST (hot-path discipline): no per-project budget OR per-project
+    # alerts off → zero overhead for non-users. `load_config()` is safe outside
+    # any writer lock (atomic-rename). A malformed budget block is a quiet
+    # warn-once no-op (mirrors maybe_record_budget_milestone).
+    try:
+        budget_cfg = _get_budget_config(load_config())
+    except _BudgetConfigError as exc:
+        _warn_budget_bad_config_once(exc)
+        return
+    projects = budget_cfg.get("projects") or {}
+    if not projects or not budget_cfg.get("project_alerts_enabled"):
+        return
+    thresholds = budget_cfg["alert_thresholds"]
+    if not thresholds:
+        return
+
+    now_utc = _command_as_of()
+    pending_alerts: list[dict[str, Any]] = []
+    conn = open_db()
+    try:
+        window = _resolve_current_budget_window(conn, now_utc)
+        if window is None:
+            return  # no resolvable week window yet
+        week_start_at, _week_end_at = window
+        week_key = week_start_at.isoformat(timespec="seconds")
+
+        # Pre-probe (hot-path discipline + [Dedup mustn't gate side effects]):
+        # which configured (project, threshold) pairs are STILL un-recorded for
+        # this week? The cost scan is skipped ONLY when EVERY pair already has a
+        # row — so a partial prior run (some-but-not-all pairs) still scans for
+        # the remainder. The skip never owes a crossing: an un-recorded pair
+        # always forces the scan.
+        recorded = {
+            (str(r[0]), int(r[1]))
+            for r in conn.execute(
+                "SELECT project_key, threshold "
+                "FROM project_budget_milestones WHERE week_start_at = ?",
+                (week_key,),
+            )
+        }
+        sorted_thresholds = sorted(thresholds)
+        pending = [
+            (p, t)
+            for p in projects
+            for t in sorted_thresholds
+            if (p, t) not in recorded
+        ]
+        if not pending:
+            return  # nothing left to cross this week → skip the cost scan
+
+        # Resolve every configured key to its ProjectKey ONCE, then route the
+        # firing-path labels through the SAME collision-disambiguation primitive
+        # the display uses (`_build_project_budget_rows` → `cmd_project`'s table
+        # / share snapshot). A bare `display_key` is just the basename, so a
+        # uniquely-named project keeps its bare basename in the notification —
+        # byte-matching the table + dashboard chip — and only same-basename
+        # roots (`/work/app` + `/personal/app`) get the `(parent)` segment
+        # ("app (work)" / "app (personal)"). The configured set is small + the
+        # resolver caches, so this is near-free on the rare crossing tick.
+        resolver_cache: dict = {}
+        proj_keys = sorted(projects)
+        pkeys = [
+            _resolve_project_key(p, "git-root", resolver_cache)
+            for p in proj_keys
+        ]
+        disambig = _project_disambiguate_labels(
+            [{"key": pk} for pk in pkeys]
+        )
+        label_by_key = {
+            proj_keys[i]: disambig.get(i, pkeys[i].display_key)
+            for i in range(len(proj_keys))
+        }
+
+        # ONE grouped scan over the week's session entries, bucketed by
+        # canonical git-root. skip_sync=False (self-sufficient): the global
+        # budget axis only warms the cache when `budget.weekly_usd` is set, so a
+        # project-only user (no global budget) reaches here with a cold cache on
+        # a no-5h-anchor tick — sync here or a crossing fires a tick late. The
+        # pre-probe above already gated this scan to the rare pending-crossing
+        # tick, so the self-sufficient sync is near-free.
+        by_proj = _sum_cost_by_project(
+            week_start_at, now_utc, mode="auto", skip_sync=False
+        )
+        for project_key, t in pending:
+            spent = float(by_proj.get(project_key, 0.0))
+            target = float(projects[project_key])
+            # +1e-9 snap-up: spent/target*100 can land one ULP below an integer
+            # threshold (CLAUDE.md float-floor gotcha).
+            consumption_pct = (spent / target * 100.0) if target > 0 else 0.0
+            if consumption_pct + 1e-9 >= t:
+                inserted = insert_project_budget_milestone(
+                    conn,
+                    week_start_at=week_key,
+                    project_key=project_key,
+                    threshold=t,
+                    budget_usd=target,
+                    spent_usd=spent,
+                    consumption_pct=consumption_pct,
+                    commit=False,
+                )
+                # Only the genuine-new-crossing winner (rowcount==1) dispatches;
+                # a racing record-usage instance gets rowcount==0 and skips.
+                if inserted == 1:
+                    crossed_at = now_utc_iso()
+                    # set-then-dispatch: alerted_at lands on the row BEFORE the
+                    # Popen, sharing this transaction with the INSERT
+                    # (commit=False). `alerted_at IS NULL` is write-once
+                    # defense-in-depth.
+                    conn.execute(
+                        "UPDATE project_budget_milestones SET alerted_at = ? "
+                        "WHERE week_start_at = ? AND project_key = ? "
+                        "  AND threshold = ? AND alerted_at IS NULL",
+                        (crossed_at, week_key, project_key, t),
+                    )
+                    # Label is collision-aware, byte-matching the display: a
+                    # uniquely-named project notifies as its bare basename,
+                    # only same-basename roots get the `(parent)` segment (the
+                    # `label_by_key` map built above via the shared
+                    # `_project_disambiguate_labels` primitive, spec §5.3).
+                    project_label = label_by_key.get(
+                        project_key, os.path.basename(project_key) or project_key
+                    )
+                    pending_alerts.append(_build_alert_payload_project_budget(
+                        threshold=t,
+                        crossed_at_utc=crossed_at,
+                        week_start_at=week_key,
+                        project=project_label,
+                        project_key=project_key,
+                        budget_usd=target,
+                        spent_usd=spent,
+                        consumption_pct=consumption_pct,
+                    ))
+        # Single commit: every INSERT + its alerted_at marker durable together.
+        conn.commit()
+    except Exception as exc:
+        eprint(
+            f"[project-budget-milestone] error recording project budget "
+            f"milestone: {exc}"
+        )
+    finally:
+        conn.close()
+
+    # Dispatch AFTER commit; a dispatch failure NEVER rolls back the milestone
+    # (set-then-dispatch invariant — one queue attempt per crossing, deduped on
+    # the alerted_at column).
+    for payload in pending_alerts:
+        try:
+            _dispatch_alert_notification(payload, mode="real")
+        except Exception as dispatch_exc:
+            eprint(f"[project-budget-alerts] dispatch failed: {dispatch_exc}")
+
+
 def _weekly_pct_week_avg_projection(conn, now_utc):
     """Compute the week-AVERAGE weekly-% projection for the current
     subscription week, snapshot-only (CHEAP — no cost SUM, no ``sync_cache``).
@@ -2486,6 +2680,7 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                 ).fetchone()
                 if latest_row is None:
                     return 0
+                latest_saved = _saved_dict_from_usage_row(latest_row)
 
                 # Probe 1: do we owe a percent milestone? Snap up before
                 # floor (status-line API returns 0.N*100 which can fall
@@ -2599,7 +2794,6 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                 heal_conn.close()
 
             if need_milestone_heal or need_5h_heal:
-                latest_saved = _saved_dict_from_usage_row(latest_row)
                 if need_milestone_heal:
                     try:
                         maybe_record_milestone(latest_saved)
@@ -2610,6 +2804,27 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                         maybe_update_five_hour_block(latest_saved)
                     except Exception as exc:
                         eprint(f"[5h-block] self-heal error: {exc}")
+
+            # Dollar-decoupled axes (budget / project-budget / projected) heal on
+            # EVERY dedup tick — USD spend can cross a $ threshold while the
+            # weekly/5h percent is flat (so should_insert is False), and a prior
+            # run may have died after insert_usage_snapshot but before the
+            # post-insert axis block. Each helper gates first on config (a cheap
+            # read for non-users) and pre-probes its recorded set before any cost
+            # scan, so non-budget users pay ~nothing here. Order matches the
+            # post-insert block so the projected budget_usd leg's skip_sync=True
+            # cache-warming dependency on the actual-budget axis still holds.
+            # [Dedup mustn't gate side effects]
+            for _heal_fn, _heal_tag in (
+                (maybe_record_budget_milestone, "budget-milestone"),
+                (maybe_record_project_budget_milestone,
+                 "project-budget-milestone"),
+                (maybe_record_projected_alert, "projected-alert"),
+            ):
+                try:
+                    _heal_fn(latest_saved)
+                except Exception as exc:
+                    eprint(f"[{_heal_tag}] self-heal error: {exc}")
         except Exception as exc:
             eprint(f"[record-usage] self-heal lookup failed: {exc}")
         return 0
@@ -2652,6 +2867,17 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
     except Exception as exc:
         eprint(f"[budget-milestone] unexpected error: {exc}")
 
+    # NEW: per-project equiv-$ budget alert firing (axis `project_budget`,
+    # #19/#121). Runs AFTER the global budget axis, but the per-project scan is
+    # self-sufficient — it passes skip_sync=False so a project-only user (no
+    # global budget warming the cache) still resolves live spend on this tick.
+    # Gated FIRST on a non-empty budget.projects + project_alerts_enabled — non-
+    # users pay only one config read.
+    try:
+        maybe_record_project_budget_milestone(saved)
+    except Exception as exc:
+        eprint(f"[project-budget-milestone] unexpected error: {exc}")
+
     # NEW: projected-pace alert firing (axis `projected`, #121). Runs in its
     # OWN detect-and-arm AFTER the weekly/5h/budget blocks; gated up front on
     # (alerts.enabled && alerts.projected_enabled) ||

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,21 +14,30 @@ 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)
 class AlertAxisDescriptor:
     """Axis-agnostic metadata shared by the record path + dashboard envelope."""
 
-    id: str            # 'weekly' | 'five_hour' | 'budget' | 'projected'
+    id: str            # 'weekly' | 'five_hour' | 'budget' | 'projected' | 'project_budget'
     chip_label: str    # SHOUT form, byte-identical with alertAxis.ts AXIS_CHIP_LABEL
     title_label: str   # sentence-case form, byte-identical with AXIS_TITLE_LABEL
     milestone_table: str  # SQLite table the dashboard envelope SELECTs from
@@ -39,6 +48,11 @@ AXIS_REGISTRY: "tuple[AlertAxisDescriptor, ...]" = (
     AlertAxisDescriptor("five_hour", "5H-BLOCK", "5h-block", "five_hour_milestones"),
     AlertAxisDescriptor("budget", "BUDGET", "Budget", "budget_milestones"),
     AlertAxisDescriptor("projected", "PROJECTED", "Projected", "projected_milestones"),
+    # Per-project weekly budget alerts (issue #19 / #121). Distinct "PROJECT"
+    # chip vs the global "BUDGET" chip; its own forward-only table.
+    AlertAxisDescriptor(
+        "project_budget", "PROJECT", "Project budget", "project_budget_milestones"
+    ),
 )
 
 AXIS_BY_ID: "dict[str, AlertAxisDescriptor]" = {d.id: d for d in AXIS_REGISTRY}