cctally 1.7.1 → 1.7.3

package/bin/cctally

@@ -3817,12 +3817,20 @@ def open_db() -> sqlite3.Connection:
             marginal_cost_usd REAL,
             usage_snapshot_id INTEGER NOT NULL,
             cost_snapshot_id INTEGER NOT NULL,
-            UNIQUE(week_start_date, percent_threshold)
+            reset_event_id INTEGER NOT NULL DEFAULT 0,
+            UNIQUE(week_start_date, percent_threshold, reset_event_id)
         )
         """
     )
 
     add_column_if_missing(conn, "percent_milestones", "five_hour_percent_at_crossing", "REAL")
+    # reset_event_id: segment column added by migration 005. Fresh-install
+    # DBs get it via the live CREATE TABLE above + the dispatcher
+    # fast-stamps the migration. Existing pre-005 DBs trip the migration's
+    # rename-recreate-copy idiom (handler in _cctally_db.py); the handler's
+    # fast-path probe stamps the marker when the column is already present
+    # (covers the corner case where a partially-upgraded DB has the column
+    # but not the new UNIQUE — re-run is safe).
 
     # alerted_at: populated by the alert-dispatch path when a milestone-INSERT
     # row's threshold matches the user's configured alerts.weekly_thresholds /
@@ -3856,6 +3864,43 @@ def open_db() -> sqlite3.Connection:
     )
     _backfill_week_reset_events(conn)
 
+    # ── five_hour_reset_events (Anthropic-issued in-place 5h credits) ──
+    # Parallel concept to ``week_reset_events`` for the 5h dimension; lives
+    # adjacent in ``_apply_schema`` because the two carry the same kind of
+    # signal at different cadences. Diverges from weekly in that the payload
+    # is the *percent values* (prior + post) rather than boundary keys,
+    # because the 5h variant has a stable ``five_hour_window_key`` and only
+    # the percent moves. See spec
+    # docs/superpowers/specs/2026-05-16-5h-in-place-credit-detection.md §3.1
+    # for rationale.
+    #
+    # UNIQUE(five_hour_window_key, effective_reset_at_utc) — supports stacked
+    # credits across DISTINCT 10-min slots inside one block (see spec §2.3
+    # "Bounded stacked-credit resolution" for the cap statement: ~30 distinct
+    # slots per 5h block when floor matches ``_canonical_5h_window_key``'s
+    # 600-second floor; same-slot collisions silently absorbed by
+    # INSERT OR IGNORE — an intentional cap, not a bug).
+    #
+    # No FK per CLAUDE.md gotcha: FKs in this codebase are documentation-only
+    # (``PRAGMA foreign_keys`` not enabled). ``five_hour_window_key`` provides
+    # the join key without a formal FK.
+    #
+    # No ``_backfill_five_hour_reset_events`` call follows (forward-only ship
+    # per spec Q5; historical backfill deferred to a future issue).
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS five_hour_reset_events (
+            id                     INTEGER PRIMARY KEY AUTOINCREMENT,
+            detected_at_utc        TEXT NOT NULL,
+            five_hour_window_key   INTEGER NOT NULL,
+            prior_percent          REAL NOT NULL,
+            post_percent           REAL NOT NULL,
+            effective_reset_at_utc TEXT NOT NULL,
+            UNIQUE(five_hour_window_key, effective_reset_at_utc)
+        )
+        """
+    )
+
     # ── five_hour_blocks (rollup, one row per API-anchored 5h block) ──
     conn.execute(
         """
@@ -3905,7 +3950,8 @@ def open_db() -> sqlite3.Connection:
             block_cost_usd              REAL    NOT NULL DEFAULT 0,
             marginal_cost_usd           REAL,
             seven_day_pct_at_crossing   REAL,
-            UNIQUE(five_hour_window_key, percent_threshold),
+            reset_event_id              INTEGER NOT NULL DEFAULT 0,
+            UNIQUE(five_hour_window_key, percent_threshold, reset_event_id),
             FOREIGN KEY (block_id) REFERENCES five_hour_blocks(id)
         )
         """
@@ -3925,6 +3971,16 @@ def open_db() -> sqlite3.Connection:
     # — never "delivery failed".
     add_column_if_missing(conn, "five_hour_milestones", "alerted_at", "TEXT")
 
+    # reset_event_id: segment column added by migration 006. Fresh-install
+    # DBs get it via the live CREATE TABLE above + the dispatcher fast-stamps
+    # the migration marker (the live DDL must carry the column AND the 3-col
+    # UNIQUE for fast-stamp to be safe — see spec §3.2). Existing pre-006
+    # DBs trip the migration's rename-recreate-copy idiom (handler in
+    # bin/_cctally_db.py); the handler's fast-path probe stamps the marker
+    # when the column is already present (covers the corner case where a
+    # partially-upgraded DB has the column but not the new UNIQUE — re-run
+    # is safe). Mirrors weekly migration 005 / `percent_milestones`.
+
     # ── five_hour_block_models (per-(block, model) rollup-child) ──
     # MUST be created BEFORE the parent-backfill gate below, because
     # _backfill_five_hour_blocks writes into this table on the fresh-install
@@ -4717,15 +4773,27 @@ def insert_cost_snapshot(
 def get_max_milestone_for_week(
     conn: sqlite3.Connection,
     week_start_date: str,
+    *,
+    reset_event_id: int = 0,
 ) -> int | None:
-    """Return the highest percent_threshold recorded for a week, or None."""
+    """Return the highest percent_threshold recorded for a week's segment,
+    or None.
+
+    ``reset_event_id`` (v1.7.2): default 0 (= pre-credit / no-event
+    sentinel) preserves legacy behavior on un-credited weeks. When an
+    in-place credit lifts a week into a new segment, callers pass the
+    segment id so the segment's threshold ledger is independent of the
+    pre-credit one — the post-credit 1% / 2% / 3% milestones fire even
+    if the pre-credit segment already crossed those thresholds.
+    """
     row = conn.execute(
         """
         SELECT MAX(percent_threshold) AS max_pct
         FROM percent_milestones
         WHERE week_start_date = ?
+          AND reset_event_id = ?
         """,
-        (week_start_date,),
+        (week_start_date, reset_event_id),
     ).fetchone()
     if row and row["max_pct"] is not None:
         return int(row["max_pct"])
@@ -4736,15 +4804,27 @@ def get_milestone_cost_for_week(
     conn: sqlite3.Connection,
     week_start_date: str,
     percent_threshold: int,
+    *,
+    reset_event_id: int = 0,
 ) -> float | None:
-    """Return the cumulative_cost_usd for a specific threshold, or None."""
+    """Return the cumulative_cost_usd for a specific (week, threshold,
+    segment), or None.
+
+    ``reset_event_id`` (v1.7.2): segment-aware lookup. Default 0 preserves
+    legacy behavior. Used by ``maybe_record_milestone`` to compute the
+    marginal cost between consecutive thresholds inside the SAME segment
+    — without the filter, the post-credit threshold-3 row would compute
+    its marginal against the pre-credit threshold-2 cost (wrong segment).
+    """
     row = conn.execute(
         """
         SELECT cumulative_cost_usd
         FROM percent_milestones
-        WHERE week_start_date = ? AND percent_threshold = ?
+        WHERE week_start_date = ?
+          AND percent_threshold = ?
+          AND reset_event_id = ?
         """,
-        (week_start_date, percent_threshold),
+        (week_start_date, percent_threshold, reset_event_id),
     ).fetchone()
     if row:
         return float(row["cumulative_cost_usd"])
@@ -4781,18 +4861,29 @@ def insert_percent_milestone(
     five_hour_percent_at_crossing: float | None = None,
     *,
     commit: bool = True,
+    reset_event_id: int = 0,
 ) -> int:
     """Insert a percent_milestones row idempotently.
 
     Returns the SQLite rowcount: 1 on a genuinely new crossing, 0 if a row
-    for (week_start_date, percent_threshold) already exists. Race-safe under
-    concurrent record-usage instances — aligns with the existing 5h-milestone
-    INSERT OR IGNORE pattern (see five_hour_milestones write path).
+    for (week_start_date, percent_threshold, reset_event_id) already exists.
+    Race-safe under concurrent record-usage instances — aligns with the
+    existing 5h-milestone INSERT OR IGNORE pattern (see five_hour_milestones
+    write path).
+
+    ``reset_event_id`` (v1.7.2 segment column, migration 005): defaults to
+    ``0`` (= pre-credit / no-event sentinel). When an in-place credit fires
+    for the current week, the caller (``maybe_record_milestone``) resolves
+    the active segment from ``week_reset_events`` and passes it in so
+    post-credit threshold crossings land as a SEPARATE row from any
+    pre-credit one at the same (week, threshold). The UNIQUE constraint
+    is on the 3-tuple, so (week=W, threshold=T, segment=0) and (W, T,
+    event_id) coexist.
 
     Callers that need the row id MUST follow up with an explicit
     `SELECT id FROM percent_milestones WHERE week_start_date=? AND
-    percent_threshold=?` query — `lastrowid` is unreliable when the row
-    is the silent-duplicate target.
+    percent_threshold=? AND reset_event_id=?` query — `lastrowid` is
+    unreliable when the row is the silent-duplicate target.
 
     ``commit=False`` skips the inner ``conn.commit()`` so the caller can
     bundle the INSERT with a follow-up ``alerted_at`` UPDATE in a single
@@ -4817,9 +4908,10 @@ def insert_percent_milestone(
           marginal_cost_usd,
           usage_snapshot_id,
           cost_snapshot_id,
-          five_hour_percent_at_crossing
+          five_hour_percent_at_crossing,
+          reset_event_id
         )
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         """,
         (
             now_utc_iso(),
@@ -4833,6 +4925,7 @@ def insert_percent_milestone(
             usage_snapshot_id,
             cost_snapshot_id,
             five_hour_percent_at_crossing,
+            reset_event_id,
         ),
     )
     if commit:
@@ -5343,10 +5436,31 @@ def _select_non_overlapping_recorded_windows(
 def _load_recorded_five_hour_windows(
     range_start: dt.datetime,
     range_end: dt.datetime,
-) -> list[dt.datetime]:
+) -> tuple[list[dt.datetime], dict[dt.datetime, dt.datetime]]:
     """Return sorted, UTC-aware recorded ``five_hour_resets_at`` values
     that anchor real 5h windows in ``[range_start, range_end]``.
 
+    Two sources contribute to the merged anchor set:
+
+    1. ``weekly_usage_snapshots.five_hour_resets_at`` — every
+       record-usage tick stores the API-derived reset moment here. The
+       count of supporting rows weights each anchor (low-count anchors
+       are downvoted in ``_select_non_overlapping_recorded_windows``).
+
+    2. ``five_hour_blocks.five_hour_resets_at`` — the canonical
+       API-anchored rollup table. Each row represents ONE accepted 5h
+       window after ``maybe_update_five_hour_block`` has merged jittered
+       reset values via ``_canonical_5h_window_key``. These are the
+       authoritative anchors; we count them with a heavy weight (1000)
+       so they always dominate over jittered raw snapshot values when
+       both sources see the same physical window. Without this source,
+       ``cctally blocks`` falls back to the heuristic anchor for the
+       ACTIVE row whenever the most recent
+       ``weekly_usage_snapshots.five_hour_resets_at`` value disagrees
+       with the canonical anchor — Bug C in v1.7.2 round 3. Tied
+       windows (jitter within 10-minute floor) collapse to the same
+       key and the canonical weight dominates.
+
     Each value is parsed as ISO-8601 (the storage format produced by
     ``cmd_record_usage``) and normalized to UTC. Naive datetimes are
     treated as already-UTC. Values are floored to the previous
@@ -5373,11 +5487,58 @@ def _load_recorded_five_hour_windows(
                 "  AND five_hour_resets_at <= ?",
                 (range_start.isoformat(), range_end.isoformat()),
             ).fetchall()
+            # Canonical API-anchored windows from the rollup table.
+            # Heavy-weight (1000 per row) so they always dominate over
+            # any jittered raw-snapshot value sharing the same floored
+            # 10-minute bucket. Wrapped in a defensive try in case the
+            # five_hour_blocks table doesn't exist yet (very-old DB on
+            # first open before the bootstrap migration ran).
+            # Pull ``block_start_at`` alongside ``five_hour_resets_at``
+            # so Bug J's overlap-truncation step (below) can preserve
+            # the real display start for credit-truncated blocks.
+            canonical_rows: list[Any] = []
+            try:
+                canonical_rows = conn.execute(
+                    "SELECT five_hour_resets_at, block_start_at "
+                    "FROM five_hour_blocks "
+                    "WHERE five_hour_resets_at IS NOT NULL "
+                    "  AND five_hour_resets_at >= ? "
+                    "  AND five_hour_resets_at <= ?",
+                    (range_start.isoformat(), range_end.isoformat()),
+                ).fetchall()
+            except sqlite3.DatabaseError:
+                canonical_rows = []
+            # In-place credit events — used by Bug J to detect canonical
+            # block overlaps that should be resolved by truncating the
+            # earlier block at the credit moment (rather than dropping
+            # one via _select_non_overlapping_recorded_windows, which
+            # leaves the dropped block's entries unanchored and
+            # rendered as a phantom heuristic "~" row).
+            credit_moments: list[dt.datetime] = []
+            try:
+                credit_rows = conn.execute(
+                    "SELECT effective_reset_at_utc "
+                    "FROM week_reset_events "
+                    "WHERE old_week_end_at = effective_reset_at_utc"
+                ).fetchall()
+                for c in credit_rows:
+                    raw = c["effective_reset_at_utc"]
+                    try:
+                        d = dt.datetime.fromisoformat(str(raw))
+                    except ValueError:
+                        continue
+                    if d.tzinfo is None:
+                        d = d.replace(tzinfo=dt.timezone.utc)
+                    else:
+                        d = d.astimezone(dt.timezone.utc)
+                    credit_moments.append(d)
+            except sqlite3.DatabaseError:
+                credit_moments = []
     except (sqlite3.DatabaseError, OSError):
         # OSError covers ensure_dirs() failures (read-only FS, permission
         # denied on parent dir) that propagate from open_db() before any
         # SQL runs. Either way, fall back to the heuristic anchor path.
-        return []
+        return [], {}
     counts: dict[dt.datetime, int] = {}
     for row in rows:
         raw = row["five_hour_resets_at"] if hasattr(row, "keys") else row[0]
@@ -5393,7 +5554,110 @@ def _load_recorded_five_hour_windows(
             d = d.astimezone(dt.timezone.utc)
         snapped = _floor_to_ten_minutes(d)
         counts[snapped] = counts.get(snapped, 0) + 1
-    return _select_non_overlapping_recorded_windows(list(counts.items()))
+    # Overlay canonical rollup anchors at heavy weight. Same flooring
+    # rule so a jittered raw value (e.g. 17:48Z) and its canonicalized
+    # rollup (e.g. 17:50Z) collapse into the same bucket; without that
+    # the high-weight canonical entry would create a NEW bucket and
+    # both would be reported as separate windows, then
+    # `_select_non_overlapping_recorded_windows` (5h-disjoint
+    # invariant) would drop the lower-weight one — but the wrong
+    # one would win when jitter exceeds 10 minutes.
+    #
+    # Bug J (v1.7.2 round-5): collect canonical (block_start, R) pairs
+    # so we can detect in-place-credit overlaps before flattening into
+    # the weighted scheduler. When two canonical 5h blocks overlap AND
+    # an in-place credit event falls inside the overlap, truncate the
+    # EARLIER block's R to the credit moment (floored to 10 min so it
+    # collapses with any same-bucket raw-snapshot value). The
+    # truncated R keeps both blocks visible — without this fix the
+    # earlier block's entries are silently rendered as a phantom
+    # heuristic "~" row by `_group_entries_into_blocks`.
+    canonical_pairs: list[tuple[dt.datetime, dt.datetime]] = []
+    for row in canonical_rows:
+        rs_raw = row["five_hour_resets_at"] if hasattr(row, "keys") else row[0]
+        bs_raw = row["block_start_at"]      if hasattr(row, "keys") else row[1]
+        if rs_raw is None or bs_raw is None:
+            continue
+        try:
+            rs = dt.datetime.fromisoformat(str(rs_raw))
+            bs = dt.datetime.fromisoformat(str(bs_raw))
+        except ValueError:
+            continue
+        if rs.tzinfo is None:
+            rs = rs.replace(tzinfo=dt.timezone.utc)
+        else:
+            rs = rs.astimezone(dt.timezone.utc)
+        if bs.tzinfo is None:
+            bs = bs.replace(tzinfo=dt.timezone.utc)
+        else:
+            bs = bs.astimezone(dt.timezone.utc)
+        canonical_pairs.append((bs, rs))
+    canonical_pairs.sort(key=lambda p: p[0])
+
+    # Detect overlap-with-credit and replace the earlier R with a
+    # credit-truncated anchor. The (anchor → real_block_start) map is
+    # returned alongside the anchor list so the renderer can show the
+    # real block_start_at on the display row (instead of the default
+    # R - 5h, which would be hours earlier for a 2h-truncated block).
+    block_start_overrides: dict[dt.datetime, dt.datetime] = {}
+    truncated_pairs: list[tuple[dt.datetime, dt.datetime]] = []
+    for i, (bs, rs) in enumerate(canonical_pairs):
+        truncated_R = rs
+        if i + 1 < len(canonical_pairs):
+            next_bs, _next_rs = canonical_pairs[i + 1]
+            if rs > next_bs:  # overlap with next block
+                # Look for a credit moment inside [next_bs, rs] — the
+                # part of the earlier block that overlaps the next.
+                for cm in credit_moments:
+                    if next_bs <= cm <= rs:
+                        cm_floored = _floor_to_ten_minutes(cm)
+                        # Only truncate if cm is strictly inside the
+                        # earlier block; otherwise leave R alone and
+                        # let `_select_non_overlapping_recorded_windows`
+                        # drop one via its weight-tiebreaker.
+                        if bs < cm_floored < rs:
+                            truncated_R = cm_floored
+                            block_start_overrides[cm_floored] = bs
+                            break
+        truncated_pairs.append((bs, truncated_R))
+
+    # Truncated anchors are credit-adjusted and known-good; bypass the
+    # `_select_non_overlapping_recorded_windows` weighted scheduler for
+    # them (the scheduler treats every R as the END of a fixed 5h
+    # window and would see a truncated R conflicting with the adjacent
+    # canonical block one slot earlier — e.g. truncated R=17:50 would
+    # collide with the prior block's R=15:50 even though their REAL
+    # intervals are [15:50, 17:50] and [10:50, 15:50] respectively —
+    # adjacent, not overlapping). Add their R directly to the selector
+    # input weight (so jittered same-bucket raw values still collapse)
+    # but skip them when computing the overlap-safe subset.
+    truncated_anchors: set[dt.datetime] = set()
+    for bs, rs in truncated_pairs:
+        snapped = _floor_to_ten_minutes(rs)
+        if rs != _floor_to_ten_minutes(rs):
+            if rs in block_start_overrides:
+                block_start_overrides[snapped] = block_start_overrides.pop(rs)
+        # Identify truncated anchors by membership in the override map
+        # (only credit-truncated entries land there).
+        if snapped in block_start_overrides:
+            truncated_anchors.add(snapped)
+        counts[snapped] = counts.get(snapped, 0) + 1000
+
+    non_truncated_items = [
+        (a, w) for a, w in counts.items() if a not in truncated_anchors
+    ]
+    selected_non_truncated = _select_non_overlapping_recorded_windows(
+        non_truncated_items
+    )
+    # Merge truncated anchors back in, sorted ascending. Their non-
+    # overlap with the surrounding canonical blocks is guaranteed by
+    # the credit-moment truncation: a truncated R sits strictly
+    # between its real block_start (which equals the prior block's R)
+    # and the next block's R.
+    selected = sorted(
+        list(selected_non_truncated) + list(truncated_anchors)
+    )
+    return selected, block_start_overrides
 
 
 def cmd_blocks(args: argparse.Namespace) -> int:
@@ -5438,15 +5702,39 @@ def cmd_blocks(args: argparse.Namespace) -> int:
     # reset R just after ``range_end`` (e.g. the active window when
     # range_end is wall-clock "now") can still anchor entries that fall
     # inside [range_start, range_end].
-    recorded_windows = _load_recorded_five_hour_windows(
+    recorded_windows, block_start_overrides = _load_recorded_five_hour_windows(
         range_start - BLOCK_DURATION, range_end + BLOCK_DURATION,
     )
 
     # Group into blocks
     blocks = _group_entries_into_blocks(
         all_entries, mode="auto",
-        recorded_windows=recorded_windows, now=now_utc,
-    )
+        recorded_windows=recorded_windows,
+        block_start_overrides=block_start_overrides,
+        now=now_utc,
+    )
+
+    # Bug E (v1.7.2 round-4): when the ACTIVE block is heuristic-anchored
+    # but a canonical ``five_hour_blocks`` row exists for the current 5h
+    # window key, swap the active block's times to the API-anchored
+    # ``block_start_at`` / ``five_hour_resets_at`` and flip its anchor to
+    # ``"recorded"`` so the renderer drops the ``~`` prefix. The
+    # heuristic anchor can sit in a different 10-minute floor bucket
+    # than the canonical anchor (e.g. 23:00 IDT vs 20:50 IDT — 130 min
+    # apart), so round-3's anchor-overlay in
+    # ``_load_recorded_five_hour_windows`` doesn't catch this case.
+    # Match by the live 5h window key (the same key
+    # ``cmd_five_hour_blocks`` would surface for the ACTIVE row) — falls
+    # back to heuristic behavior whenever the canonical row is missing.
+    #
+    # Bug F (v1.7.2 round-5): pass ``all_entries`` so the swap also
+    # re-aggregates token / cost totals over the canonical interval. The
+    # heuristic block holds only entries from the heuristic anchor
+    # onwards; the canonical block may start earlier and include 1-2h of
+    # additional entries. Without re-aggregation the displayed window
+    # said one thing and the cost said another (live data: window
+    # 20:50→01:50 with $45 cost vs the real $128).
+    _maybe_swap_active_block_to_canonical(blocks, all_entries, now=now_utc)
 
     if args.json:
         print(_blocks_to_json(blocks))
@@ -5457,6 +5745,105 @@ def cmd_blocks(args: argparse.Namespace) -> int:
     return 0
 
 
+def _maybe_swap_active_block_to_canonical(
+    blocks: list[Any],
+    all_entries: list[Any],
+    *,
+    now: dt.datetime,
+) -> None:
+    """In-place swap of an ACTIVE heuristic block to its API-anchored
+    canonical window — timestamps AND token/cost totals.
+
+    Looks up the live ``five_hour_window_key`` from the most recent
+    ``weekly_usage_snapshots`` row, then joins to ``five_hour_blocks``
+    for that key. If found AND the canonical window still contains
+    ``now`` (resets_at > now), rewrites the active block to span the
+    canonical ``[block_start_at, five_hour_resets_at)`` interval and
+    flips ``anchor`` to ``"recorded"``. Token / cost totals are
+    re-aggregated from ``all_entries`` filtered to that interval via
+    ``_aggregate_block`` — the canonical window may contain 1-2h more
+    activity than the heuristic grouping did, so the cost shown next
+    to the swapped timestamps stays consistent with them (Bug F).
+
+    No-op when:
+      - No block is active (no ``is_active`` and not gap).
+      - The active block's anchor is already ``"recorded"``.
+      - No live snapshot exists, or the snapshot's ``five_hour_window_key``
+        is NULL.
+      - No canonical ``five_hour_blocks`` row matches the live key.
+      - The canonical window's ``five_hour_resets_at`` is already in
+        the past relative to ``now`` (canonical block is closed; the
+        heuristic block is genuinely the current activity).
+
+    Surgical helper called once from ``cmd_blocks`` after grouping.
+    """
+    # Find the active (non-gap, heuristic) block — there's at most one.
+    active_idx = None
+    for i, b in enumerate(blocks):
+        if not b.is_gap and b.is_active:
+            active_idx = i
+            break
+    if active_idx is None or blocks[active_idx].anchor != "heuristic":
+        return
+    active = blocks[active_idx]
+    try:
+        with open_db() as conn:
+            snap = conn.execute(
+                "SELECT five_hour_window_key FROM weekly_usage_snapshots "
+                "WHERE five_hour_window_key IS NOT NULL "
+                "ORDER BY captured_at_utc DESC, id DESC LIMIT 1"
+            ).fetchone()
+            if snap is None or snap["five_hour_window_key"] is None:
+                return
+            key = int(snap["five_hour_window_key"])
+            row = conn.execute(
+                "SELECT block_start_at, five_hour_resets_at "
+                "FROM five_hour_blocks WHERE five_hour_window_key = ? "
+                "LIMIT 1",
+                (key,),
+            ).fetchone()
+    except (sqlite3.DatabaseError, OSError):
+        return
+    if row is None:
+        return
+    try:
+        block_start = parse_iso_datetime(
+            row["block_start_at"], "five_hour_blocks.block_start_at"
+        )
+        block_end = parse_iso_datetime(
+            row["five_hour_resets_at"], "five_hour_blocks.five_hour_resets_at"
+        )
+    except ValueError:
+        return
+    # Normalize to UTC for stable comparisons (block_start_at can carry
+    # the host-local offset; five_hour_resets_at is UTC).
+    block_start_utc = block_start.astimezone(dt.timezone.utc)
+    block_end_utc = block_end.astimezone(dt.timezone.utc)
+    # If the canonical window has already ended, don't displace the
+    # heuristic active block — the canonical block is closed and the
+    # heuristic anchor reflects real ongoing activity in a later window.
+    if block_end_utc <= now.astimezone(dt.timezone.utc):
+        return
+    # Re-aggregate entries over the canonical interval. Build a fresh
+    # Block via ``_build_activity_block`` (mode="auto" matches
+    # ``_group_entries_into_blocks``'s default) so every total stays in
+    # one code path — no field-by-field assignment that could drift if
+    # the dataclass grows new fields.
+    canonical_entries = [
+        e for e in all_entries
+        if block_start_utc <= e.timestamp < block_end_utc
+    ]
+    rebuilt = _build_activity_block(
+        canonical_entries,
+        block_start_utc,
+        block_end_utc,
+        now.astimezone(dt.timezone.utc),
+        "auto",
+        anchor="recorded",
+    )
+    blocks[active_idx] = rebuilt
+
+
 def _parse_cli_date_range(
     args: argparse.Namespace,
     *,
@@ -7048,11 +7435,29 @@ def _apply_reset_events_to_weekrefs(
         week: its API-derived start (= new resets_at - 7d) backdates into
         the pre-reset week. Override ref.week_start_at = effective_reset_at_utc
         so the new week starts at the actual reset moment.
+      - **In-place credit (v1.7.2 round-3, Bug B).** Detected via the row
+        shape ``old_week_end_at == effective_reset_at_utc`` (the live and
+        backfill detection paths both write this shape — see
+        ``test_event_row_old_is_effective_not_cur_end``). For these events,
+        the credited week's ref matches ``new_week_end_at`` (the original
+        resets_at is unchanged), so the post-credit override above
+        rewrites ``week_start_at`` to ``effective``. But the pre-credit
+        segment of the SAME week — where the user spent the bulk of their
+        usage before the credit — is dropped, because no other ref in
+        ``refs`` carries ``week_end_at == effective``. Synthesize a
+        pre-credit ref alongside the post-credit one: its
+        ``week_start_at`` stays at the ref's original API-derived value,
+        its ``week_end_at`` becomes ``effective`` (closes the pre-credit
+        segment). Credited weeks render as TWO trend rows downstream.
 
     The ref's `week_start` (date) and `key` fields are intentionally left at
     the API-derived values — they're the lookup keys for
     weekly_usage_snapshots / weekly_cost_snapshots. Only the display-facing
     `week_start_at` / `week_end_at` (and the derived `week_end` date) shift.
+    Both the pre-credit and post-credit synthesized refs share the same
+    `key` so downstream per-segment readers
+    (``cmd_percent_breakdown`` / dashboard milestone panel) can still
+    filter milestones by ``reset_event_id`` against the same lookup keys.
     """
     events = conn.execute(
         "SELECT old_week_end_at, new_week_end_at, effective_reset_at_utc "
@@ -7062,6 +7467,15 @@ def _apply_reset_events_to_weekrefs(
         return refs
     pre_map  = {e["old_week_end_at"]: e["effective_reset_at_utc"] for e in events}
     post_map = {e["new_week_end_at"]: e["effective_reset_at_utc"] for e in events}
+    # In-place credit events have `old == effective` (the row shape the
+    # live + backfill detection paths agree on). Project the set of
+    # `new_week_end_at` values for those events so we can detect them
+    # while iterating refs and split the credited week into TWO refs.
+    in_place_credit_new_ends: set[str] = {
+        e["new_week_end_at"]
+        for e in events
+        if e["old_week_end_at"] == e["effective_reset_at_utc"]
+    }
     out: list[WeekRef] = []
     for ref in refs:
         new_ref = ref
@@ -7076,7 +7490,43 @@ def _apply_reset_events_to_weekrefs(
                 pass
         if ref.week_end_at and ref.week_end_at in post_map:
             reset_at = post_map[ref.week_end_at]
+            # In-place credit: synthesize a pre-credit ref FIRST so it
+            # lands in `out` before the post-credit ref. The pre-credit
+            # ref keeps the ORIGINAL API-derived week_start_at; only its
+            # week_end_at shifts to `effective`. The post-credit ref
+            # (constructed below via the standard `replace`) carries
+            # week_start_at = effective, week_end_at = original.
+            # Order: pre-credit BEFORE post-credit so chronological
+            # iteration in cmd_report's trend table renders them
+            # naturally (older segment above the newer one in DESC
+            # ordering: post-credit is "more recent" so the post-credit
+            # row should come FIRST in the DESC list — but the original
+            # ref was already in DESC position, and we insert pre-credit
+            # AFTER the post-credit. Concretely: post-credit takes the
+            # ref's original slot; pre-credit goes one slot later).
+            if ref.week_end_at in in_place_credit_new_ends:
+                try:
+                    reset_dt = parse_iso_datetime(
+                        reset_at, "reset_event.effective"
+                    )
+                    pre_end_date = (
+                        # internal fallback: host-local intentional
+                        reset_dt - dt.timedelta(seconds=1)
+                    ).astimezone().date()
+                    pre_credit_ref = replace(
+                        ref,
+                        week_end_at=reset_at,
+                        week_end=pre_end_date,
+                    )
+                except ValueError:
+                    pre_credit_ref = None
+            else:
+                pre_credit_ref = None
             new_ref = replace(new_ref, week_start_at=reset_at)
+            out.append(new_ref)
+            if pre_credit_ref is not None:
+                out.append(pre_credit_ref)
+            continue
         out.append(new_ref)
     return out
 
@@ -7151,6 +7601,71 @@ def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
                     " effective_reset_at_utc) VALUES (?, ?, ?, ?)",
                     (row["captured_at_utc"], prior_end, cur_end, effective_iso),
                 )
+        elif prior_end and cur_end == prior_end:
+            # In-place credit branch (v1.7.2). Mirrors the live detection
+            # in cmd_record_usage: same end_at across two captures + ≥25pp
+            # drop in weekly_percent + prior end still in the future at
+            # captured_dt → Anthropic-issued goodwill credit. One event
+            # row with old == new == cur_end, effective = floor_to_hour
+            # of the captured_at when the drop was first observed.
+            try:
+                prior_end_dt = parse_iso_datetime(prior_end, "backfill.prior")
+                captured_dt  = parse_iso_datetime(row["captured_at_utc"], "backfill.cap")
+            except ValueError:
+                prior_end = cur_end
+                prior_pct = cur_pct
+                continue
+            if (
+                captured_dt < prior_end_dt
+                and prior_pct is not None and cur_pct is not None
+                and (float(prior_pct) - float(cur_pct)) >= _RESET_PCT_DROP_THRESHOLD
+            ):
+                # Pre-check on ``new_week_end_at`` (mirrors the live
+                # detection path's pre-check). Necessary because the
+                # UNIQUE(old, new) constraint alone WON'T dedup against
+                # legacy/broken-shape rows: pre-fix DBs may have
+                # ``(cur_end, cur_end)`` rows for the same credit that
+                # the new shape writes as ``(effective_iso, cur_end)``.
+                # Without this pre-check, the backfill writes a second
+                # row for the same credit on every open_db() call after
+                # upgrade. (See round-2 review Bug 1.)
+                already = conn.execute(
+                    "SELECT 1 FROM week_reset_events "
+                    "WHERE new_week_end_at = ? LIMIT 1",
+                    (cur_end,),
+                ).fetchone()
+                if already is not None:
+                    prior_end = cur_end
+                    prior_pct = cur_pct
+                    continue
+                # Canonicalize to UTC before isoformat so the stored
+                # offset is `+00:00`, matching the live detection path
+                # (cmd_record_usage uses now_utc which is already UTC).
+                # parse_iso_datetime returns .astimezone() (host-local
+                # fallback at bin/cctally:_local_tz_name gate); without
+                # this normalization, non-UTC hosts would store the
+                # column as e.g. `+03:00`, breaking lex comparisons
+                # downstream (CLAUDE.md gotcha: 5h-block cross-reset
+                # comparisons go through unixepoch(), NOT lex
+                # BETWEEN/</>; the reset-aware DB clamp here applies
+                # the same rule). The reset-aware clamp now wraps both
+                # sides with unixepoch() (Bug 2 fix), but a canonical
+                # UTC offset on write is the right defense-in-depth.
+                effective_iso = (
+                    _floor_to_hour(captured_dt.astimezone(dt.timezone.utc))
+                    .isoformat(timespec="seconds")
+                )
+                # Row shape: old=effective_iso, new=cur_end (distinct
+                # values). See the live-detection site in
+                # bin/_cctally_record.py for the full rationale; in
+                # short, old==new collapses the credited week to a
+                # zero-width window in _apply_reset_events_to_weekrefs.
+                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 (?, ?, ?, ?)",
+                    (row["captured_at_utc"], effective_iso, cur_end, effective_iso),
+                )
         prior_end = cur_end
         prior_pct = cur_pct
     # Flush implicit transaction so callers using explicit BEGIN
@@ -7165,6 +7680,14 @@ def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
 # 86→0 and 34→0 cases while filtering 35→33-style jitter.
 _RESET_PCT_DROP_THRESHOLD = 25.0
 
+# In-place 5h-credit threshold. Mirrors `_RESET_PCT_DROP_THRESHOLD` but
+# scaled down for the 5h dimension: typical 5h usage stays under ~10pp in
+# a single block, so a 5pp drop sits well above natural variation while
+# proportionally being a larger signal than 25pp is on the weekly scale.
+# See spec docs/superpowers/specs/2026-05-16-5h-in-place-credit-detection.md
+# §2.1 (Q1) for rationale.
+_FIVE_HOUR_RESET_PCT_DROP_THRESHOLD = 5.0
+
 
 def _week_ref_has_reset_event(
     conn: sqlite3.Connection, ref: WeekRef
@@ -8080,6 +8603,24 @@ def cmd_report(args: argparse.Namespace) -> int:
                 week_end_date=current_end.isoformat(),
             )
 
+        # Bug D (v1.7.2 round-4): when an in-place credit event exists for
+        # the current subscription week, `_apply_reset_events_to_weekrefs`
+        # synthesizes a pre-credit ref alongside the post-credit one (both
+        # share `WeekRef.key`). The live "current week" segment is the
+        # POST-credit one (its `week_start_at` was shifted to the
+        # effective reset moment). Route `current_ref` through the same
+        # override so its `week_start_at` reflects the post-credit start;
+        # this lets the per-row match below disambiguate the synthesized
+        # pre-credit ref from the live post-credit ref via both
+        # `key` AND `week_start_at`. Order contract from
+        # `_apply_reset_events_to_weekrefs`: post-credit ref lands at
+        # index 0, pre-credit at index 1. Non-credit weeks return the
+        # single input ref unchanged, so this is a no-op on the common
+        # path.
+        _adjusted_current = _apply_reset_events_to_weekrefs(conn, [current_ref])
+        if _adjusted_current:
+            current_ref = _adjusted_current[0]
+
         weeks = get_recent_weeks(conn, max(1, args.weeks))
         if not weeks:
             # Format-aware empty path mirrors cmd_forecast:18578-18629 — a
@@ -8132,8 +8673,38 @@ def cmd_report(args: argparse.Namespace) -> int:
         except OauthUsageConfigError:
             _fresh_cfg = _get_oauth_usage_config({})
 
+        # Build a set of week_start_date keys that occur MORE THAN ONCE
+        # in `weeks` — these are credited weeks (round-3, Bug B) where
+        # `_apply_reset_events_to_weekrefs` synthesized a pre-credit
+        # ref alongside the post-credit ref. Both refs share
+        # `week_start_date` so the default
+        # ``get_latest_usage_for_week(conn, ref)`` returns the SAME row
+        # (the most recent snapshot in the whole week) for both,
+        # collapsing the pre-credit row's `weeklyPercent` to the
+        # post-credit value. For those keys ONLY, pin `as_of_utc` to
+        # the ref's `week_end_at` so each segment renders its own
+        # latest snapshot. Non-credit weeks (single ref per key) keep
+        # the legacy unfiltered lookup so test fixtures that seed
+        # snapshots OUTSIDE the API-derived week window (e.g.
+        # `test_report_freshness`) keep finding their rows.
+        _split_keys = {
+            r.week_start.isoformat()
+            for r in weeks
+            if sum(
+                1 for x in weeks
+                if x.week_start.isoformat() == r.week_start.isoformat()
+            ) > 1
+        }
+
         for week_ref in weeks:
-            usage = get_latest_usage_for_week(conn, week_ref)
+            key = week_ref.week_start.isoformat()
+            usage = get_latest_usage_for_week(
+                conn,
+                week_ref,
+                as_of_utc=(
+                    week_ref.week_end_at if key in _split_keys else None
+                ),
+            )
 
             # For weeks touched by a reset event, the cached
             # weekly_cost_snapshots row covers the API-derived range (which
@@ -8197,7 +8768,20 @@ def cmd_report(args: argparse.Namespace) -> int:
                         "age_seconds": int(age_s),
                     }
             trend.append(row)
-            if week_ref.key == current_ref.key:
+            # Bug D (v1.7.2 round-4): for credited weeks `weeks` contains
+            # TWO refs sharing `key` (pre-credit + post-credit segments).
+            # `current_ref` was routed through
+            # `_apply_reset_events_to_weekrefs` above so its
+            # `week_start_at` reflects the post-credit segment's effective
+            # start (or the original start for non-credit weeks). Match on
+            # BOTH `key` AND `week_start_at` so the pre-credit ref doesn't
+            # overwrite the post-credit row's selection on the second
+            # iteration (last-write-wins on key-only equality picked the
+            # wrong row on the user's live data).
+            if (
+                week_ref.key == current_ref.key
+                and week_ref.week_start_at == current_ref.week_start_at
+            ):
                 current_row = row
 
         if current_row is None and trend:
@@ -8637,7 +9221,39 @@ def cmd_percent_breakdown(args: argparse.Namespace) -> int:
             except ValueError:
                 pass
 
-        milestones = get_milestones_for_week(conn, week_start_date)
+        # v1.7.2 segment filter: when a week_reset_events row exists for
+        # the current ``week_end_at``, narrow the milestone listing to
+        # the active (latest) segment so a credited week's header (which
+        # already reflects the post-credit window via the canon-boundary
+        # rewrite above) is coherent with the body. Sentinel ``0`` covers
+        # pre-credit / no-event weeks; pre-005 DBs that didn't have the
+        # column also default to 0 via the migration's ALTER DEFAULT.
+        active_segment = 0
+        canon_end_for_lookup = None
+        latest_end_row = conn.execute(
+            "SELECT week_end_at FROM weekly_usage_snapshots "
+            "WHERE week_start_date = ? AND week_end_at IS NOT NULL "
+            "ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
+            (week_start_date,),
+        ).fetchone()
+        if latest_end_row is not None:
+            canon_end_for_lookup = _canonicalize_optional_iso(
+                latest_end_row["week_end_at"], "pb.cur"
+            )
+        if canon_end_for_lookup:
+            seg_row = conn.execute(
+                "SELECT id FROM week_reset_events "
+                "WHERE new_week_end_at = ? "
+                "ORDER BY id DESC LIMIT 1",
+                (canon_end_for_lookup,),
+            ).fetchone()
+            if seg_row is not None:
+                active_segment = int(seg_row["id"])
+
+        milestones = [
+            m for m in get_milestones_for_week(conn, week_start_date)
+            if int(m["reset_event_id"] or 0) == active_segment
+        ]
 
         milestone_list = []
         for m in milestones:
@@ -8672,7 +9288,17 @@ def cmd_percent_breakdown(args: argparse.Namespace) -> int:
         else:
             print(f"Week: {week_start_date}..{week_end_date}")
         if not milestone_list:
-            print("No percent milestones recorded for this week.")
+            if active_segment > 0:
+                # v1.7.2: distinguish post-credit empty (just got
+                # credited, no crossings yet) from genuinely-empty week.
+                # The pre-credit ledger still exists in the DB — just
+                # filtered out of the body — so the user shouldn't see
+                # "No milestones" and assume the data is gone.
+                print(
+                    "(post-credit segment, no milestones crossed yet)"
+                )
+            else:
+                print("No percent milestones recorded for this week.")
             return 0
 
         print("Percent breakdown:\n")
@@ -8887,6 +9513,31 @@ def cmd_five_hour_blocks(args: argparse.Namespace) -> int:
         # to fill seven_day_pct_at_block_end on the active row.
         latest_7d, latest_window_key = _latest_seven_day_and_window(conn)
 
+        # Pre-load credit events for every window_key the rows query
+        # returned. Single index-scan over `five_hour_reset_events`;
+        # build a window_key -> list[Credit] map keyed for in-process
+        # JOIN against each block dict. Used by both the text/JSON
+        # render path AND the share-output snapshot wiring (spec §5.1.1).
+        # Loaded in a single pass — no per-block SELECT.
+        credit_rows = conn.execute(
+            "SELECT five_hour_window_key, prior_percent, post_percent, "
+            "       effective_reset_at_utc "
+            "  FROM five_hour_reset_events "
+            " ORDER BY five_hour_window_key, effective_reset_at_utc"
+        ).fetchall()
+        credits_by_window: dict[int, list[dict]] = {}
+        for cr in credit_rows:
+            credits_by_window.setdefault(
+                int(cr["five_hour_window_key"]), []
+            ).append({
+                "effectiveResetAtUtc": cr["effective_reset_at_utc"],
+                "priorPercent": float(cr["prior_percent"]),
+                "postPercent": float(cr["post_percent"]),
+                "deltaPp": round(
+                    float(cr["post_percent"]) - float(cr["prior_percent"]), 1
+                ),
+            })
+
         # Build per-block dicts with the active-flag side-channel.
         block_dicts: list[dict] = []
         for r in rows:
@@ -8895,6 +9546,11 @@ def cmd_five_hour_blocks(args: argparse.Namespace) -> int:
             d["__is_active"] = is_active
             if is_active and latest_7d is not None:
                 d["seven_day_pct_at_block_end"] = latest_7d
+            # Side-channel (parallel to __is_active): list of credit
+            # event dicts for this block's window. Empty list when none.
+            d["__credits"] = credits_by_window.get(
+                int(d["five_hour_window_key"]), []
+            )
             block_dicts.append(d)
 
         # Shareable-reports gate: --format short-circuits the JSON / table
@@ -9008,18 +9664,50 @@ def cmd_five_hour_breakdown(args: argparse.Namespace) -> int:
             )
             return 2
 
+        # Spec §5.2: ORDER BY captured_at_utc ASC (NOT percent_threshold)
+        # so post-credit segments interleave with pre-credit ones in
+        # time-order — same human threshold number can appear twice
+        # (once per reset_event_id segment) and must render in the
+        # order it crossed. Bucket B per §3.2: read ALL segments (no
+        # ``reset_event_id`` filter).
         milestones = conn.execute(
             """
             SELECT percent_threshold, captured_at_utc,
                    block_cost_usd, marginal_cost_usd,
-                   seven_day_pct_at_crossing
+                   seven_day_pct_at_crossing, reset_event_id
               FROM five_hour_milestones
              WHERE block_id = ?
-             ORDER BY percent_threshold ASC
+             ORDER BY captured_at_utc ASC, id ASC
             """,
             (block["id"],),
         ).fetchall()
 
+        # Spec §5.2 — load in-place credit events for this block's
+        # window, ascending by effective_reset_at_utc, so the text
+        # renderer can interleave a ``⚡ CREDIT  -Xpp @ HH:MM`` divider
+        # row between pre- and post-credit milestone segments and JSON
+        # consumers see the parallel ``credits[]`` array (Section 5.2).
+        credit_rows = conn.execute(
+            """
+            SELECT effective_reset_at_utc, prior_percent, post_percent
+              FROM five_hour_reset_events
+             WHERE five_hour_window_key = ?
+             ORDER BY effective_reset_at_utc ASC
+            """,
+            (block["five_hour_window_key"],),
+        ).fetchall()
+        credits_list: list[dict] = [
+            {
+                "effectiveResetAtUtc": c["effective_reset_at_utc"],
+                "priorPercent": float(c["prior_percent"]),
+                "postPercent": float(c["post_percent"]),
+                "deltaPp": round(
+                    float(c["post_percent"]) - float(c["prior_percent"]), 1
+                ),
+            }
+            for c in credit_rows
+        ]
+
         crossed = bool(block.get("crossed_seven_day_reset"))
         p_start = block.get("seven_day_pct_at_block_start")
         p_end = block.get("seven_day_pct_at_block_end")
@@ -9056,6 +9744,10 @@ def cmd_five_hour_breakdown(args: argparse.Namespace) -> int:
             "sevenDayPctDeltaPp":      delta,
             "crossedSevenDayReset":    crossed,
         }
+        # Spec §5.2: expose ``resetEventId`` on each milestone so JSON
+        # consumers can disambiguate post-credit threshold repeats from
+        # pre-credit ones. ``0`` is the pre-credit/no-credit sentinel
+        # (matches the schema default).
         ms_out = [
             {
                 "percentThreshold":      m["percent_threshold"],
@@ -9066,13 +9758,23 @@ def cmd_five_hour_breakdown(args: argparse.Namespace) -> int:
                     else round(m["marginal_cost_usd"], 9)
                 ),
                 "sevenDayPctAtCrossing": m["seven_day_pct_at_crossing"],
+                "resetEventId":          int(m["reset_event_id"] or 0),
             }
             for m in milestones
         ]
 
         if args.json:
+            # Spec §5.2: ``credits`` is the parallel array to
+            # ``milestones`` — same shape as the ``credits`` field on
+            # ``five-hour-blocks --json`` (§5.1). Stacked credits across
+            # distinct 10-min slots produce multiple entries.
             print(json.dumps(
-                {"schemaVersion": 1, "block": block_out, "milestones": ms_out},
+                {
+                    "schemaVersion": 1,
+                    "block": block_out,
+                    "milestones": ms_out,
+                    "credits": credits_list,
+                },
                 indent=2,
             ))
             return 0
@@ -9113,7 +9815,47 @@ def cmd_five_hour_breakdown(args: argparse.Namespace) -> int:
         headers = ["#", "Threshold", "Cumulative Cost", "Marginal Cost",
                    "7d at crossing"]
         rows = []
-        for idx, m in enumerate(ms_out, start=1):
+        # Spec §5.2 — merged event stream. Interleave milestones and
+        # credits in time-order (``capturedAt`` for milestones,
+        # ``effectiveResetAtUtc`` for credits). Credits render as a
+        # divider row with ``⚡ CREDIT`` in the Threshold cell and the
+        # delta-pp + HH:MM in the rightmost cell; the milestone row
+        # numbering counter (``#``) continues across the divider so the
+        # ordinal still reflects "the Nth event in this block."
+        merged_events: list[tuple[str, dict]] = []
+        for m in ms_out:
+            merged_events.append(("milestone", m))
+        for c in credits_list:
+            merged_events.append(("credit", c))
+        merged_events.sort(key=lambda ev: (
+            ev[1]["effectiveResetAtUtc"] if ev[0] == "credit"
+            else ev[1]["capturedAt"]
+        ))
+        idx = 0
+        for kind, ev in merged_events:
+            idx += 1
+            if kind == "credit":
+                # Spec §5.2: ⚡ CREDIT  -Xpp @ HH:MM divider row.
+                # HH:MM rendered in the display tz via format_display_dt.
+                # ``format_display_dt`` is the documented chokepoint for
+                # human-displayed datetimes (CLAUDE.md). The deltaPp
+                # value is float; format as integer ppm (mirrors the
+                # five-hour-blocks chip in §5.1).
+                hhmm = format_display_dt(
+                    ev["effectiveResetAtUtc"],
+                    args._resolved_tz,
+                    fmt="%H:%M",
+                    suffix=False,
+                )
+                rows.append([
+                    str(idx),
+                    "⚡ CREDIT",
+                    f"{ev['deltaPp']:+.0f}pp",
+                    "",
+                    f"@ {hhmm}",
+                ])
+                continue
+            m = ev
             cum = f"${m['blockCostUSD']:.6f}"
             marg = (
                 "n/a" if m["marginalCostUSD"] is None
@@ -9888,6 +10630,7 @@ def doctor_gather_state(
     # ── Data freshness ───────────────────────────────────────────────
     latest_snapshot_at = None
     forked_bucket_counts: dict | None = None
+    credited_weeks: list[dict] | None = None
     try:
         if DB_PATH.exists():
             conn = sqlite3.connect(str(DB_PATH))
@@ -9924,6 +10667,61 @@ def doctor_gather_state(
                         )
                     except sqlite3.OperationalError:
                         forked_bucket_counts[key] = 0
+                # v1.7.2 credited-week tracking. For each week with a
+                # past-effective ``week_reset_events`` row, gather the
+                # latest weekly_percent + count of post-credit milestones.
+                # The check warns when latest_percent >= 1.0 AND
+                # post_credit_milestone_count == 0.
+                # unixepoch() normalizes the cross-offset comparison.
+                try:
+                    credit_rows = conn.execute(
+                        """
+                        SELECT wre.id AS event_id,
+                               wre.new_week_end_at AS end_at,
+                               wre.effective_reset_at_utc AS effective
+                          FROM week_reset_events wre
+                         WHERE unixepoch(wre.effective_reset_at_utc)
+                               <= unixepoch(?)
+                        """,
+                        (now_utc_iso(),),
+                    ).fetchall()
+                    credited_weeks = []
+                    for cr in credit_rows:
+                        end_at = cr[1]
+                        evt_id = cr[0]
+                        latest = conn.execute(
+                            """
+                            SELECT week_start_date, weekly_percent
+                              FROM weekly_usage_snapshots
+                             WHERE week_end_at = ?
+                             ORDER BY captured_at_utc DESC, id DESC
+                             LIMIT 1
+                            """,
+                            (end_at,),
+                        ).fetchone()
+                        if latest is None or latest[0] is None:
+                            continue
+                        ws = latest[0]
+                        lp = float(latest[1] or 0.0)
+                        try:
+                            mc_row = conn.execute(
+                                "SELECT COUNT(*) FROM percent_milestones "
+                                "WHERE week_start_date = ? AND reset_event_id = ?",
+                                (ws, evt_id),
+                            ).fetchone()
+                            mc = int(mc_row[0]) if mc_row and mc_row[0] else 0
+                        except sqlite3.OperationalError:
+                            mc = 0
+                        credited_weeks.append({
+                            "week_start_date": ws,
+                            "latest_weekly_percent": lp,
+                            "post_credit_milestone_count": mc,
+                            "event_id": evt_id,
+                        })
+                except sqlite3.OperationalError:
+                    # week_reset_events table missing — treat as no
+                    # credited weeks (pre-feature DB).
+                    credited_weeks = []
             finally:
                 conn.close()
     except Exception:
@@ -10069,6 +10867,7 @@ def doctor_gather_state(
         cache_last_entry_at=cache_last_entry_at,
         claude_jsonl_present=claude_jsonl_present,
         forked_bucket_counts=forked_bucket_counts,
+        credited_weeks=credited_weeks,
         codex_entries_count=codex_entries_count,
         codex_last_entry_at=codex_last_entry_at,
         codex_jsonl_present=codex_jsonl_present,
@@ -13205,8 +14004,21 @@ def _build_five_hour_blocks_snapshot(
         used_pct = float(r.get("final_five_hour_percent") or 0.0)
         crossed = bool(r.get("crossed_seven_day_reset"))
         cell_text = "⚡" if crossed else "—"
+        # Spec §5.1.1 (Codex r2 finding 3): consume the ``__credits``
+        # side-channel set by ``cmd_five_hour_blocks`` and append a
+        # ``⚡ -Xpp, -Ypp`` chip to the block_start cell. Pure-string
+        # cell content flows uniformly through markdown / HTML table /
+        # SVG text renderers without per-format additions. Symmetric to
+        # the existing ⚡ glyph in the cross_reset cell — by position
+        # (block_start suffix vs. dedicated column) the two annotations
+        # remain visually distinguishable.
+        credits = r.get("__credits") or []
+        block_cell = block_lbl
+        if credits:
+            deltas = ", ".join(f"{c['deltaPp']:+.0f}pp" for c in credits)
+            block_cell = f"{block_lbl} ⚡ {deltas}"
         snap_rows.append(_lib_share.Row(cells={
-            "block_start": _lib_share.TextCell(block_lbl),
+            "block_start": _lib_share.TextCell(block_cell),
             "cost": _lib_share.MoneyCell(cost_usd),
             "used_pct": _lib_share.PercentCell(used_pct),
             "cross_reset": _lib_share.TextCell(cell_text),