cctally 1.20.1 → 1.20.3

package/CHANGELOG.md

@@ -5,6 +5,16 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.20.3] - 2026-05-28
+
+### Fixed
+- **The dashboard's Blocks panel no longer renders the just-started active block with a `~` heuristic marker, and the previous block no longer silently disappears from the panel ~20 minutes after a 5h reset.** Both symptoms came from the same root cause in `_select_non_overlapping_recorded_windows`: when two genuinely-adjacent canonical 5h windows had `resets_at` values whose 10-minute-floored keys landed less than 5h apart (e.g. OLD `R=09:00:01Z` → floor `09:00`, NEW `R=13:59:59Z` → floor `13:50` — a 4h 50m floored-distance for a real block-pair with a 2-second sub-second overlap on the boundary), the weighted-interval-scheduling DP treated them as conflicting and dropped the lighter-weighted one. At `t≈0` after a reset that meant the NEW canonical window vanished from the selector's output, so the dashboard's Blocks panel partitioned NEW-window entries into the heuristic leftover bucket and rendered them with `anchor='heuristic'` and a `_floor_to_hour` `start_at` (the `~` chip in `BlocksPanel.tsx:33-34`); ~20 minutes later, once the NEW window's snapshot count caught up, the DP would flip and drop OLD instead, making the previous block silently disappear. CLI `cctally blocks --active` was unaffected (it queries `five_hour_blocks` directly with `is_closed=0`, bypassing this scheduler). Fix: any item carrying the canonical-source weight overlay (`_CANONICAL_WEIGHT_THRESHOLD = 1000`) is force-restored to the result set if the DP dropped it — `maybe_update_five_hour_block` already deduplicated via `_canonical_5h_window_key` pre-insert, so two canonical rows are by definition non-overlapping physically and don't need re-arbitration on a floor-distance check. The DP still runs over the full item set (canonical + raw), so a non-canonical phantom R adjacent to a canonical anchor in a different floor bucket continues to lose by weight comparison; the bypass only restores canonical items, never adds back a raw-only phantom. (#116)
+
+## [1.20.2] - 2026-05-28
+
+### Fixed
+- **`cctally record-usage` now rejects implausibly-dated `--resets-at` epochs before they can poison the SQLite stats history, and refuses to charge already-expired 5h windows against the previous block.** A real 366-day-off statusline payload silently wrote a phantom-year row that displaced subsequent weeks in `cctally report` / `cctally-dollar-per-percent`. The new guard validates both arguments before any `datetime.fromtimestamp()` call (so ms-epochs, year-off bugs, and negative epochs reject gracefully instead of crashing): `--resets-at ∈ [now − 30d, now + 8d]` exits 2 on miss (preserving the documented "manually replay a missed snapshot" path within 30d), and `--five-hour-resets-at ∈ [now − 10m, now + 6h]` drops the 5h fields and continues with the weekly snapshot on miss (so a stale-5h replay still writes its weekly row). The 10-minute past slack matches `_FIVE_HOUR_JITTER_FLOOR_SECONDS` — wide enough for boundary jitter / clock skew, tight enough that lagged status-line responses around a 5h rollover can no longer pollute the prior block's `_compute_block_totals` with entries that belong to the new window. The refresh-layer wrapper (`_refresh_usage_inproc`) surfaces guard misses as `status="record_failed"` so the dashboard / CLI don't silently report success on a dropped payload. (#112)
+
 ## [1.20.1] - 2026-05-28
 
 ### Fixed

package/bin/_cctally_record.py

@@ -171,6 +171,7 @@ from _cctally_core import (
     make_week_ref,
     _get_alerts_config,
     _AlertsConfigError,
+    _command_as_of,
 )
 from _lib_five_hour import _canonical_5h_window_key
 from _lib_pricing import _calculate_entry_cost
@@ -300,6 +301,35 @@ def _hook_tick_make_mock_refresh(*args, **kwargs):
 # and no dependency on cctally's module instance.
 _PERCENT_NORMALIZE_DECIMALS = 10
 
+# Plausibility band for --resets-at / --five-hour-resets-at (issue #112).
+# Out-of-band epochs are guarded at cmd_record_usage ingress before any
+# datetime.fromtimestamp() call, so absurd values (ms-epochs, year-off
+# bugs) can't crash the call or stamp phantom-week rows.
+#
+# The two bands are deliberately asymmetric and reject differently:
+#
+#   --resets-at: 30d past / 8d future. Wide past slack preserves the
+#       documented "manually replay a missed snapshot" use case
+#       (docs/commands/record-usage.md). Out-of-band → return 2
+#       (entire call rejected, no weekly row written).
+#
+#   --five-hour-resets-at: 10m past / 6h future. Tight past slack is
+#       intentional: maybe_update_five_hour_block computes
+#       _compute_block_totals(block_start_at, captured_at_dt) where
+#       captured_at_dt ≈ now and block_start_at = resets_at - 5h, so
+#       accepting an already-expired 5h resets_at pollutes the prior
+#       block with session_entries that belong to the NEXT block. 10m
+#       matches _FIVE_HOUR_JITTER_FLOOR_SECONDS (the canonical-window-key
+#       jitter floor) — enough for boundary jitter / clock skew, not
+#       enough for cross-block pollution. Out-of-band → drop the 5h
+#       fields and continue (the weekly snapshot still writes), so a
+#       manual replay with stale 5h flags doesn't fail-close on a
+#       documented recovery path.
+_RECORD_USAGE_WEEK_PAST_SLACK_S = 30 * 86400
+_RECORD_USAGE_WEEK_FUTURE_BAND_S = 8 * 86400
+_RECORD_USAGE_5H_PAST_SLACK_S = 600  # 10 min; matches _FIVE_HOUR_JITTER_FLOOR_SECONDS
+_RECORD_USAGE_5H_FUTURE_BAND_S = 6 * 3600
+
 
 # One-shot guard so a misbehaving caller passing a non-int
 # fiveHourWindowKey doesn't spam the log on every insert. Set on first
@@ -1273,6 +1303,24 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
     weekly_percent = _normalize_percent(args.percent)
     resets_at = int(args.resets_at)
 
+    # Plausibility guard (issue #112). Band-check epochs BEFORE any
+    # dt.datetime.fromtimestamp() call so absurd values (ms-epoch,
+    # year-off bugs, negative) reject gracefully instead of raising
+    # OverflowError. Reject path returns exit 2 so
+    # _refresh_usage_inproc maps it to status="record_failed" instead
+    # of silently reporting success on a dropped payload.
+    now_dt = _command_as_of()
+    now_epoch = int(now_dt.timestamp())
+    if not (now_epoch - _RECORD_USAGE_WEEK_PAST_SLACK_S
+            <= resets_at
+            <= now_epoch + _RECORD_USAGE_WEEK_FUTURE_BAND_S):
+        eprint(
+            f"[record-usage] rejecting --resets-at={resets_at}: outside "
+            f"plausibility band [now-30d, now+8d]; "
+            f"now={now_epoch} ({now_dt.isoformat()}). No row written."
+        )
+        return 2
+
     five_hour_percent: float | None = None
     five_hour_resets_at_str: str | None = None
     five_hour_window_key: int | None = None
@@ -1281,9 +1329,35 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
         five_hour_percent = _normalize_percent(args.five_hour_percent)
     if args.five_hour_resets_at is not None:
         five_hour_resets_at_epoch = int(args.five_hour_resets_at)
-        five_hour_resets_at_str = dt.datetime.fromtimestamp(
-            five_hour_resets_at_epoch, tz=dt.timezone.utc
-        ).isoformat(timespec="seconds")
+        # Band-check BEFORE fromtimestamp (issue #112).
+        #
+        # Out-of-band 5h is non-fatal: drop the 5h fields and continue
+        # so the weekly snapshot still writes. Two motivating cases:
+        #   (a) docs' manual-replay path (record-usage.md) emits the
+        #       original status-line args verbatim, including stale 5h
+        #       flags — rejecting the whole call there contradicts the
+        #       wider 30d weekly past slack.
+        #   (b) An already-expired 5h resets_at would pollute the prior
+        #       block's totals (block_start_at = resets_at - 5h →
+        #       _compute_block_totals charges entries past the real
+        #       reset to this block). Dropping the 5h portion here
+        #       skips maybe_update_five_hour_block entirely.
+        if not (now_epoch - _RECORD_USAGE_5H_PAST_SLACK_S
+                <= five_hour_resets_at_epoch
+                <= now_epoch + _RECORD_USAGE_5H_FUTURE_BAND_S):
+            eprint(
+                f"[record-usage] dropping --five-hour-resets-at="
+                f"{five_hour_resets_at_epoch}: outside plausibility band "
+                f"[now-10m, now+6h]; now={now_epoch} "
+                f"({now_dt.isoformat()}). Weekly snapshot still written; "
+                f"5h fields will be NULL."
+            )
+            five_hour_percent = None
+            five_hour_resets_at_epoch = None
+        else:
+            five_hour_resets_at_str = dt.datetime.fromtimestamp(
+                five_hour_resets_at_epoch, tz=dt.timezone.utc
+            ).isoformat(timespec="seconds")
         # five_hour_window_key derivation is deferred until after open_db()
         # so we can pass the most-recent stored sample as the prior anchor.
         # See _canonical_5h_window_key docstring (spec invariant #3:
@@ -1406,7 +1480,12 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                     prior["week_end_at"], "record.prior"
                 )
                 prior_pct = prior["weekly_percent"]
-                now_utc = dt.datetime.now(dt.timezone.utc)
+                # Use _command_as_of() so CCTALLY_AS_OF pins the predicate
+                # for tests (no behavior change in production — falls back
+                # to wall-clock when the env hook is unset). This makes
+                # mid-week-reset detection deterministic against fixtures
+                # whose `prior_end` is a fixed historical instant.
+                now_utc = _command_as_of()
                 if prior_end_canon and prior_end_canon != cur_end_canon:
                     prior_end_dt = parse_iso_datetime(prior_end_canon, "prior.week_end_at")
                     # Fire only when (a) prior window was still in the FUTURE

package/bin/cctally

@@ -3951,11 +3951,21 @@ def _resolve_block_selector(
     return dict(row) if row else None
 
 
+# Items in `_select_non_overlapping_recorded_windows` whose weight is
+# >= this threshold are treated as canonical (sourced from
+# ``five_hour_blocks``) and bypass the 5h non-overlap constraint. Must
+# stay in sync with the ``counts[snapped] = counts.get(snapped, 0) + 1000``
+# overlay in ``_load_recorded_five_hour_windows`` — same constant, same
+# meaning. Issue #116.
+_CANONICAL_WEIGHT_THRESHOLD = 1000
+
+
 def _select_non_overlapping_recorded_windows(
     items: list[tuple[dt.datetime, int]],
 ) -> list[dt.datetime]:
     """Pick the max-weight subset of recorded ``R`` values that respect
-    the 5h non-overlap constraint.
+    the 5h non-overlap constraint, with canonical anchors guaranteed
+    to survive.
 
     Anthropic 5h windows cannot truly overlap: the next window only
     opens once the previous one resets, so consecutive real ``R``
@@ -3968,6 +3978,23 @@ def _select_non_overlapping_recorded_windows(
     snapshots: the subset that maximizes total support wins. Tie-break
     in the take branch favors including more ``R`` values.
 
+    Canonical bypass (issue #116): any item with weight at least
+    ``_CANONICAL_WEIGHT_THRESHOLD`` came from the authoritative
+    ``five_hour_blocks`` rollup (the caller overlays at +1000).
+    ``maybe_update_five_hour_block`` already deduped via
+    ``_canonical_5h_window_key`` pre-insert, so two canonical rows are
+    by definition non-overlapping physically — they only appear "in
+    conflict" here when their 10-min-floored keys land less than
+    ``BLOCK_DURATION`` apart, which happens at every real reset
+    boundary when Anthropic's ``resets_at`` jitters sub-second across
+    the boundary (e.g. OLD ``R=09:00:01Z`` floors to ``09:00``, NEW
+    ``R=13:59:59Z`` floors to ``13:50`` — 4h 50m floored-distance for
+    a genuinely-adjacent block pair). The DP still runs over the full
+    item set so non-canonical phantoms next to a canonical anchor get
+    dropped by weight comparison; the canonical-bypass only force-
+    restores canonical items the DP dropped, never adds back a raw-
+    only phantom.
+
     Args:
       items: ``(R, support_count)`` pairs.
 
@@ -4012,6 +4039,11 @@ def _select_non_overlapping_recorded_windows(
         else:
             i -= 1
     chosen.reverse()
+    # Canonical bypass: force-restore any canonical-weight anchor the DP
+    # dropped (issue #116). Keep the result sorted ascending.
+    canonical = {R for R, w in items_sorted if w >= _CANONICAL_WEIGHT_THRESHOLD}
+    if canonical and not canonical.issubset(chosen):
+        return sorted(set(chosen) | canonical)
     return chosen
 
 
@@ -4297,7 +4329,7 @@ def _load_recorded_five_hour_windows(
         # (only credit-truncated entries land there).
         if snapped in block_start_overrides:
             truncated_anchors.add(snapped)
-        counts[snapped] = counts.get(snapped, 0) + 1000
+        counts[snapped] = counts.get(snapped, 0) + _CANONICAL_WEIGHT_THRESHOLD
 
     non_truncated_items = [
         (a, w) for a, w in counts.items() if a not in truncated_anchors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctally",
-  "version": "1.20.1",
+  "version": "1.20.3",
   "description": "Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.",
   "homepage": "https://github.com/omrikais/cctally",
   "repository": {