cctally 1.22.3 → 1.23.0

package/bin/_cctally_record.py

@@ -285,6 +285,38 @@ def insert_budget_milestone(*args, **kwargs):
     return sys.modules["cctally"].insert_budget_milestone(*args, **kwargs)
 
 
+def insert_projected_milestone(*args, **kwargs):
+    return sys.modules["cctally"].insert_projected_milestone(*args, **kwargs)
+
+
+def _projected_levels_already_latched(*args, **kwargs):
+    return sys.modules["cctally"]._projected_levels_already_latched(*args, **kwargs)
+
+
+def _build_alert_payload_projected(*args, **kwargs):
+    return sys.modules["cctally"]._build_alert_payload_projected(*args, **kwargs)
+
+
+def _fetch_current_week_snapshots(*args, **kwargs):
+    return sys.modules["cctally"]._fetch_current_week_snapshots(*args, **kwargs)
+
+
+def _apply_midweek_reset_override(*args, **kwargs):
+    return sys.modules["cctally"]._apply_midweek_reset_override(*args, **kwargs)
+
+
+def _assess_forecast_confidence(*args, **kwargs):
+    return sys.modules["cctally"]._assess_forecast_confidence(*args, **kwargs)
+
+
+def _build_budget_status_inputs(*args, **kwargs):
+    return sys.modules["cctally"]._build_budget_status_inputs(*args, **kwargs)
+
+
+def compute_budget_status(*args, **kwargs):
+    return sys.modules["cctally"].compute_budget_status(*args, **kwargs)
+
+
 def _dispatch_alert_notification(*args, **kwargs):
     return sys.modules["cctally"]._dispatch_alert_notification(*args, **kwargs)
 
@@ -384,6 +416,7 @@ _logged_window_key_coerce_failure = False
 #   _cctally_core.HOOK_TICK_THROTTLE_PATH / _LOCK_PATH
 #   c._FIVE_HOUR_JITTER_FLOOR_SECONDS — _lib_five_hour.* re-export
 #   c._RESET_PCT_DROP_THRESHOLD       — bin/_cctally_weekrefs.py constant (re-exported on cctally ns)
+#   c._is_reset_drop                  — bin/_cctally_weekrefs.py helper (re-exported on cctally ns)
 #   c.HOOK_TICK_DEFAULT_THROTTLE_SECONDS
 
 
@@ -787,6 +820,235 @@ def maybe_record_budget_milestone(saved: dict[str, Any]) -> None:
             eprint(f"[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``).
+
+    Returns ``(projected_pct, low_conf)`` or ``None`` when no current-week
+    snapshot resolves. The value is computed by the IDENTICAL formula +
+    IDENTICAL inputs that produce ``ForecastOutput.week_avg_projection_pct``
+    (``_load_forecast_inputs`` → ``_compute_forecast``): ``p_now`` / elapsed /
+    remaining come from ``_fetch_current_week_snapshots`` +
+    ``_apply_midweek_reset_override`` (the same reset-aware window resolution
+    forecast uses), ``r_avg = p_now / elapsed_hours`` (``p_week_start`` treated
+    as 0, matching the forecast kernel), and
+    ``projected = p_now + r_avg * remaining_hours``. The reconcile invariant
+    binds the fired value to forecast's ``week_avg_projection_pct`` within
+    1e-9, so the two MUST share the formula by construction.
+
+    LOW CONF mirrors the displayed forecast confidence: the binary
+    ``_assess_forecast_confidence(elapsed_hours, p_now, len(samples))`` plus the
+    ``no_sample_ge_24h`` clause ``_load_forecast_inputs`` appends — so a thin
+    early-week window that forecast renders ``LOW CONF`` never fires a
+    projected alert.
+
+    Deliberately does NOT call ``_sum_cost_for_range`` (the weekly-% projection
+    needs no spend; the forecast kernel's ``week_avg_projection_pct`` is also
+    spend-free).
+    """
+    fetched = _fetch_current_week_snapshots(conn, now_utc)
+    if fetched is None:
+        return None
+    week_start_at, week_end_at, samples = fetched
+    week_start_at, samples = _apply_midweek_reset_override(
+        conn, week_start_at, week_end_at, samples
+    )
+    if not samples:
+        return None
+    p_now = samples[-1][1]
+    elapsed_hours = (now_utc - week_start_at).total_seconds() / 3600.0
+    remaining_hours = max(0.0, (week_end_at - now_utc).total_seconds() / 3600.0)
+    r_avg = p_now / elapsed_hours if elapsed_hours > 0 else 0.0
+    projected_pct = p_now + r_avg * remaining_hours
+
+    # Confidence: same predicate + the same no_sample_ge_24h augmentation that
+    # _load_forecast_inputs applies, so this LOW CONF gate == forecast's.
+    confidence, _reasons = _assess_forecast_confidence(
+        elapsed_hours, p_now, len(samples)
+    )
+    target_24h = now_utc - dt.timedelta(hours=24)
+    has_sample_ge_24h = any(s[0] <= target_24h for s in samples)
+    if not has_sample_ge_24h:
+        confidence = "low"
+    return (projected_pct, confidence == "low")
+
+
+def maybe_record_projected_alert(saved: dict[str, Any]) -> None:
+    """Projected-pace detect-and-arm (axis ``projected``, #121).
+
+    Fires on the WEEK-AVERAGE projection (never the displayed high-end verdict
+    band) for ``weekly_pct`` and/or ``budget_usd``. Its OWN detect-and-arm —
+    NOT folded into ``maybe_record_milestone`` (Section 1 / Codex P0-3) — called
+    from ``cmd_record_usage`` in its own ``try`` after the weekly/5h/budget
+    blocks.
+
+    Master gates (Codex P1-2): ``weekly_pct`` fires only under
+    ``alerts.enabled && alerts.projected_enabled``; ``budget_usd`` only under
+    ``_budget_alerts_active(budget_cfg) && budget.projected_enabled``. Both
+    toggles default OFF (no surprise notifications on upgrade). When NEITHER is
+    on, returns after only a cheap config read — no projection math, no cost
+    work.
+
+    Pre-probe (Codex P1-1): a metric whose levels are ALL already latched is
+    skipped BEFORE any projection / cost work.
+
+    Snap-up (Codex P2-1): a level fires when ``projected + 1e-9 >= threshold``.
+    Latch / fire-once: ``UNIQUE(week_start_at, metric, threshold)`` + the
+    rowcount==1 predicate — a later recovery neither un-fires nor re-fires.
+    Mid-week reset re-anchors ``week_start_at`` (budget pattern; no
+    ``reset_event_id``).
+
+    Set-then-dispatch: INSERT ``commit=False``, stamp ``alerted_at`` in the same
+    txn, commit, THEN best-effort dispatch. A dispatch failure never rolls back
+    the milestone.
+
+    The ``budget_usd`` leg reuses the SAME ``_build_budget_status_inputs`` +
+    ``compute_budget_status`` path that produces ``budget --json``'s
+    ``week_avg_projection_usd`` (the reconcile-bound field) — value-exact by
+    construction. The cache is already warm from the actual-budget axis's spend
+    SUM this same tick, so this is not a second aggregation pass; the pre-probe
+    additionally skips it entirely when all budget levels are latched.
+    """
+    # The `projected_enabled` toggles are validated keys on the alerts/budget
+    # blocks (bool-validated; default OFF), so read them straight off the
+    # validated getter dicts — no raw-block fallback (which would re-emit the
+    # "unknown alerts config key" warning every tick and bypass bool
+    # validation). Master gates still compose with the parent-axis predicates.
+    cfg = load_config()
+    try:
+        alerts_cfg = _get_alerts_config(cfg)
+    except _AlertsConfigError as exc:
+        _warn_alerts_bad_config_once(exc)
+        alerts_cfg = {"enabled": False, "projected_enabled": False}
+    try:
+        budget_cfg = _get_budget_config(cfg)
+    except _BudgetConfigError as exc:
+        _warn_budget_bad_config_once(exc)
+        budget_cfg = {}
+
+    weekly_on = bool(alerts_cfg.get("enabled")) and bool(
+        alerts_cfg.get("projected_enabled")
+    )
+    budget_on = _budget_alerts_active(budget_cfg) and bool(
+        budget_cfg.get("projected_enabled")
+    )
+    if not (weekly_on or budget_on):
+        return  # cheap config-only path — non-projected users pay nothing
+
+    now_utc = _command_as_of()
+    pending: list[dict[str, Any]] = []
+    conn = open_db()
+    try:
+        # ── weekly_pct leg (snapshot-only, cheap) ───────────────────────────
+        if weekly_on:
+            w_window = _fetch_current_week_snapshots(conn, now_utc)
+            if w_window is not None:
+                ws_at, we_at, samples = w_window
+                ws_at, _ = _apply_midweek_reset_override(
+                    conn, ws_at, we_at, samples
+                )
+                week_key = ws_at.isoformat(timespec="seconds")
+                levels = (90, 100)
+                if not _projected_levels_already_latched(
+                    conn, week_start_at=week_key, metric="weekly_pct",
+                    levels=levels,
+                ):
+                    proj = _weekly_pct_week_avg_projection(conn, now_utc)
+                    if proj is not None and not proj[1]:
+                        value = proj[0]
+                        for t in levels:
+                            if value + 1e-9 >= t:
+                                pending.append(dict(
+                                    week_start_at=week_key,
+                                    metric="weekly_pct",
+                                    threshold=t,
+                                    projected_value=value,
+                                    denominator=100.0,
+                                ))
+
+        # ── budget_usd leg (reuses the tick's spend via the shared path) ─────
+        if budget_on:
+            target = budget_cfg["weekly_usd"]
+            thresholds = tuple(
+                sorted(set(int(t) for t in budget_cfg["alert_thresholds"]))
+            )
+            window = _resolve_current_budget_window(conn, now_utc)
+            if window is not None and thresholds:
+                b_ws_at, _b_we_at = window
+                b_week_key = b_ws_at.isoformat(timespec="seconds")
+                if not _projected_levels_already_latched(
+                    conn, week_start_at=b_week_key, metric="budget_usd",
+                    levels=thresholds,
+                ):
+                    # skip_sync=True: the actual-budget axis
+                    # (maybe_record_budget_milestone) already ran a
+                    # _sum_cost_for_range this same tick, warming the cache.
+                    # Avoids a redundant JSONL ingest pass here.
+                    inputs = _build_budget_status_inputs(
+                        conn, target_usd=target, now_utc=now_utc,
+                        alert_thresholds=thresholds, skip_sync=True,
+                    )
+                    if inputs is not None:
+                        status = compute_budget_status(inputs)
+                        if not status.low_confidence:
+                            value = status.week_avg_projection_usd
+                            for t in thresholds:
+                                if value + 1e-9 >= (t / 100.0) * float(target):
+                                    pending.append(dict(
+                                        week_start_at=b_week_key,
+                                        metric="budget_usd",
+                                        threshold=t,
+                                        projected_value=value,
+                                        denominator=float(target),
+                                    ))
+
+        # ── arm (set-then-dispatch): INSERT + stamp alerted_at in one txn ────
+        fired: list[dict[str, Any]] = []
+        for p in pending:
+            inserted = insert_projected_milestone(
+                conn,
+                week_start_at=p["week_start_at"],
+                metric=p["metric"],
+                threshold=p["threshold"],
+                projected_value=p["projected_value"],
+                denominator=p["denominator"],
+                commit=False,
+            )
+            # Only the genuine-new-crossing winner (rowcount==1) arms+dispatches;
+            # a racing record-usage instance gets rowcount==0 and skips.
+            if inserted == 1:
+                conn.execute(
+                    "UPDATE projected_milestones SET alerted_at = ? "
+                    "WHERE week_start_at = ? AND metric = ? AND threshold = ? "
+                    "  AND alerted_at IS NULL",
+                    (now_utc_iso(), p["week_start_at"], p["metric"],
+                     p["threshold"]),
+                )
+                fired.append(p)
+        # Single commit: every INSERT + its alerted_at marker durable together.
+        conn.commit()
+    except Exception as exc:
+        eprint(f"[projected-alert] error recording projected milestone: {exc}")
+        fired = []
+    finally:
+        conn.close()
+
+    # Dispatch AFTER commit; a dispatch failure NEVER rolls back the milestone
+    # (set-then-dispatch invariant).
+    for p in fired:
+        try:
+            payload = _build_alert_payload_projected(
+                metric=p["metric"],
+                threshold=p["threshold"],
+                projected_value=p["projected_value"],
+                denominator=p["denominator"],
+                week_start_at=p["week_start_at"],
+            )
+            _dispatch_alert_notification(payload, mode="real")
+        except Exception as dispatch_exc:
+            eprint(f"[projected-alert] dispatch failed: {dispatch_exc}")
+
+
 def _compute_block_totals(
     block_start_at: dt.datetime,
     range_end: dt.datetime,
@@ -1433,6 +1695,134 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
         conn.close()
 
 
+# ── Reset-to-zero debounce marker (issue #128) ─────────────────────────────
+# A transient Anthropic OAuth zero (cold replica / outage) against non-trivial
+# usage would otherwise mis-fire the live in-place reset-to-zero detector. We
+# debounce: the first ~0 ARMS this marker (it does not fire); the next reading
+# CONFIRMS (fires) only if usage stayed low, or CLEARS on recovery toward the
+# baseline. The marker is needed because the write-site clamp suppresses the
+# deferred first zero, so it leaves no DB trace. Losing the marker is always
+# safe (a real reset re-arms and fires one tick later). Best-effort file I/O —
+# the detector must never crash on a marker hiccup. See
+# docs/superpowers/specs/2026-06-02-reset-zero-debounce-design.md.
+_RESET_ZERO_MARKER_NAME = "pending-reset-zero-7d"
+
+
+def _reset_zero_marker_path():
+    return _cctally_core.APP_DIR / _RESET_ZERO_MARKER_NAME
+
+
+def _arm_reset_zero_marker(week_start_date, cur_end_canon, *,
+                           baseline_pct, first_zero_iso):
+    """Persist the pending reset-to-zero candidate. ``first_zero_iso`` MUST be
+    the ``_command_as_of()`` clock value (it becomes the effective anchor on
+    confirm), NOT wall-clock."""
+    try:
+        _reset_zero_marker_path().write_text(
+            f"{week_start_date} {cur_end_canon} "
+            f"{float(baseline_pct)} {first_zero_iso}\n"
+        )
+    except OSError:
+        pass
+
+
+def _clear_reset_zero_marker():
+    try:
+        _reset_zero_marker_path().unlink(missing_ok=True)
+    except OSError:
+        pass
+
+
+def _read_reset_zero_marker():
+    """Return ``(week_start_date, cur_end_canon, baseline_pct, first_zero_iso)``
+    or ``None`` when missing / empty / garbled. Validates ALL fields (arity,
+    float baseline, parseable timestamp) so a malformed marker re-arms cleanly
+    rather than wedging the confirm path."""
+    try:
+        raw = _reset_zero_marker_path().read_text().strip()
+    except OSError:
+        return None
+    if not raw:
+        return None
+    parts = raw.split()
+    if len(parts) != 4:
+        return None
+    week_start_date, cur_end_canon, baseline_raw, first_zero_iso = parts
+    try:
+        baseline_pct = float(baseline_raw)
+    except ValueError:
+        return None
+    try:
+        parse_iso_datetime(first_zero_iso, "reset_zero_marker.first_zero")
+    except ValueError:
+        return None
+    return (week_start_date, cur_end_canon, baseline_pct, first_zero_iso)
+
+
+def _fire_in_place_credit(conn, week_start_date, cur_end_canon, weekly_percent,
+                          *, observed_pre_credit_pct, effective_dt):
+    """Emit/refresh the in-place weekly-credit artifacts (issue #19 + #128).
+    Shared by the immediate >=25pp path and the debounced reset-to-zero
+    confirmation path.
+
+    Side-effect ordering is load-bearing: the event-row INSERT is dedup-gated
+    on a pre-check, but the hwm force-write and stale-replica DELETE run
+    UNCONDITIONALLY — a prior run may have committed the event then died before
+    the pivots (memory: project_dedup_must_not_gate_side_effects). The pivots
+    are individually idempotent (file overwrite + DELETE on a stable predicate).
+
+    ``effective_dt`` is the (already-resolved) reset moment; the immediate path
+    passes ``_floor_to_hour(now_utc)``, the debounced path passes the floored
+    first-zero instant from the marker."""
+    effective_iso = effective_dt.isoformat(timespec="seconds")
+    # Pre-check keyed on new_week_end_at: suppress a duplicate event row across
+    # ticks. UNIQUE(old, new) also dedups, but the pre-check avoids a useless
+    # write attempt and keeps logs clean.
+    already = conn.execute(
+        "SELECT 1 FROM week_reset_events WHERE new_week_end_at = ? LIMIT 1",
+        (cur_end_canon,),
+    ).fetchone()
+    if already is None:
+        # Row shape: old=effective_iso, new=cur_end_canon (DISTINCT) so only
+        # post_map fires on the credited week in _apply_reset_events_to_weekrefs
+        # (old==new collapses it to a zero-width window). observed_pre_credit_pct
+        # stamps the pre-credit baseline (issue #45).
+        conn.execute(
+            "INSERT OR IGNORE INTO week_reset_events "
+            "(detected_at_utc, old_week_end_at, new_week_end_at, "
+            " effective_reset_at_utc, observed_pre_credit_pct) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (now_utc_iso(), effective_iso, cur_end_canon,
+             effective_iso, float(observed_pre_credit_pct)),
+        )
+        conn.commit()
+    # Unconditional pivot 1: force-write hwm-7d so the next status-line render
+    # reflects the post-credit value (the monotonic guard at the normal write
+    # site would refuse to decrease the file).
+    try:
+        (_cctally_core.APP_DIR / "hwm-7d").write_text(
+            f"{week_start_date} {weekly_percent}\n"
+        )
+    except OSError:
+        pass
+    # Unconditional pivot 2: race-defensive cleanup of stale pre-credit replays
+    # (external claude-statusline can replay pre-credit --percent values that
+    # land captured_at >= effective with pct ~= baseline and dominate the
+    # reset-aware clamp). 1.0pp tolerance band absorbs rounding drift; both
+    # sides wrapped in unixepoch() for offset robustness.
+    try:
+        conn.execute(
+            "DELETE FROM weekly_usage_snapshots "
+            "WHERE week_start_date = ? "
+            "  AND unixepoch(captured_at_utc) >= unixepoch(?) "
+            "  AND ABS(weekly_percent - ?) < 1.0",
+            (week_start_date, effective_iso, float(observed_pre_credit_pct)),
+        )
+        conn.commit()
+    except sqlite3.DatabaseError as exc:
+        eprint(f"[record-usage] post-credit cleanup failed: {exc}")
+
+
 def cmd_record_usage(args: argparse.Namespace) -> int:
     """Record usage data from Claude Code status line rate_limits."""
     c = _cctally()
@@ -1639,7 +2029,7 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                     if (
                         prior_end_dt > now_utc
                         and prior_pct is not None
-                        and (float(prior_pct) - float(weekly_percent)) >= c._RESET_PCT_DROP_THRESHOLD
+                        and c._is_reset_drop(prior_pct, weekly_percent)
                     ):
                         # See _backfill_week_reset_events for why we floor
                         # the reset moment to the hour (natural display
@@ -1655,146 +2045,80 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                         )
                         conn.commit()
                 elif prior_end_canon and prior_end_canon == cur_end_canon:
-                    # In-place credit branch (v1.7.2). When `resets_at` stays
-                    # unchanged but `weekly_percent` drops by RESET_PCT_DROP_THRESHOLD
-                    # or more, Anthropic has issued a goodwill in-place weekly
-                    # credit. Emit one week_reset_events row keyed on the
-                    # current end_at (old == new) so the reset-aware clamp
-                    # above and the milestone segment writer can pivot to
-                    # the post-credit segment. The seed snapshot lands via
-                    # the now-reset-aware clamp on this same call.
+                    # In-place credit branch (v1.7.2) + reset-to-zero debounce
+                    # (issue #128). Same end_at across two captures. A >=25pp drop
+                    # is a goodwill credit and fires immediately; a reset-to-zero
+                    # (post <= floor, 3..25pp drop) is debounced against a
+                    # transient API zero — armed on the first ~0, confirmed only
+                    # if the next reading stays low (<= half the pre-zero
+                    # baseline), cleared on recovery toward baseline. The gate
+                    # drops the _is_reset_drop term so the recovery-clear path is
+                    # reachable. See the spec for the midpoint rationale.
                     prior_end_dt = parse_iso_datetime(prior_end_canon, "prior.week_end_at")
-                    if (
-                        prior_end_dt > now_utc
-                        and prior_pct is not None
-                        and (float(prior_pct) - float(weekly_percent)) >= c._RESET_PCT_DROP_THRESHOLD
-                    ):
-                        # Pre-check (Q5 belt-and-suspenders): suppress duplicate
-                        # event rows for the same new_week_end_at across
-                        # consecutive ticks. UNIQUE(old, new) at the DDL
-                        # also catches the duplicate in the (old == new) case,
-                        # but the pre-check avoids a useless write attempt
-                        # and keeps the log clean. After the seed lands at
-                        # post-credit %, the next tick's `prior_pct` will be
-                        # the post-credit value so the drop predicate alone
-                        # also suffices — pre-check is belt-and-suspenders.
-                        already = conn.execute(
-                            "SELECT 1 FROM week_reset_events "
-                            "WHERE new_week_end_at = ? LIMIT 1",
-                            (cur_end_canon,),
-                        ).fetchone()
-                        effective_dt = _floor_to_hour(now_utc)
-                        effective_iso = effective_dt.isoformat(timespec="seconds")
-                        if already is None:
-                            # Row shape: old=effective_iso, new=cur_end_canon
-                            # (distinct values). The previous shape stored
-                            # old==new==cur_end_canon, which let BOTH
-                            # _apply_reset_events_to_weekrefs maps
-                            # (pre_map[old] and post_map[new]) fire on the
-                            # SAME WeekRef — pre_map rewrote week_end_at to
-                            # effective, post_map rewrote week_start_at to
-                            # effective, collapsing the credited week to a
-                            # zero-width window in downstream renders. With
-                            # old==effective and new==cur_end_canon, only
-                            # post_map fires on the credited week (setting
-                            # week_start_at = effective, the intended
-                            # behavior); pre_map keys on effective_iso and
-                            # finds no matching WeekRef in practice. The
-                            # UNIQUE(old, new) constraint permits this
-                            # row, and the pre-check above keys on
-                            # new_week_end_at so dedup still works.
-                            # Stamp ``observed_pre_credit_pct = prior_pct``
-                            # (issue #45): durable record of the pre-credit
-                            # baseline we observed at write time. Decouples
-                            # any future cleanup tooling from re-deriving
-                            # prior_pct via SELECT. Existing rows from
-                            # migration 007 carry NULL.
-                            conn.execute(
-                                "INSERT OR IGNORE INTO week_reset_events "
-                                "(detected_at_utc, old_week_end_at, new_week_end_at, "
-                                " effective_reset_at_utc, observed_pre_credit_pct) "
-                                "VALUES (?, ?, ?, ?, ?)",
-                                (now_utc_iso(), effective_iso, cur_end_canon,
-                                 effective_iso, float(prior_pct)),
-                            )
-                            conn.commit()
-                        # Pivots fire UNCONDITIONALLY whenever a credit
-                        # is detected — they're NOT gated on
-                        # ``already is None``. Memory
-                        # ``project_dedup_must_not_gate_side_effects.md``:
-                        # "Skipping a no-op INSERT must NOT skip
-                        # milestones/rollups/alerts; prior run may have
-                        # died mid-flight." Crash scenario: tick N
-                        # committed the event row, then died before
-                        # HWM + DELETE. Tick N+1's pre-check sees
-                        # ``already`` non-None (the row IS in the
-                        # table) and would skip the pivots, leaving
-                        # the system wedged on pre-credit HWM + stale-
-                        # replica rows. Pivots are individually
-                        # idempotent (file overwrite + DELETE on stable
-                        # predicate), so re-running them is safe.
-                        # ``effective_iso`` is resolved above; on a
-                        # recovery tick it lands on the SAME 10-min
-                        # slot as the original (now_utc has drifted
-                        # only seconds), so the DELETE predicate's
-                        # ``unixepoch(captured_at_utc) >= unixepoch(?)``
-                        # still matches every stale-replica row.
-                        #
-                        # Force-write hwm-7d so the next status-line
-                        # render reflects the post-credit value. The
-                        # monotonic guard at the normal write site
-                        # (below) would refuse to decrease the file;
-                        # this write is the credit-only escape hatch.
-                        # Lands AFTER the conn.commit() so a concurrent
-                        # record-usage reader doesn't see the new HWM
-                        # before the event row is durable.
-                        try:
-                            (_cctally_core.APP_DIR / "hwm-7d").write_text(
-                                f"{week_start_date} {weekly_percent}\n"
-                            )
-                        except OSError:
-                            pass
-
-                        # Race-defensive cleanup. Between the moment
-                        # Anthropic credited the user (effective_iso)
-                        # and this code firing, the EXTERNAL
-                        # claude-statusline tool can replay stale
-                        # pre-credit `--percent` values (it has its
-                        # own in-memory HWM cache and re-runs us once
-                        # per status-line tick). Those replays land
-                        # captured_at_utc >= effective_iso with
-                        # weekly_percent near prior_pct (the pre-credit
-                        # value), and they dominate the reset-aware
-                        # clamp's MAX over the post-credit segment so
-                        # legitimate fresh OAuth values are rejected.
-                        # 1.0pp tolerance band (issue #45) around the
-                        # observed pre-credit baseline absorbs any
-                        # rounding drift between cctally's OAuth read
-                        # and statusline's --percent payload (today
-                        # they match byte-identically, but the band
-                        # future-proofs against Anthropic or statusline
-                        # changing rounding). The band stays well below
-                        # the 25pp in-place credit detection threshold,
-                        # so legitimate post-credit values are never
-                        # caught. Bind is the in-scope ``prior_pct``,
-                        # which equals the just-stamped
-                        # ``observed_pre_credit_pct`` on the event row.
-                        try:
-                            conn.execute(
-                                "DELETE FROM weekly_usage_snapshots "
-                                "WHERE week_start_date = ? "
-                                "  AND unixepoch(captured_at_utc) >= "
-                                "      unixepoch(?) "
-                                "  AND ABS(weekly_percent - ?) < 1.0",
-                                (week_start_date, effective_iso,
-                                 float(prior_pct)),
+                    if prior_end_dt > now_utc and prior_pct is not None:
+                        drop = float(prior_pct) - float(weekly_percent)
+                        big_drop = drop >= c._RESET_PCT_DROP_THRESHOLD
+                        zero_only = (
+                            (not big_drop)
+                            and float(weekly_percent) <= c._RESET_ZERO_FLOOR_PCT
+                            and drop >= c._RESET_ZERO_MIN_DROP_PCT
+                        )
+                        if big_drop:
+                            # >=25pp goodwill credit — fire immediately, never
+                            # debounced. Clear any pending arm (now moot).
+                            _clear_reset_zero_marker()
+                            _fire_in_place_credit(
+                                conn, week_start_date, cur_end_canon, weekly_percent,
+                                observed_pre_credit_pct=float(prior_pct),
+                                effective_dt=_floor_to_hour(now_utc),
                             )
-                            conn.commit()
-                        except sqlite3.DatabaseError as exc:
-                            eprint(
-                                "[record-usage] post-credit cleanup "
-                                f"failed: {exc}"
+                        else:
+                            marker = _read_reset_zero_marker()
+                            armed = (
+                                marker is not None
+                                and marker[0] == week_start_date
+                                and marker[1] == cur_end_canon
                             )
+                            if armed:
+                                baseline_pct = marker[2]
+                                if float(weekly_percent) <= baseline_pct / 2.0:
+                                    # Second reading stayed low → confirm. Anchor
+                                    # the reset at the FIRST-zero instant from the
+                                    # marker (UTC-normalized like the backfill
+                                    # in-place path).
+                                    first_zero_dt = parse_iso_datetime(
+                                        marker[3], "reset_zero_marker.first_zero"
+                                    ).astimezone(dt.timezone.utc)
+                                    _fire_in_place_credit(
+                                        conn, week_start_date, cur_end_canon,
+                                        weekly_percent,
+                                        observed_pre_credit_pct=baseline_pct,
+                                        effective_dt=_floor_to_hour(first_zero_dt),
+                                    )
+                                    # Clear ONLY after the fire completes (P2a):
+                                    # a mid-fire crash leaves the marker armed so
+                                    # the next zero re-confirms + re-runs the
+                                    # idempotent pivots.
+                                    _clear_reset_zero_marker()
+                                else:
+                                    # Recovered toward baseline → transient zero,
+                                    # not a reset. Clear, do not fire.
+                                    _clear_reset_zero_marker()
+                            elif zero_only:
+                                # First ~0 → arm; do NOT fire. The write clamp
+                                # suppresses this 0 (no event row yet), so the
+                                # prior snapshot stays at the baseline and this
+                                # shape re-evaluates next tick. first_zero_iso is
+                                # the _command_as_of() value (now_utc), NOT
+                                # wall-clock — it becomes the effective anchor.
+                                _arm_reset_zero_marker(
+                                    week_start_date, cur_end_canon,
+                                    baseline_pct=float(prior_pct),
+                                    first_zero_iso=now_utc.isoformat(timespec="seconds"),
+                                )
+                            # else: not a reset shape and not armed → nothing.
+                            #       A non-matching stale marker is inert (ignored
+                            #       on key mismatch, overwritten by the next arm).
 
             # ── 5h in-place credit detection (parallel to weekly above) ──
             # Spec §2.2 of
@@ -2328,6 +2652,16 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
     except Exception as exc:
         eprint(f"[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) ||
+    # (_budget_alerts_active && budget.projected_enabled) — both toggles
+    # default OFF, so non-projected users pay only a cheap config read.
+    try:
+        maybe_record_projected_alert(saved)
+    except Exception as exc:
+        eprint(f"[projected-alert] unexpected error: {exc}")
+
     # Write high-water mark so the status line never displays a regression.
     # The file contains "week_start_date weekly_percent" on one line.
     try:

package/bin/_cctally_tui.py

@@ -1193,6 +1193,7 @@ class DataSnapshot:
             r_recent=r_recent,
             final_percent_low=final_low,
             final_percent_high=final_high,
+            week_avg_projection_pct=used_pct + r_avg * remaining_hours,
             projected_cap=final_high >= 100.0,
             already_capped=False,
             cap_at=None,