cctally 1.7.2 → 1.7.4

package/bin/_cctally_refresh.py

@@ -55,6 +55,23 @@ def _cctally():
     return sys.modules["cctally"]
 
 
+# === Honest imports from extracted homes ===================================
+# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
+# import from _cctally_core. `load_config` plus out-of-scope helpers
+# (`_resolve_oauth_token`, `_fetch_oauth_usage`, `_bust_statusline_cache`,
+# `_refresh_usage_inproc`, `_get_oauth_usage_config`,
+# `_seconds_since_iso`, `_select_last_known_snapshot`,
+# `_newest_snapshot_age_seconds`, `_normalize_percent`,
+# `_forecast_color_enabled`, `_discover_cc_version`, `cmd_record_usage`)
+# stay on the _cctally() accessor.
+from _cctally_core import (
+    eprint,
+    now_utc_iso,
+    _iso_to_epoch,
+    _format_short_duration,
+)
+
+
 # =========================================================================
 # Exception classes
 # =========================================================================
@@ -289,14 +306,13 @@ def _render_refresh_usage_text(payload: dict, color: bool, now_epoch: int) -> st
     The ``5h`` segment is omitted entirely when ``payload["five_hour"]`` is None.
     Color codes are emitted only when ``color`` is True.
     """
-    c = _cctally()
     a = _REFRESH_USAGE_ANSI if color else {k: "" for k in _REFRESH_USAGE_ANSI}
 
     seven = payload["seven_day"]
     seven_pct = seven["used_percent"]
     seven_resets = seven.get("resets_at_epoch")
     if seven_resets is not None:
-        seven_ttl = c._format_short_duration(seven_resets - now_epoch)
+        seven_ttl = _format_short_duration(seven_resets - now_epoch)
         seven_seg = (
             f"{a['yellow']}7d {seven_pct:.0f}%{a['reset']}"
             f" {a['orange']}(in {seven_ttl}){a['reset']}"
@@ -309,7 +325,7 @@ def _render_refresh_usage_text(payload: dict, color: bool, now_epoch: int) -> st
         five_pct = five["used_percent"]
         five_resets = five.get("resets_at_epoch")
         if five_resets is not None:
-            five_ttl = c._format_short_duration(five_resets - now_epoch)
+            five_ttl = _format_short_duration(five_resets - now_epoch)
             five_seg = (
                 f" | {a['yellow']}5h {five_pct:.0f}%{a['reset']}"
                 f" {a['orange']}(in {five_ttl}){a['reset']}"
@@ -420,14 +436,13 @@ def _bust_statusline_cache(path: str = _STATUSLINE_OAUTH_CACHE) -> str:
     ``"absent"`` (file did not exist), ``"error"`` (delete failed for
     a non-FileNotFoundError reason — logged via eprint, does NOT raise).
     """
-    c = _cctally()
     try:
         os.remove(path)
         return "busted"
     except FileNotFoundError:
         return "absent"
     except OSError as exc:
-        c.eprint(f"refresh-usage: cache-bust failed: {exc}")
+        eprint(f"refresh-usage: cache-bust failed: {exc}")
         return "error"
 
 
@@ -450,7 +465,7 @@ def _cmd_refresh_usage_handle_rate_limit(args: argparse.Namespace, exc) -> int:
     quiet = bool(getattr(args, "quiet", False))
 
     if snap is None:
-        c.eprint("refresh-usage: rate-limited; no last-known data; "
+        eprint("refresh-usage: rate-limited; no last-known data; "
                  "status-line will populate on next CC tick")
         if json_mode:
             print(json.dumps({
@@ -467,7 +482,7 @@ def _cmd_refresh_usage_handle_rate_limit(args: argparse.Namespace, exc) -> int:
         _freshness_label(age_s, cfg) if age_s is not None else "stale"
     )
 
-    c.eprint(f"refresh-usage: rate-limited; using last-known "
+    eprint(f"refresh-usage: rate-limited; using last-known "
              f"(captured {int(age_s) if age_s is not None else '?'}s ago)")
 
     if json_mode:
@@ -550,7 +565,7 @@ def _refresh_usage_inproc(timeout_seconds: float = 5.0) -> _RefreshUsageResult:
         # built then a downstream cmd_record_usage call fails).
         seven_pct = c._normalize_percent(float(seven["utilization"]))
         seven_resets_iso = seven["resets_at"]
-        seven_resets_epoch = c._iso_to_epoch(seven_resets_iso)
+        seven_resets_epoch = _iso_to_epoch(seven_resets_iso)
     except (TypeError, ValueError, KeyError) as exc:
         return _RefreshUsageResult(
             status="parse_failed",
@@ -566,7 +581,7 @@ def _refresh_usage_inproc(timeout_seconds: float = 5.0) -> _RefreshUsageResult:
         try:
             five_pct = c._normalize_percent(float(five["utilization"]))
             five_resets_iso = five["resets_at"]
-            five_resets_epoch = c._iso_to_epoch(five_resets_iso)
+            five_resets_epoch = _iso_to_epoch(five_resets_iso)
         except (TypeError, ValueError) as exc:
             # 5h is optional - silently degrade rather than fail the command
             # (parity with the previous cmd_refresh_usage behavior; the eprint
@@ -599,7 +614,7 @@ def _refresh_usage_inproc(timeout_seconds: float = 5.0) -> _RefreshUsageResult:
     # (tests/test_refresh_usage_cmd.py:55, test_refresh_usage_inproc.py:18).
     cache_state = c._bust_statusline_cache()
 
-    fetched_at = c.now_utc_iso()
+    fetched_at = now_utc_iso()
     fresh_envelope = {
         "label": "fresh",
         "captured_at": fetched_at,
@@ -652,7 +667,7 @@ def cmd_refresh_usage(args: argparse.Namespace) -> int:
         # Emit BEFORE rendering so stderr flushes consistently for harnesses
         # that grep across both streams.
         for warning in result.warnings:
-            c.eprint(f"refresh-usage: {warning}")
+            eprint(f"refresh-usage: {warning}")
         payload = result.payload or {}
         if getattr(args, "json", False):
             print(_serialize_refresh_usage_json(payload))
@@ -668,7 +683,7 @@ def cmd_refresh_usage(args: argparse.Namespace) -> int:
             args, RefreshUsageRateLimitError(result.reason or "rate limited"))
 
     if result.status == "no_oauth_token":
-        c.eprint("refresh-usage: no OAuth token found "
+        eprint("refresh-usage: no OAuth token found "
                  "(run 'claude' once to authenticate)")
         return 2
 
@@ -678,9 +693,9 @@ def cmd_refresh_usage(args: argparse.Namespace) -> int:
         # config-error reason string verbatim so we can detect it here.
         reason = result.reason or ""
         if reason.startswith("invalid oauth_usage config:"):
-            c.eprint(f"cctally: {reason}")
+            eprint(f"cctally: {reason}")
             return 2
-        c.eprint(f"refresh-usage: OAuth fetch failed: {reason}")
+        eprint(f"refresh-usage: OAuth fetch failed: {reason}")
         return 3
 
     if result.status == "parse_failed":
@@ -688,7 +703,7 @@ def cmd_refresh_usage(args: argparse.Namespace) -> int:
         # only seven_day failures (RefreshUsageMalformedError or unparseable
         # field extraction) propagate here. Preserve the original exact
         # error-line shape for bash harnesses that grep stderr.
-        c.eprint(f"refresh-usage: {result.reason or ''}")
+        eprint(f"refresh-usage: {result.reason or ''}")
         return 4
 
     if result.status == "record_failed":
@@ -698,13 +713,13 @@ def cmd_refresh_usage(args: argparse.Namespace) -> int:
                 rc = int(reason.split()[1])
             except (IndexError, ValueError):
                 rc = -1
-            c.eprint(f"refresh-usage: failed to record usage (exit {rc})")
+            eprint(f"refresh-usage: failed to record usage (exit {rc})")
         else:
-            c.eprint(f"refresh-usage: failed to record usage: {reason}")
+            eprint(f"refresh-usage: failed to record usage: {reason}")
         return 5
 
     # Defensive: unknown status from _refresh_usage_inproc -> treat as parse error.
-    c.eprint(f"refresh-usage: unexpected status {result.status!r}")
+    eprint(f"refresh-usage: unexpected status {result.status!r}")
     return 4
 
 
@@ -757,7 +772,7 @@ def _hook_tick_oauth_refresh(
     seven = api["seven_day"]
     try:
         seven_pct = c._normalize_percent(float(seven["utilization"]))
-        seven_resets_epoch = c._iso_to_epoch(seven["resets_at"])
+        seven_resets_epoch = _iso_to_epoch(seven["resets_at"])
     except (TypeError, ValueError, KeyError):
         return "err(parse)", None
     five = api.get("five_hour") if isinstance(api.get("five_hour"), dict) else None
@@ -766,7 +781,7 @@ def _hook_tick_oauth_refresh(
     if five is not None and "utilization" in five and "resets_at" in five:
         try:
             five_pct = c._normalize_percent(float(five["utilization"]))
-            five_resets_epoch = c._iso_to_epoch(five["resets_at"])
+            five_resets_epoch = _iso_to_epoch(five["resets_at"])
         except (TypeError, ValueError):
             five_pct = None
             five_resets_epoch = None

package/bin/_cctally_setup.py

@@ -63,6 +63,18 @@ def _cctally():
     return sys.modules["cctally"]
 
 
+# === Honest imports from extracted homes ===================================
+# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
+# import from _cctally_core. Path constants (`APP_DIR`,
+# `CLAUDE_SETTINGS_PATH`, `HOOK_TICK_LOG_PATH`) plus the extensive
+# out-of-scope setup-specific helpers (legacy migration, hook surgery,
+# OAuth token, sync_cache, …) stay on the _cctally() accessor.
+from _cctally_core import (
+    eprint,
+    _command_as_of,
+)
+
+
 # ── settings.json hook surgery ─────────────────────────────────────────
 
 
@@ -430,7 +442,7 @@ def _legacy_resolve_backup_dir() -> pathlib.Path:
     so a re-run never overwrites a prior migration's snapshot.
     """
     c = _cctally()
-    now = c._command_as_of()
+    now = _command_as_of()
     stamp = now.strftime("%Y%m%d-%H%M%S")
     base = pathlib.Path.home() / ".claude" / f"{c._LEGACY_BACKUP_DIR_PREFIX}{stamp}"
     base.mkdir(parents=True, exist_ok=True)
@@ -614,7 +626,6 @@ def _setup_read_legacy_prompt_input(stream, reprompt: str | None = None) -> bool
     us). When None (test default), no reprompt is emitted — useful for unit
     tests that drive `stream` from io.StringIO.
     """
-    eprint = _cctally().eprint
     yes_words = {"y", "yes"}
     no_words = {"n", "no"}
     for attempt in range(3):
@@ -815,7 +826,7 @@ def _setup_status(args: argparse.Namespace) -> int:
     try:
         settings = c._load_claude_settings()
     except c.SetupError as exc:
-        c.eprint(f"setup: warning: {exc}")
+        eprint(f"setup: warning: {exc}")
         settings = {}
     hook_counts = _setup_count_hook_entries(settings)
     oauth = _setup_oauth_token_present()
@@ -911,14 +922,14 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
     try:
         settings = c._load_claude_settings()
     except c.SetupError as exc:
-        c.eprint(f"setup: {exc}")
+        eprint(f"setup: {exc}")
         return 1
     settings, removed = _settings_merge_uninstall(settings)
     if removed:
         try:
             c._write_claude_settings_atomic(settings)
         except OSError as exc:
-            c.eprint(f"setup: failed to write {c.CLAUDE_SETTINGS_PATH}: {exc}")
+            eprint(f"setup: failed to write {c.CLAUDE_SETTINGS_PATH}: {exc}")
             return 2
     out.append(f"Removed {removed} hook entries from {c.CLAUDE_SETTINGS_PATH}")
 
@@ -938,7 +949,7 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
                     dst.unlink()
                     sym_removed += 1
                 except OSError as exc:
-                    c.eprint(f"setup: failed to remove {dst}: {exc}")
+                    eprint(f"setup: failed to remove {dst}: {exc}")
     out.append(f"Removed {sym_removed} symlinks from {dst_dir}/")
 
     legacy = _setup_detect_legacy_snippet()
@@ -1000,7 +1011,7 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
                         "exit_code": 1,
                     }, indent=2))
                 else:
-                    c.eprint(f"setup: failed to wipe {c.APP_DIR}: {exc}")
+                    eprint(f"setup: failed to wipe {c.APP_DIR}: {exc}")
                 return 1
     else:
         out.append(
@@ -1039,7 +1050,7 @@ def _setup_dry_run(args: argparse.Namespace) -> int:
         # against an empty dict simply yields detected=False for entries (files
         # detection is independent of settings). Mirror _setup_status's pattern
         # so the user sees the same condition that would fail _setup_install.
-        c.eprint(f"setup: warning: {exc}")
+        eprint(f"setup: warning: {exc}")
         settings = {}
     detection = _setup_detect_legacy_bespoke_hooks(settings)
     sym_results = []
@@ -1238,7 +1249,7 @@ def _setup_install(args: argparse.Namespace) -> int:
 
     claude_dir = pathlib.Path.home() / ".claude"
     if not claude_dir.exists():
-        c.eprint(
+        eprint(
             f"~/.claude/ does not exist. If Claude Code isn't installed yet, "
             f"install it first. If it is installed, run `claude` once to "
             f"initialize, then re-run cctally setup."
@@ -1259,7 +1270,7 @@ def _setup_install(args: argparse.Namespace) -> int:
     try:
         settings = c._load_claude_settings()
     except c.SetupError as exc:
-        c.eprint(f"setup: {exc}")
+        eprint(f"setup: {exc}")
         return 1
 
     # ── Legacy bespoke hook detection + migration decision (spec §1, §2) ──
@@ -1304,7 +1315,7 @@ def _setup_install(args: argparse.Namespace) -> int:
             # still propagates into this code path post-extraction (§5.6 option C).
             backup_dir = c._legacy_resolve_backup_dir()
         except OSError as exc:
-            c.eprint(f"setup: cannot create migration backup dir: {exc}")
+            eprint(f"setup: cannot create migration backup dir: {exc}")
             return 1
         # Unwire BEFORE the merge so the same atomic write removes legacy
         # entries and adds cctally entries (spec §2 step 6).
@@ -1322,14 +1333,14 @@ def _setup_install(args: argparse.Namespace) -> int:
     try:
         _settings_merge_install(settings, abs_path)
     except c.SetupError as exc:
-        c.eprint(f"setup: {exc}")
+        eprint(f"setup: {exc}")
         return 1
 
     sym_results = _setup_create_symlinks(repo_root, dst_dir)
     failed = [r for r in sym_results if r.status == "failed"]
     if failed:
         for r in failed:
-            c.eprint(f"setup: symlink {r.name} failed: {r.detail}")
+            eprint(f"setup: symlink {r.name} failed: {r.detail}")
         return 1
     new_count = sum(1 for r in sym_results if r.status == "created")
     same_count = sum(1 for r in sym_results if r.status == "already")
@@ -1356,7 +1367,7 @@ def _setup_install(args: argparse.Namespace) -> int:
     try:
         c._write_claude_settings_atomic(settings)
     except OSError as exc:
-        c.eprint(f"setup: failed to write {c.CLAUDE_SETTINGS_PATH}: {exc}")
+        eprint(f"setup: failed to write {c.CLAUDE_SETTINGS_PATH}: {exc}")
         return 2
 
     # ── Post-write migration apply (spec §2 steps 6a, 6b) ──
@@ -1548,7 +1559,6 @@ def _setup_install(args: argparse.Namespace) -> int:
 
 
 def cmd_setup(args: argparse.Namespace) -> int:
-    c = _cctally()
     # Migration flags are install-mode-only. Reject combinations with
     # --status or --uninstall (per spec Section 2 mode×flag matrix). The
     # mutex group on the parser already prevents both flags being set
@@ -1560,7 +1570,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
         else None
     )
     if mig_flag and (getattr(args, "status", False) or getattr(args, "uninstall", False)):
-        c.eprint(f"setup: {mig_flag} is install-mode only")
+        eprint(f"setup: {mig_flag} is install-mode only")
         return 2
     if getattr(args, "uninstall", False):
         return _setup_uninstall(args)

package/bin/_cctally_sync_week.py

@@ -30,12 +30,27 @@ def _cctally():
     return sys.modules["cctally"]
 
 
+# === Honest imports from extracted homes ===================================
+# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
+# import from _cctally_core. `load_config` stays on the _cctally()
+# accessor per spec §3.5 monkeypatch carve-out. Z-high helpers
+# (`compute_week_cost`, `insert_cost_snapshot`) and out-of-scope
+# (`pick_week_selection`) stay on the accessor per spec §3.7.
+from _cctally_core import (
+    get_week_start_name,
+    open_db,
+    format_local_iso,
+    make_week_ref,
+    get_latest_usage_for_week,
+)
+
+
 def cmd_sync_week(args: argparse.Namespace) -> int:
     c = _cctally()
     config = c.load_config()
-    week_start_name = c.get_week_start_name(config, args.week_start_name)
+    week_start_name = get_week_start_name(config, args.week_start_name)
 
-    conn = c.open_db()
+    conn = open_db()
     try:
         selection = c.pick_week_selection(
             conn,
@@ -54,8 +69,8 @@ def cmd_sync_week(args: argparse.Namespace) -> int:
             start_iso_override=selection.start_iso_override,
             end_iso_override=selection.end_iso_override,
         )
-        week_start_at = selection.start_iso_override or c.format_local_iso(week_start, end_of_day=False)
-        week_end_at = selection.end_iso_override or c.format_local_iso(week_end, end_of_day=True)
+        week_start_at = selection.start_iso_override or format_local_iso(week_start, end_of_day=False)
+        week_end_at = selection.end_iso_override or format_local_iso(week_end, end_of_day=True)
         insert_id = c.insert_cost_snapshot(
             conn,
             week_start=week_start,
@@ -69,13 +84,13 @@ def cmd_sync_week(args: argparse.Namespace) -> int:
             project=args.project,
         )
 
-        week_ref = c.make_week_ref(
+        week_ref = make_week_ref(
             week_start_date=week_start.isoformat(),
             week_end_date=week_end.isoformat(),
             week_start_at=week_start_at,
             week_end_at=week_end_at,
         )
-        usage_row = c.get_latest_usage_for_week(conn, week_ref)
+        usage_row = get_latest_usage_for_week(conn, week_ref)
         weekly_percent = float(usage_row["weekly_percent"]) if usage_row else None
         dollars_per_percent = (
             result.cost_usd / weekly_percent if weekly_percent and weekly_percent > 0 else None

package/bin/_cctally_tui.py

@@ -202,43 +202,40 @@ def _cctally():
     return sys.modules["cctally"]
 
 
+# === Honest imports from extracted homes ===================================
+# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3.
+from _cctally_core import (
+    eprint,
+    parse_iso_datetime,
+    _now_utc,
+    open_db,
+    get_latest_usage_for_week,
+    _canonicalize_optional_iso,
+    make_week_ref,
+)
+from _lib_display_tz import (
+    format_display_dt,
+    resolve_display_tz,
+    normalize_display_tz_value,
+    _compute_display_block,
+)
+from _lib_aggregators import _aggregate_monthly
+
+
 # === Module-level back-ref shims for helpers that STAY in bin/cctally ======
 # Each shim resolves ``sys.modules['cctally'].X`` at CALL TIME (not bind
 # time), so monkeypatches on cctally's namespace propagate into the moved
-# code unchanged. Mirrors the precedent established in
-# ``bin/_cctally_record.py``, ``bin/_cctally_cache.py``,
-# ``bin/_cctally_db.py``, ``bin/_cctally_update.py``, and
-# ``bin/_cctally_dashboard.py``.
-def eprint(*args, **kwargs):
-    return sys.modules["cctally"].eprint(*args, **kwargs)
-
-
-def parse_iso_datetime(*args, **kwargs):
-    return sys.modules["cctally"].parse_iso_datetime(*args, **kwargs)
-
-
-def _now_utc(*args, **kwargs):
-    return sys.modules["cctally"]._now_utc(*args, **kwargs)
-
-
-def open_db(*args, **kwargs):
-    return sys.modules["cctally"].open_db(*args, **kwargs)
-
-
+# code unchanged. `load_config` and `get_claude_session_entries` STAY as
+# shims even though their natural homes are decentralized (_cctally_config
+# / _cctally_cache) — tests monkeypatch them via `ns["X"]` (21 sites total,
+# audited 2026-05-17); direct imports would silently bypass the patches.
+# See spec §3.5 (carve-out) and §3.7 (stays-on-shim allowlist).
 def load_config(*args, **kwargs):
     return sys.modules["cctally"].load_config(*args, **kwargs)
 
 
-def format_display_dt(*args, **kwargs):
-    return sys.modules["cctally"].format_display_dt(*args, **kwargs)
-
-
-def resolve_display_tz(*args, **kwargs):
-    return sys.modules["cctally"].resolve_display_tz(*args, **kwargs)
-
-
-def normalize_display_tz_value(*args, **kwargs):
-    return sys.modules["cctally"].normalize_display_tz_value(*args, **kwargs)
+def get_claude_session_entries(*args, **kwargs):
+    return sys.modules["cctally"].get_claude_session_entries(*args, **kwargs)
 
 
 def _resolve_display_tz_obj(*args, **kwargs):
@@ -253,10 +250,6 @@ def _apply_midweek_reset_override(*args, **kwargs):
     return sys.modules["cctally"]._apply_midweek_reset_override(*args, **kwargs)
 
 
-def _compute_display_block(*args, **kwargs):
-    return sys.modules["cctally"]._compute_display_block(*args, **kwargs)
-
-
 def _compute_forecast(*args, **kwargs):
     return sys.modules["cctally"]._compute_forecast(*args, **kwargs)
 
@@ -297,18 +290,6 @@ def _aggregate_claude_sessions(*args, **kwargs):
     return sys.modules["cctally"]._aggregate_claude_sessions(*args, **kwargs)
 
 
-def _aggregate_monthly(*args, **kwargs):
-    return sys.modules["cctally"]._aggregate_monthly(*args, **kwargs)
-
-
-def get_claude_session_entries(*args, **kwargs):
-    return sys.modules["cctally"].get_claude_session_entries(*args, **kwargs)
-
-
-def get_latest_usage_for_week(*args, **kwargs):
-    return sys.modules["cctally"].get_latest_usage_for_week(*args, **kwargs)
-
-
 def get_latest_cost_for_week(*args, **kwargs):
     return sys.modules["cctally"].get_latest_cost_for_week(*args, **kwargs)
 
@@ -317,10 +298,6 @@ def get_milestones_for_week(*args, **kwargs):
     return sys.modules["cctally"].get_milestones_for_week(*args, **kwargs)
 
 
-def _canonicalize_optional_iso(*args, **kwargs):
-    return sys.modules["cctally"]._canonicalize_optional_iso(*args, **kwargs)
-
-
 def get_recent_weeks(*args, **kwargs):
     return sys.modules["cctally"].get_recent_weeks(*args, **kwargs)
 
@@ -1030,6 +1007,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 +1089,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":
@@ -1498,7 +1532,7 @@ def _tui_build_trend(
             canon_start, canon_end = c._get_canonical_boundary_for_date(
                 conn, latest_usage["week_start_date"]
             )
-            current_ref = c.make_week_ref(
+            current_ref = make_week_ref(
                 week_start_date=latest_usage["week_start_date"],
                 week_end_date=latest_usage["week_end_date"],
                 week_start_at=canon_start,
@@ -1888,6 +1922,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 +1950,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 +2423,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 +2491,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: