cctally 1.61.0 → 1.63.0

package/bin/_cctally_db.py

@@ -2310,7 +2310,9 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
             cache_read_tokens   INTEGER NOT NULL DEFAULT 0,
             usage_extra_json    TEXT,
             cost_usd_raw        REAL,
-            speed               TEXT
+            speed               TEXT,
+            mutation_seq        INTEGER NOT NULL DEFAULT 0,
+            mutation_min_ts     TEXT
         );
         CREATE INDEX IF NOT EXISTS idx_entries_timestamp
             ON session_entries(timestamp_utc);
@@ -2474,6 +2476,30 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
     # after cost_usd_raw to match the CREATE TABLE order; cache migration 008
     # then backfills it from the legacy blob on existing rows.
     add_column_if_missing(conn, "session_entries", "speed", "TEXT")
+    # #270: the durable per-row mutation signal. ``mutation_seq`` is a change
+    # stamp bumped on every insert + every WHERE-passing in-place UPSERT (from a
+    # cache_meta counter, ingest side); ``mutation_min_ts`` records the EARLIEST
+    # event time the row has ever held, so a finalization that overwrites
+    # ``timestamp_utc`` and moves the row across a bucket boundary still lets the
+    # closed-bucket watermark reach the OLD bucket. Idempotent column-adds (no
+    # marker, no version — a pure column+index add, not a framework migration);
+    # ``INTEGER NOT NULL DEFAULT 0`` is a metadata-only add in SQLite (no table
+    # rewrite on a large session_entries). The covering index
+    # ``idx_entries_mutation_seq`` backs the one new query shape
+    # ``MIN(mutation_min_ts) WHERE mutation_seq > ?`` (index-only range-min over
+    # the delta) plus the ``WHERE mutation_seq > ?`` filters. Both the column
+    # adds AND the index MUST run BEFORE the legacy FTS early-return below (the
+    # ``_apply_cache_schema_legacy_early_return_before_new_table`` gotcha), so an
+    # old cache.db that early-returns still receives them. The index create is
+    # kept OUT of the top executescript on purpose: on an existing DB the CREATE
+    # TABLE there is a no-op, so the columns do not exist yet and an index over
+    # them would raise — it must follow the add_column_if_missing calls.
+    add_column_if_missing(
+        conn, "session_entries", "mutation_seq", "INTEGER NOT NULL DEFAULT 0")
+    add_column_if_missing(conn, "session_entries", "mutation_min_ts", "TEXT")
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_entries_mutation_seq "
+        "ON session_entries(mutation_seq, mutation_min_ts)")
     # Existing-DB guard for the skill-content fold link (cctally-dev
     # skill-content-nesting): the message-level sourceToolUseID. Idempotent
     # column-add (no marker, no version); cache migration 006 then re-ingests

package/bin/_cctally_parser.py

@@ -868,6 +868,21 @@ def _build_statusline_parser(subparsers, name, *, help_text, xref):
         action="store_false",
         help="Suppress cctally 5h%%/7d%% segment.",
     )
+    p.add_argument(
+        "--usage-only",
+        dest="usage_only",
+        action="store_true",
+        default=None,
+        help="Render only subscription usage percentages, e.g. "
+             "`5h 36%% · 7d 35%%` (config key statusline.usage_only).",
+    )
+    p.add_argument(
+        "--no-usage-only",
+        dest="usage_only",
+        action="store_false",
+        help="Render the full statusline even when statusline.usage_only "
+             "is enabled in config.",
+    )
     p.add_argument(
         "--config",
         dest="config",

package/bin/_cctally_statusline.py

@@ -218,6 +218,14 @@ def cmd_statusline(args: argparse.Namespace) -> int:
         )
         ext_on = True
 
+    usage_only = _resolve(args.usage_only, "usage_only", False)
+    if not isinstance(usage_only, bool):
+        warn_once(
+            f"cctally statusline: invalid statusline.usage_only="
+            f"{usage_only!r}; using False"
+        )
+        usage_only = False
+
     tz_name = _resolve_statusline_tz(getattr(args, "timezone", None), cfg, warn_once)
 
     # Color: explicit CLI > NO_COLOR env > TTY detect.
@@ -232,6 +240,7 @@ def cmd_statusline(args: argparse.Namespace) -> int:
         context_low_threshold=int(args.context_low_threshold),
         context_medium_threshold=int(args.context_medium_threshold),
         cctally_extensions=bool(ext_on),
+        usage_only=bool(usage_only),
         color=bool(color),
         display_tz_name=tz_name,
         debug=bool(args.debug),
@@ -634,4 +643,3 @@ def _build_statusline_injections(warn_once):
         warn_once=warn_once,
     )
 
-

package/bin/_cctally_tui.py

@@ -1798,20 +1798,26 @@ def _tui_sessions_cached(
 
 def _fetch_affected_session_entries(
     cache_conn: "sqlite3.Connection",
-    last_seen_max_id: int,
+    last_seen_seq: int,
     range_start: dt.datetime,
     range_end: dt.datetime,
 ) -> "list":
-    """Fetch (timestamp-ASC) every entry of every session touched by a row with
-    ``id > last_seen`` — expanded across ``session_id`` siblings so a resumed
-    session re-aggregates WHOLE — within ``[range_start, range_end]``.
+    """Fetch (timestamp-ASC) every entry of every session touched by a row
+    CHANGED since ``last_seen_seq`` — expanded across ``session_id`` siblings so
+    a resumed session re-aggregates WHOLE — within ``[range_start, range_end]``.
 
     The column list + ``LEFT JOIN`` mirror ``get_claude_session_entries``
     EXACTLY (including the materialized ``speed`` column → ``usage_extra``), so
     the per-session aggregate is byte-identical to the from-scratch pass. The
     affected-source-paths set is inlined as a SQL subquery (parameterized only
-    by ``last_seen``) so the fetch stays a single timestamp-ordered result —
+    by ``last_seen_seq``) so the fetch stays a single timestamp-ordered result —
     no Python ``IN`` list to chunk, and stable first-seen model order.
+
+    #270 (§7d, Codex-2c): the two affected-path subqueries key on
+    ``mutation_seq > ?``, NOT ``id > ?`` — so an id-stable in-place finalization
+    of an EXISTING session's row (which leaves ``MAX(id)`` flat) still selects
+    that session's sibling paths and it re-aggregates WHOLE. On a pure-insert
+    interval ``{mutation_seq > last}`` == ``{id > last}``, so byte-identical.
     """
     c = _cctally()
     _JoinedClaudeEntry = c._JoinedClaudeEntry
@@ -1825,23 +1831,23 @@ def _fetch_affected_session_entries(
         "LEFT JOIN session_files sf ON sf.path = se.source_path "
         "WHERE se.timestamp_utc >= ? AND se.timestamp_utc <= ? "
         "  AND se.source_path IN ("
-        # Sibling paths of every session_id touched by a new row ...
+        # Sibling paths of every session_id touched by a changed row ...
         "    SELECT sf2.path FROM session_files sf2 WHERE sf2.session_id IN ("
         "      SELECT sf1.session_id FROM session_files sf1 "
         "      JOIN (SELECT DISTINCT source_path FROM session_entries "
-        "            WHERE id > ?) af "
+        "            WHERE mutation_seq > ?) af "
         "        ON af.source_path = sf1.path "
         "      WHERE sf1.session_id IS NOT NULL"
         "    )"
         # ... UNION the touched files themselves (covers fallback / not-yet-
         # backfilled session_files rows keyed by filename stem).
         "    UNION "
-        "    SELECT DISTINCT source_path FROM session_entries WHERE id > ?"
+        "    SELECT DISTINCT source_path FROM session_entries WHERE mutation_seq > ?"
         "  ) "
         "ORDER BY se.timestamp_utc ASC"
     )
     rows = cache_conn.execute(
-        sql, (start_iso, end_iso, last_seen_max_id, last_seen_max_id),
+        sql, (start_iso, end_iso, last_seen_seq, last_seen_seq),
     ).fetchall()
     return [
         _JoinedClaudeEntry(
@@ -2155,6 +2161,22 @@ def _tui_build_snapshot(
         # `reconcile_projects_env_cache` succeeds. Off ⇒ `_build_projects_envelope`
         # does the full-window walk (CLI / drill / test byte-identical).
         use_projects_env_cache = False
+        # ── #271 M3: Bug-K pre-credit segment cache (spec §18) ──────────────
+        # A DEDICATED flag (Codex-BK-2 — NOT piggybacked on `use_group_a_cache`):
+        # OFF by default, flipped ON only on the dashboard sync-thread NON-IDLE
+        # path after the once-per-rebuild `reconcile_bugk_cache` succeeds. Off ⇒
+        # the Weekly builder's Bug-K synthesis re-folds the closed pre-credit
+        # window directly each tick (CLI / share / test byte-identical). A
+        # failed/absent reconcile must fall back to direct compute, never reuse
+        # stale segment state.
+        use_bugk_segment_cache = False
+        # ── #272: cache-report per-day cache (spec §5/§6) ───────────────────
+        # Same gating: OFF by default, flipped ON only on the dashboard
+        # sync-thread NON-IDLE path after the once-per-rebuild
+        # `reconcile_cache_report_cache` succeeds. Off ⇒ `build_cache_report_snapshot`
+        # fetches + folds the full 14d window every tick (byte-identical to the
+        # cached path). A failed/absent reconcile falls back to full recompute.
+        use_cache_report_cache = False
         # ── Three-path dispatch — idle short-circuit (spec §3, #268 M5.1) ──
         # Compute the composite data-version signature (cheap MAX(id) descents
         # over cache.db + stats.db + the reset-event change-signal + the
@@ -2222,6 +2244,7 @@ def _tui_build_snapshot(
                         _sc.reconcile_weekref_cache(
                             _rc_cache_conn,
                             max_entry_id=dispatch_sig.max_entry_id,
+                            max_mutation_seq=dispatch_sig.entry_mutation_seq,
                             reset_sig=dispatch_sig.reset_sig,
                         )
                         use_weekref_cost_cache = True
@@ -2233,10 +2256,50 @@ def _tui_build_snapshot(
                         _sc.reconcile_projects_env_cache(
                             _rc_cache_conn,
                             max_entry_id=dispatch_sig.max_entry_id,
+                            max_mutation_seq=dispatch_sig.entry_mutation_seq,
                             max_wus_id=dispatch_sig.max_wus_id,
                             sf_sig=_sc.session_files_sig(_rc_cache_conn),
                         )
                         use_projects_env_cache = True
+                        # #271 M3: reconcile the Bug-K pre-credit segment cache
+                        # with the SAME short-lived cache conn (its watermark
+                        # query lives in cache.db), using the dispatch-signature
+                        # legs already computed. Only after this succeeds does
+                        # `_dashboard_build_weekly_periods` opt into the cache
+                        # below (`use_bugk_segment_cache=True`).
+                        _sc.reconcile_bugk_cache(
+                            _rc_cache_conn,
+                            max_entry_id=dispatch_sig.max_entry_id,
+                            max_mutation_seq=dispatch_sig.entry_mutation_seq,
+                            reset_sig=dispatch_sig.reset_sig,
+                        )
+                        use_bugk_segment_cache = True
+                        # #272: reconcile the cache-report per-day cache with the
+                        # SAME short-lived cache conn (its watermark query +
+                        # session_files_sig both live in cache.db), using the
+                        # dispatch-signature legs already computed. `sf_sig`
+                        # closes the lazy-`project_path`-backfill hole (Codex-1);
+                        # `tz_key` full-clears on a display-tz change (every
+                        # calendar-day key shifts). Only after this succeeds does
+                        # `build_cache_report_snapshot` opt into the cache below.
+                        _sc.reconcile_cache_report_cache(
+                            _rc_cache_conn,
+                            max_entry_id=dispatch_sig.max_entry_id,
+                            max_mutation_seq=dispatch_sig.entry_mutation_seq,
+                            reset_sig=dispatch_sig.reset_sig,
+                            sf_sig=_sc.session_files_sig(_rc_cache_conn),
+                            # `_load_sibling` is the canonical idempotent
+                            # sibling-access idiom (it returns the already-loaded
+                            # cctally-bound kernel instance). `_lib_cache_report`
+                            # is loaded eagerly at import (bin/cctally), so this
+                            # is a plain re-fetch of a populated `sys.modules`
+                            # entry — NOT a first-tick KeyError guard.
+                            bucket_tz=_cctally()._load_sibling(
+                                "_lib_cache_report"
+                            )._resolve_bucket_tz(_build_display_tz),
+                            tz_key=str(_build_display_tz),
+                        )
+                        use_cache_report_cache = True
                     finally:
                         _rc_cache_conn.close()
                 except Exception as exc:
@@ -2327,6 +2390,7 @@ def _tui_build_snapshot(
             weekly_periods = _dashboard_build_weekly_periods(
                 conn, now_utc, n=12, skip_sync=skip_sync,
                 use_group_a_cache=True,
+                use_bugk_segment_cache=use_bugk_segment_cache,
             )
             # ``stable_sum`` (math.fsum) returns float ``0.0`` on empty rows,
             # so the envelope stays byte-stable with the pre-fix ``0.0`` shape
@@ -2560,6 +2624,7 @@ def _tui_build_snapshot(
                 anomaly_window_days=_dash_mod.CACHE_REPORT_ANOMALY_WINDOW_DAYS,
                 display_tz=_build_display_tz,
                 skip_sync=skip_sync,
+                use_cache_report_cache=use_cache_report_cache,
             )
         except Exception as exc:
             errors.append(f"cache-report: {exc}")

package/bin/_cctally_weekrefs.py

@@ -309,6 +309,15 @@ def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
     c = _cctally()
     # #269 M4.4: skip the full rescan when neither the snapshots nor the
     # reset events moved since the last successful backfill on this DB file.
+    #
+    # #271 §9d rider (from the #269 final review): the skip signature
+    # (`_backfill_reset_events_signature`, a MAX(id)/COUNT descent) is blind to a
+    # NON-max `weekly_usage_snapshots` DELETE — dropping a middle row leaves
+    # MAX(id) and could leave COUNT unchanged vs a prior state, so a rescan may
+    # be skipped. That is byte-safe because this backfill is ADD-ONLY
+    # (`INSERT OR IGNORE INTO week_reset_events`): a skipped rescan can only fail
+    # to *add* an event, never *remove* a needed one, matching the pre-#269
+    # idempotent behavior exactly.
     db_id = _backfill_db_identity(conn)
     sig = _backfill_reset_events_signature(conn)
     if db_id is not None:

package/bin/_lib_aggregators.py

@@ -106,6 +106,94 @@ class BucketUsage:
     model_breakdowns: list[dict[str, Any]]  # Sorted by cost desc
 
 
+def _new_bucket_acc() -> dict[str, Any]:
+    """A fresh running accumulator for one bucket (the pre-``BucketUsage`` shape).
+
+    The single per-bucket accumulation state shared by the full-pass
+    ``_aggregate_buckets`` and #271's incremental current-bucket accumulator, so
+    the byte-identity proof reduces to "same primitive, entries appended in the
+    same order" (spec §6).
+    """
+    return {
+        "input": 0, "output": 0, "cache_create": 0, "cache_read": 0,
+        "cost": 0.0, "models": {}, "models_order": [],
+    }
+
+
+def _fold_entry(acc: dict[str, Any], entry: UsageEntry, mode: str = "auto") -> None:
+    """Fold one entry into ``acc`` (the exact per-entry logic of ``_aggregate_buckets``).
+
+    Carries over verbatim: the ``<synthetic>`` skip (never touches ``acc`` for
+    them, so it is safe over an unfiltered delta stream), the ``-fast``
+    ``display_model`` suffix, the ``_calculate_entry_cost`` call, the four
+    integer token ``+=``, the running float ``cost +=``, the per-model
+    sub-bucket sums, and the first-seen ``models_order.append``. Order-sensitive:
+    the running ``cost`` is a left-fold, so callers MUST fold in the same order
+    the full pass would (the pinned ``(timestamp_utc, id)`` order, #271 §5).
+    """
+    if entry.model == "<synthetic>":
+        return
+    usage = entry.usage
+    display_model = f"{entry.model}-fast" if usage.get("speed") == "fast" else entry.model
+    inp = int(usage.get("input_tokens", 0) or 0)
+    out = int(usage.get("output_tokens", 0) or 0)
+    cc = int(usage.get("cache_creation_input_tokens", 0) or 0)
+    cr = int(usage.get("cache_read_input_tokens", 0) or 0)
+    cost = _calculate_entry_cost(
+        entry.model, usage, mode=mode, cost_usd=entry.cost_usd,
+    )
+    acc["input"] += inp
+    acc["output"] += out
+    acc["cache_create"] += cc
+    acc["cache_read"] += cr
+    acc["cost"] += cost
+    model_bucket = acc["models"].setdefault(display_model, {
+        "input": 0, "output": 0, "cache_create": 0, "cache_read": 0, "cost": 0.0,
+    })
+    model_bucket["input"] += inp
+    model_bucket["output"] += out
+    model_bucket["cache_create"] += cc
+    model_bucket["cache_read"] += cr
+    model_bucket["cost"] += cost
+    if display_model not in acc["models_order"]:
+        acc["models_order"].append(display_model)
+
+
+def _finalize_bucket(bucket_key: str, acc: dict[str, Any]) -> BucketUsage:
+    """Build the immutable ``BucketUsage`` from a running accumulator.
+
+    Copies ``models`` / ``model_breakdowns`` so the returned row shares no
+    mutable state with ``acc`` (F7 — a live accumulator may keep being folded,
+    e.g. #271's persisted current-bucket state).
+    """
+    model_breakdowns = [
+        {
+            "modelName": model,
+            "inputTokens": mb["input"],
+            "outputTokens": mb["output"],
+            "cacheCreationTokens": mb["cache_create"],
+            "cacheReadTokens": mb["cache_read"],
+            "cost": mb["cost"],
+        }
+        for model, mb in acc["models"].items()
+    ]
+    model_breakdowns.sort(key=lambda m: m["cost"], reverse=True)
+    total_tokens = (
+        acc["input"] + acc["output"] + acc["cache_create"] + acc["cache_read"]
+    )
+    return BucketUsage(
+        bucket=bucket_key,
+        input_tokens=acc["input"],
+        output_tokens=acc["output"],
+        cache_creation_tokens=acc["cache_create"],
+        cache_read_tokens=acc["cache_read"],
+        total_tokens=total_tokens,
+        cost_usd=acc["cost"],
+        models=list(acc["models_order"]),
+        model_breakdowns=model_breakdowns,
+    )
+
+
 def _aggregate_buckets(
     entries: list[UsageEntry],
     key_fn: Callable[[UsageEntry], str],
@@ -117,84 +205,23 @@ def _aggregate_buckets(
     The returned list is sorted by bucket key ascending — callers reverse
     for --order desc.  Model breakdowns within each bucket are sorted by
     descending cost, matching upstream ccusage.
+
+    The per-entry accumulation is the shared ``_fold_entry`` primitive (spec
+    §6): a ``<synthetic>`` entry is skipped BEFORE keying (so a synthetic-only
+    key never materializes an empty bucket), and each surviving entry is folded
+    into its bucket's running accumulator, finalized per key in ascending order.
     """
     by_bucket: dict[str, dict[str, Any]] = {}
-    models_order: dict[str, list[str]] = {}
-
     for entry in entries:
         if entry.model == "<synthetic>":
             continue
-        usage = entry.usage
-        display_model = f"{entry.model}-fast" if usage.get("speed") == "fast" else entry.model
         key = key_fn(entry)
-        bucket = by_bucket.setdefault(key, {
-            "input": 0,
-            "output": 0,
-            "cache_create": 0,
-            "cache_read": 0,
-            "cost": 0.0,
-            "models": {},
-        })
-        order = models_order.setdefault(key, [])
+        acc = by_bucket.get(key)
+        if acc is None:
+            by_bucket[key] = acc = _new_bucket_acc()
+        _fold_entry(acc, entry, mode)
 
-        inp = int(usage.get("input_tokens", 0) or 0)
-        out = int(usage.get("output_tokens", 0) or 0)
-        cc = int(usage.get("cache_creation_input_tokens", 0) or 0)
-        cr = int(usage.get("cache_read_input_tokens", 0) or 0)
-        cost = _calculate_entry_cost(
-            entry.model, usage, mode=mode, cost_usd=entry.cost_usd,
-        )
-
-        bucket["input"] += inp
-        bucket["output"] += out
-        bucket["cache_create"] += cc
-        bucket["cache_read"] += cr
-        bucket["cost"] += cost
-
-        model_bucket = bucket["models"].setdefault(display_model, {
-            "input": 0,
-            "output": 0,
-            "cache_create": 0,
-            "cache_read": 0,
-            "cost": 0.0,
-        })
-        model_bucket["input"] += inp
-        model_bucket["output"] += out
-        model_bucket["cache_create"] += cc
-        model_bucket["cache_read"] += cr
-        model_bucket["cost"] += cost
-
-        if display_model not in order:
-            order.append(display_model)
-
-    result: list[BucketUsage] = []
-    for key in sorted(by_bucket.keys()):
-        b = by_bucket[key]
-        model_breakdowns = [
-            {
-                "modelName": model,
-                "inputTokens": mb["input"],
-                "outputTokens": mb["output"],
-                "cacheCreationTokens": mb["cache_create"],
-                "cacheReadTokens": mb["cache_read"],
-                "cost": mb["cost"],
-            }
-            for model, mb in b["models"].items()
-        ]
-        model_breakdowns.sort(key=lambda m: m["cost"], reverse=True)
-        total_tokens = b["input"] + b["output"] + b["cache_create"] + b["cache_read"]
-        result.append(BucketUsage(
-            bucket=key,
-            input_tokens=b["input"],
-            output_tokens=b["output"],
-            cache_creation_tokens=b["cache_create"],
-            cache_read_tokens=b["cache_read"],
-            total_tokens=total_tokens,
-            cost_usd=b["cost"],
-            models=models_order[key],
-            model_breakdowns=model_breakdowns,
-        ))
-    return result
+    return [_finalize_bucket(key, by_bucket[key]) for key in sorted(by_bucket.keys())]
 
 
 def _aggregate_daily(