cctally 1.21.2 → 1.22.0

package/bin/_cctally_setup.py

@@ -293,6 +293,12 @@ _SETUP_STALE_SYMLINK_NAMES = (
 )
 
 
+# The npm package ships a Node shim as the `cctally` entry point. Its
+# basename differs from the command name, so any code matching a
+# symlink's readlink target by basename must special-case it.
+_CCTALLY_NPM_SHIM_BASENAME = "cctally-npm-shim.js"
+
+
 def _setup_resolve_symlink_source(repo_root: pathlib.Path, name: str) -> pathlib.Path:
     """Resolve the symlink target for a given PATH-name.
 
@@ -310,27 +316,27 @@ def _setup_resolve_symlink_source(repo_root: pathlib.Path, name: str) -> pathlib
     documented. All other names map directly to ``bin/<name>``.
     """
     if name == "cctally" and "node_modules" in repo_root.parts:
-        shim = repo_root / "bin" / "cctally-npm-shim.js"
+        shim = repo_root / "bin" / _CCTALLY_NPM_SHIM_BASENAME
         if shim.exists():
             return shim
     return repo_root / "bin" / name
 
 
 def _setup_resolve_hook_target(repo_root: pathlib.Path) -> pathlib.Path:
-    """Resolve the absolute path that goes into Claude Code hook entries.
-
-    Single chokepoint shared by ``_setup_install``, ``_setup_dry_run``
-    (text + JSON envelopes), and any other site that emits a hook
-    command. Routes through :func:`_setup_resolve_symlink_source` so
-    npm-layout installs point hooks at the Node shim instead of the
-    Python script directly — without this, the shim's
-    ``CCTALLY_PYTHON`` honoring works for interactive ``cctally`` calls
-    but every hook fire bypasses it via ``/usr/bin/env python3`` and
-    silently fails when the user's ``python3`` doesn't meet the version
-    floor. The returned path is fully resolved (symlinks followed) so
-    the recorded hook entry survives later filesystem rearrangements
-    of the source clone or the npm install root.
+    """Absolute path recorded in Claude Code hook entries.
+
+    Brew installs: return the version-stable `<prefix>/bin/cctally` (the
+    formula's symlink, which self-heals on `brew upgrade`) WITHOUT
+    `.resolve()` — resolving would pin the hook to the versioned keg and
+    dangle after `brew cleanup` (issue #119). Source/npm: keep the
+    `.resolve()` semantics (survives clone/node_modules rearrangement and
+    the npm-shim branch in `_setup_resolve_symlink_source`).
     """
+    if _setup_is_brew_install(repo_root):
+        prefix = _setup_brew_prefix(repo_root)
+        stable = pathlib.Path(prefix) / "bin" / "cctally"
+        if stable.exists():
+            return stable
     return _setup_resolve_symlink_source(repo_root, "cctally").resolve()
 
 
@@ -446,19 +452,23 @@ def _setup_cleanup_stale_symlinks(
     """
     results: list[_SetupSymlinkResult] = []
     repo_root = _setup_resolve_repo_root()
-    for name in _SETUP_STALE_SYMLINK_NAMES:
+    retired_names = set(_SETUP_STALE_SYMLINK_NAMES)
+    for name in dict.fromkeys(_SETUP_STALE_SYMLINK_NAMES + tuple(_cctally().SETUP_SYMLINK_NAMES)):
         dst = dst_dir / name
         if not _setup_symlink_is_retired(dst, name, repo_root):
             continue
+        if name in retired_names:
+            should_remove = True                       # retired command: unconditional
+        else:                                           # active name: reachability-gated
+            is_dangling = not dst.resolve(strict=False).exists() if dst.is_symlink() else False
+            should_remove = is_dangling or _reachable_elsewhere(name)
+        if not should_remove:
+            continue
         try:
             dst.unlink()
-            results.append(
-                _SetupSymlinkResult(name, "removed-stale", "stale (from prior version)")
-            )
+            results.append(_SetupSymlinkResult(name, "removed-stale", "stale (issue #119 cleanup)"))
         except OSError as exc:
-            results.append(
-                _SetupSymlinkResult(name, "failed", f"unlink failed: {exc}")
-            )
+            results.append(_SetupSymlinkResult(name, "failed", f"unlink failed: {exc}"))
     return results
 
 
@@ -522,7 +532,11 @@ def _setup_symlink_is_retired(
         target = os.readlink(dst)
     except OSError:
         return False
-    if pathlib.Path(target).name != name:
+    target_basename = pathlib.Path(target).name
+    accepted = {name}
+    if name == "cctally":
+        accepted.add(_CCTALLY_NPM_SHIM_BASENAME)
+    if target_basename not in accepted:
         # User-managed symlink that happens to share the name; leave alone.
         return False
     # Resolve target relative to the symlink's parent so relative
@@ -546,9 +560,30 @@ def _setup_symlink_is_retired(
     # *from* an npm/brew install doesn't classify its own siblings as
     # foreign — that's the active-symlinks loop's job.
     target_str = str(target_path)
+    # "Same install root" means the target lives UNDER the current
+    # ``repo_root`` tree. Use a separator-anchored prefix check rather
+    # than a bare substring of the token: a same-``repo_root`` npm install
+    # has ``repo_root == <…>/node_modules/cctally`` (no trailing slash),
+    # so the raw ``"/node_modules/cctally/" in repo_root_str`` test would
+    # spuriously miss and classify the live channel's own link as foreign
+    # (issue #119 finding #7 — the npm `cctally` shim under its own
+    # ``node_modules/cctally`` must be preserved, not retired).
     repo_root_str = str(repo_root)
+    repo_root_prefix = repo_root_str.rstrip(os.sep) + os.sep
+    target_under_repo_root = (
+        target_str == repo_root_str or target_str.startswith(repo_root_prefix)
+    )
     for token in _SETUP_FOREIGN_INSTALL_ROOT_TOKENS:
-        if token in target_str and token not in repo_root_str:
+        if token not in target_str:
+            continue
+        # Homebrew keg links are NEVER owned by ~/.local/bin under the
+        # issue-#119 policy, so retire them regardless of which keg /
+        # whether repo_root is itself a keg. Other foreign roots
+        # (node_modules) retire only when the target is NOT under the
+        # current install root.
+        if token == _SETUP_FOREIGN_INSTALL_ROOT_TOKENS[0]:   # "/Cellar/cctally/"
+            return True
+        if not target_under_repo_root:
             return True
     return False
 
@@ -558,6 +593,44 @@ def _setup_path_includes_local_bin() -> bool:
     return local_bin in os.environ.get("PATH", "").split(os.pathsep)
 
 
+def _setup_is_brew_install(repo_root: pathlib.Path) -> bool:
+    """True when this cctally runs from a Homebrew keg.
+
+    `_setup_resolve_repo_root()` `.resolve()`s `__file__`, so a brew
+    install reliably carries the `/Cellar/cctally/` token (Apple Silicon,
+    Intel, Linuxbrew all funnel through it). Reuses the single token
+    source in `_SETUP_FOREIGN_INSTALL_ROOT_TOKENS[0]`. Cheap — no
+    `npm prefix` subprocess; we only need the brew yes/no.
+    """
+    return _SETUP_FOREIGN_INSTALL_ROOT_TOKENS[0] in str(repo_root)
+
+
+def _setup_brew_prefix(repo_root: pathlib.Path) -> str:
+    """The Homebrew `<prefix>` (e.g. `/opt/homebrew`) for a brew keg
+    `repo_root`. Splits on the single-source brew token so we never spell
+    the Cellar path a third way. Callers must guard with
+    `_setup_is_brew_install(repo_root)` first; off a keg this returns the
+    unchanged string."""
+    return str(repo_root).split(_SETUP_FOREIGN_INSTALL_ROOT_TOKENS[0])[0]
+
+
+def _reachable_elsewhere(name: str) -> bool:
+    """Would `<name>` still be found on PATH if the ~/.local/bin slot
+    didn't exist? Excludes the ~/.local/bin directory (realpath-compared)
+    so a stale link can't satisfy its own reachability check (issue #119
+    finding #6)."""
+    local_bin = _setup_local_bin_dir()
+    try:
+        local_real = os.path.realpath(local_bin)
+    except OSError:
+        local_real = str(local_bin)
+    dirs = [
+        d for d in os.environ.get("PATH", "").split(os.pathsep)
+        if d and os.path.realpath(d) != local_real
+    ]
+    return shutil.which(name, path=os.pathsep.join(dirs)) is not None
+
+
 def _setup_shell_rc_hint() -> str:
     shell = os.environ.get("SHELL", "")
     if "zsh" in shell:
@@ -580,7 +653,16 @@ def _setup_detect_legacy_snippet() -> tuple[pathlib.Path, list[int]] | None:
             text = path.read_text(encoding="utf-8", errors="replace")
         except OSError:
             continue
-        hits = [i + 1 for i, ln in enumerate(text.splitlines()) if c.LEGACY_STATUSLINE_NEEDLE in ln]
+        # Skip lines whose first non-whitespace char is `#`: a shell comment
+        # that merely references the legacy command in prose (e.g. a NOTE
+        # documenting its removal) is not an executing snippet (issue #115).
+        # POSIX shell only treats `#` as a comment marker at start-of-token,
+        # so this covers natural-language comments without parsing the shell.
+        hits = [
+            i + 1
+            for i, ln in enumerate(text.splitlines())
+            if c.LEGACY_STATUSLINE_NEEDLE in ln and not ln.lstrip().startswith("#")
+        ]
         if hits:
             return (path, hits)
     return None
@@ -1008,35 +1090,25 @@ def _setup_compute_symlink_state(
 ) -> "list[tuple[str, str]]":
     """Per-symlink (name, state) for `_setup_status` + `doctor_gather_state`.
 
-    state ∈ {"ok", "wrong", "missing"}:
-      - "ok": ``dst_dir/name`` is a symlink whose target is reachable.
-        The target is NOT required to match ``repo_root/bin/<name>`` —
-        power users routinely have the symlinks installed by one
-        cctally channel (npm/brew) while running ``doctor`` from a
-        parallel source clone, which would otherwise produce a 0/N
-        false negative on a perfectly healthy install. The diagnostic
-        question is "is `cctally-X` invokable from PATH?", not "did
-        THIS checkout install the symlink?". ``_setup_create_symlinks``
-        keeps its own strict equality check for install-management
-        (replace-vs-already).
-      - "wrong": a non-symlink file occupies the slot, or the symlink
-        target is dangling. Unchanged by the PATH-aware fallback below —
-        a dangling/occupied slot stays "wrong" even if the command is
-        reachable elsewhere (that's the §9 brew-cleanup follow-up's job).
-      - "missing": nothing at ``dst_dir/name`` AND the command is not
-        reachable on ``$PATH`` via another channel. When the slot is
-        empty but ``shutil.which(name)`` resolves (e.g. a brew
-        ``<prefix>/bin`` install), the state is "ok" instead — the
-        diagnostic question is "is cctally-X invokable?" (issue #114).
-
-    ``repo_root`` is unused here — retained on the signature for
-    call-site stability across `_setup_status` and `doctor_gather_state`.
+    state ∈ {"ok", "stale", "wrong", "missing"}.
+      - ok:      resolvable non-retired link, OR empty slot reachable elsewhere.
+      - stale:   retired link (Cellar/foreign/dangling) AND command reachable
+                 via a non-~/.local/bin dir (safely cleanable). Issue #119.
+      - wrong:   non-symlink file in slot; dangling non-retired link; OR a
+                 retired link with no reachable_elsewhere fallback (broken, or
+                 the pathological only-path-live-Cellar case).
+      - missing: empty slot, not reachable elsewhere.
+    Retired check precedes the resolve()->ok branch so a LIVE Cellar link is
+    classed stale, not masked as ok.
     """
-    del repo_root  # unused; see docstring
     out: list[tuple[str, str]] = []
     for name in _cctally().SETUP_SYMLINK_NAMES:
         dst = dst_dir / name
+        reachable = _reachable_elsewhere(name)
         if dst.is_symlink():
+            if _setup_symlink_is_retired(dst, name, repo_root):
+                out.append((name, "stale" if reachable else "wrong"))
+                continue
             try:
                 dst.resolve(strict=True)
                 out.append((name, "ok"))
@@ -1044,11 +1116,7 @@ def _setup_compute_symlink_state(
                 out.append((name, "wrong"))
         elif dst.exists():
             out.append((name, "wrong"))
-        elif shutil.which(name):
-            # Slot empty in dst_dir but the command is reachable on PATH
-            # via another channel (e.g. brew's <prefix>/bin). The
-            # diagnostic question is "is cctally-X invokable?", so treat
-            # as ok rather than false-warning. (Issue #114.)
+        elif reachable:
             out.append((name, "ok"))
         else:
             out.append((name, "missing"))
@@ -1085,8 +1153,11 @@ def _setup_status(args: argparse.Namespace) -> int:
     repo_root = _setup_resolve_repo_root()
     dst_dir = _setup_local_bin_dir()
     sym_state = _setup_compute_symlink_state(repo_root, dst_dir)
-    sym_ok = sum(1 for _, s in sym_state if s == "ok")
-    stale_syms = _setup_detect_stale_symlinks(dst_dir)
+    sym_ok = sum(1 for _, s in sym_state if s in ("ok", "stale"))     # available = ok + stale
+    active_stale = [n for n, s in sym_state if s == "stale"]
+    retired_stale = _setup_detect_stale_symlinks(dst_dir)
+    stale_syms = list(dict.fromkeys(active_stale + retired_stale))    # union, order-stable
+    is_brew = _setup_is_brew_install(repo_root)
     on_path = _setup_path_includes_local_bin()
     try:
         settings = c._load_claude_settings()
@@ -1140,8 +1211,12 @@ def _setup_status(args: argparse.Namespace) -> int:
             f"  Stale symlinks {len(stale_syms)} from prior version: {', '.join(stale_syms)}  ⚠"
         )
         out.append("                 run `cctally setup` to remove")
-    out.append(f"  PATH includes  {'yes' if on_path else 'no'}                                   "
-               f"{'✓' if on_path else '⚠'}")
+    if is_brew and (on_path or any(s in ("ok", "stale") for _, s in sym_state)):
+        prefix = _setup_brew_prefix(repo_root)
+        out.append(f"  PATH           brew: commands via {prefix}/bin                 ✓")
+    else:
+        out.append(f"  PATH includes  {'yes' if on_path else 'no'}                                   "
+                   f"{'✓' if on_path else '⚠'}")
     out.append(f"Hooks ({_cctally_core.CLAUDE_SETTINGS_PATH})")
     for ev in c.SETUP_HOOK_EVENTS:
         marker = "✓" if hook_counts[ev] >= 1 else "✗"
@@ -1381,14 +1456,20 @@ def _setup_dry_run(args: argparse.Namespace) -> int:
     new = sum(1 for _, s in sym_results if s == "would-create")
     same = sum(1 for _, s in sym_results if s == "already")
     blocked = [name for name, s in sym_results if s == "blocked"]
+    is_brew = _setup_is_brew_install(repo_root)
     out: list[str] = []
-    out.append(
-        f"Would symlink {len(c.SETUP_SYMLINK_NAMES)} files to {dst_dir}/ "
-        f"({same} already correct, {new} new)"
-    )
-    if blocked:
-        out.append(f"⚠ Blocked (non-symlink files exist): {', '.join(blocked)}")
-        out.append("  Remove them manually then re-run.")
+    if is_brew:
+        prefix = _setup_brew_prefix(repo_root)
+        out.append(f"Brew install — would skip ~/.local/bin/ symlinks "
+                   f"(commands on PATH via {prefix}/bin/)")
+    else:
+        out.append(
+            f"Would symlink {len(c.SETUP_SYMLINK_NAMES)} files to {dst_dir}/ "
+            f"({same} already correct, {new} new)"
+        )
+        if blocked:
+            out.append(f"⚠ Blocked (non-symlink files exist): {', '.join(blocked)}")
+            out.append("  Remove them manually then re-run.")
 
     out.append(f"Would add {len(c.SETUP_HOOK_EVENTS)} hook entries to {_cctally_core.CLAUDE_SETTINGS_PATH}:")
     abs_path = str(_setup_resolve_hook_target(repo_root))
@@ -1460,13 +1541,18 @@ def _setup_dry_run(args: argparse.Namespace) -> int:
         envelope = {
             "schema_version": 1,
             "mode": "dry-run",
-            "symlinks": {
-                "would_create": new,
-                "already": same,
-                "blocked": blocked,
-                "destination": str(dst_dir),
-                "total": len(c.SETUP_SYMLINK_NAMES),
-            },
+            "symlinks": (
+                {"skipped": True, "reason": "brew", "would_create": 0,
+                 "already": 0, "blocked": [], "destination": str(dst_dir),
+                 "total": 0,
+                 "would_remove_stale": [
+                     n for n, s in _setup_compute_symlink_state(repo_root, dst_dir)
+                     if s == "stale"
+                 ]}
+                if is_brew else
+                {"would_create": new, "already": same, "blocked": blocked,
+                 "destination": str(dst_dir), "total": len(c.SETUP_SYMLINK_NAMES)}
+            ),
             "hooks": {
                 "would_add": [
                     {
@@ -1658,24 +1744,40 @@ def _setup_install(args: argparse.Namespace) -> int:
     # disturbs a user's hand-rolled symlink sharing the name.
     stale_results = _setup_cleanup_stale_symlinks(dst_dir)
 
-    sym_results = _setup_create_symlinks(repo_root, dst_dir)
-    failed = [r for r in sym_results if r.status == "failed"]
-    if failed:
-        for r in failed:
-            eprint(f"setup: symlink {r.name} failed: {r.detail}")
-        return 1
-    new_count = sum(1 for r in sym_results if r.status == "created")
-    same_count = sum(1 for r in sym_results if r.status == "already")
-    repl_count = sum(1 for r in sym_results if r.status == "replaced")
-    detail_parts = []
-    if new_count:
-        detail_parts.append(f"{new_count} newly created")
-    if same_count:
-        detail_parts.append(f"{same_count} already correct")
-    if repl_count:
-        detail_parts.append(f"{repl_count} re-pointed")
-    detail = ", ".join(detail_parts) or "no changes"
-    out.append(f"✓ Symlinks at {dst_dir}/: {len(sym_results)}/{len(sym_results)} ({detail})")
+    # Issue #119: brew owns <prefix>/bin/, never ~/.local/bin/. On a brew
+    # install, skip symlink CREATION entirely (commands reach PATH via the
+    # formula's <prefix>/bin/) but keep everything else — cleanup, hook
+    # wiring, cache bootstrap. The new/same/repl counts are initialized to
+    # 0 here so the install JSON envelope references are always bound on
+    # the brew branch (sym_results stays empty).
+    is_brew = _setup_is_brew_install(repo_root)
+    new_count = same_count = repl_count = 0
+    if is_brew:
+        prefix = _setup_brew_prefix(repo_root)
+        out.append(
+            f"✓ Brew install detected — commands are on PATH via {prefix}/bin/; "
+            f"skipping ~/.local/bin/ symlinks"
+        )
+        sym_results = []
+    else:
+        sym_results = _setup_create_symlinks(repo_root, dst_dir)
+        failed = [r for r in sym_results if r.status == "failed"]
+        if failed:
+            for r in failed:
+                eprint(f"setup: symlink {r.name} failed: {r.detail}")
+            return 1
+        new_count = sum(1 for r in sym_results if r.status == "created")
+        same_count = sum(1 for r in sym_results if r.status == "already")
+        repl_count = sum(1 for r in sym_results if r.status == "replaced")
+        detail_parts = []
+        if new_count:
+            detail_parts.append(f"{new_count} newly created")
+        if same_count:
+            detail_parts.append(f"{same_count} already correct")
+        if repl_count:
+            detail_parts.append(f"{repl_count} re-pointed")
+        detail = ", ".join(detail_parts) or "no changes"
+        out.append(f"✓ Symlinks at {dst_dir}/: {len(sym_results)}/{len(sym_results)} ({detail})")
     removed_stale = [r for r in stale_results if r.status == "removed-stale"]
     failed_stale = [r for r in stale_results if r.status == "failed"]
     if removed_stale:
@@ -1687,7 +1789,7 @@ def _setup_install(args: argparse.Namespace) -> int:
         out.append(f"⚠ Could not remove stale {r.name}: {r.detail}")
         warnings += 1
 
-    if not _setup_path_includes_local_bin():
+    if not is_brew and not _setup_path_includes_local_bin():
         warnings += 1
         rc = _setup_shell_rc_hint()
         out.append(f"⚠ {dst_dir} is not on your PATH. Add to {rc}:")
@@ -1695,6 +1797,25 @@ def _setup_install(args: argparse.Namespace) -> int:
         out.append("  Then reload (`source ...`) or open a new terminal.")
         out.append("  (Hooks still work — we used absolute paths in settings.json.)")
 
+    # Pinned-only-path guidance (issue #119 finding #10): if any active
+    # name's slot is a live retired link with no reachable_elsewhere
+    # fallback, setup deliberately won't remove it (would break the only
+    # reachable copy) — surface the actionable PATH fix instead of silence.
+    pinned = [
+        n for n, s in _setup_compute_symlink_state(repo_root, dst_dir)
+        if s == "wrong" and (dst_dir / n).is_symlink()
+        and _setup_symlink_is_retired(dst_dir / n, n, repo_root)
+        and (dst_dir / n).resolve(strict=False).exists()
+    ]
+    if pinned:
+        prefix = _setup_brew_prefix(repo_root) if is_brew else "<prefix>"
+        out.append(
+            f"⚠ cctally is reachable only via a legacy ~/.local/bin link. "
+            f"Put {prefix}/bin on your PATH (eval \"$(brew shellenv)\"), then "
+            f"re-run cctally setup to clean it."
+        )
+        warnings += 1
+
     c._backup_claude_settings()
     try:
         c._write_claude_settings_atomic(settings)
@@ -1863,8 +1984,11 @@ def _setup_install(args: argparse.Namespace) -> int:
                 "created": new_count,
                 "already": same_count,
                 "replaced": repl_count,
-                "total": len(sym_results),
+                "total": len(sym_results),          # 0 on brew (sym_results == [])
                 "destination": str(dst_dir),
+                **({"skipped": True, "reason": "brew",
+                    "stale_removed": [r.name for r in stale_results if r.status == "removed-stale"]}
+                   if is_brew else {}),
             },
             "hooks": {
                 "events_added": list(c.SETUP_HOOK_EVENTS),

package/bin/_lib_alerts_payload.py

@@ -192,3 +192,53 @@ def _build_alert_payload_five_hour(
             "primary_model": primary_model,
         },
     }
+
+
+def _alert_text_budget(payload: dict, tz: "ZoneInfo | None") -> tuple[str, str, str]:
+    """Build (title, subtitle, body) for an equiv-$ budget threshold alert.
+
+    ``week_start_at`` is an instant, but the budget alert text doesn't render
+    it (the subtitle is the threshold, the body the dollar progress) — so no
+    ``format_display_dt`` call is needed here. ``tz`` is accepted for
+    signature parity with peer ``_alert_text_*`` builders and intentionally
+    unused.
+    """
+    threshold = int(payload["threshold"])
+    title = "cctally - budget"
+    subtitle = f"{threshold}% of budget"
+    ctx = payload.get("context") or {}
+    spent = float(ctx.get("spent_usd") or 0.0)
+    budget = float(ctx.get("budget_usd") or 0.0)
+    consumption = float(ctx.get("consumption_pct") or 0.0)
+    body = f"${spent:,.2f} of ${budget:,.2f} ({consumption:.0f}% of budget)"
+    return title, subtitle, body
+
+
+def _build_alert_payload_budget(
+    *,
+    threshold: int,
+    crossed_at_utc: str,
+    week_start_at: str,
+    budget_usd: float,
+    spent_usd: float,
+    consumption_pct: float,
+) -> dict:
+    """Build the alert payload for an equiv-$ budget threshold crossing.
+
+    See ``_build_alert_payload_weekly`` for the ``alerted_at == crossed_at``
+    rationale (set-then-dispatch invariant). ``axis: "budget"`` is the third
+    alert axis (Task 4 surfaces it in the dashboard Recent-alerts panel).
+    """
+    return {
+        "id": f"budget:{week_start_at}:{threshold}",
+        "axis": "budget",
+        "threshold": int(threshold),
+        "crossed_at": crossed_at_utc,
+        "alerted_at": crossed_at_utc,  # set-then-dispatch
+        "context": {
+            "week_start_at": week_start_at,
+            "budget_usd": float(budget_usd),
+            "spent_usd": float(spent_usd),
+            "consumption_pct": float(consumption_pct),
+        },
+    }

package/bin/_lib_budget.py

@@ -0,0 +1,133 @@
+"""Pure-function kernel for `cctally budget` (no I/O — every dep injected).
+
+Mirrors the _lib_statusline.py / _lib_doctor.py / _lib_pricing_check.py
+pattern. Re-exported on the cctally module. See
+docs/superpowers/specs/2026-05-29-cctally-budget-design.md §3.
+"""
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+
+# Early in the week / no data → projections are unreliable; annotate LOW CONF
+# (mirrors forecast's thin-data caution). Tunable single source of truth.
+_BUDGET_LOW_CONF_ELAPSED_FRACTION = 0.15
+# Fallback warn fraction when alert_thresholds is empty (alerts silenced) but
+# we still render a verdict.
+_BUDGET_DEFAULT_WARN_FRACTION = 0.90
+
+
+def project_linear(
+    current: float,
+    remaining: float,
+    rate_low: float,
+    rate_high: float,
+) -> tuple[float, float]:
+    """Project ``current + rate * remaining`` for a (low, high) rate band.
+
+    Pure; unit-agnostic — percent for forecast, dollars for budget. The caller
+    is responsible for passing ``rate_low <= rate_high`` if it wants ordered
+    output; this primitive does NOT sort (forecast sorts the outputs to stay a
+    byte-exact no-op vs its goldens; budget passes a pre-ordered band).
+    """
+    return (current + rate_low * remaining, current + rate_high * remaining)
+
+
+@dataclass(frozen=True)
+class BudgetInputs:
+    target_usd: float
+    spent_usd: float            # cumulative equiv-$ this subscription week
+    recent_24h_usd: float       # trailing-24h equiv-$ (recent-rate projection)
+    week_start_at: dt.datetime  # effective (post-reset) week start, tz-aware
+    week_end_at: dt.datetime    # tz-aware
+    now: dt.datetime            # tz-aware
+    alert_thresholds: tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class BudgetStatus:
+    spent_usd: float
+    remaining_usd: float                # target - spent (may be < 0)
+    consumption_pct: float              # spent / target * 100 (monotonic key)
+    elapsed_fraction: float             # [0, 1]
+    projected_eow_low_usd: float
+    projected_eow_high_usd: float
+    verdict: str                        # "ok" | "warn" | "over"
+    daily_budget_remaining_usd: float   # remaining / remaining-days
+    daily_pace_usd: float               # current burn $/day (week-average)
+    low_confidence: bool
+    crossed_thresholds: tuple[int, ...]
+
+
+def compute_budget_status(inputs: BudgetInputs) -> BudgetStatus:
+    """Compute budget status from injected inputs. Pure; deterministic."""
+    target = float(inputs.target_usd)
+    spent = float(inputs.spent_usd)
+
+    total_seconds = (inputs.week_end_at - inputs.week_start_at).total_seconds()
+    elapsed_seconds = (inputs.now - inputs.week_start_at).total_seconds()
+    # Clamp elapsed into [0, total] so a now before/after the window stays sane.
+    if total_seconds <= 0:
+        elapsed_seconds = 0.0
+        elapsed_fraction = 0.0
+    else:
+        elapsed_seconds = max(0.0, min(elapsed_seconds, total_seconds))
+        elapsed_fraction = elapsed_seconds / total_seconds
+    remaining_seconds = max(0.0, total_seconds - elapsed_seconds)
+
+    elapsed_hours = elapsed_seconds / 3600.0
+    remaining_hours = remaining_seconds / 3600.0
+    remaining_days = remaining_hours / 24.0
+
+    consumption_pct = (spent / target * 100.0) if target > 0 else 0.0
+    remaining_usd = target - spent
+
+    # Dollar rates ($/hour). Week-average from spend-so-far; recent from
+    # trailing-24h spend. Ordered band low<=high for project_linear.
+    rate_avg = (spent / elapsed_hours) if elapsed_hours > 0 else 0.0
+    rate_recent = float(inputs.recent_24h_usd) / 24.0
+    rate_low = min(rate_avg, rate_recent)
+    rate_high = max(rate_avg, rate_recent)
+
+    projected_low, projected_high = project_linear(
+        spent, remaining_hours, rate_low, rate_high
+    )
+
+    daily_pace_usd = rate_avg * 24.0
+    daily_budget_remaining_usd = (
+        (remaining_usd / remaining_days) if remaining_days > 0 else remaining_usd
+    )
+
+    thresholds = tuple(sorted(set(int(t) for t in inputs.alert_thresholds)))
+    if thresholds:
+        warn_fraction = min(thresholds) / 100.0
+    else:
+        warn_fraction = _BUDGET_DEFAULT_WARN_FRACTION
+
+    projected = max(projected_low, projected_high)
+    if spent > target or projected > target:
+        verdict = "over"
+    elif projected >= warn_fraction * target:
+        verdict = "warn"
+    else:
+        verdict = "ok"
+
+    low_confidence = (
+        elapsed_fraction < _BUDGET_LOW_CONF_ELAPSED_FRACTION or spent <= 0.0
+    )
+
+    crossed = tuple(t for t in thresholds if consumption_pct + 1e-9 >= t)
+
+    return BudgetStatus(
+        spent_usd=spent,
+        remaining_usd=remaining_usd,
+        consumption_pct=consumption_pct,
+        elapsed_fraction=elapsed_fraction,
+        projected_eow_low_usd=projected_low,
+        projected_eow_high_usd=projected_high,
+        verdict=verdict,
+        daily_budget_remaining_usd=daily_budget_remaining_usd,
+        daily_pace_usd=daily_pace_usd,
+        low_confidence=low_confidence,
+        crossed_thresholds=crossed,
+    )