cctally 1.10.1 → 1.10.2

package/CHANGELOG.md

@@ -5,6 +5,11 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.10.2] - 2026-05-21
+
+### Fixed
+- `blocks` panel + CLI no longer renders a phantom ACTIVE heuristic block when a canonical 5h reset doesn't fall on a 10-minute boundary. The legacy partition predicate used `[R_floored - 5h, R_floored)` as the bucket interval, so floor-band entries — session timestamps inside `[floor(R), R)` (e.g. the 09:30–09:39:59 UTC band for a 09:39:59 reset) — fell into neither the preceding nor the following recorded bucket, dropped to `leftover`, and became a phantom heuristic block running `+5h` from `floor_to_hour(first_leftover_entry)`. With current-time activity in the band, that phantom block was `is_active=True` and overlapped the real canonical ACTIVE block, surfacing as TWO ACTIVE rows in `cctally blocks` and a `~HH:00` heuristic plus a `HH:40` recorded entry in the dashboard `/api/data` payload. The fix routes both the entry partition AND the recorded `Block` construction (start_time / end_time / is_active / burn / projection) through a single `_exact_interval(R)` helper that returns the canonical `(block_start_at, five_hour_resets_at)` from `five_hour_blocks` (jitter intact); `_load_recorded_five_hour_windows` grows a third return — `canonical_intervals: {R_floored → (bs_utc, rs_utc)}` — plumbed through `build_blocks_view`, `cmd_blocks`, `_dashboard_build_blocks_view`, and the `/api/block/:start_at` handler. Raw-only anchors (no canonical `five_hour_blocks` row) fall back to the legacy `(R - 5h, R)` shape. Credit-truncated anchors compose with the new path: the truncation rewrites the upper bound in-place inside `canonical_intervals` while preserving the override-supplied `bs`. Regression: new `tests/fixtures/blocks/floor-band-trap/` scenario (canonical reset at `T:39:59 UTC` with 8 dense entries in the trap band) locks the kernel behavior; new `test_block_detail_floor_band_trap_returns_exact_window` in `tests/test_dashboard_api_block.py` covers the panel ↔ detail consistency surface (clicking a block whose canonical reset is off the 10-min boundary returns 200 with the exact `bs` window instead of 404'ing against the floored bs). ([#76](https://github.com/omrikais/cctally-dev/issues/76))
+
 ## [1.10.1] - 2026-05-20
 
 ### Fixed

package/bin/_cctally_dashboard.py

@@ -2330,8 +2330,8 @@ def _dashboard_build_blocks_view(conn: "sqlite3.Connection",
     entries = get_entries(fetch_start, fetch_end, skip_sync=skip_sync)
     entries = [e for e in entries if week_start_at <= e.timestamp < week_end_at]
 
-    recorded_windows, block_start_overrides = _load_recorded_five_hour_windows(
-        fetch_start, fetch_end,
+    recorded_windows, block_start_overrides, canonical_intervals = (
+        _load_recorded_five_hour_windows(fetch_start, fetch_end)
     )
     c = _cctally()
     return c.build_blocks_view(
@@ -2339,6 +2339,7 @@ def _dashboard_build_blocks_view(conn: "sqlite3.Connection",
         now_utc=now_utc,
         recorded_windows=recorded_windows,
         block_start_overrides=block_start_overrides,
+        canonical_intervals=canonical_intervals,
         range_start=week_start_at,
         range_end=week_end_at,
         display_tz=display_tz,
@@ -5997,7 +5998,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             now_utc = _command_as_of()
             # Recorded-windows lookup widens by one block on each side so
             # a recorded reset just outside the bounds can still anchor.
-            recorded_windows, block_start_overrides = (
+            recorded_windows, block_start_overrides, canonical_intervals = (
                 _load_recorded_five_hour_windows(
                     start_at - BLOCK_DURATION, end_at + BLOCK_DURATION,
                 )
@@ -6020,6 +6021,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 entries_in_window, mode="auto",
                 recorded_windows=recorded_windows,
                 block_start_overrides=block_start_overrides,
+                canonical_intervals=canonical_intervals,
                 now=now_utc,
             )
             target = next(

package/bin/_lib_blocks.py

@@ -95,6 +95,9 @@ def _group_entries_into_blocks(
     *,
     recorded_windows: list[dt.datetime] | None = None,
     block_start_overrides: dict[dt.datetime, dt.datetime] | None = None,
+    canonical_intervals: dict[
+        dt.datetime, tuple[dt.datetime, dt.datetime]
+    ] | None = None,
     now: dt.datetime | None = None,
 ) -> list[Block]:
     """Group sorted UsageEntry objects into 5-hour blocks with gap detection.
@@ -103,21 +106,29 @@ def _group_entries_into_blocks(
     The last block is marked active if now < block_start + 5h.
 
     When `recorded_windows` is non-empty, entries whose timestamp falls in
-    [R - BLOCK_DURATION, R) for some R in recorded_windows are partitioned
-    into per-R buckets and built as 'recorded' blocks. Leftover entries
-    run through the existing gap-detection heuristic (anchor='heuristic').
+    the exact ``[bs, rs)`` interval of each accepted anchor are
+    partitioned into per-R buckets and built as 'recorded' blocks.
+    Leftover entries run through the existing gap-detection heuristic
+    (anchor='heuristic').
+
+    `canonical_intervals` (issue #76): an optional
+    ``{R_floored → (bs_utc, rs_utc)}`` map carrying the EXACT
+    ``(block_start_at, five_hour_resets_at)`` per accepted anchor. Drives
+    both the partition predicate AND Phase 1.5 ``Block`` construction
+    so floor-band entries (timestamps inside ``[floor(R), R)`` for a
+    canonical reset that doesn't fall on a 10-minute boundary) land in
+    the right bucket and the rendered window matches Anthropic's actual
+    interval. Anchors missing from the map fall back to ``(R - 5h, R)``
+    (the legacy floored shape) — preserves raw-only / pre-rollup
+    history behavior.
 
     `block_start_overrides` (v1.7.2 round-5 / Bug J): an optional
-    `{R → block_start_at}` map. When present for a given R, the
-    recorded block's displayed ``start_time`` becomes the override
-    instead of the default ``R - BLOCK_DURATION``. Used by
-    ``_load_recorded_five_hour_windows`` to preserve the real
-    ``five_hour_blocks.block_start_at`` for credit-truncated windows
-    (an in-place credit shortens the prior 5h block's effective end
-    to the credit moment, but the block's API-derived START is
-    unchanged — without an override the renderer would compute
-    ``start = truncated_R - 5h`` which is hours before the real start
-    and confuses the user with an off-by-hours window header).
+    ``{R → block_start_at}`` map. Provides the same override semantics
+    for callers that don't pass ``canonical_intervals``. When BOTH are
+    present, ``canonical_intervals`` wins (the credit-truncation path
+    in ``_load_recorded_five_hour_windows`` writes a unified entry
+    into ``canonical_intervals`` already carrying the override-supplied
+    ``bs`` and the truncated ``rs``).
 
     `now` pins the current instant (typically via `_command_as_of()`). When
     omitted, falls back to wall clock so existing callers are unaffected.
@@ -131,31 +142,44 @@ def _group_entries_into_blocks(
 
     recorded_windows = sorted(recorded_windows or [])
     block_start_overrides = block_start_overrides or {}
+    canonical_intervals = canonical_intervals or {}
+
+    # Single source of truth for the (bs, rs) interval of each accepted
+    # anchor — shared by the partition predicate below AND Phase 1.5
+    # block construction. issue #76: a 10-min-floored R as a partition
+    # boundary trapped floor-band entries into a phantom heuristic
+    # block whenever R was off the 10-min boundary; routing both
+    # surfaces through this helper keeps them consistent.
+    def _exact_interval(R: dt.datetime) -> tuple[dt.datetime, dt.datetime]:
+        if R in canonical_intervals:
+            return canonical_intervals[R]
+        bs = block_start_overrides.get(R, R - BLOCK_DURATION)
+        return (bs, R)
 
     # ── Partition entries by recorded windows ──────────────────────────
     # For each R in recorded_windows, entries whose timestamp falls in
-    # [override_start_or_R-5h, R) go into recorded_buckets[R]. Everything
-    # else (gaps between recorded windows, or fully outside any window)
-    # drops into `leftover` and runs through the existing heuristic
-    # grouper.
-    #
-    # Why override_start_or_R-5h, not always R-5h: a credit-truncated
-    # canonical block has R = effective_reset_at_utc (e.g. 17:58Z) but
-    # its real ``block_start_at`` is unchanged (e.g. 15:50Z). Using
-    # `R - 5h` as the partition floor would pull entries from earlier
-    # blocks (e.g. 12:58-15:50Z range) into the truncated bucket. The
-    # override keeps the real start so each entry lands in the bucket
-    # whose API-defined interval actually contains it.
+    # [bs, rs) (the EXACT canonical interval, NOT the 10-min-floored
+    # shape) go into recorded_buckets[R]. Everything else (gaps between
+    # recorded windows, or fully outside any window) drops into
+    # `leftover` and runs through the existing heuristic grouper.
     recorded_buckets: dict[dt.datetime, list[UsageEntry]] = {
         R: [] for R in recorded_windows
     }
     leftover: list[UsageEntry] = []
+    # Sort the (interval, R) pairs by rs so bisect_right(rs_keys, ts)
+    # locates the candidate window in O(log n) per entry.
+    sorted_intervals: list[
+        tuple[tuple[dt.datetime, dt.datetime], dt.datetime]
+    ] = sorted(
+        [(_exact_interval(R), R) for R in recorded_windows],
+        key=lambda item: item[0][1],
+    )
+    rs_keys = [iv[0][1] for iv in sorted_intervals]
     for entry in entries_sorted:
-        idx = bisect.bisect_right(recorded_windows, entry.timestamp)
-        if idx < len(recorded_windows):
-            R = recorded_windows[idx]
-            bucket_start = block_start_overrides.get(R, R - BLOCK_DURATION)
-            if bucket_start <= entry.timestamp:
+        idx = bisect.bisect_right(rs_keys, entry.timestamp)
+        if idx < len(sorted_intervals):
+            (bs, rs), R = sorted_intervals[idx]
+            if bs <= entry.timestamp < rs:
                 recorded_buckets[R].append(entry)
                 continue
         leftover.append(entry)
@@ -192,17 +216,22 @@ def _group_entries_into_blocks(
 
     # Clamp each raw_block's end so it cannot overlap a later recorded
     # window. Entries in `leftover` are by construction earlier than the
-    # next recorded R - 5h boundary, so the heuristic block belongs to a
-    # PREVIOUS 5h window that ended no later than that boundary. Without
-    # this clamp, the +5h heuristic span can cross into the recorded
-    # window and produce two simultaneously-active rows.
+    # next recorded window's real ``bs``, so the heuristic block belongs
+    # to a PREVIOUS 5h window that ended no later than that boundary.
+    # Without this clamp, the +5h heuristic span can cross into the
+    # recorded window and produce two simultaneously-active rows.
+    # issue #76: use the EXACT ``bs`` from ``_exact_interval`` so the
+    # clamp matches the partition predicate above (using a floored
+    # ``R - 5h`` would leave a sliver of overlap whenever bs sits in
+    # the 10-min floor band).
     if recorded_windows:
         for rb in raw_blocks:
             idx = bisect.bisect_right(recorded_windows, rb["start"])
             if idx < len(recorded_windows):
-                next_R_start = recorded_windows[idx] - BLOCK_DURATION
-                if rb["start"] < next_R_start < rb["end"]:
-                    rb["end"] = next_R_start
+                next_R = recorded_windows[idx]
+                next_bs, _next_rs = _exact_interval(next_R)
+                if rb["start"] < next_bs < rb["end"]:
+                    rb["end"] = next_bs
 
     # Track the "actual first entry timestamp" for each block so Phase 3
     # can compute gap ends the same way the legacy interleaved code did
@@ -210,18 +239,19 @@ def _group_entries_into_blocks(
     # floor-to-hour window start). Maps id(block) -> actual first ts.
     first_entry_ts_by_block: dict[int, dt.datetime] = {}
 
-    # Phase 1.5: Build recorded Block objects from non-empty buckets
+    # Phase 1.5: Build recorded Block objects from non-empty buckets.
+    # issue #76: ``start_time`` / ``end_time`` come from the SAME
+    # ``_exact_interval(R)`` that drives the partition predicate above.
+    # Without this, a canonical reset off the 10-min boundary would
+    # render with the floored window (off by up to 9m59s) and
+    # ``is_active`` / burn / projection would compute against the
+    # wrong endpoints, even though the partition was correct.
     recorded_block_objs: list[Block] = []
     for R in recorded_windows:
         bucket = recorded_buckets[R]
         if not bucket:
             continue
-        # Display start: override when present (credit-truncated
-        # canonical blocks need their real block_start_at so the
-        # rendered window header matches Anthropic's actual interval);
-        # default to R - BLOCK_DURATION for normal canonical anchors.
-        start_time = block_start_overrides.get(R, R - BLOCK_DURATION)
-        end_time = R
+        start_time, end_time = _exact_interval(R)
         bucket_sorted = sorted(bucket, key=lambda e: e.timestamp)
         blk = _build_activity_block(
             bucket_sorted, start_time, end_time, now, mode,

package/bin/_lib_view_models.py

@@ -1146,6 +1146,7 @@ def build_blocks_view(
     now_utc,
     recorded_windows=None,
     block_start_overrides=None,
+    canonical_intervals=None,
     range_start=None,
     range_end=None,
     display_tz=None,
@@ -1191,6 +1192,7 @@ def build_blocks_view(
         mode=mode,
         recorded_windows=recorded_windows,
         block_start_overrides=block_start_overrides,
+        canonical_intervals=canonical_intervals,
         now=now_utc,
     )
     rows: list = []

package/bin/cctally

@@ -3401,10 +3401,42 @@ def _select_non_overlapping_recorded_windows(
 def _load_recorded_five_hour_windows(
     range_start: dt.datetime,
     range_end: dt.datetime,
-) -> tuple[list[dt.datetime], dict[dt.datetime, dt.datetime]]:
+) -> tuple[
+    list[dt.datetime],
+    dict[dt.datetime, dt.datetime],
+    dict[dt.datetime, tuple[dt.datetime, dt.datetime]],
+]:
     """Return sorted, UTC-aware recorded ``five_hour_resets_at`` values
     that anchor real 5h windows in ``[range_start, range_end]``.
 
+    Returns a 3-tuple ``(selected, block_start_overrides, canonical_intervals)``:
+
+      * ``selected``: list of 10-min-floored ``R`` anchors (sorted),
+        each representing one accepted canonical 5h window. Same shape
+        as before — drives `_group_entries_into_blocks`'s
+        ``recorded_windows=`` kwarg.
+
+      * ``block_start_overrides``: ``{R_floored → block_start_at_utc}``
+        for credit-truncated anchors (Bug J). When a credit moment
+        falls inside a canonical block's overlap with the next block,
+        the earlier ``R`` is replaced by the credit moment (floored to
+        10 min) and the original ``block_start_at`` is recorded here so
+        the renderer keeps the real display start.
+
+      * ``canonical_intervals``: ``{R_floored → (bs_utc, rs_utc)}``
+        carrying the **exact** ``(block_start_at, five_hour_resets_at)``
+        for every selected anchor that has a canonical
+        ``five_hour_blocks`` row. ``rs_utc`` is the un-floored reset
+        moment (jitter intact), ``bs_utc`` is the API-derived block
+        start normalized to UTC. Drives `_group_entries_into_blocks`'s
+        partition predicate AND Phase 1.5 block construction
+        (issue #76 — 10-min-floor partition trap). Anchors with no
+        canonical row (legacy weekly-snapshots-only) are absent from
+        the map and the partitioner falls back to ``(R - 5h, R)``.
+        Credit-truncated anchors land here with the truncated upper
+        bound (``rs = effective_reset``) and the override-supplied
+        ``bs`` (the real pre-truncation block start).
+
     Two sources contribute to the merged anchor set:
 
     1. ``weekly_usage_snapshots.five_hour_resets_at`` — every
@@ -3515,7 +3547,7 @@ def _load_recorded_five_hour_windows(
         # OSError covers ensure_dirs() failures (read-only FS, permission
         # denied on parent dir) that propagate from open_db() before any
         # SQL runs. Either way, fall back to the heuristic anchor path.
-        return [], {}
+        return [], {}, {}
     counts: dict[dt.datetime, int] = {}
     for row in rows:
         raw = row["five_hour_resets_at"] if hasattr(row, "keys") else row[0]
@@ -3571,6 +3603,21 @@ def _load_recorded_five_hour_windows(
         canonical_pairs.append((bs, rs))
     canonical_pairs.sort(key=lambda p: p[0])
 
+    # issue #76: canonical_intervals maps every floored R -> its EXACT
+    # (block_start_at, five_hour_resets_at) — both UTC, rs un-floored
+    # (jitter intact). Drives the partition predicate AND Phase 1.5
+    # block construction in `_group_entries_into_blocks` so floor-band
+    # entries (timestamps in [floor(R), R)) land in the right bucket
+    # and the displayed window matches Anthropic's actual interval.
+    # Built before the credit-truncation loop below so that loop can
+    # rewrite the upper bound in-place (truncated R replaces rs).
+    canonical_intervals: dict[
+        dt.datetime, tuple[dt.datetime, dt.datetime]
+    ] = {}
+    for bs, rs in canonical_pairs:
+        snapped = _floor_to_ten_minutes(rs)
+        canonical_intervals[snapped] = (bs, rs)
+
     # Detect overlap-with-credit and replace the earlier R with a
     # credit-truncated anchor. The (anchor → real_block_start) map is
     # returned alongside the anchor list so the renderer can show the
@@ -3595,6 +3642,21 @@ def _load_recorded_five_hour_windows(
                         if bs < cm_floored < rs:
                             truncated_R = cm_floored
                             block_start_overrides[cm_floored] = bs
+                            # Rewrite canonical_intervals[snapped_orig]
+                            # to the truncated interval under the
+                            # truncated key. issue #76: the
+                            # partitioner reads canonical_intervals
+                            # for the exact bs/rs; the truncated entry
+                            # must reflect the credit-shifted upper
+                            # bound (cm_floored) AND the real bs (the
+                            # override) so partition + Phase 1.5
+                            # render the credit-shortened block
+                            # consistently.
+                            snapped_orig = _floor_to_ten_minutes(rs)
+                            canonical_intervals.pop(snapped_orig, None)
+                            canonical_intervals[cm_floored] = (
+                                bs, cm_floored,
+                            )
                             break
         truncated_pairs.append((bs, truncated_R))
 
@@ -3634,7 +3696,16 @@ def _load_recorded_five_hour_windows(
     selected = sorted(
         list(selected_non_truncated) + list(truncated_anchors)
     )
-    return selected, block_start_overrides
+    # Filter canonical_intervals down to selected anchors. Raw-only
+    # anchors (selected via weekly_usage_snapshots but absent from
+    # five_hour_blocks) stay out of the map; the partitioner falls
+    # back to (R - 5h, R) for them. issue #76 / spec §1.1 D1.
+    canonical_intervals = {
+        R: canonical_intervals[R]
+        for R in selected
+        if R in canonical_intervals
+    }
+    return selected, block_start_overrides, canonical_intervals
 
 
 def cmd_blocks(args: argparse.Namespace) -> int:
@@ -3679,8 +3750,10 @@ def cmd_blocks(args: argparse.Namespace) -> int:
     # reset R just after ``range_end`` (e.g. the active window when
     # range_end is wall-clock "now") can still anchor entries that fall
     # inside [range_start, range_end].
-    recorded_windows, block_start_overrides = _load_recorded_five_hour_windows(
-        range_start - BLOCK_DURATION, range_end + BLOCK_DURATION,
+    recorded_windows, block_start_overrides, canonical_intervals = (
+        _load_recorded_five_hour_windows(
+            range_start - BLOCK_DURATION, range_end + BLOCK_DURATION,
+        )
     )
 
     # Group into blocks via the view-model kernel (issue #56). The
@@ -3700,6 +3773,7 @@ def cmd_blocks(args: argparse.Namespace) -> int:
         now_utc=now_utc,
         recorded_windows=recorded_windows,
         block_start_overrides=block_start_overrides,
+        canonical_intervals=canonical_intervals,
         range_start=range_start,
         range_end=range_end,
         display_tz=tz,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctally",
-  "version": "1.10.1",
+  "version": "1.10.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": {