cctally 1.7.2 → 1.7.4

package/bin/cctally

@@ -210,6 +210,43 @@ PUBLIC_REPO = "omrikais/cctally"
 #
 # Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md §6.3-6.4
 
+# === _cctally_core: leaf kernel (MUST load first; sibling imports
+# `from _cctally_core import …` depend on this being in sys.modules
+# before any other sibling's module body runs). Spec
+# 2026-05-17-cctally-core-kernel-extraction.md §2.5. ===
+_cctally_core = _load_sibling("_cctally_core")
+
+# Eager re-exports for the 24 kernel symbols. Preserves
+# `cctally.<name>` attribute access AND `ns["<name>"]` dict-subscript
+# paths used heavily by tests (e.g. ns["open_db"]() in 125+ sites).
+# Don't add to PEP 562 __getattr__ registry — eager binding is the
+# whole point.
+eprint = _cctally_core.eprint
+now_utc_iso = _cctally_core.now_utc_iso
+parse_iso_datetime = _cctally_core.parse_iso_datetime
+parse_date_str = _cctally_core.parse_date_str
+format_local_iso = _cctally_core.format_local_iso
+_iso_to_epoch = _cctally_core._iso_to_epoch
+_format_short_duration = _cctally_core._format_short_duration
+_normalize_week_boundary_dt = _cctally_core._normalize_week_boundary_dt
+_now_utc = _cctally_core._now_utc
+_command_as_of = _cctally_core._command_as_of
+get_week_start_name = _cctally_core.get_week_start_name
+compute_week_bounds = _cctally_core.compute_week_bounds
+WEEKDAY_MAP = _cctally_core.WEEKDAY_MAP
+DEFAULT_WEEK_START = _cctally_core.DEFAULT_WEEK_START
+ensure_dirs = _cctally_core.ensure_dirs
+_AlertsConfigError = _cctally_core._AlertsConfigError
+_ALERTS_CONFIG_VALID_KEYS = _cctally_core._ALERTS_CONFIG_VALID_KEYS
+_validate_threshold_list = _cctally_core._validate_threshold_list
+_get_alerts_config = _cctally_core._get_alerts_config
+open_db = _cctally_core.open_db
+WeekRef = _cctally_core.WeekRef
+_canonicalize_optional_iso = _cctally_core._canonicalize_optional_iso
+make_week_ref = _cctally_core.make_week_ref
+_get_latest_row_for_week = _cctally_core._get_latest_row_for_week
+get_latest_usage_for_week = _cctally_core.get_latest_usage_for_week
+
 _lib_semver = _load_sibling("_lib_semver")
 _SEMVER_NUM = _lib_semver._SEMVER_NUM
 _SEMVER_RE = _lib_semver._SEMVER_RE
@@ -2195,9 +2232,6 @@ def _migrate_legacy_data_dir() -> None:
     )
 
 
-DEFAULT_WEEK_START = "monday"
-
-
 def _get_claude_data_dirs() -> list[pathlib.Path]:
     """Return Claude Code data directories containing a projects/ subdir."""
     env_val = os.environ.get("CLAUDE_CONFIG_DIR", "").strip()
@@ -2352,79 +2386,6 @@ def _resolve_primary_model_for_block(
 
 
 
-WEEKDAY_MAP = {
-    "monday": 0,
-    "tuesday": 1,
-    "wednesday": 2,
-    "thursday": 3,
-    "friday": 4,
-    "saturday": 5,
-    "sunday": 6,
-}
-
-_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
-
-
-def eprint(*args: Any) -> None:
-    print(*args, file=sys.stderr)
-
-
-def now_utc_iso(now_utc: dt.datetime | None = None) -> str:
-    """Return a UTC-ISO 'Z'-suffixed timestamp with seconds precision.
-
-    When ``now_utc`` is omitted (the default), reads wall-clock — existing
-    behavior, preserved byte-for-byte for all existing callers. When a
-    tz-aware UTC datetime is supplied (typically via ``_command_as_of()``),
-    it is used verbatim so callers that honor ``CCTALLY_AS_OF`` get a
-    stable, caller-pinned timestamp.
-    """
-    value = now_utc if now_utc is not None else dt.datetime.now(dt.timezone.utc)
-    return (
-        value.astimezone(dt.timezone.utc)
-        .replace(microsecond=0)
-        .isoformat()
-        .replace("+00:00", "Z")
-    )
-
-
-def _iso_to_epoch(s: str) -> int:
-    """Parse an ISO-8601 timestamp and return Unix epoch seconds.
-
-    Naive ISO strings (no timezone) are treated as UTC, matching the
-    statusline-command.sh ``_iso_to_epoch`` helper. ``Z`` suffix is
-    handled by mapping to ``+00:00`` since ``datetime.fromisoformat``
-    accepts ``Z`` natively from Python 3.11.
-    """
-    s = s.strip()
-    if s.endswith("Z"):
-        s = s[:-1] + "+00:00"
-    parsed = dt.datetime.fromisoformat(s)
-    if parsed.tzinfo is None:
-        parsed = parsed.replace(tzinfo=dt.timezone.utc)
-    return int(parsed.timestamp())
-
-
-def _format_short_duration(seconds: int) -> str:
-    """Format a duration as a short top-two-units string.
-
-    Examples: ``6d 4h``, ``2h 15m``, ``2h``, ``45m``, ``30s``, ``0s``.
-    Mirrors the shape used by ``~/.claude/statusline-command.sh``'s
-    format_duration helper. Negative inputs clamp to ``0s``.
-    """
-    s = max(0, int(seconds))
-    if s >= 86400:
-        days = s // 86400
-        hours = (s % 86400) // 3600
-        return f"{days}d {hours}h" if hours else f"{days}d"
-    if s >= 3600:
-        hours = s // 3600
-        minutes = (s % 3600) // 60
-        return f"{hours}h {minutes}m" if minutes else f"{hours}h"
-    if s >= 60:
-        return f"{s // 60}m"
-    return f"{s}s"
-
-
 def _read_keychain_oauth_blob() -> str | None:
     """Read the Claude Code keychain entry on macOS via `security`.
 
@@ -2557,96 +2518,6 @@ def _select_last_known_snapshot() -> dict | None:
     }
 
 
-def ensure_dirs() -> None:
-    APP_DIR.mkdir(parents=True, exist_ok=True)
-    LOG_DIR.mkdir(parents=True, exist_ok=True)
-
-
-
-
-class _AlertsConfigError(ValueError):
-    """Raised by _get_alerts_config on invalid alerts block."""
-
-
-_ALERTS_CONFIG_VALID_KEYS = {"enabled", "weekly_thresholds", "five_hour_thresholds"}
-
-
-def _validate_threshold_list(name: str, value: object) -> "list[int]":
-    """Validate one of the alerts threshold lists.
-
-    Rules: non-empty list of plain ints (NOT bools — `bool` is an `int`
-    subclass), each in [1, 100], strictly increasing (no duplicates).
-    Error messages mention `alerts.<name>` so users can locate the
-    offending key in their config.json.
-    """
-    if not isinstance(value, list):
-        raise _AlertsConfigError(f"alerts.{name} must be a list of integers")
-    if len(value) == 0:
-        raise _AlertsConfigError(
-            f"alerts.{name} must not be empty (disable alerts via alerts.enabled=false)"
-        )
-    out: "list[int]" = []
-    prev = -1
-    seen: "set[int]" = set()
-    for item in value:
-        if not isinstance(item, int) or isinstance(item, bool):
-            raise _AlertsConfigError(
-                f"alerts.{name} items must be integers, got {type(item).__name__}: {item!r}"
-            )
-        if item < 1 or item > 100:
-            raise _AlertsConfigError(
-                f"alerts.{name} items must be in [1, 100], got {item}"
-            )
-        if item in seen:
-            raise _AlertsConfigError(
-                f"alerts.{name} contains duplicate value {item}"
-            )
-        if item <= prev:
-            raise _AlertsConfigError(
-                f"alerts.{name} must be strictly increasing, got {prev} then {item}"
-            )
-        seen.add(item)
-        prev = item
-        out.append(item)
-    return out
-
-
-def _get_alerts_config(cfg: "dict | None") -> dict:
-    """Return the validated alerts block. Raises _AlertsConfigError on failure.
-
-    Defaults applied at read time so future default-tuning takes effect
-    for users who never customized. Unknown sub-keys under `alerts.*`
-    emit a one-line warn-and-ignore (mirrors the `display.tz` posture
-    for forward compatibility).
-    """
-    block = (cfg or {}).get("alerts", {}) or {}
-    if not isinstance(block, dict):
-        raise _AlertsConfigError("alerts must be an object")
-    # warn-and-ignore unknown keys (forward compat; matches display.tz posture)
-    for k in block.keys():
-        if k not in _ALERTS_CONFIG_VALID_KEYS:
-            print(
-                f"warning: ignoring unknown alerts config key: {k}",
-                file=sys.stderr,
-            )
-    enabled = block.get("enabled", False)
-    if not isinstance(enabled, bool):
-        raise _AlertsConfigError(
-            f"alerts.enabled must be a JSON boolean, got {type(enabled).__name__}: {enabled!r}"
-        )
-    weekly = _validate_threshold_list(
-        "weekly_thresholds", block.get("weekly_thresholds", [90, 95])
-    )
-    five_hour = _validate_threshold_list(
-        "five_hour_thresholds", block.get("five_hour_thresholds", [90, 95])
-    )
-    return {
-        "enabled": enabled,
-        "weekly_thresholds": weekly,
-        "five_hour_thresholds": five_hour,
-    }
-
-
 def _normalize_alerts_enabled_value(raw: str) -> bool:
     """Normalize a CLI string value to a JSON bool. Raises ValueError on unknown.
 
@@ -2724,60 +2595,6 @@ ORIGINAL_ENTRYPOINT: "str | None" = None
 _UPDATE_WORKER: "UpdateWorker | None" = None
 
 
-def get_week_start_name(config: dict[str, Any], override: str | None = None) -> str:
-    if override:
-        name = override.strip().lower()
-    else:
-        name = str(config.get("collector", {}).get("week_start", DEFAULT_WEEK_START)).strip().lower()
-    if name not in WEEKDAY_MAP:
-        raise ValueError(
-            f"Invalid week start '{name}'. Allowed: {', '.join(WEEKDAY_MAP.keys())}"
-        )
-    return name
-
-
-def compute_week_bounds(anchor_dt: dt.datetime, week_start_name: str) -> tuple[dt.date, dt.date]:
-    start_idx = WEEKDAY_MAP[week_start_name]
-    # internal fallback: host-local intentional
-    local_anchor = anchor_dt.astimezone()
-    local_date = local_anchor.date()
-    diff = (local_date.weekday() - start_idx) % 7
-    start = local_date - dt.timedelta(days=diff)
-    end = start + dt.timedelta(days=6)
-    return start, end
-
-
-def parse_date_str(value: str, label: str) -> dt.date:
-    s = value.strip()
-    if not _DATE_RE.match(s):
-        raise ValueError(f"{label} must be YYYY-MM-DD")
-    return dt.date.fromisoformat(s)
-
-
-def parse_iso_datetime(value: str, label: str) -> dt.datetime:
-    s = value.strip()
-    if not s:
-        raise ValueError(f"{label} must be a non-empty ISO datetime")
-    try:
-        parsed = dt.datetime.fromisoformat(s.replace("Z", "+00:00"))
-    except ValueError as exc:
-        raise ValueError(f"{label} must be ISO datetime") from exc
-
-    if parsed.tzinfo is None:
-        # internal fallback: host-local intentional
-        local_tz = dt.datetime.now().astimezone().tzinfo
-        parsed = parsed.replace(tzinfo=local_tz)
-    # internal fallback: host-local intentional
-    return parsed.astimezone()
-
-
-def format_local_iso(d: dt.date, end_of_day: bool) -> str:
-    t = dt.time(23, 59, 59) if end_of_day else dt.time(0, 0, 0)
-    # internal fallback: host-local intentional
-    local_dt = dt.datetime.combine(d, t).astimezone()
-    return local_dt.isoformat(timespec="seconds")
-
-
 def _parse_iso_datetime_optional(value: Any) -> dt.datetime | None:
     if not isinstance(value, str) or not value.strip():
         return None
@@ -3652,441 +3469,6 @@ def _trend_row_recency_seconds(row: dict[str, Any]) -> float:
     return 0.0
 
 
-def _normalize_week_boundary_dt(value: dt.datetime) -> dt.datetime:
-    """
-    Normalize known Anthropic boundary jitter.
-
-    Anthropic resets are always on hour boundaries. Relative reset text
-    ("in XX hr YY min") produces minute-level drift on every capture, and
-    the UI occasionally alternates between HH:00 and HH-1:59 for the same
-    logical reset.
-
-    Canonicalization: round to the nearest hour.
-    - minutes 0..29 -> HH:00
-    - minutes 30..59 -> (HH+1):00
-    """
-    normalized = value.replace(second=0, microsecond=0)
-    if normalized.minute >= 30:
-        normalized = (normalized + dt.timedelta(hours=1)).replace(
-            minute=0,
-            second=0,
-            microsecond=0,
-        )
-    elif normalized.minute > 0:
-        normalized = normalized.replace(
-            minute=0,
-            second=0,
-            microsecond=0,
-        )
-    return normalized
-
-
-def open_db() -> sqlite3.Connection:
-    ensure_dirs()
-    conn = sqlite3.connect(DB_PATH)
-    conn.row_factory = sqlite3.Row
-    conn.execute("PRAGMA journal_mode=WAL")
-    conn.execute("PRAGMA synchronous=NORMAL")
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS weekly_usage_snapshots (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            captured_at_utc TEXT NOT NULL,
-            week_start_date TEXT NOT NULL,
-            week_end_date TEXT NOT NULL,
-            week_start_at TEXT,
-            week_end_at TEXT,
-            weekly_percent REAL NOT NULL,
-            page_url TEXT,
-            source TEXT NOT NULL DEFAULT 'userscript',
-            payload_json TEXT NOT NULL
-        )
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_usage_week_time
-        ON weekly_usage_snapshots(week_start_date, captured_at_utc DESC, id DESC)
-        """
-    )
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS weekly_cost_snapshots (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            captured_at_utc TEXT NOT NULL,
-            week_start_date TEXT NOT NULL,
-            week_end_date TEXT NOT NULL,
-            week_start_at TEXT,
-            week_end_at TEXT,
-            range_start_iso TEXT,
-            range_end_iso TEXT,
-            cost_usd REAL NOT NULL,
-            source TEXT NOT NULL DEFAULT 'cctally-range-cost',
-            mode TEXT NOT NULL DEFAULT 'auto',
-            project TEXT
-        )
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_cost_week_time
-        ON weekly_cost_snapshots(week_start_date, captured_at_utc DESC, id DESC)
-        """
-    )
-
-    add_column_if_missing(conn, "weekly_usage_snapshots", "week_start_at", "TEXT")
-    add_column_if_missing(conn, "weekly_usage_snapshots", "week_end_at", "TEXT")
-    add_column_if_missing(conn, "weekly_usage_snapshots", "five_hour_percent", "REAL")
-    add_column_if_missing(conn, "weekly_usage_snapshots", "five_hour_resets_at", "TEXT")
-    # five_hour_window_key — canonical (10-min-floored epoch) key for
-    # jitter-tolerant equality. Anthropic's status-line API jitters
-    # rate_limits.5h.resets_at by ~seconds within the same physical 5h
-    # window; joining on the raw ISO string treats each jittered fetch as
-    # a new window, escaping the monotonic clamp at cmd_record_usage.
-    # Backfill is RESUMABLE: Python's sqlite3 auto-commits DDL,
-    # so a process killed mid-loop would leave the column added with NULL
-    # keys for unprocessed rows. The gating below detects that partial
-    # state on the next open_db() call (`five_hour_resets_at IS NOT NULL
-    # AND five_hour_window_key IS NULL`) and completes the backfill, so
-    # the original Bug B can't silently re-emerge for half-migrated rows.
-    needs_5h_key_backfill = add_column_if_missing(
-        conn, "weekly_usage_snapshots", "five_hour_window_key", "INTEGER"
-    )
-    if not needs_5h_key_backfill and conn.execute(
-        "SELECT 1 FROM weekly_usage_snapshots "
-        "WHERE five_hour_resets_at IS NOT NULL "
-        "  AND five_hour_window_key IS NULL "
-        "LIMIT 1"
-    ).fetchone() is not None:
-        needs_5h_key_backfill = True
-
-    if needs_5h_key_backfill:
-        backfill_rows = conn.execute(
-            "SELECT id, five_hour_resets_at FROM weekly_usage_snapshots "
-            "WHERE five_hour_resets_at IS NOT NULL "
-            "  AND five_hour_window_key IS NULL"
-        ).fetchall()
-        for row in backfill_rows:
-            try:
-                iso = row[1]
-                d = parse_iso_datetime(iso, "five_hour_resets_at backfill")
-                epoch = int(d.timestamp())
-                key = _canonical_5h_window_key(epoch)
-                conn.execute(
-                    "UPDATE weekly_usage_snapshots "
-                    "SET five_hour_window_key = ? WHERE id = ?",
-                    (key, row[0]),
-                )
-            except (ValueError, TypeError) as exc:
-                eprint(f"[migration] skipped row {row[0]}: {exc}")
-        conn.execute(
-            "CREATE INDEX IF NOT EXISTS idx_weekly_usage_snapshots_5h_window_key "
-            "ON weekly_usage_snapshots(five_hour_window_key)"
-        )
-        conn.commit()
-
-    add_column_if_missing(conn, "weekly_cost_snapshots", "week_start_at", "TEXT")
-    add_column_if_missing(conn, "weekly_cost_snapshots", "week_end_at", "TEXT")
-    add_column_if_missing(conn, "weekly_cost_snapshots", "range_start_iso", "TEXT")
-    add_column_if_missing(conn, "weekly_cost_snapshots", "range_end_iso", "TEXT")
-
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_usage_week_start_at_time
-        ON weekly_usage_snapshots(week_start_at, captured_at_utc DESC, id DESC)
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_cost_week_start_at_time
-        ON weekly_cost_snapshots(week_start_at, captured_at_utc DESC, id DESC)
-        """
-    )
-
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS percent_milestones (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            captured_at_utc TEXT NOT NULL,
-            week_start_date TEXT NOT NULL,
-            week_end_date TEXT NOT NULL,
-            week_start_at TEXT,
-            week_end_at TEXT,
-            percent_threshold INTEGER NOT NULL,
-            cumulative_cost_usd REAL NOT NULL,
-            marginal_cost_usd REAL,
-            usage_snapshot_id INTEGER NOT NULL,
-            cost_snapshot_id INTEGER NOT NULL,
-            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 /
-    # alerts.five_hour_thresholds (and alerts.enabled is true). NULL means
-    # "alerts were disabled at the moment of crossing OR the threshold wasn't
-    # in the configured list" — never "alert delivery failed" (dispatch is
-    # best-effort and write-once forward-only). The matching ALTER for
-    # `five_hour_milestones` lives right after that table's CREATE block
-    # below, since the table doesn't exist yet at this point in `open_db()`.
-    add_column_if_missing(conn, "percent_milestones", "alerted_at", "TEXT")
-
-    # Mid-week reset events: when Anthropic advances `rate_limits.seven_day.
-    # resets_at` before the previously-declared reset actually fires (i.e.,
-    # gives the user a fresh weekly window before the old one naturally
-    # expired), we record one row here so display + cost layers can treat
-    # the effective reset moment as the old week's end AND the new week's
-    # start — preventing the API's -7d-derived new week from overlapping
-    # the old week. Inserted by cmd_record_usage on detection; read by
-    # _apply_reset_events_to_weekrefs and the cost live-recompute path.
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS week_reset_events (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            detected_at_utc        TEXT NOT NULL,
-            old_week_end_at        TEXT NOT NULL,
-            new_week_end_at        TEXT NOT NULL,
-            effective_reset_at_utc TEXT NOT NULL,
-            UNIQUE(old_week_end_at, new_week_end_at)
-        )
-        """
-    )
-    _backfill_week_reset_events(conn)
-
-    # ── five_hour_blocks (rollup, one row per API-anchored 5h block) ──
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS five_hour_blocks (
-            id                            INTEGER PRIMARY KEY AUTOINCREMENT,
-            five_hour_window_key          INTEGER NOT NULL UNIQUE,
-            five_hour_resets_at           TEXT    NOT NULL,
-            block_start_at                TEXT    NOT NULL,
-            first_observed_at_utc         TEXT    NOT NULL,
-            last_observed_at_utc          TEXT    NOT NULL,
-            final_five_hour_percent       REAL    NOT NULL,
-            seven_day_pct_at_block_start  REAL,
-            seven_day_pct_at_block_end    REAL,
-            crossed_seven_day_reset       INTEGER NOT NULL DEFAULT 0,
-            total_input_tokens            INTEGER NOT NULL DEFAULT 0,
-            total_output_tokens           INTEGER NOT NULL DEFAULT 0,
-            total_cache_create_tokens     INTEGER NOT NULL DEFAULT 0,
-            total_cache_read_tokens       INTEGER NOT NULL DEFAULT 0,
-            total_cost_usd                REAL    NOT NULL DEFAULT 0,
-            is_closed                     INTEGER NOT NULL DEFAULT 0,
-            created_at_utc                TEXT    NOT NULL,
-            last_updated_at_utc           TEXT    NOT NULL
-        )
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_five_hour_blocks_block_start
-        ON five_hour_blocks(block_start_at DESC)
-        """
-    )
-
-    # ── five_hour_milestones (per-percent crossings inside a 5h block) ──
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS five_hour_milestones (
-            id                          INTEGER PRIMARY KEY AUTOINCREMENT,
-            block_id                    INTEGER NOT NULL,
-            five_hour_window_key        INTEGER NOT NULL,
-            percent_threshold           INTEGER NOT NULL,
-            captured_at_utc             TEXT    NOT NULL,
-            usage_snapshot_id           INTEGER NOT NULL,
-            block_input_tokens          INTEGER NOT NULL DEFAULT 0,
-            block_output_tokens         INTEGER NOT NULL DEFAULT 0,
-            block_cache_create_tokens   INTEGER NOT NULL DEFAULT 0,
-            block_cache_read_tokens     INTEGER NOT NULL DEFAULT 0,
-            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),
-            FOREIGN KEY (block_id) REFERENCES five_hour_blocks(id)
-        )
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_five_hour_milestones_block
-        ON five_hour_milestones(block_id)
-        """
-    )
-
-    # alerted_at: see the matching ALTER on `percent_milestones` above for
-    # rationale. Same write-once forward-only semantics: the alert-dispatch
-    # path stamps this column on milestone-INSERT rows whose threshold
-    # matches the user's configured `alerts.five_hour_thresholds`. NULL =
-    # "alerts disabled at moment of crossing OR threshold not configured"
-    # — never "delivery failed".
-    add_column_if_missing(conn, "five_hour_milestones", "alerted_at", "TEXT")
-
-    # ── 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
-    # path. UNIQUE keyed on (five_hour_window_key, model) — durable across
-    # parent rebuilds. Live writes use DELETE WHERE five_hour_window_key = ?.
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS five_hour_block_models (
-            id                          INTEGER PRIMARY KEY AUTOINCREMENT,
-            block_id                    INTEGER NOT NULL,
-            five_hour_window_key        INTEGER NOT NULL,
-            model                       TEXT    NOT NULL,
-            input_tokens                INTEGER NOT NULL DEFAULT 0,
-            output_tokens               INTEGER NOT NULL DEFAULT 0,
-            cache_create_tokens         INTEGER NOT NULL DEFAULT 0,
-            cache_read_tokens           INTEGER NOT NULL DEFAULT 0,
-            cost_usd                    REAL    NOT NULL DEFAULT 0,
-            entry_count                 INTEGER NOT NULL DEFAULT 0,
-            UNIQUE(five_hour_window_key, model),
-            FOREIGN KEY (block_id) REFERENCES five_hour_blocks(id)
-        )
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_five_hour_block_models_block
-        ON five_hour_block_models(block_id)
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_five_hour_block_models_window
-        ON five_hour_block_models(five_hour_window_key)
-        """
-    )
-
-    # ── five_hour_block_projects (per-(block, project_path) rollup-child) ──
-    # NULL session_files.project_path → '(unknown)' sentinel at write time,
-    # keeping reconcile invariant SUM(child.cost) == parent.total intact.
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS five_hour_block_projects (
-            id                          INTEGER PRIMARY KEY AUTOINCREMENT,
-            block_id                    INTEGER NOT NULL,
-            five_hour_window_key        INTEGER NOT NULL,
-            project_path                TEXT    NOT NULL,
-            input_tokens                INTEGER NOT NULL DEFAULT 0,
-            output_tokens               INTEGER NOT NULL DEFAULT 0,
-            cache_create_tokens         INTEGER NOT NULL DEFAULT 0,
-            cache_read_tokens           INTEGER NOT NULL DEFAULT 0,
-            cost_usd                    REAL    NOT NULL DEFAULT 0,
-            entry_count                 INTEGER NOT NULL DEFAULT 0,
-            UNIQUE(five_hour_window_key, project_path),
-            FOREIGN KEY (block_id) REFERENCES five_hour_blocks(id)
-        )
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_five_hour_block_projects_block
-        ON five_hour_block_projects(block_id)
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_five_hour_block_projects_window
-        ON five_hour_block_projects(five_hour_window_key)
-        """
-    )
-
-    # Migration framework dispatcher. Replaces the prior inline gate stack
-    # (has_blocks + _migration_done) with the framework's _run_pending_-
-    # migrations entry point. See spec §2.3, §5.2 + the migration handlers
-    # decorated with @stats_migration further down in this file.
-    #
-    # MUST run BEFORE any DDL or write that touches `schema_migrations`
-    # (Codex P1 #1 fix on c3625ee + e7fdcc8): the dispatcher's fresh-install
-    # detection snapshots `schema_migrations`'s existence in sqlite_master
-    # BEFORE its own CREATE TABLE IF NOT EXISTS. Pre-creating the table
-    # earlier in open_db() (or letting `_backfill_five_hour_blocks` insert
-    # markers first) flips that snapshot to True on a brand-new DB and
-    # dead-codes the stamp-only fast path. The dispatcher is now the sole
-    # creator of `schema_migrations` + `schema_migrations_skipped`.
-    _run_pending_migrations(
-        conn, registry=_STATS_MIGRATIONS, db_label="stats.db",
-    )
-
-    # One-time historical backfill of five_hour_blocks (rollup only;
-    # milestones are forward-only per spec §4.3 / [Write-once milestones]).
-    # Idempotent via UNIQUE(five_hour_window_key) + INSERT OR IGNORE.
-    # Runs AFTER the dispatcher so `schema_migrations` exists for the
-    # marker INSERTs inside the backfill body, and so any fresh-install
-    # stamp-only path the dispatcher took above is already committed.
-    existing = conn.execute(
-        "SELECT 1 FROM five_hour_blocks LIMIT 1"
-    ).fetchone()
-    has_snapshots = conn.execute(
-        "SELECT 1 FROM weekly_usage_snapshots "
-        "WHERE five_hour_window_key IS NOT NULL "
-        "  AND five_hour_percent     IS NOT NULL "
-        "LIMIT 1"
-    ).fetchone()
-    if not existing and has_snapshots:
-        inserted = _backfill_five_hour_blocks(conn)
-        # Re-run the 5h dedup migration AFTER backfill creates parents.
-        # The dispatcher above ran while five_hour_blocks was empty, so
-        # the dedup handler no-op'd and stamped its marker. Snapshot
-        # keys can carry jitter beyond the 600s canonical floor (the
-        # 003_* migration handles up to 1800s grouping), so the
-        # backfill's `DISTINCT five_hour_window_key` over those keys
-        # can produce duplicate parent rows for one physical 5h
-        # window. Without this re-invocation those duplicates persist
-        # forever — the marker says it ran. Handler owns its own
-        # BEGIN/COMMIT and is idempotent (no groups → no-op).
-        #
-        # Honor `db skip` here as well: if the operator marked 003 as
-        # skipped (e.g., poison pill on their machine), we must NOT
-        # back-door run the handler. Duplicates introduced by the
-        # backfill will persist until they `db unskip` — which is the
-        # explicit choice the skip records. Failure path mirrors the
-        # dispatcher's contract: route through _log_migration_error so
-        # the next interactive command renders the banner, and clear
-        # the log entry on success so the banner auto-dismisses.
-        if inserted > 0:
-            target_name = "003_merge_5h_block_duplicates_v1"
-            try:
-                skipped = {
-                    row[0] for row in conn.execute(
-                        "SELECT name FROM schema_migrations_skipped"
-                    ).fetchall()
-                }
-            except sqlite3.OperationalError:
-                skipped = set()
-            if target_name not in skipped:
-                for _m in _STATS_MIGRATIONS:
-                    if _m.name == target_name:
-                        qualified = f"stats.db:{target_name}"
-                        try:
-                            _m.handler(conn)
-                            _clear_migration_error_log_entries(qualified)
-                        except Exception as exc:
-                            _log_migration_error(
-                                name=qualified,
-                                exc=exc,
-                                tb=traceback.format_exc(),
-                            )
-                            eprint(f"[migration {qualified}] failed: {exc}")
-                        break
-
-    conn.commit()
-    return conn
-
-
-
 @dataclass
 class CacheModelBreakdown:
     model_name: str
@@ -4589,85 +3971,6 @@ def compute_week_cost(
     )
 
 
-def _canonicalize_optional_iso(value: str | None, label: str) -> str | None:
-    if value is None:
-        return None
-    s = value.strip()
-    if s == "":
-        return None
-    normalized = _normalize_week_boundary_dt(parse_iso_datetime(s, label)).astimezone(dt.timezone.utc)
-    return normalized.isoformat(timespec="seconds")
-
-
-@dataclass(frozen=True)
-class WeekRef:
-    week_start: dt.date
-    week_end: dt.date | None
-    week_start_at: str | None
-    week_end_at: str | None
-    key: str
-
-
-def make_week_ref(
-    week_start_date: str,
-    week_end_date: str | None,
-    week_start_at: str | None = None,
-    week_end_at: str | None = None,
-) -> WeekRef:
-    week_start = dt.date.fromisoformat(week_start_date)
-    week_end = dt.date.fromisoformat(week_end_date) if week_end_date else None
-    start_at = _canonicalize_optional_iso(week_start_at, "weekStartAt")
-    end_at = _canonicalize_optional_iso(week_end_at, "weekEndAt")
-
-    return WeekRef(
-        week_start=week_start,
-        week_end=week_end,
-        week_start_at=start_at,
-        week_end_at=end_at,
-        key=week_start.isoformat(),
-    )
-
-
-def _get_latest_row_for_week(
-    conn: sqlite3.Connection,
-    table_name: str,
-    week_ref: WeekRef,
-    as_of_utc: str | None = None,
-) -> sqlite3.Row | None:
-    if as_of_utc is None:
-        return conn.execute(
-            f"""
-            SELECT *
-            FROM {table_name}
-            WHERE week_start_date = ?
-            ORDER BY captured_at_utc DESC, id DESC
-            LIMIT 1
-            """,
-            (week_ref.week_start.isoformat(),),
-        ).fetchone()
-    return conn.execute(
-        f"""
-        SELECT *
-        FROM {table_name}
-        WHERE week_start_date = ?
-          AND captured_at_utc <= ?
-        ORDER BY captured_at_utc DESC, id DESC
-        LIMIT 1
-        """,
-        (week_ref.week_start.isoformat(), as_of_utc),
-    ).fetchone()
-
-
-def get_latest_usage_for_week(
-    conn: sqlite3.Connection,
-    week_ref: WeekRef,
-    as_of_utc: str | None = None,
-) -> sqlite3.Row | None:
-    return _get_latest_row_for_week(
-        conn, "weekly_usage_snapshots", week_ref, as_of_utc=as_of_utc,
-    )
-
-
 def get_latest_cost_for_week(conn: sqlite3.Connection, week_ref: WeekRef) -> sqlite3.Row | None:
     return _get_latest_row_for_week(conn, "weekly_cost_snapshots", week_ref)
 
@@ -5484,6 +4787,18 @@ def _load_recorded_five_hour_windows(
                     else:
                         d = d.astimezone(dt.timezone.utc)
                     credit_moments.append(d)
+                # Issue #44: the inner-loop break below latches onto the
+                # first credit in [next_bs, rs]. With two credits inside
+                # the same pre-credit canonical 5h window, the wrong one
+                # (the later one) wins when SQLite returns rows in
+                # insertion order rather than time order — collapsing
+                # two distinct truncated anchors onto the same floored
+                # bucket and silently dropping one via override-map
+                # overwrite. Sort once so the break consistently picks
+                # the EARLIEST credit, which is the one that actually
+                # ended the earlier block (its floor equals the next
+                # block's block_start_at by construction).
+                credit_moments.sort()
             except sqlite3.DatabaseError:
                 credit_moments = []
     except (sqlite3.DatabaseError, OSError):
@@ -6358,46 +5673,6 @@ def cmd_codex_session(args: argparse.Namespace) -> int:
     return 0
 
 
-def _command_as_of() -> dt.datetime:
-    """Testing hook: CCTALLY_AS_OF env var overrides wall-clock `now` for
-    time-dependent commands. Shared by cmd_project, cmd_weekly,
-    cmd_cache_report, cmd_codex_weekly, cmd_diff (and any future
-    time-dependent command). Format: ISO-8601 with Z or explicit tz offset.
-    """
-    override = os.environ.get("CCTALLY_AS_OF")
-    if override:
-        override = override.strip()
-        if override.endswith("Z"):
-            override = override[:-1] + "+00:00"
-        return dt.datetime.fromisoformat(override).astimezone(dt.timezone.utc)
-    return dt.datetime.now(dt.timezone.utc)
-
-
-def _now_utc() -> dt.datetime:
-    """UTC now, with CCTALLY_AS_OF env override for fixture-stability.
-
-    Single time source for the `update` subcommand and its supporting
-    state machine (TTL gates, ``remind_after.until_utc`` comparisons,
-    log timestamps, install-method detection cache). Mirrors the
-    documented CCTALLY_AS_OF precedent (see CLAUDE.md — `project` has
-    a hidden `CCTALLY_AS_OF` env hook, and `_command_as_of` /
-    `_share_now_utc` reuse it for `weekly`/`forecast`/share-render).
-    Accepts ISO-8601 with `Z` or explicit offset; result is always
-    tz-aware UTC.
-
-    Raises ValueError on malformed CCTALLY_AS_OF — deliberate fail-loud
-    for the dev hook so fixture authors notice typos immediately rather
-    than silently falling back to wall-clock time.
-    """
-    override = os.environ.get("CCTALLY_AS_OF")
-    if override:
-        override = override.strip()
-        if override.endswith("Z"):
-            override = override[:-1] + "+00:00"
-        return dt.datetime.fromisoformat(override).astimezone(dt.timezone.utc)
-    return dt.datetime.now(dt.timezone.utc)
-
-
 def _load_week_snapshots(
     since: dt.datetime, until: dt.datetime
 ) -> dict[dt.datetime, float]:
@@ -7632,6 +6907,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 +8740,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 +8773,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 +8891,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 +8971,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 +8985,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 +9042,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 +13231,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),