cctally 1.20.1 → 1.20.2

package/CHANGELOG.md

@@ -5,6 +5,11 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctally",
-  "version": "1.20.1",
+  "version": "1.20.2",
   "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": {