cctally 1.7.2 → 1.7.3

package/bin/_cctally_tui.py

@@ -1030,6 +1030,56 @@ def _tui_build_percent_milestones(
     return out
 
 
+def _tui_build_five_hour_milestones(
+    conn: sqlite3.Connection,
+    five_hour_window_key: int | None,
+) -> list[dict]:
+    """Return per-percent 5h-block milestones for the given window, in
+    capture-time order. Spec §5.3 — drives the CurrentWeekModal's new
+    5h-milestone timeline section.
+
+    Bucket B per §3.2: NO ``reset_event_id`` filter — both pre- and
+    post-credit segments render in the merged chronological stream so
+    the user sees the full history of the active block including
+    repeated threshold values after an in-place credit. The React layer
+    differentiates rows by ``reset_event_id`` for key uniqueness.
+
+    Returns [] when the current week has no API-anchored 5h block. The
+    envelope-shaped dict mirrors the CLI ``five-hour-breakdown --json``
+    milestone objects but with snake_case keys (envelope convention).
+    """
+    if five_hour_window_key is None:
+        return []
+    rows = conn.execute(
+        """
+        SELECT percent_threshold, captured_at_utc, block_cost_usd,
+               marginal_cost_usd, seven_day_pct_at_crossing,
+               reset_event_id
+          FROM five_hour_milestones
+         WHERE five_hour_window_key = ?
+         ORDER BY captured_at_utc ASC, id ASC
+        """,
+        (int(five_hour_window_key),),
+    ).fetchall()
+    out: list[dict] = []
+    for r in rows:
+        out.append({
+            "percent_threshold": int(r["percent_threshold"]),
+            "captured_at_utc":   r["captured_at_utc"],
+            "block_cost_usd":    float(r["block_cost_usd"]),
+            "marginal_cost_usd": (
+                None if r["marginal_cost_usd"] is None
+                else float(r["marginal_cost_usd"])
+            ),
+            "seven_day_pct_at_crossing": (
+                None if r["seven_day_pct_at_crossing"] is None
+                else float(r["seven_day_pct_at_crossing"])
+            ),
+            "reset_event_id": int(r["reset_event_id"] or 0),
+        })
+    return out
+
+
 @dataclass
 class DataSnapshot:
     """All data needed to render one TUI frame. Produced by sync thread,
@@ -1062,6 +1112,13 @@ class DataSnapshot:
     # `current_week.five_hour_block` is precomputed via
     # `_select_current_block_for_envelope`).
     alerts: list[dict] = field(default_factory=list)
+    # ---- 5h in-place credit (v1.7.x) ----
+    # Already-envelope-shaped dicts for the CurrentWeekModal's new 5h
+    # milestone timeline (spec §5.3, Codex r1 finding 3). Parallel to
+    # ``percent_milestones`` (which carries the WEEKLY timeline). Loaded
+    # at sync-thread time so ``snapshot_to_envelope`` stays a pure
+    # renderer; empty list when no current 5h block is bound.
+    five_hour_milestones: list[dict] = field(default_factory=list)
 
     @classmethod
     def synthesize_for_marketing(cls, *, as_of_iso: str) -> "DataSnapshot":
@@ -1888,6 +1945,19 @@ def _tui_build_snapshot(
             alerts = _build_alerts_envelope_array(conn)
         except Exception as exc:
             errors.append(f"alerts: {exc}")
+        # ---- 5h in-place credit (v1.7.x) ----
+        # Load 5h milestones (pre + post credit) for the current
+        # block's window so CurrentWeekModal can render a merged
+        # chronological timeline alongside its weekly milestones.
+        # Spec §5.3 (Codex r1 finding 3).
+        fh_milestones: list[dict] = []
+        try:
+            win_key = None
+            if cw is not None and isinstance(cw.five_hour_block, dict):
+                win_key = cw.five_hour_block.get("five_hour_window_key")
+            fh_milestones = _tui_build_five_hour_milestones(conn, win_key)
+        except Exception as exc:
+            errors.append(f"five-hour-milestones: {exc}")
         return DataSnapshot(
             current_week=cw,
             forecast=fc,
@@ -1903,6 +1973,7 @@ def _tui_build_snapshot(
             blocks_panel=blocks_panel,
             daily_panel=daily_panel,
             alerts=alerts,
+            five_hour_milestones=fh_milestones,
         )
     finally:
         conn.close()
@@ -2375,11 +2446,26 @@ def _tui_panel_current_week(
         f"${cw.dollars_per_percent:.2f}"
         if cw.dollars_per_percent is not None else "—"
     )
+    # Spec §5.4 — credit badge next to the 5h percent. Source: same
+    # ``cw.five_hour_block.credits`` channel that drives the dashboard
+    # chip; only show when at least one credit is present for the
+    # current block. Format: ``⚡ -Xpp`` (single) / ``⚡ -Xpp, -Ypp``
+    # (stacked across distinct 10-min slots).
+    fh_credit_badge = ""
+    fhb = getattr(cw, "five_hour_block", None)
+    if isinstance(fhb, dict):
+        fh_credits = fhb.get("credits") or []
+        if fh_credits:
+            deltas = ", ".join(
+                f"{float(c.get('delta_pp', 0.0)):+.0f}pp"
+                for c in fh_credits
+            )
+            fh_credit_badge = f" {{bright}}⚡ {deltas}{{/}}"
     lines = [
         "",
         f" Used   {{{used_cls}}}{bar_fill}{{/}} {{{used_cls}.b}}{cw.used_pct:>5.1f}%{{/}}",
         "",
-        f" 5-hour {{bar.accent}}{five_bar}{{/}} {{bright}}{int(five):>3d}%{{/}}",
+        f" 5-hour {{bar.accent}}{five_bar}{{/}} {{bright}}{int(five):>3d}%{{/}}{fh_credit_badge}",
         f"        {{dim}}{fr_str}{{/}}" if fr_str else "",
         "",
         f" {{dim}}Spent{{/}}    {{bright}}${cw.spent_usd:.2f}{{/}}        "
@@ -2428,6 +2514,19 @@ def _tui_panel_current_week_hero(
     else:
         reset_suffix = ""
 
+    # Spec §5.4 — credit badge in the hero variant. Same source as the
+    # grid variant; append after the reset suffix so the badge follows
+    # the "resets in" timer.
+    fhb_hero = getattr(cw, "five_hour_block", None)
+    if isinstance(fhb_hero, dict):
+        fh_credits_hero = fhb_hero.get("credits") or []
+        if fh_credits_hero:
+            deltas_hero = ", ".join(
+                f"{float(c.get('delta_pp', 0.0)):+.0f}pp"
+                for c in fh_credits_hero
+            )
+            reset_suffix = f"{reset_suffix}  {{bright}}⚡ {deltas_hero}{{/}}"
+
     if snap.last_sync_error:
         health = "{warn}daemon error{/}"
     elif snap.last_sync_at is None:

package/bin/_lib_render.py

@@ -2671,6 +2671,12 @@ def _five_hour_blocks_to_json(
             "sevenDayPctAtBlockEnd":   p_end,
             "sevenDayPctDeltaPp":      delta,
             "crossedSevenDayReset":    crossed,
+            # Spec §5.1 — in-place credit events for this 5h block, in
+            # ascending effective_reset_at order. Empty list when the
+            # block carries no credit detections. Source: ``__credits``
+            # side-channel attached by ``cmd_five_hour_blocks`` via
+            # ``credits_by_window``.
+            "credits":                 d.get("__credits") or [],
         }
         if breakdown_axis == "model":
             out["modelBreakdowns"] = [
@@ -2752,6 +2758,20 @@ def _render_five_hour_blocks_table(
         formatted_start = _format_block_start(d["block_start_at"], args._resolved_tz)
         if crossed:
             formatted_start = f"⚡ {formatted_start}"
+        # Spec §5.1 — credit chip suffix. When the block carries one or
+        # more in-place credit events (5h credit detection v1.7.x;
+        # __credits side-channel set by ``cmd_five_hour_blocks``), append
+        # a ⚡-prefixed chip listing the per-credit delta-pp. Multiple
+        # credits in the same block concatenate (e.g.
+        # `⚡ credited -20pp, -8pp`). The chip text sits AFTER the
+        # block-start cell's existing crossed-reset glyph so the two
+        # signals visually disambiguate by position (crossed-reset
+        # prefix vs. credit suffix). Both use ⚡ — different semantics,
+        # different positions.
+        credits = d.get("__credits") or []
+        if credits:
+            deltas = ", ".join(f"{c['deltaPp']:+.0f}pp" for c in credits)
+            formatted_start = f"{formatted_start} ⚡ credited {deltas}"
         rows.append([
             formatted_start,
             "ACTIVE" if d["__is_active"] else "closed",

package/bin/cctally

@@ -3864,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(
         """
@@ -3913,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)
         )
         """
@@ -3933,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
@@ -7632,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
@@ -9457,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:
@@ -9465,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
@@ -9578,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")
@@ -9626,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"],
@@ -9636,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
@@ -9683,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
@@ -13832,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),