cctally 1.7.0 → 1.7.2

package/CHANGELOG.md

@@ -5,6 +5,33 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.7.2] - 2026-05-16
+
+### Fixed
+- `cctally record-usage`: detect Anthropic-issued in-place weekly credits (utilization drops while `resets_at` stays unchanged) and emit a `week_reset_events` row + force-write `hwm-7d` + seed a post-credit snapshot so dashboard / forecast / report / percent-breakdown / TUI stop freezing at the pre-credit high-water mark. Fires on a `>=25.0pp` drop, the same threshold as the existing boundary-shift path that catches Anthropic-shifted `resets_at` advances mid-week. Deduped via belt-and-suspenders: a pre-check `SELECT 1 FROM week_reset_events WHERE new_week_end_at = ?` short-circuits before any INSERT attempt, the `UNIQUE(old_week_end_at, new_week_end_at)` DDL constraint absorbs any race that slips past, and the post-credit seed snapshot brings prior_pct down to ~current_pct so the next tick's drop predicate is naturally below threshold (single trigger per credit). HWM file `hwm-7d` is force-written via the credit-only escape hatch since the normal monotonic-up write path at `bin/_cctally_record.py:1511-1525` would refuse to decrease it; force-write lands AFTER `conn.commit()` of the event row so a concurrent reader doesn't see the new HWM before the durable signal of the credit.
+- `cctally record-usage`: the monotonic 7d DB clamp now joins against `week_reset_events`, so post-credit `MAX(weekly_percent)` filters to samples captured at-or-after `effective_reset_at_utc`. Fresh OAuth values land naturally instead of being held back by pre-credit history. No-op when no event row exists for the week (`COALESCE` defaults the filter to epoch-zero, so the regression-guard `test_reset_aware_clamp_without_event_preserves_legacy_behavior` confirms byte-identical legacy clamp behavior on un-credited weeks).
+- `cctally`: `_backfill_week_reset_events` extended to detect historical in-place weekly credits in existing DBs via the same predicate as the live path — parallel `elif prior_end == cur_end` branch inside the existing scan loop, same `prior_end_dt > captured_dt` + `>=25pp` drop gate, same `_floor_to_hour` for the effective moment. Idempotent via `UNIQUE(old_week_end_at, new_week_end_at)` + `INSERT OR IGNORE`; the existing boundary-shift branch is byte-identical to v1.7.1 so existing user DBs synthesize event rows for past credits without affecting prior backfill output.
+- `cctally percent_milestones`: schema migration 005 adds a `reset_event_id` column (default 0 = pre-credit segment / no-event sentinel) and reshapes the UNIQUE constraint from `(week_start_date, percent_threshold)` to `(week_start_date, percent_threshold, reset_event_id)` so post-credit threshold crossings land as separate rows from any pre-credit ones at the same threshold. SQLite can't ALTER a UNIQUE constraint in place — the handler uses the rename-recreate-copy idiom inside its own `BEGIN/COMMIT`; fast-path probe stamps the marker without re-doing the rename when the column is already present (covers fresh-install + partial-failure-retry cases). Existing rows backfill to `reset_event_id = 0` via the column DEFAULT; the migration's per-migration goldens at `tests/fixtures/migrations/per-migration/005_percent_milestones_reset_event_id/{pre,post}.sqlite` are the first lazy-adopted entries under that directory pattern.
+- `cctally percent-breakdown` + dashboard milestone panel + TUI percent-milestones panel: now filter milestone rows by the active `week_reset_events` segment for the queried week (the latest event keyed on the canonical hour-floored `week_end_at`). A credited week's header (which already reflects the post-credit window via the canon-boundary rewrite) is now coherent with its body — pre- and post-credit crossings read as independent ledgers. An empty post-credit segment renders a distinct "(post-credit segment, no milestones crossed yet)" hint so the user can distinguish a freshly-credited week from a genuinely silent one; without this, a fresh-credited week would render "No percent milestones recorded for this week" while the pre-credit ledger is still intact in the DB.
+- `cctally` milestone writer (`maybe_record_milestone` + helpers): now stamps the active `week_reset_events.id` into `percent_milestones.reset_event_id` so post-credit threshold crossings land as separate rows; `get_max_milestone_for_week`, `get_milestone_cost_for_week`, the `alerted_at` UPDATE inside the writer, and the post-INSERT cumulative-cost SELECT for the alert payload all gained a `reset_event_id` filter. Active-segment resolution uses `unixepoch()` on both sides of the `<=` comparison to absorb the `+00:00` vs `Z` offset mix between `week_reset_events.effective_reset_at_utc` (stored as `+00:00`) and a snapshot's `captured_at_utc` (stored as `Z`). Combined with the new UNIQUE shape this means a credited week sees post-credit 1% / 2% / 3% alerts fire fresh even if the pre-credit ledger already crossed those thresholds; the self-heal probe in the dedup-no-insert bail-out path is now also segment-scoped so the post-credit ledger doesn't get silently suppressed by a high pre-credit MAX.
+- `cctally doctor`: new `data.post_credit_milestones` check warns when a credited week (`week_reset_events` row with effective < now) has `latest_weekly_percent >= 1.0` AND zero post-credit milestone rows. Informational WARN (no remediation), since the next `record-usage` tick at >=1% will self-heal via the segment-aware probe — surfaces the upgrade-window gap between when the credit lands and when the user accumulates enough usage to cross the post-credit 1% threshold. The `weekly_percent < 1.0` short-circuit prevents false-positive warns immediately after a credit when the user simply hasn't started using the new segment yet.
+- `cctally record-usage`: round-3 user-test follow-up — defensive cleanup in the in-place credit detection branch. Between the moment Anthropic credits the user and `cctally record-usage` firing, the external `claude-statusline` tool can replay stale pre-credit `--percent` values (its in-memory HWM cache hasn't refreshed yet) — those replays land `captured_at_utc >= effective_reset_at_utc` and poison the reset-aware clamp's MAX over the post-credit segment, blocking legitimate fresh OAuth values from landing. The credit branch now runs a narrow DELETE pass scoped to `(week_start_date = ?, captured_at_utc >= effective_iso, round(weekly_percent, 1) = round(prior_pct, 1))` after writing the event row + force-writing `hwm-7d`. Strict-equality predicate avoids deleting legitimate post-credit climbs. Reported by user on the v1.7.2 dev branch with manual recovery already applied to the production DB; fix prevents recurrence.
+- `cctally report` / `weekly`: round-3 user-test follow-up — credited weeks now render as TWO trend rows (pre-credit segment closed at `effective_reset_at_utc` AND post-credit segment opening at `effective_reset_at_utc`). Previously only the post-credit segment surfaced and the pre-credit segment's usage + cost (the bulk of the week's spend in the originating incident: 67% / $1484 across 6 days) was silently dropped from the trend table. `_apply_reset_events_to_weekrefs` synthesizes the pre-credit ref alongside the post-credit one for events whose row shape is `old_week_end_at == effective_reset_at_utc` (the in-place credit marker — boundary-shift events stay single-ref). `cmd_report`'s per-trend-row usage lookup now passes `as_of_utc = ref.week_end_at` for credited weeks so each segment renders its own latest snapshot (the shared `week_start_date` lookup key would otherwise return the post-credit value for both rows); non-credit weeks still use the unfiltered lookup so existing test fixtures that seed snapshots outside the API-derived week window keep finding their rows.
+- `cctally blocks`: round-3 user-test follow-up — `_load_recorded_five_hour_windows` now overlays canonical anchors from `five_hour_blocks.five_hour_resets_at` (heavy-weight = 1000 per row) on top of the existing `weekly_usage_snapshots.five_hour_resets_at` source. The canonical rollup table holds the API-anchored 5h reset moment after `_canonical_5h_window_key` has absorbed Anthropic's seconds-level jitter; the heavy weight ensures that whenever the rollup table sees a window, the rollup's anchor always wins over any jittered raw snapshot value at the same 10-minute-floored key. Symptom this fixes: after an in-place credit, `cctally blocks` showed the ACTIVE row with the heuristic `~HH:MM` prefix while `cctally five-hour-blocks` correctly showed `⚡ HH:MM` (API-anchored). Both views now agree on the API anchor whenever the rollup table has it.
+- `cctally report`: round-4 user-test follow-up — the "current week" summary box no longer renders the PRE-credit row (the closed segment) for credited weeks. Round-3's pre-credit ref synthesis in `_apply_reset_events_to_weekrefs` left both refs sharing `WeekRef.key`, so the match predicate `week_ref.key == current_ref.key` matched BOTH refs in `cmd_report`'s `current_row` loop and last-write-wins picked whichever was processed last. `current_ref` is now routed through `_apply_reset_events_to_weekrefs` itself so its `week_start_at` reflects the post-credit segment's effective start, and the row-match tightens to require BOTH `key` AND `week_start_at` equality — the pre-credit ref (original `week_start_at`) no longer overwrites the post-credit row's selection. Non-credited weeks are unaffected (`_apply_reset_events_to_weekrefs` is a no-op without an event row). On the user's live DB: summary box now correctly shows post-credit `4%` instead of pre-credit `67%`.
+- `cctally blocks`: round-4 user-test follow-up — the ACTIVE 5h row now swaps to the API-anchored window when a canonical `five_hour_blocks` row exists for the current `five_hour_window_key`. Round-3's anchor-overlay in `_load_recorded_five_hour_windows` only fires when heuristic and canonical fall in the same 10-minute floor bucket; the user's heuristic ACTIVE anchor at `23:00 IDT` and the API-anchored `20:50 IDT` are 130 minutes apart (different floor buckets) so the swap didn't trigger. A new post-pass helper `_maybe_swap_active_block_to_canonical` looks up the live key from `weekly_usage_snapshots`, joins to `five_hour_blocks`, and — when the canonical window is still open relative to `now` — rewrites the active block's `start_time` / `end_time` to the canonical pair and flips `anchor` to `"recorded"` so the renderer drops the `~` prefix. Skips cleanly when no canonical row matches or the canonical window has already closed (then the heuristic anchor reflects genuine ongoing activity in a later window). `cctally blocks` ACTIVE row + `cctally five-hour-blocks` ACTIVE row now agree on the API anchor.
+- `cctally blocks`: round-5 user-test follow-up — the active-block canonical swap now ALSO re-aggregates token / cost totals over the canonical interval (Bug F). The round-4 swap only rewrote the displayed timestamps; the underlying entries were still grouped against the heuristic anchor's `[heuristic_start, heuristic_end)` interval, so a displayed `20:50 IDT → 01:50 IDT` window could show cost from the heuristic's `23:00 → 04:00` group instead — on live data the user saw the swapped window with a $45.42 total when the canonical window's real cost was $128+. `_maybe_swap_active_block_to_canonical` now takes the `all_entries` list, filters to `[canonical_block_start, canonical_block_end)`, and rebuilds the block via `_build_activity_block(...)` so every total stays in one code path (no field-by-field assignment that could drift if the dataclass grows). The displayed timestamps and totals are now coherent on every active-block swap.
+- `cctally` dashboard envelope `trend.weeks[]` (and `cctally weekly-history`): round-5 user-test follow-up — credited weeks now render as TWO trend rows with correct per-segment `used_pct` values (Bug G). Round-3 fixed `cmd_report`'s trend table but `_tui_build_trend` (in `bin/_cctally_tui.py`) — which feeds the dashboard's `trend.weeks[]` envelope, the dashboard share modal's trend panel, and `weekly-history` — still used a key-only `get_latest_usage_for_week(conn, week_ref)` lookup that returned the SAME post-credit snapshot for both segments (both refs share `WeekRef.key`). User saw "May 09 4%" and "May 15 4%" side-by-side in the dashboard's `$/1% Trend` panel — both segments collapsed to the post-credit value. The fix mirrors `cmd_report`'s pattern: detect split-keys (where multiple refs in `week_refs` share `key`), pin `as_of_utc = week_ref.week_end_at` for those refs so each segment finds its own latest snapshot, and route the current_ref through `_apply_reset_events_to_weekrefs` so the `is_current` predicate can disambiguate by BOTH `key` AND `week_start_at` (not just key). Non-credit weeks keep the legacy unfiltered lookup so existing fixtures stay byte-stable.
+- `cctally` dashboard Weekly panel: round-5 user-test follow-up — credited weeks now show TWO rows in the Weekly panel (pre-credit + post-credit segments) instead of silently dropping the pre-credit interval (Bug K). `_apply_reset_events_to_subweeks` shifts the credited SubWeek's `start_ts` to `effective_reset_at_utc`, so `_aggregate_weekly`'s bucket for that week covers ONLY the post-credit interval; the bulk of the week's cost (the user's $1491 of pre-credit spend) was invisible in the panel — only the $134 post-credit segment showed up. `_dashboard_build_weekly_periods` now post-processes its bucket-built rows: for each in-place credit event (`old_week_end_at == effective_reset_at_utc` shape) whose post-credit SubWeek end_ts matches a built row, the dashboard re-walks the entries list filtered to `[original_start, effective)`, re-aggregates cost / tokens / per-model via `_calculate_entry_cost`, looks up `weekly_percent` capped to `captured_at_utc <= effective_reset_at_utc` (the pre-credit peak), and inserts a synthesized pre-credit `WeeklyPeriodRow` BEFORE the post-credit row. Pre-credit row's label uses the original start date, post-credit's label keeps the effective reset date; `is_current` only fires on the post-credit row (the live segment). No-op on non-credit weeks.
+- `cctally blocks`: round-5 user-test follow-up — eliminated the phantom heuristic "~" block that appeared between two canonical blocks after an in-place credit (Bug J). Anthropic's credit creates two overlapping canonical 5h windows: the pre-credit `[block_start_at, original_resets_at]` (e.g. 15:50 → 20:50 UTC) and the post-credit `[block_start_at, new_resets_at]` (e.g. 17:50 → 22:50 UTC). `_select_non_overlapping_recorded_windows` enforces the 5h-disjoint invariant by dropping ONE of the overlapping anchors — leaving the dropped block's entries unanchored and rendered as a heuristic "~" row at $45 sandwiched between the two real canonical rows (visible on the user's `cctally blocks` output). `_load_recorded_five_hour_windows` now detects overlapping canonical pairs where an in-place credit moment falls inside the overlap, truncates the EARLIER block's R to the credit moment (10-min floor), and records `(truncated_R → original_block_start)` in a new `block_start_overrides` map returned alongside the anchor list. Truncated anchors bypass the weighted scheduler (their non-overlap is guaranteed by construction, but the scheduler treats every R as the end of a full 5h window and would still flag them as colliding with the adjacent earlier block). `_group_entries_into_blocks` accepts `block_start_overrides` and uses it both for entry partitioning (the bucket's lower bound becomes the override, not `R - 5h`) and display (the recorded block's `start_time` becomes the override, not `R - 5h` which would be hours before the real start). Result: the truncated block displays correctly with its real `block_start_at` and its real ~2-hour duration instead of the misleading 5h heuristic window. Threaded through `cmd_blocks`, `_dashboard_build_blocks_panel`, and the dashboard `/api/block/:start_at` handler so all three callers see the same anchor set.
+
+## [1.7.1] - 2026-05-15
+
+### Fixed
+- `cctally record-usage` / `sync-week`: `week_start_date` bucket key is now anchored on the canonical UTC calendar day of `week_start_at`, not the host-local-TZ `.date()` of the parsed datetime. When the cctally process briefly inherits a non-UTC `TZ` (e.g., `TZ=America/Los_Angeles` for a `+03:00` host process during refactor work), the same physical subscription week silently forks across two `week_start_date` values, leaving `cctally report` Trend with two rows per current window — one frozen at the moment of the TZ flip, one still updating. The writer fix at `_derive_week_from_payload` / `pick_week_selection` prevents new ghosts; a companion self-heal migration `004_heal_forked_week_start_date_buckets` merges any pre-existing forked rows on the next `open_db()` (usage/cost UPDATE the date columns to `substr(at, 1, 10)`; milestones DELETE on `UNIQUE(week_start_date, percent_threshold)` collision against the canonical row, else UPDATE). A new `data.forked_buckets` doctor check (visible in `cctally doctor` and the dashboard) surfaces the invariant as `fail` with per-table counts so the next regression is visible immediately. `_bootstrap_rename_legacy_markers` is now idempotent against the duplicate-marker case — both the legacy unprefixed and the new prefixed marker rows present from a back-and-forth across cctally versions — by DELETEing the legacy row when its prefixed counterpart already exists and preserving the prefixed row's authoritative `applied_at_utc`; previously the plain UPDATE collided on `schema_migrations.PRIMARY KEY` and permanently blocked the dispatcher from running any subsequent migration (including the heal).
+- `brew` installs: `cctally --help`, `cctally doctor`, the dashboard share GUI, and the CLI `--format md|html|svg` flag no longer crash with `FileNotFoundError` looking for runtime sibling modules. The Homebrew formula template's install block enumerated only `USER_FACING_BINS` since v1.4.0, so the lazy-loaded `_lib_doctor.py` / `_lib_share.py` / `_lib_share_templates.py` siblings never reached `libexec/bin` on brew layouts — `doctor`, the share modal, and the `--format` flag have been latently broken on every brew install since they landed. The v1.6.1 CHANGELOG note that "Homebrew copies the whole prefix; brew unaffected" was incorrect — the formula has always copied a per-name list, not the whole prefix. The bin/cctally split refactor on this branch promoted `_lib_semver` to an EAGER import at `bin/cctally:213`, which would have turned the latent crash into an immediate one (`cctally --help` itself stops resolving on a brew install missing the sibling). `homebrew/cctally.rb.template` now installs every `bin/_lib_*.py` and `bin/_cctally_*.py` runtime sibling via `Dir.glob` alongside `USER_FACING_BINS`, and `tests/test_package_files.py` gains a parity guard so future sibling additions can't silently drop out of the brew install layout. The next release cut after this branch merges ships a working brew formula for the first time since v1.4.0.
+- `update` (self-heal): `_self_heal_current_version` no longer corrupts the global `update-state.json` when `cctally` is invoked from a development clone. The post-command hook reads `CHANGELOG_PATH` via `__file__` (resolved against the dev tree's `CHANGELOG.md`, not the installed binary's), so any `./bin/cctally` invocation from the source tree — including the six phases of `cctally release` itself — stamped `current_version` to whatever the dev tree's CHANGELOG claimed, masking the actually-installed version on the user's machine until the next `rm ~/.local/share/cctally/update-state.json`. The self-heal now early-returns when a `.git/` directory sits next to `CHANGELOG_PATH`, since production tarballs (npm tar, brew archive) never ship `.git/`; legitimate out-of-band upgrades on installed npm/brew binaries still self-heal as before. Symmetric twin of the v1.7.0 brew fix (CHANGELOG-via-`__file__` ≠ installed-binary's CHANGELOG); same root cause, different trigger. Resolves [#42](https://github.com/omrikais/cctally-dev/issues/42).
+
 ## [1.7.0] - 2026-05-13
 
 ### Added

package/bin/_cctally_alerts.py

@@ -0,0 +1,231 @@
+"""Alert dispatch I/O + `cctally alerts test` entry point.
+
+Lazy I/O sibling: holds the two helpers that perform real-world side
+effects for the threshold-actions feature, plus the test-entry command:
+
+- `_alerts_log_path()` — resolve / mkdir the `alerts.log` path under
+  `LOG_DIR`. Pure path-derivation that touches the filesystem (creates
+  the parent dir) on every call.
+- `_dispatch_alert_notification(payload, *, popen_factory, mode, tz)` —
+  spawn `osascript` (best-effort, non-blocking) to display a macOS
+  Notification Center popup, then append a single tab-delimited line to
+  `alerts.log` with the terminal status. Fire-and-forget contract; never
+  raises.
+- `cmd_alerts_test(args)` — synthetic-payload entry point exposed via
+  `cctally alerts test`. Builds a payload through the same
+  `_build_alert_payload_*` helpers production uses, routes through
+  `_dispatch_alert_notification` with `mode="test"`, and reports the
+  outcome via stdout / exit code.
+
+The pure payload primitives (`_alert_text_weekly`,
+`_alert_text_five_hour`, `_escape_applescript_string`,
+`_build_alert_payload_weekly`, `_build_alert_payload_five_hour`) live
+in `bin/_lib_alerts_payload.py` (Phase A extraction); this module
+imports them directly via `_load_lib`, which keeps the dispatch path
+free of an extra bounce through cctally's re-exports.
+
+bin/cctally back-references via `_cctally()` (spec §5.5 pattern, same
+as `bin/_cctally_setup.py`):
+- `LOG_DIR` — base dir under which `alerts.log` lives (subject to
+  HOME-redirection by test fixtures via `monkeypatch.setitem(ns,
+  "LOG_DIR", ...)`).
+- `now_utc_iso` — single timestamp source used for both the log-line
+  timestamp and the synthetic test payload's `crossed_at_utc`.
+
+bin/cctally re-exports every public symbol below so the
+`bin/cctally-alerts-dispatch-test` harness (SourceFileLoader-based,
+attribute access via `m._dispatch_alert_notification(...)`) and the
+existing internal call sites in `cmd_record_usage` + the dashboard
+alerts/test handler resolve unchanged.
+
+Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import importlib.util as _ilu
+import os
+import pathlib
+import subprocess
+import sys
+
+
+def _cctally():
+    """Resolve the current `cctally` module at call-time (spec §5.5)."""
+    return sys.modules["cctally"]
+
+
+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
+
+
+_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
+_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
+
+
+def _alerts_log_path() -> "pathlib.Path":
+    """Return ``~/.local/share/cctally/logs/alerts.log`` (parent dirs created).
+
+    Resolves through the same ``APP_DIR`` / ``LOG_DIR`` derived at module
+    import time from ``Path.home()``, so a HOME override before import (the
+    pattern used elsewhere in this codebase — e.g. ``cctally-config-test``)
+    transparently relocates the log without a separate env-var convention.
+    """
+    log_dir = _cctally().LOG_DIR
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir / "alerts.log"
+
+
+def _dispatch_alert_notification(
+    payload: dict,
+    *,
+    popen_factory=subprocess.Popen,
+    mode: str = "real",
+    tz: "object | None" = None,
+) -> str:
+    """Spawn osascript to display a macOS notification (non-blocking, best-effort).
+
+    Returns ``"queued"`` on successful Popen, ``"spawn_error: <ExcType>: <msg>"``
+    on failure. Writes EXACTLY ONE line to ``alerts.log`` with the terminal
+    status (no contradictory pre-/post-Popen log pair). Never raises:
+    Popen-spawn failures and log-write failures are both swallowed so the
+    dispatch contract stays independent of the OS / FS state.
+
+    Production callers ignore the return value (fire-and-forget); test
+    callers assert on it via an injected ``popen_factory``.
+
+    Integration-harness escape hatch: when ``popen_factory`` is left as
+    its default (``subprocess.Popen``) AND the env var
+    ``CCTALLY_TEST_POPEN_FACTORY=raise_filenotfound`` is set, swap in a
+    factory that raises ``FileNotFoundError("no osascript")``. Used by
+    ``bin/cctally-alerts-test`` to exercise the spawn-error branch
+    end-to-end (subprocess invocation of ``cctally record-usage`` —
+    direct kwargs-injection isn't reachable through the CLI). Only the
+    one canonical token is honored; unknown values fall through to real
+    Popen so a typo can't silently neuter dispatch in production.
+    """
+    if (
+        popen_factory is subprocess.Popen
+        and os.environ.get("CCTALLY_TEST_POPEN_FACTORY") == "raise_filenotfound"
+    ):
+        def _raise_filenotfound(*_args, **_kwargs):
+            raise FileNotFoundError("no osascript")
+        popen_factory = _raise_filenotfound
+
+    axis = payload["axis"]
+    if axis == "weekly":
+        title, subtitle, body = _alert_text_weekly(payload, tz)
+    elif axis == "five_hour":
+        title, subtitle, body = _alert_text_five_hour(payload, tz)
+    else:
+        title, subtitle, body = (
+            "cctally - alert",
+            "",
+            f"axis={axis} threshold={payload.get('threshold')}",
+        )
+
+    script = (
+        f'display notification "{_escape_applescript_string(body)}"'
+        f' with title "{_escape_applescript_string(title)}"'
+        f' subtitle "{_escape_applescript_string(subtitle)}"'
+    )
+
+    status: str
+    try:
+        popen_factory(
+            ["osascript", "-e", script],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            close_fds=True,
+            start_new_session=True,
+        )
+        status = "queued"
+    except (FileNotFoundError, PermissionError, OSError) as exc:
+        status = f"spawn_error: {exc.__class__.__name__}: {exc}"
+
+    # SINGLE log line per dispatch attempt (Codex P1#2 fix: no
+    # contradictory "queued" + "spawn_error" pair for the same call).
+    try:
+        log_path = _alerts_log_path()
+        ctx = payload.get("context") or {}
+        window_key = (
+            ctx.get("week_start_date")
+            or ctx.get("five_hour_window_key")
+            or ""
+        )
+        line = (
+            f"{_cctally().now_utc_iso()}\t{axis}\t{payload.get('threshold')}\t{window_key}"
+            f"\t{mode}\t{status}\n"
+        )
+        with open(log_path, "a") as f:
+            f.write(line)
+    except OSError:
+        pass  # log-write failures must not affect dispatch contract
+
+    return status
+
+
+def cmd_alerts_test(args: argparse.Namespace) -> int:
+    """Send a synthetic test alert through the dispatch pipeline.
+
+    Builds a synthetic payload via the same ``_build_alert_payload_*``
+    helpers production uses, then routes through ``_dispatch_alert_notification``
+    with ``mode="test"`` so the alerts.log line carries the ``test``
+    discriminator (5th tab-delimited field) — distinguishes from real
+    threshold-crossing alerts written by ``cmd_record_usage``.
+
+    No DB writes: this path exists purely to validate end-to-end
+    osascript + log behavior. Exit codes:
+      0  alert was queued (Popen succeeded)
+      1  osascript missing on this host (FileNotFoundError)
+      2  --threshold out of [1, 100] range
+      3  other spawn error (PermissionError, OSError, ...)
+    """
+    c = _cctally()
+    axis = "weekly" if args.axis == "weekly" else "five_hour"
+    threshold = int(args.threshold)
+    if not (1 <= threshold <= 100):
+        print(
+            f"cctally: --threshold must be in [1, 100], got {threshold}",
+            file=sys.stderr,
+        )
+        return 2
+    if axis == "weekly":
+        payload = _build_alert_payload_weekly(
+            threshold=threshold,
+            crossed_at_utc=c.now_utc_iso(),
+            week_start_date=dt.date.today().isoformat(),
+            cumulative_cost_usd=1.23,
+            dollars_per_percent=0.01,
+        )
+    else:
+        payload = _build_alert_payload_five_hour(
+            threshold=threshold,
+            crossed_at_utc=c.now_utc_iso(),
+            five_hour_window_key=int(dt.datetime.now(dt.timezone.utc).timestamp()),
+            block_start_at=c.now_utc_iso(),
+            block_cost_usd=1.23,
+            primary_model="claude-sonnet-4-6",
+        )
+    status = _dispatch_alert_notification(payload, mode="test")
+    if status == "queued":
+        print("Test alert dispatched (mode=test). Check Notification Center.")
+        return 0
+    if "FileNotFoundError" in status:
+        print(f"cctally: {status}", file=sys.stderr)
+        return 1
+    print(f"cctally: {status}", file=sys.stderr)
+    return 3