cctally 1.7.1 → 1.7.3

package/bin/_cctally_record.py

@@ -372,6 +372,47 @@ def _normalize_percent(value: "float | int | None") -> "float | None":
     return round(float(value), _PERCENT_NORMALIZE_DECIMALS)
 
 
+def _resolve_active_five_hour_reset_event_id(
+    conn: "sqlite3.Connection",
+    five_hour_window_key: int,
+) -> int:
+    """Return ``id`` of the most-recent ``five_hour_reset_events`` row for
+    ``five_hour_window_key``, else 0 (pre-credit / no-event sentinel).
+
+    Mirrors the weekly active-segment resolution pattern used by
+    ``maybe_record_milestone`` for ``percent_milestones.reset_event_id``.
+    Called once per ``maybe_update_five_hour_block`` invocation and the
+    return value is threaded through every read/write site that keys on
+    ``(five_hour_window_key, percent_threshold)`` so post-credit threshold
+    crossings land as a distinct row from any pre-credit one at the same
+    threshold. See spec
+    docs/superpowers/specs/2026-05-16-5h-in-place-credit-detection.md §3.3.
+
+    Returns ``0`` when:
+      - The window has no ``five_hour_reset_events`` row (most blocks).
+      - The table doesn't exist yet (DB predates this feature).
+
+    Returns the largest ``id`` matching the window otherwise; the
+    ``ORDER BY id DESC LIMIT 1`` clause is what *defines* "active" in
+    the stacked-credit case (spec §2.3 — multiple events across distinct
+    10-min slots): pre-credit milestones key on ``seg=0``, milestones
+    between credit 1 and credit 2 key on event-1's id, and milestones
+    after credit 2 key on event-2's id.
+    """
+    try:
+        row = conn.execute(
+            "SELECT id FROM five_hour_reset_events "
+            "WHERE five_hour_window_key = ? "
+            "ORDER BY id DESC LIMIT 1",
+            (int(five_hour_window_key),),
+        ).fetchone()
+    except sqlite3.DatabaseError:
+        return 0
+    if row is None:
+        return 0
+    return int(row["id"])
+
+
 def maybe_record_milestone(
     saved: dict[str, Any],
 ) -> None:
@@ -398,7 +439,31 @@ def maybe_record_milestone(
 
     conn = open_db()
     try:
-        max_existing = get_max_milestone_for_week(conn, week_start_date)
+        # Resolve the active segment for THIS captured moment. The segment
+        # is the latest week_reset_events row keyed on week_end_at whose
+        # effective_reset_at_utc <= captured_at; 0 = pre-credit / no-event
+        # sentinel. ``unixepoch()`` normalizes the comparison across mixed
+        # +00:00 / Z offsets (see precedent at bin/cctally:_compute_block_totals
+        # cross-reset detection; also project gotcha
+        # ``unixepoch_for_cross_offset_compare``).
+        captured_at_iso = saved.get("capturedAt") or now_utc_iso()
+        reset_event_id = 0
+        if week_end_at:
+            seg_row = conn.execute(
+                """
+                SELECT id FROM week_reset_events
+                 WHERE new_week_end_at = ?
+                   AND unixepoch(effective_reset_at_utc) <= unixepoch(?)
+                 ORDER BY id DESC LIMIT 1
+                """,
+                (week_end_at, captured_at_iso),
+            ).fetchone()
+            if seg_row is not None:
+                reset_event_id = int(seg_row["id"])
+
+        max_existing = get_max_milestone_for_week(
+            conn, week_start_date, reset_event_id=reset_event_id,
+        )
         if max_existing is not None and current_floor <= max_existing:
             return
 
@@ -482,7 +547,10 @@ def maybe_record_milestone(
         pending_alerts: list[dict[str, Any]] = []
         for pct in range(start_threshold, current_floor + 1):
             if pct == start_threshold and max_existing is not None:
-                prev_cost = get_milestone_cost_for_week(conn, week_start_date, max_existing)
+                prev_cost = get_milestone_cost_for_week(
+                    conn, week_start_date, max_existing,
+                    reset_event_id=reset_event_id,
+                )
                 marginal = (cumulative_cost - prev_cost) if prev_cost is not None else None
             else:
                 marginal = None
@@ -499,6 +567,7 @@ def maybe_record_milestone(
                 cost_snapshot_id=cost_snapshot_id,
                 five_hour_percent_at_crossing=five_hour_percent,
                 commit=False,
+                reset_event_id=reset_event_id,
             )
             # ── Threshold-actions dispatch (set-then-dispatch, spec §3.2) ──
             # Only the genuine-new-crossing winner (rowcount==1) reaches this
@@ -523,17 +592,22 @@ def maybe_record_milestone(
                     conn.execute(
                         "UPDATE percent_milestones SET alerted_at = ? "
                         "WHERE week_start_date = ? AND percent_threshold = ? "
-                        "AND alerted_at IS NULL",
-                        (crossed_at, week_start_date, pct),
+                        "  AND reset_event_id = ? "
+                        "  AND alerted_at IS NULL",
+                        (crossed_at, week_start_date, pct, reset_event_id),
                     )
                     # Cheap re-read for payload context (cumulative_cost_usd
                     # reflects the value persisted on insert, immune to any
                     # subsequent recompute drift). SELECT inside the open
                     # transaction is fine; values reflect post-INSERT state.
+                    # Filter by reset_event_id so a credited week's
+                    # alert payload reads the post-credit row, not a
+                    # stale pre-credit row at the same (week, threshold).
                     row = conn.execute(
                         "SELECT cumulative_cost_usd FROM percent_milestones "
-                        "WHERE week_start_date = ? AND percent_threshold = ?",
-                        (week_start_date, pct),
+                        "WHERE week_start_date = ? AND percent_threshold = ? "
+                        "  AND reset_event_id = ?",
+                        (week_start_date, pct, reset_event_id),
                     ).fetchone()
                     if row is not None:
                         cum = float(row["cumulative_cost_usd"])
@@ -930,7 +1004,23 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
             # Snap-up-by-1e-9 per the gotcha: 0.50 * 100 == 49.99...9 in
             # IEEE-754, so bare math.floor would miss the 50 threshold.
             current_floor = math.floor(float(five_hour_percent) + 1e-9)
+
+            # Resolve active segment ONCE so every per-site read + write
+            # below sees the same value within this transaction. Spec
+            # §3.3 & §3.4 of
+            # docs/superpowers/specs/2026-05-16-5h-in-place-credit-detection.md:
+            # the active segment is the latest five_hour_reset_events row
+            # for this window_key, else sentinel 0 (pre-credit).
+            active_reset_event_id = _resolve_active_five_hour_reset_event_id(
+                conn, int(five_hour_window_key)
+            )
+
             if current_floor >= 1:
+                # Site A — MAX(percent_threshold) scoped to active segment.
+                # Without the reset_event_id filter, MAX returns the
+                # pre-credit max and post-credit milestones from 1..max
+                # are silently never emitted.
+                #
                 # Use max(percent_threshold) directly (not prior block's
                 # final_pct) so first-observation already-mid-stream doesn't
                 # synthesize crossings 1..(current_floor - 1) we never had
@@ -938,8 +1028,8 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
                 # maybe_record_milestone's max_existing path.
                 row = conn.execute(
                     "SELECT MAX(percent_threshold) AS m FROM five_hour_milestones "
-                    "WHERE five_hour_window_key = ?",
-                    (int(five_hour_window_key),),
+                    "WHERE five_hour_window_key = ? AND reset_event_id = ?",
+                    (int(five_hour_window_key), active_reset_event_id),
                 ).fetchone()
                 max_existing = row["m"] if row and row["m"] is not None else None
 
@@ -952,14 +1042,21 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
                     # block_id was resolved above (before the children writes) and
                     # is still in scope here.
 
+                    # Site B — prior-cost lookup scoped to active segment.
                     # Marginal-cost lookup for the start_threshold milestone
                     # (only when there's a prior milestone in this block).
+                    # Without the reset_event_id filter, marginal could be
+                    # computed against a pre-credit row whose block_cost is
+                    # unrelated to the post-credit segment's totals.
                     prior_cost: float | None = None
                     if max_existing is not None:
                         prev_row = conn.execute(
                             "SELECT block_cost_usd FROM five_hour_milestones "
-                            "WHERE five_hour_window_key = ? AND percent_threshold = ?",
-                            (int(five_hour_window_key), int(max_existing)),
+                            "WHERE five_hour_window_key = ? "
+                            "  AND percent_threshold = ? "
+                            "  AND reset_event_id = ?",
+                            (int(five_hour_window_key), int(max_existing),
+                             active_reset_event_id),
                         ).fetchone()
                         if prev_row is not None:
                             prior_cost = float(prev_row["block_cost_usd"])
@@ -969,6 +1066,12 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
                             marginal: float | None = totals["cost_usd"] - prior_cost
                         else:
                             marginal = None
+                        # Site C — INSERT stamps the resolved
+                        # ``active_reset_event_id`` (0 = pre-credit, else
+                        # the latest five_hour_reset_events.id). UNIQUE
+                        # is now (window_key, threshold, reset_event_id)
+                        # so post-credit threshold crossings re-fire
+                        # fresh — not absorbed into the pre-credit row.
                         cur = conn.execute(
                             """
                             INSERT OR IGNORE INTO five_hour_milestones (
@@ -983,9 +1086,10 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
                               block_cache_read_tokens,
                               block_cost_usd,
                               marginal_cost_usd,
-                              seven_day_pct_at_crossing
+                              seven_day_pct_at_crossing,
+                              reset_event_id
                             )
-                            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                             """,
                             (
                                 block_id,
@@ -1000,6 +1104,7 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
                                 totals["cost_usd"],
                                 marginal,
                                 weekly_percent,
+                                active_reset_event_id,
                             ),
                         )
                         # ── Threshold-actions dispatch (set-then-dispatch, spec §3.2) ──
@@ -1028,11 +1133,19 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
                             and pct in alerts_cfg["five_hour_thresholds"]
                         ):
                             crossed_at = now_utc_iso()
+                            # Site D — alerted_at UPDATE scoped to the
+                            # active segment, so the post-credit row
+                            # gets stamped without overwriting an
+                            # already-alerted pre-credit row at the
+                            # same threshold.
                             conn.execute(
                                 "UPDATE five_hour_milestones SET alerted_at = ? "
-                                "WHERE five_hour_window_key = ? AND percent_threshold = ? "
-                                "AND alerted_at IS NULL",
-                                (crossed_at, int(five_hour_window_key), int(pct)),
+                                "WHERE five_hour_window_key = ? "
+                                "  AND percent_threshold = ? "
+                                "  AND reset_event_id = ? "
+                                "  AND alerted_at IS NULL",
+                                (crossed_at, int(five_hour_window_key),
+                                 int(pct), active_reset_event_id),
                             )
                             # Cheap re-reads inside BEGIN are SELECT-only and
                             # safe; values reflect post-INSERT state. We
@@ -1040,10 +1153,17 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
                             # are in scope) and defer ONLY the Popen-side
                             # _dispatch_alert_notification to after the outer
                             # commit.
+                            # Site E — alert-payload reread scoped to
+                            # the active segment so the dispatch shows
+                            # post-credit cost, not the pre-credit
+                            # row's stale value at the same threshold.
                             cost_row = conn.execute(
                                 "SELECT block_cost_usd FROM five_hour_milestones "
-                                "WHERE five_hour_window_key = ? AND percent_threshold = ?",
-                                (int(five_hour_window_key), int(pct)),
+                                "WHERE five_hour_window_key = ? "
+                                "  AND percent_threshold = ? "
+                                "  AND reset_event_id = ?",
+                                (int(five_hour_window_key), int(pct),
+                                 active_reset_event_id),
                             ).fetchone()
                             block_row = conn.execute(
                                 "SELECT block_start_at FROM five_hour_blocks "
@@ -1305,9 +1425,9 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                     prior["week_end_at"], "record.prior"
                 )
                 prior_pct = prior["weekly_percent"]
+                now_utc = dt.datetime.now(dt.timezone.utc)
                 if prior_end_canon and prior_end_canon != cur_end_canon:
                     prior_end_dt = parse_iso_datetime(prior_end_canon, "prior.week_end_at")
-                    now_utc = dt.datetime.now(dt.timezone.utc)
                     # Fire only when (a) prior window was still in the FUTURE
                     # (Anthropic shifted the boundary before natural expiration),
                     # AND (b) weekly_percent dropped by RESET_PCT_DROP_THRESHOLD
@@ -1331,32 +1451,429 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                              effective_iso),
                         )
                         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.
+                    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.
+                            conn.execute(
+                                "INSERT OR IGNORE INTO week_reset_events "
+                                "(detected_at_utc, old_week_end_at, new_week_end_at, "
+                                " effective_reset_at_utc) VALUES (?, ?, ?, ?)",
+                                (now_utc_iso(), effective_iso, cur_end_canon,
+                                 effective_iso),
+                            )
+                            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:
+                            (c.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 == 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.
+                        # Strict equality (round(.,1)) keeps this
+                        # narrow: we only delete rows whose percent
+                        # exactly matches the pre-credit value we just
+                        # observed — legitimate post-credit climbs
+                        # past `prior_pct` (rare, but possible if the
+                        # credit is small + activity is heavy) stay.
+                        try:
+                            conn.execute(
+                                "DELETE FROM weekly_usage_snapshots "
+                                "WHERE week_start_date = ? "
+                                "  AND unixepoch(captured_at_utc) >= "
+                                "      unixepoch(?) "
+                                "  AND round(weekly_percent, 1) = "
+                                "      round(?, 1)",
+                                (week_start_date, effective_iso,
+                                 float(prior_pct)),
+                            )
+                            conn.commit()
+                        except sqlite3.DatabaseError as exc:
+                            eprint(
+                                "[record-usage] post-credit cleanup "
+                                f"failed: {exc}"
+                            )
+
+            # ── 5h in-place credit detection (parallel to weekly above) ──
+            # Spec §2.2 of
+            # docs/superpowers/specs/2026-05-16-5h-in-place-credit-detection.md.
+            # Slot SECOND so the weekly branch retains control-flow
+            # priority — both branches are independent (they touch
+            # different tables) and the order has no behavioral
+            # interaction. Same outer try/except wraps both so a
+            # 5h-detection failure logs but does not regress the rest
+            # of cmd_record_usage.
+            #
+            # Diverges from weekly in three places:
+            #   - Threshold: 5.0pp (constant on cctally module), not 25.0pp.
+            #     The 5h envelope is smaller so a 5pp move is
+            #     proportionally larger.
+            #   - Effective-iso floor: 10-min (matches
+            #     ``_canonical_5h_window_key``'s 600s floor), not hour.
+            #     Up to ~30 distinct slots per 5h block; same-slot
+            #     collisions absorbed by UNIQUE per spec §2.3.
+            #   - Pre-check: pair-checks the latest event's
+            #     ``(prior_percent, post_percent)`` against this tick's
+            #     ``(prior_5h_pct, five_hour_percent)``, not
+            #     ``new_week_end_at`` equality. A genuine replay matches
+            #     BOTH fields; a NEW credit-with-idle (prior_pct equals
+            #     the prior credit's post_pct because the user didn't
+            #     move between credits) matches only one field and
+            #     correctly proceeds to write a second event row.
+            try:
+                if (
+                    five_hour_window_key is not None
+                    and five_hour_percent is not None
+                ):
+                    prior_5h_row = conn.execute(
+                        "SELECT five_hour_window_key, five_hour_percent, "
+                        "       five_hour_resets_at "
+                        "  FROM weekly_usage_snapshots "
+                        " WHERE five_hour_window_key IS NOT NULL "
+                        "   AND five_hour_percent IS NOT NULL "
+                        " ORDER BY captured_at_utc DESC, id DESC LIMIT 1"
+                    ).fetchone()
+                    if (
+                        prior_5h_row is not None
+                        and int(prior_5h_row["five_hour_window_key"])
+                            == int(five_hour_window_key)
+                        and prior_5h_row["five_hour_resets_at"] is not None
+                    ):
+                        prior_5h_pct = float(prior_5h_row["five_hour_percent"])
+                        prior_5h_resets_dt = parse_iso_datetime(
+                            prior_5h_row["five_hour_resets_at"],
+                            "prior.five_hour_resets_at",
+                        )
+                        # ``now_utc`` was bound earlier in this same
+                        # outer try block from
+                        # ``dt.datetime.now(dt.timezone.utc)``; reuse it
+                        # so both branches see the same instant.
+                        if (
+                            prior_5h_resets_dt > now_utc
+                            and (prior_5h_pct - float(five_hour_percent))
+                                >= c._FIVE_HOUR_RESET_PCT_DROP_THRESHOLD
+                        ):
+                            # Pair-check dedup pre-check (spec §2.2;
+                            # refined by Codex r4 P1 finding). The
+                            # round-1 predicate compared only the
+                            # latest event's ``post_percent`` against
+                            # this tick's ``prior_5h_pct``; that
+                            # false-positived on a legitimate 2nd
+                            # credit where the user was idle between
+                            # credits (Credit 1 lands prior=20/post=5;
+                            # user does nothing; Credit 2 arrives with
+                            # CLI percent=0 so prior_5h_pct=5 reads
+                            # equal to stored post_percent=5 →
+                            # silently swallowed). Pair-checking
+                            # against BOTH fields disambiguates: a
+                            # genuine replay matches BOTH; a new
+                            # credit-with-idle matches at most ONE
+                            # (the prior side coincides but
+                            # post_percent differs).
+                            most_recent = conn.execute(
+                                "SELECT prior_percent, post_percent "
+                                "  FROM five_hour_reset_events "
+                                " WHERE five_hour_window_key = ? "
+                                " ORDER BY id DESC LIMIT 1",
+                                (int(five_hour_window_key),),
+                            ).fetchone()
+                            is_dup = (
+                                most_recent is not None
+                                and round(prior_5h_pct, 1)
+                                == round(float(most_recent["prior_percent"]), 1)
+                                and round(float(five_hour_percent), 1)
+                                == round(float(most_recent["post_percent"]), 1)
+                            )
+                            # 10-min floor (spec §2.3 — bounded
+                            # stacked-credit resolution; one event per
+                            # 10-min slot per block). Resolved BEFORE
+                            # the ``if not is_dup`` branch so it's in
+                            # scope for the pivots below (per memory
+                            # ``project_dedup_must_not_gate_side_effects.md``:
+                            # the recovery-tick path must still force
+                            # HWM + DELETE even when the INSERT is
+                            # absorbed by the pre-check or by
+                            # UNIQUE — see comment below for the
+                            # crash scenario). ``_floor_to_ten_minutes``
+                            # is a cctally module attribute; the
+                            # ``c.X`` accessor resolves at call time
+                            # so test ``monkeypatch.setitem(ns,
+                            # "_floor_to_ten_minutes", …)``
+                            # propagates.
+                            effective_dt = c._floor_to_ten_minutes(now_utc)
+                            effective_iso = effective_dt.isoformat(
+                                timespec="seconds"
+                            )
+                            if not is_dup:
+                                conn.execute(
+                                    "INSERT OR IGNORE INTO five_hour_reset_events "
+                                    "(detected_at_utc, five_hour_window_key, "
+                                    " prior_percent, post_percent, "
+                                    " effective_reset_at_utc) "
+                                    "VALUES (?, ?, ?, ?, ?)",
+                                    (
+                                        now_utc_iso(),
+                                        int(five_hour_window_key),
+                                        prior_5h_pct,
+                                        float(five_hour_percent),
+                                        effective_iso,
+                                    ),
+                                )
+                                conn.commit()
+                            # Pivots fire UNCONDITIONALLY whenever a
+                            # credit is detected — NOT gated on
+                            # ``not is_dup`` and NOT on
+                            # ``rowcount == 1``. 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 A:
+                            # tick N committed the event row, then died
+                            # before HWM + DELETE. Tick N+1's
+                            # INSERT OR IGNORE returns rowcount == 0
+                            # (UNIQUE absorbs) but the system is still
+                            # wedged on the pre-credit HWM + stale-
+                            # replica rows. Crash scenario B (the
+                            # Codex r4 finding): a recovery tick where
+                            # ``(prior, post)`` pair-matches the
+                            # already-stored event row also takes the
+                            # ``is_dup`` branch; without the hoist the
+                            # pivots would be skipped and the system
+                            # would stay wedged. The pivots are
+                            # individually idempotent (file overwrite
+                            # + DELETE on a stable predicate), so
+                            # re-running them on the recovery tick is
+                            # always safe. Mirrors the weekly hoist at
+                            # ``_cctally_record.py`` after the
+                            # ``if already is None`` block (grep
+                            # ``Force-write hwm-7d``).
+                            #
+                            # Force-write hwm-5h: bypasses the
+                            # monotonic guard at the normal hwm-5h
+                            # writer below. Lands AFTER
+                            # ``conn.commit()`` so a concurrent reader
+                            # doesn't see the new HWM before the
+                            # event row is durable. File format
+                            # matches the canonical writer:
+                            # ``<key> <percent>\n``.
+                            try:
+                                (c.APP_DIR / "hwm-5h").write_text(
+                                    f"{int(five_hour_window_key)} "
+                                    f"{float(five_hour_percent)}\n"
+                                )
+                            except OSError:
+                                pass
+                            # Stale-replica DELETE (spec §4.3).
+                            # Defends against claude-statusline
+                            # replaying the pre-credit
+                            # ``--five-hour-percent`` value past the
+                            # credit moment from its own in-memory
+                            # HWM cache. Strict round-1 equality
+                            # keeps the scope narrow — only rows
+                            # whose five_hour_percent exactly matches
+                            # the just-observed pre-credit value are
+                            # removed. ``unixepoch()`` on both sides
+                            # for offset robustness (Z vs +00:00).
+                            try:
+                                conn.execute(
+                                    "DELETE FROM weekly_usage_snapshots "
+                                    " WHERE five_hour_window_key = ? "
+                                    "   AND unixepoch(captured_at_utc) "
+                                    "       >= unixepoch(?) "
+                                    "   AND round(five_hour_percent, 1) "
+                                    "       = round(?, 1)",
+                                    (
+                                        int(five_hour_window_key),
+                                        effective_iso,
+                                        prior_5h_pct,
+                                    ),
+                                )
+                                conn.commit()
+                            except sqlite3.DatabaseError as exc:
+                                eprint(
+                                    "[record-usage] 5h post-credit "
+                                    f"cleanup failed: {exc}"
+                                )
+            except (sqlite3.DatabaseError, ValueError, TypeError) as exc:
+                eprint(
+                    f"[record-usage] 5h in-place-credit detection "
+                    f"failed: {exc}"
+                )
         except (sqlite3.DatabaseError, ValueError) as exc:
             eprint(f"[record-usage] reset-event detection failed: {exc}")
 
-        # 7-day usage is monotonically non-decreasing within a billing week.
-        # A lower value means stale rate-limit data from a previous API call;
-        # skip the insert to avoid regressing the reported usage.
+        # 7-day usage is monotonically non-decreasing within a billing week
+        # — UNTIL Anthropic issues an in-place weekly credit. When a
+        # week_reset_events row exists for THIS week_end_at, the MAX query
+        # filters to samples captured at-or-after the segment's
+        # effective_reset_at_utc so a fresh post-credit OAuth value (e.g.
+        # 2%) lands instead of being held back by stale pre-credit history
+        # (e.g. 67%). When no event row exists, COALESCE defaults to
+        # epoch-zero so the filter is a no-op and legacy clamp behavior
+        # is preserved byte-identically.
+        # NB: comparison wrapped with ``unixepoch()`` on BOTH sides.
+        # ``captured_at_utc`` is stored with `Z` suffix, but
+        # ``effective_reset_at_utc`` may have a non-UTC offset on
+        # historical backfill rows written before Bug 3 was fixed
+        # (parse_iso_datetime returned host-local). Lex string compare
+        # on mixed offsets silently mis-orders moments for non-UTC
+        # hosts (CLAUDE.md gotcha: 5h-block cross-reset flag — "all
+        # comparisons go through unixepoch(), NOT lex
+        # BETWEEN/`<`/`>`"). Same rule applies here.
         max_row = conn.execute(
-            "SELECT MAX(weekly_percent) AS v FROM weekly_usage_snapshots WHERE week_start_date = ?",
-            (week_start_date,),
+            """
+            SELECT MAX(weekly_percent) AS v
+              FROM weekly_usage_snapshots
+             WHERE week_start_date = ?
+               AND unixepoch(captured_at_utc) >= unixepoch(COALESCE(
+                 (SELECT effective_reset_at_utc
+                    FROM week_reset_events
+                   WHERE new_week_end_at = ?
+                   ORDER BY id DESC
+                   LIMIT 1),
+                 '1970-01-01T00:00:00Z'
+               ))
+            """,
+            (week_start_date, week_end_at),
         ).fetchone()
         if max_row and max_row["v"] is not None and round(weekly_percent, 1) < round(float(max_row["v"]), 1):
             should_insert = False
         else:
-            # 5-hour usage is monotonically non-decreasing within a window.
-            # A lower value means stale API data; clamp to existing max.
-            # Joining on five_hour_window_key (canonical 10-min-floored
+            # 5-hour usage is monotonically non-decreasing within a window
+            # — UNTIL an in-place 5h credit fires. When a
+            # ``five_hour_reset_events`` row exists for THIS
+            # ``five_hour_window_key``, the MAX query filters to samples
+            # captured at-or-after the event's ``effective_reset_at_utc``
+            # so a fresh post-credit OAuth value (e.g. 4%) lands instead
+            # of being re-clamped to the pre-credit max (e.g. 28%). When
+            # no event row exists, ``COALESCE`` defaults to epoch-zero so
+            # the filter is a no-op and legacy clamp behavior is preserved
+            # byte-identically.
+            #
+            # ``unixepoch()`` on BOTH sides for offset robustness — stored
+            # ``captured_at_utc`` carries ``Z`` while
+            # ``effective_reset_at_utc`` carries ``+00:00``. Lex compare
+            # would silently mis-order moments for non-UTC hosts (same
+            # gotcha as the weekly clamp / 5h-block cross-reset flag).
+            #
+            # Joining on ``five_hour_window_key`` (canonical 10-min-floored
             # epoch) absorbs Anthropic's seconds-level jitter on
-            # resets_at; an ISO-string equality at this site silently
+            # ``resets_at``; an ISO-string equality at this site silently
             # skipped the clamp every time a jittered fetch landed in
             # the same physical 5h window (spec Bug B).
+            #
+            # Spec §4.1 of
+            # docs/superpowers/specs/2026-05-16-5h-in-place-credit-detection.md.
             if five_hour_percent is not None and five_hour_window_key is not None:
                 max_5h_row = conn.execute(
-                    "SELECT MAX(five_hour_percent) AS v FROM weekly_usage_snapshots WHERE five_hour_window_key = ?",
-                    (five_hour_window_key,),
+                    """
+                    SELECT MAX(five_hour_percent) AS v
+                      FROM weekly_usage_snapshots
+                     WHERE five_hour_window_key = ?
+                       AND unixepoch(captured_at_utc) >= unixepoch(COALESCE(
+                         (SELECT effective_reset_at_utc
+                            FROM five_hour_reset_events
+                           WHERE five_hour_window_key = ?
+                           ORDER BY id DESC
+                           LIMIT 1),
+                         '1970-01-01T00:00:00Z'
+                       ))
+                    """,
+                    (int(five_hour_window_key), int(five_hour_window_key)),
                 ).fetchone()
-                if max_5h_row and max_5h_row["v"] is not None and round(five_hour_percent, 1) < round(float(max_5h_row["v"]), 1):
+                if (
+                    max_5h_row
+                    and max_5h_row["v"] is not None
+                    and round(five_hour_percent, 1)
+                        < round(float(max_5h_row["v"]), 1)
+                ):
                     five_hour_percent = float(max_5h_row["v"])
 
             # Dedup vs last snapshot: if BOTH weekly_percent and
@@ -1426,11 +1943,29 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                 )
                 need_milestone_heal = False
                 if latest_floor >= 1:
+                    # v1.7.2: scope the heal probe to the ACTIVE segment.
+                    # Without this, a credited week's MAX over the whole
+                    # ledger would still read the pre-credit ceiling
+                    # (e.g. 67%) and silently suppress the post-credit
+                    # ledger's heal even though it has zero rows.
+                    captured_at_for_probe = latest_row["captured_at_utc"]
+                    week_end_at_for_probe = latest_row["week_end_at"]
+                    heal_segment = 0
+                    if week_end_at_for_probe and captured_at_for_probe:
+                        seg = heal_conn.execute(
+                            "SELECT id FROM week_reset_events "
+                            "WHERE new_week_end_at = ? "
+                            "  AND unixepoch(effective_reset_at_utc) <= unixepoch(?) "
+                            "ORDER BY id DESC LIMIT 1",
+                            (week_end_at_for_probe, captured_at_for_probe),
+                        ).fetchone()
+                        if seg is not None:
+                            heal_segment = int(seg["id"])
                     max_existing = heal_conn.execute(
                         "SELECT MAX(percent_threshold) AS m "
                         "FROM percent_milestones "
-                        "WHERE week_start_date = ?",
-                        (week_start_date,),
+                        "WHERE week_start_date = ? AND reset_event_id = ?",
+                        (week_start_date, heal_segment),
                     ).fetchone()
                     if max_existing is None or max_existing["m"] is None:
                         need_milestone_heal = True
@@ -1442,6 +1977,16 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                 # last_observed_at_utc is stale relative to the latest
                 # snapshot's captured_at_utc (the kill landed between
                 # insert_usage_snapshot and maybe_update_five_hour_block).
+                #
+                # Round-3: ALSO scope the milestone-coverage half of
+                # this probe by ACTIVE 5h SEGMENT. Without this, a
+                # credited block's MAX over the whole milestone ledger
+                # would still read the pre-credit ceiling (e.g. 28%) and
+                # silently suppress the post-credit ledger's heal even
+                # though it has zero rows. Mirrors weekly Probe 1's
+                # segment-aware fix above. Uses
+                # ``_resolve_active_five_hour_reset_event_id`` to find
+                # the active segment for the latest snapshot's window.
                 need_5h_heal = False
                 window_key = latest_row["five_hour_window_key"]
                 if window_key is not None:
@@ -1458,6 +2003,45 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                         < latest_row["captured_at_utc"]
                     ):
                         need_5h_heal = True
+                    else:
+                        # Block row exists AND last_observed is fresh
+                        # — but the post-credit milestone segment may
+                        # still owe rows. Scope MAX(percent_threshold)
+                        # by the active reset_event_id segment so
+                        # post-credit climbs from threshold 1 trigger
+                        # heal even when the pre-credit segment already
+                        # crossed higher thresholds. Probe shape mirrors
+                        # weekly Probe 1 (lines 1922-1956).
+                        five_hour_percent_for_probe = latest_row[
+                            "five_hour_percent"
+                        ]
+                        if five_hour_percent_for_probe is not None:
+                            latest_5h_floor = math.floor(
+                                float(five_hour_percent_for_probe) + 1e-9
+                            )
+                            if latest_5h_floor >= 1:
+                                heal_5h_segment = (
+                                    _resolve_active_five_hour_reset_event_id(
+                                        heal_conn, int(window_key)
+                                    )
+                                )
+                                max_5h_existing = heal_conn.execute(
+                                    "SELECT MAX(percent_threshold) AS m "
+                                    "FROM five_hour_milestones "
+                                    "WHERE five_hour_window_key = ? "
+                                    "  AND reset_event_id = ?",
+                                    (int(window_key), heal_5h_segment),
+                                ).fetchone()
+                                if (
+                                    max_5h_existing is None
+                                    or max_5h_existing["m"] is None
+                                ):
+                                    need_5h_heal = True
+                                elif (
+                                    int(max_5h_existing["m"])
+                                    < latest_5h_floor
+                                ):
+                                    need_5h_heal = True
             finally:
                 heal_conn.close()