cctally 1.22.4 → 1.24.0

package/bin/_lib_alert_axes.py

@@ -0,0 +1,53 @@
+"""Pure kernel: alert-axis descriptors + registry + shared severity policy.
+
+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
+(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.
+
+Stdlib-only, no I/O at import time. bin/cctally re-exports the public symbols.
+Spec: docs/superpowers/specs/2026-06-01-alerts-axis-registry-projected-pace-design.md
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# 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 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'
+    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
+
+
+AXIS_REGISTRY: "tuple[AlertAxisDescriptor, ...]" = (
+    AlertAxisDescriptor("weekly", "WEEKLY", "Weekly", "percent_milestones"),
+    AlertAxisDescriptor("five_hour", "5H-BLOCK", "5h-block", "five_hour_milestones"),
+    AlertAxisDescriptor("budget", "BUDGET", "Budget", "budget_milestones"),
+    AlertAxisDescriptor("projected", "PROJECTED", "Projected", "projected_milestones"),
+)
+
+AXIS_BY_ID: "dict[str, AlertAxisDescriptor]" = {d.id: d for d in AXIS_REGISTRY}

package/bin/_lib_alert_dispatch.py

@@ -0,0 +1,141 @@
+"""Pure kernel: cross-platform alert dispatch decisions + severity->urgency.
+
+resolve_notifier() picks the active notifier; build_command() returns the exact
+arg-list to spawn (osascript / notify-send / a config-driven command_template),
+or None ("no popup; log + dashboard only"). NO I/O at import time, and the
+decision is parameterized on `platform` + `which_on_path` so every OS branch is
+unit-testable from any host. bin/_cctally_alerts.py is the I/O glue: it injects
+the real sys.platform / shutil.which and spawns the result with shell=False.
+
+Trust model (spec Q3): alerts.command_template is *trusted local command
+execution* (the user owns config.json). shell=False + the arg-list form block
+alert-text shell-injection (a week label with $(...) or ; is one literal arg);
+the native notify-send path adds a `--` end-of-options delimiter against
+option-injection.
+
+Stdlib-only. bin/cctally re-exports the public symbols.
+Spec: docs/superpowers/specs/2026-06-02-alerts-dispatch-severity-seams-design.md
+"""
+from __future__ import annotations
+
+import importlib.util as _ilu
+import pathlib
+import sys
+
+# notify-send urgency tokens keyed by the 3-tier severity from
+# _lib_alert_axes.severity_for.
+_SEVERITY_URGENCY = {"info": "low", "warn": "normal", "critical": "critical"}
+
+# The documented command_template substitution tokens (one-pass, no re-scan).
+_TEMPLATE_TOKENS = frozenset(
+    {"title", "subtitle", "body", "severity", "urgency", "axis", "threshold", "metric"}
+)
+
+
+def _load_lib(name: str):
+    cached = sys.modules.get(name)
+    if cached is not None:
+        return cached
+    p = pathlib.Path(__file__).resolve().parent / f"{name}.py"
+    spec = _ilu.spec_from_file_location(name, p)
+    mod = _ilu.module_from_spec(spec)
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def severity_to_urgency(severity: str) -> str:
+    """Map a 3-tier severity to a notify-send urgency token."""
+    return _SEVERITY_URGENCY.get(severity, "normal")
+
+
+def resolve_notifier(cfg: dict, *, platform: str, which_on_path) -> str:
+    """Return the effective notifier id for this host + validated alerts cfg.
+
+    `platform` is a sys.platform-style string; `which_on_path` is a callable
+    name -> bool. An explicitly-selected native notifier that is unavailable on
+    this host downgrades to 'none' (rather than being spawned and failing).
+    """
+    selector = cfg.get("notifier", "auto")
+    template = cfg.get("command_template")
+    is_darwin = platform == "darwin"
+    is_linux = platform.startswith("linux")
+
+    if selector == "osascript":
+        return "osascript" if is_darwin else "none"
+    if selector == "notify-send":
+        return "notify-send" if (is_linux and which_on_path("notify-send")) else "none"
+    if selector == "command":
+        return "command" if template else "none"
+    if selector == "none":
+        return "none"
+    # auto
+    if template:
+        return "command"
+    if is_darwin:
+        return "osascript"
+    if is_linux and which_on_path("notify-send"):
+        return "notify-send"
+    return "none"
+
+
+def _substitute_tokens(arg: str, values: dict) -> str:
+    """One-pass left-to-right substitution: replace only the documented
+    {tokens}; leave every other character (including stray/unmatched braces)
+    literal; substituted values are NOT re-scanned. Missing keys -> ""."""
+    out = []
+    i, n = 0, len(arg)
+    while i < n:
+        ch = arg[i]
+        if ch == "{":
+            close = arg.find("}", i + 1)
+            if close != -1 and arg[i + 1:close] in _TEMPLATE_TOKENS:
+                out.append(str(values.get(arg[i + 1:close], "")))
+                i = close + 1
+                continue
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+
+def build_command(
+    notifier: str,
+    *,
+    title: str,
+    subtitle: str,
+    body: str,
+    severity: str,
+    urgency: str,
+    payload: dict,
+    command_template,
+):
+    """Return the arg-list to spawn for `notifier`, or None ('no popup')."""
+    if notifier == "osascript":
+        esc = _load_lib("_lib_alerts_payload")._escape_applescript_string
+        script = (
+            f'display notification "{esc(body)}"'
+            f' with title "{esc(title)}"'
+            f' subtitle "{esc(subtitle)}"'
+        )
+        return ["osascript", "-e", script]
+    if notifier == "notify-send":
+        folded = f"{subtitle}\n{body}" if subtitle.strip() else body
+        return ["notify-send", "-u", urgency, "--", title, folded]
+    if notifier == "command":
+        if not command_template:
+            return None
+        # A payload key present-but-None (e.g. a weekly payload's metric=None)
+        # substitutes as "" — same surface as an absent key.
+        def _pv(key):
+            v = payload.get(key)
+            return "" if v is None else v
+
+        values = {
+            "title": title, "subtitle": subtitle, "body": body,
+            "severity": severity, "urgency": urgency,
+            "axis": _pv("axis"),
+            "threshold": _pv("threshold"),
+            "metric": _pv("metric"),
+        }
+        return [_substitute_tokens(a, values) for a in command_template]
+    return None  # "none" or unknown -> no popup

package/bin/_lib_alerts_payload.py

@@ -242,3 +242,70 @@ def _build_alert_payload_budget(
             "consumption_pct": float(consumption_pct),
         },
     }
+
+
+def _alert_text_projected(payload: dict, tz: "ZoneInfo | None") -> tuple[str, str, str]:
+    """Build (title, subtitle, body) for a projected-pace alert (#121).
+
+    These fire on the WEEK-AVERAGE projection — what you're tracking toward at
+    the current week-average pace — NOT on an actual crossing. The text carries
+    an explicit "(projection)" / "on current pace" cue so a user never confuses
+    a projected alert with an actual-crossing one (which the weekly/budget
+    builders render). The rendered numbers come from the payload (the values
+    snapshotted at crossing), never from live config (Codex P0-4). ``tz`` is
+    accepted for signature parity with peer ``_alert_text_*`` builders and
+    intentionally unused (no instant is rendered, same as ``_alert_text_budget``).
+    """
+    metric = payload["metric"]
+    t = int(payload["threshold"])
+    proj = float(payload["projected_value"])
+    denom = float(payload["denominator"])
+    if metric == "weekly_pct":
+        title = f"cctally - projected to reach {t}% this week"
+        subtitle = "On current pace (projection)"
+        body = f"Projected ~{proj:.0f}% of cap by reset (week-average pace)"
+    else:  # budget_usd
+        title = "cctally - projected to exceed budget"
+        subtitle = f"On current pace (projection) - {t}% of budget"
+        body = (
+            f"Projected ${proj:,.2f} of ${denom:,.2f} budget "
+            f"(week-average pace)"
+        )
+    return title, subtitle, body
+
+
+def _build_alert_payload_projected(
+    *,
+    metric: str,
+    threshold: int,
+    projected_value: float,
+    denominator: float,
+    week_start_at: str,
+) -> dict:
+    """Build the alert payload for a projected-pace threshold crossing (#121).
+
+    ``axis: "projected"`` is the fourth alert axis; ``metric`` discriminates
+    ``weekly_pct`` (denominator 100.0, "% of cap") from ``budget_usd``
+    (denominator = target_usd, "$ of budget"). The frontend renders context
+    FROM these row-sourced fields (``metric`` / ``projected_value`` /
+    ``denominator``), not from live config that may have changed since crossing
+    (Codex P0-4). No ``crossed_at``/``alerted_at`` keys here: the projected
+    detector stamps ``alerted_at`` on the DB row itself in the same txn before
+    dispatch (set-then-dispatch), and the dashboard envelope reads it from the
+    row — mirroring ``_build_alert_payload_budget``'s context-only shape minus
+    the redundant timestamp echo.
+    """
+    return {
+        "id": f"projected:{week_start_at}:{metric}:{int(threshold)}",
+        "axis": "projected",
+        "metric": str(metric),
+        "threshold": int(threshold),
+        "projected_value": float(projected_value),
+        "denominator": float(denominator),
+        "context": {
+            "week_start_at": week_start_at,
+            "metric": str(metric),
+            "projected_value": float(projected_value),
+            "denominator": float(denominator),
+        },
+    }

package/bin/_lib_budget.py

@@ -52,6 +52,7 @@ class BudgetStatus:
     elapsed_fraction: float             # [0, 1]
     projected_eow_low_usd: float
     projected_eow_high_usd: float
+    week_avg_projection_usd: float      # spent + rate_avg*remaining (smooth estimator)
     verdict: str                        # "ok" | "warn" | "over"
     daily_budget_remaining_usd: float   # remaining / remaining-days
     daily_pace_usd: float               # current burn $/day (week-average)
@@ -93,6 +94,12 @@ def compute_budget_status(inputs: BudgetInputs) -> BudgetStatus:
         spent, remaining_hours, rate_low, rate_high
     )
 
+    # Smooth week-average end-of-week projection (additive surface field).
+    # Distinct from the displayed band (which keys off the high end): this is
+    # the conservative week-average value the projected-pace alert axis fires
+    # on. spent + rate_avg*remaining (== project_linear collapsed to one rate).
+    week_avg_projection_usd = spent + rate_avg * remaining_hours
+
     daily_pace_usd = rate_avg * 24.0
     daily_budget_remaining_usd = (
         (remaining_usd / remaining_days) if remaining_days > 0 else remaining_usd
@@ -125,6 +132,7 @@ def compute_budget_status(inputs: BudgetInputs) -> BudgetStatus:
         elapsed_fraction=elapsed_fraction,
         projected_eow_low_usd=projected_low,
         projected_eow_high_usd=projected_high,
+        week_avg_projection_usd=week_avg_projection_usd,
         verdict=verdict,
         daily_budget_remaining_usd=daily_budget_remaining_usd,
         daily_pace_usd=daily_pace_usd,

package/bin/cctally

@@ -366,14 +366,27 @@ _build_codex_weekly_parser = _cctally_parser._build_codex_weekly_parser
 _build_codex_session_parser = _cctally_parser._build_codex_session_parser
 
 
+_lib_alert_axes = _load_sibling("_lib_alert_axes")
+severity_for = _lib_alert_axes.severity_for
+AlertAxisDescriptor = _lib_alert_axes.AlertAxisDescriptor
+AXIS_REGISTRY = _lib_alert_axes.AXIS_REGISTRY
+AXIS_BY_ID = _lib_alert_axes.AXIS_BY_ID
+
 _lib_alerts_payload = _load_sibling("_lib_alerts_payload")
 _alert_text_weekly = _lib_alerts_payload._alert_text_weekly
 _alert_text_five_hour = _lib_alerts_payload._alert_text_five_hour
 _alert_text_budget = _lib_alerts_payload._alert_text_budget
+_alert_text_projected = _lib_alerts_payload._alert_text_projected
 _escape_applescript_string = _lib_alerts_payload._escape_applescript_string
 _build_alert_payload_weekly = _lib_alerts_payload._build_alert_payload_weekly
 _build_alert_payload_five_hour = _lib_alerts_payload._build_alert_payload_five_hour
 _build_alert_payload_budget = _lib_alerts_payload._build_alert_payload_budget
+_build_alert_payload_projected = _lib_alerts_payload._build_alert_payload_projected
+
+_lib_alert_dispatch = _load_sibling("_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
 
 _lib_five_hour = _load_sibling("_lib_five_hour")
 _FIVE_HOUR_JITTER_FLOOR_SECONDS = _lib_five_hour._FIVE_HOUR_JITTER_FLOOR_SECONDS
@@ -799,6 +812,8 @@ _PERCENT_NORMALIZE_DECIMALS = _cctally_record._PERCENT_NORMALIZE_DECIMALS
 _normalize_percent = _cctally_record._normalize_percent
 maybe_record_milestone = _cctally_record.maybe_record_milestone
 maybe_record_budget_milestone = _cctally_record.maybe_record_budget_milestone
+maybe_record_projected_alert = _cctally_record.maybe_record_projected_alert
+_weekly_pct_week_avg_projection = _cctally_record._weekly_pct_week_avg_projection
 _compute_block_totals = _cctally_record._compute_block_totals
 maybe_update_five_hour_block = _cctally_record.maybe_update_five_hour_block
 cmd_record_usage = _cctally_record.cmd_record_usage
@@ -2053,6 +2068,8 @@ get_milestone_cost_for_week         = _cctally_milestones.get_milestone_cost_for
 get_milestones_for_week             = _cctally_milestones.get_milestones_for_week             # forecast c.; tui shim; percent-breakdown c.
 insert_percent_milestone            = _cctally_milestones.insert_percent_milestone            # record shim; idempotency-test mod.
 insert_budget_milestone             = _cctally_milestones.insert_budget_milestone             # record shim
+insert_projected_milestone          = _cctally_milestones.insert_projected_milestone          # record shim
+_projected_levels_already_latched   = _cctally_milestones._projected_levels_already_latched   # record shim
 _reconcile_budget_milestones_on_set = _cctally_milestones._reconcile_budget_milestones_on_set # test_budget_alerts ns[]
 _reconcile_budget_on_config_write   = _cctally_milestones._reconcile_budget_on_config_write   # forecast/config/dashboard c.; test_forecast_ns_patch mod. patch