cctally 1.61.0 → 1.63.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.63.0] - 2026-07-07
+
+### Added
+- `cctally statusline --usage-only` renders just the subscription usage chip (`5h X% · 7d Y%`), dropping the model, cost, burn-rate, context, and reset-countdown segments — for users who want a small quota indicator in their prompt without the cost telemetry. Persist it with `cctally config set statusline.usage_only true`; `--no-usage-only` forces the full statusline when the config key is on. Contributed by @nathanm4 (public PR #3).
+
+## [1.62.0] - 2026-07-06
+
+### Changed
+- Dashboard warm rebuilds are materially faster on very large histories: the Daily, Weekly, Monthly, and Projects panels now fold only new activity into the current period each refresh instead of re-summing the whole open period, a `record-usage` write no longer forces a full projects rebuild, and on weeks with an in-place credit the pre-credit segment of the Weekly panel is now computed once and reused instead of being re-summed on every refresh. Output is unchanged (#271).
+- The dashboard's cache-report card is now the last panel to join the warm-refresh fast path: each closed day's cache-savings breakdown is computed once and reused, so a live refresh recomputes only today instead of re-reading and re-folding the whole 14-day window every time — a large chunk of the remaining per-refresh work on big histories. This holds even when the trailing two weeks contain a day with no activity (a weekend or a day off): a quiet day is remembered as quiet, so it no longer forces the card back onto the slow full-window path on every refresh. The card's per-project net-savings values shift by a negligible floating-point amount as a side effect of the order-independent fold this relies on; everything else is unchanged (#272).
+
+### Fixed
+- The live dashboard no longer serves a stale value for a past day, week, or month after a streaming message that began in that period finalizes after the period has rolled over — an in-place finalization that reused the same cache row previously slipped the idle-path snapshot check, so the closed period could keep showing its pre-finalization total until the next real change; the dashboard now recomputes the affected period (and no longer double-counts the current period's open bucket in the same situation) (#270).
+- The live dashboard's memory footprint no longer creeps upward by a tiny amount for each day it stays running: the cache-report card's per-day cache (added in #272) now drops days that have rolled out of its trailing two-week window instead of holding onto them until the next restart. Output is unchanged (#275).
+
 ## [1.61.0] - 2026-07-05
 
 ### Added

package/bin/_cctally_cache.py

@@ -805,6 +805,34 @@ def _prune_orphaned_cache_entries(conn, *, lock_timeout=None):
         lock_fh.close()
 
 
+def _bump_mutation_seq(conn: sqlite3.Connection) -> int:
+    """Atomically increment the ``session_entries`` mutation counter in
+    ``cache_meta`` and return the new value (#270, spec §6).
+
+    The counter (key ``session_entries_mutation_seq``) is a monotonic integer
+    stamped onto every insert and every WHERE-passing in-place UPSERT so an
+    id-stable finalization advances the composite dispatch signature (via the
+    ``entry_mutation_seq`` leg) and the change-aware watermark, closing the
+    dashboard idle-path stale-snapshot hole.
+
+    ``value`` has TEXT affinity; ``CAST(... AS INTEGER) + 1`` yields an integer
+    stored back as text, and ``RETURNING value`` returns that text form so
+    ``int(...)`` is correct. Called PER FILE inside ``sync_cache``'s per-file
+    write transaction (rollback-safe: a file that rolls back reverts the counter
+    and its row stamps together), under the single-writer ``cache.db.lock``
+    flock, so no concurrency guard beyond the flock is needed. ``cache_meta`` is
+    guaranteed present by ``_apply_cache_schema`` before any ``sync_cache`` runs.
+    """
+    row = conn.execute(
+        "INSERT INTO cache_meta(key, value) "
+        "VALUES ('session_entries_mutation_seq', '1') "
+        "ON CONFLICT(key) DO UPDATE SET "
+        "    value = CAST(cache_meta.value AS INTEGER) + 1 "
+        "RETURNING value"
+    ).fetchone()
+    return int(row[0])
+
+
 def sync_cache(
     conn: sqlite3.Connection,
     *,
@@ -1493,6 +1521,18 @@ def sync_cache(
                     )
                     stats.files_reset_truncated += 1
                 if rows:
+                    # #270: bump the per-file mutation counter BEFORE capturing
+                    # `before`, so this cache_meta write stays OUTSIDE the
+                    # [before, after] total_changes window and never inflates
+                    # `stats.rows_changed` (byte-identity). Per file (not once
+                    # per sync) for rollback-safety: the counter write is atomic
+                    # with the row stamps in this file's write transaction, so a
+                    # file that rolls back reverts both together (spec §6). Each
+                    # row built for this file is stamped mutation_seq = this
+                    # file's `sync_seq` and mutation_min_ts = its own
+                    # timestamp_utc (== the event time on insert).
+                    sync_seq = _bump_mutation_seq(conn)
+                    stamped_rows = [r + (sync_seq, r[2]) for r in rows]
                     before = conn.total_changes
                     # ccusage-parity ON CONFLICT DO UPDATE: higher-token total
                     # wins on conflict; speed-set breaks ties. The partial
@@ -1522,8 +1562,9 @@ def sync_cache(
                            (source_path, line_offset, timestamp_utc, model,
                             msg_id, req_id, input_tokens, output_tokens,
                             cache_create_tokens, cache_read_tokens,
-                            usage_extra_json, speed, cost_usd_raw)
-                           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)
+                            usage_extra_json, speed, cost_usd_raw,
+                            mutation_seq, mutation_min_ts)
+                           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
                            ON CONFLICT(msg_id, req_id)
                            WHERE msg_id IS NOT NULL AND req_id IS NOT NULL
                            DO UPDATE SET
@@ -1535,7 +1576,32 @@ def sync_cache(
                                cache_read_tokens = excluded.cache_read_tokens,
                                usage_extra_json = excluded.usage_extra_json,
                                speed = excluded.speed,
-                               cost_usd_raw = excluded.cost_usd_raw
+                               cost_usd_raw = excluded.cost_usd_raw,
+                               -- #270: stamp the change. mutation_seq advances
+                               -- exactly when this guarded UPSERT's WHERE passes
+                               -- (incl. the equal-tokens speed-tiebreak branch,
+                               -- Codex-2d). mutation_min_ts accumulates the
+                               -- EARLIEST event time the row has held —
+                               -- session_entries.mutation_min_ts is the OLD
+                               -- (pre-update) value, excluded.timestamp_utc the
+                               -- finalization's new time — so a finalization
+                               -- that moves the row across a bucket boundary
+                               -- still lets the closed-bucket watermark reach
+                               -- the OLD bucket (spec §6/§7b). The SET reads
+                               -- pre-update column values, unaffected by the
+                               -- sibling timestamp_utc = excluded.timestamp_utc.
+                               -- COALESCE(mutation_min_ts, timestamp_utc) guards
+                               -- a LEGACY row (written before these columns
+                               -- existed: mutation_min_ts NULL): SQLite scalar
+                               -- MIN(NULL, x) is NULL, which would strand the
+                               -- watermark; the pre-update timestamp_utc is that
+                               -- legacy row's old event time, so both its old
+                               -- and new buckets stay reachable. No-op for
+                               -- non-legacy rows (mutation_min_ts already set).
+                               mutation_seq = excluded.mutation_seq,
+                               mutation_min_ts = MIN(COALESCE(session_entries.mutation_min_ts,
+                                                              session_entries.timestamp_utc),
+                                                     excluded.timestamp_utc)
                            WHERE
                                (excluded.input_tokens + excluded.output_tokens
                                 + excluded.cache_create_tokens + excluded.cache_read_tokens)
@@ -1551,7 +1617,7 @@ def sync_cache(
                                AND excluded.speed IS NOT NULL
                                AND session_entries.speed IS NULL
                             )""",
-                        rows,
+                        stamped_rows,
                     )
                     stats.rows_changed += conn.total_changes - before
                 # Conversation message ingest (Plan 1). Lands in the SAME
@@ -2302,7 +2368,14 @@ def iter_entries(
         )
         sql += r" AND source_path LIKE ? ESCAPE '\'"
         params.append(f"%/projects/{escaped}/%")
-    sql += " ORDER BY timestamp_utc ASC"
+    # Explicit (timestamp_utc, id) tie-break (#271 §5 / Codex-3): the
+    # `idx_entries_timestamp` index already stores keys as (timestamp_utc,
+    # rowid), so an index-driven walk yields exactly this order and pinning it
+    # is free at runtime (goldens unchanged). The pin converts that OBSERVED
+    # planner behavior into a CONTRACT — a guaranteed total fold order — which
+    # is what makes #271's incremental current-bucket append provably
+    # byte-identical to the full-pass fold.
+    sql += " ORDER BY timestamp_utc ASC, id ASC"
 
     entries: list[UsageEntry] = []
     for row in conn.execute(sql, params):
@@ -2328,6 +2401,74 @@ def iter_entries(
     return entries
 
 
+def iter_entries_with_id(
+    conn: sqlite3.Connection,
+    range_start: dt.datetime,
+    range_end: dt.datetime,
+    *,
+    after_seq: int | None = None,
+    after_ts: dt.datetime | None = None,
+) -> list[tuple[int, UsageEntry]]:
+    """Like ``iter_entries`` but yields ``(id, UsageEntry)`` rows, ordered
+    ``(timestamp_utc, id)``, for #271's current-bucket accumulator (§7d).
+
+    When ``after_seq`` / ``after_ts`` are given, restricts to the incremental
+    delta ``(mutation_seq > after_seq OR timestamp_utc > after_ts)`` — the
+    ``mutation_seq`` leg (#270 §8) catches genuinely-new ingests AND id-stable
+    in-place finalizations (which advance ``mutation_seq`` while leaving ``id``
+    flat, so the pre-#270 ``id > after_id`` leg missed them and double-counted);
+    the ``timestamp_utc`` leg catches already-ingested rows that newly entered
+    the window because ``now`` advanced (Codex-1). Both disjuncts stay
+    index-usable (``idx_entries_mutation_seq`` range + ``idx_entries_timestamp``
+    range), so the delta is O(delta), not a full current-bucket scan (an
+    ``EXPLAIN QUERY PLAN`` regression test guards this, Codex-2). On a
+    pure-insert interval ``{mutation_seq > after_seq}`` == ``{id > after_id}``
+    (each insert carries a fresh seq monotone with id), so the delta row set is
+    byte-identical to the old ``id`` leg (§7b). The ``id`` is still SELECTed (the
+    accumulator's ``id <= reconciled_max_id`` pre-existing-row cold-refold trigger
+    reads it). ``iter_entries``' public ``list[UsageEntry]`` shape and
+    ``UsageEntry`` (which has no ``id`` field) are left untouched — this is a
+    thin internal sibling, not an overload (Codex-5).
+    """
+    start_iso = range_start.astimezone(dt.timezone.utc).isoformat()
+    end_iso = range_end.astimezone(dt.timezone.utc).isoformat()
+    sql = (
+        "SELECT id, timestamp_utc, model, input_tokens, output_tokens, "
+        "cache_create_tokens, cache_read_tokens, speed, cost_usd_raw, source_path "
+        "FROM session_entries "
+        "WHERE timestamp_utc >= ? AND timestamp_utc <= ?"
+    )
+    params: list[Any] = [start_iso, end_iso]
+    if after_seq is not None or after_ts is not None:
+        after_seq_val = -1 if after_seq is None else int(after_seq)
+        after_ts_val = (
+            "" if after_ts is None
+            else after_ts.astimezone(dt.timezone.utc).isoformat()
+        )
+        sql += " AND (mutation_seq > ? OR timestamp_utc > ?)"
+        params += [after_seq_val, after_ts_val]
+    sql += " ORDER BY timestamp_utc ASC, id ASC"
+
+    out: list[tuple[int, UsageEntry]] = []
+    for row in conn.execute(sql, params):
+        usage: dict[str, Any] = {
+            "input_tokens":                row[3],
+            "output_tokens":               row[4],
+            "cache_creation_input_tokens": row[5],
+            "cache_read_input_tokens":     row[6],
+        }
+        if row[7] is not None:  # speed (materialized column, #181)
+            usage["speed"] = row[7]
+        out.append((row[0], UsageEntry(
+            timestamp=dt.datetime.fromisoformat(row[1]),
+            model=row[2],
+            usage=usage,
+            cost_usd=row[8],
+            source_path=row[9],
+        )))
+    return out
+
+
 def _collect_entries_direct(
     range_start: dt.datetime,
     range_end: dt.datetime,
@@ -2462,7 +2603,16 @@ def get_claude_session_entries(
         )
         sql += r" AND se.source_path LIKE ? ESCAPE '\'"
         params.append(f"%/projects/{escaped}/%")
-    sql += " ORDER BY se.timestamp_utc ASC"
+    # Explicit (timestamp_utc, id) tie-break (#275) — the same contract #271 §5
+    # pinned on `get_entries` (see the twin ORDER BY above). `id` is the rowid, so
+    # against `idx_entries_timestamp` (which stores keys as (timestamp_utc, rowid))
+    # this is free at runtime and byte-identical to today's observed order. Pinning
+    # it makes the fold order a total, plan-INDEPENDENT contract: the #272 warm path
+    # folds today over a narrow `[today_start, now]` query while the cold path folds
+    # over the full `[since, now]` query, and both — plus the `+=` day-row fold and
+    # the by_project partials — must agree on equal-timestamp rows regardless of
+    # which plan SQLite picks for either window.
+    sql += " ORDER BY se.timestamp_utc ASC, se.id ASC"
 
     rows = conn.execute(sql, params).fetchall()
 

package/bin/_cctally_config.py

@@ -309,6 +309,7 @@ ALLOWED_CONFIG_KEYS = (
     "statusline.visual_burn_rate",
     "statusline.cost_source",
     "statusline.cctally_extensions",
+    "statusline.usage_only",
     "budget.weekly_usd",
     "budget.alerts_enabled",
     "budget.alert_thresholds",
@@ -379,6 +380,25 @@ def _validate_statusline_cctally_extensions(value):
     )
 
 
+def _validate_statusline_usage_only(value):
+    """Validate ``statusline.usage_only``.
+
+    Accepts booleans (preferred) or canonical truthy/falsy strings
+    (``true``/``false``/``yes``/``no``/``on``/``off``/``1``/``0``).
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lo = value.strip().lower()
+        if lo in ("true", "yes", "on", "1"):
+            return True
+        if lo in ("false", "no", "off", "0"):
+            return False
+    raise ValueError(
+        f"statusline.usage_only must be boolean (got {value!r})"
+    )
+
+
 def cmd_config(args: argparse.Namespace) -> int:
     """Get/set/unset persisted user preferences in config.json.
 
@@ -544,6 +564,7 @@ def _config_known_value(config: dict, key: str) -> "object":
         "statusline.visual_burn_rate",
         "statusline.cost_source",
         "statusline.cctally_extensions",
+        "statusline.usage_only",
     ):
         sl_block = config.get("statusline") if isinstance(config, dict) else None
         if not isinstance(sl_block, dict):
@@ -554,6 +575,7 @@ def _config_known_value(config: dict, key: str) -> "object":
             "visual_burn_rate": "off",
             "cost_source": "auto",
             "cctally_extensions": True,
+            "usage_only": False,
         }
         if stored is None:
             return defaults[inner]
@@ -561,6 +583,7 @@ def _config_known_value(config: dict, key: str) -> "object":
             "visual_burn_rate": _validate_statusline_visual_burn_rate,
             "cost_source": _validate_statusline_cost_source,
             "cctally_extensions": _validate_statusline_cctally_extensions,
+            "usage_only": _validate_statusline_usage_only,
         }[inner]
         try:
             return validator(stored)
@@ -987,12 +1010,14 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         "statusline.visual_burn_rate",
         "statusline.cost_source",
         "statusline.cctally_extensions",
+        "statusline.usage_only",
     ):
         inner_key = key.split(".", 1)[1]
         validator = {
             "visual_burn_rate": _validate_statusline_visual_burn_rate,
             "cost_source": _validate_statusline_cost_source,
             "cctally_extensions": _validate_statusline_cctally_extensions,
+            "usage_only": _validate_statusline_usage_only,
         }[inner_key]
         try:
             normalized = validator(raw)
@@ -1390,6 +1415,7 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
         "statusline.visual_burn_rate",
         "statusline.cost_source",
         "statusline.cctally_extensions",
+        "statusline.usage_only",
     ):
         inner_key = key.split(".", 1)[1]
         with config_writer_lock():