cctally 1.59.0 → 1.61.0

package/bin/_lib_view_models.py

@@ -264,6 +264,16 @@ class TuiSessionRow:
     # without re-reading ``session_files`` and so the share path can
     # privacy-scrub via ``_lib_share._scrub``.
     project_path: str | None = None
+    # Dashboard/TUI-only: the human-readable session title (AI-generated
+    # title when present, else the first non-marker user prompt). Populated
+    # by the dashboard/TUI snapshot wrapper (``_cctally_tui._tui_build_sessions``)
+    # via ``_lib_conversation_query._session_titles_map``; left ``None`` on the
+    # CLI ``session`` / share paths (they call ``build_sessions_view`` directly).
+    # This is transcript-derived content — it rides the per-request transcript
+    # privacy gate at envelope serialization (never emitted when the gate is
+    # closed). Defaults ``None`` so fixture rows built positionally stay
+    # compatible.
+    title: str | None = None
 
 
 # === Internal helpers ======================================================
@@ -325,7 +335,8 @@ class DailyView:
     display_tz_label: str = ""
 
 
-def build_daily_view(entries, *, now_utc, display_tz=None, mode="auto"):
+def build_daily_view(entries, *, now_utc, display_tz=None, mode="auto",
+                     aggregated_override=None):
     """Build a ``DailyView`` from raw ``UsageEntry`` list (spec §5.1).
 
     Gap-free: only days with entries appear in ``view.rows`` /
@@ -341,9 +352,22 @@ def build_daily_view(entries, *, now_utc, display_tz=None, mode="auto"):
     Leaves ``DailyPanelRow.label`` and ``intensity_bucket`` at dataclass
     defaults — the dashboard envelope adapter populates them. CLI /
     share consumers ignore them and read ``view.aggregated`` instead.
+
+    ``aggregated_override`` (#268): when provided (a list/tuple of
+    ``BucketUsage`` in ascending bucket-key order), skip the
+    ``_aggregate_daily(entries, ...)`` re-costing and build the view over
+    those pre-aggregated buckets instead. This is the reuse seam the
+    dashboard's cached daily builder uses to serve immutable past days
+    from memory while keeping every downstream derivation (rows,
+    ``cache_hit_pct``, totals, ``period_start``) single-sourced here. When
+    ``None`` (CLI / share / cold path) behavior is unchanged and
+    byte-identical.
     """
     _agg = _load_lib("_lib_aggregators")
-    buckets = _agg._aggregate_daily(entries, mode=mode, tz=display_tz)
+    if aggregated_override is not None:
+        buckets = list(aggregated_override)
+    else:
+        buckets = _agg._aggregate_daily(entries, mode=mode, tz=display_tz)
     if not buckets:
         return DailyView(
             rows=(),
@@ -434,7 +458,8 @@ class MonthlyView:
     display_tz_label: str = ""
 
 
-def build_monthly_view(entries, *, now_utc, n=12, display_tz=None, mode="auto"):
+def build_monthly_view(entries, *, now_utc, n=12, display_tz=None, mode="auto",
+                       aggregated_override=None):
     """Build a ``MonthlyView`` for the trailing ``n`` calendar months
     (spec §5.2).
 
@@ -445,9 +470,21 @@ def build_monthly_view(entries, *, now_utc, n=12, display_tz=None, mode="auto"):
     Totals (``total_cost_usd`` / ``total_tokens``) sum over the
     truncated row set so the React panel sees the same number as the
     CLI table footer would.
+
+    ``aggregated_override`` (#268): when provided (a list/tuple of
+    ``BucketUsage`` in ascending bucket-key order), skip the
+    ``_aggregate_monthly(entries, ...)`` re-costing and build the view over
+    those pre-aggregated buckets. The reverse + cap-to-``n`` +
+    ``delta_cost_pct`` + ``is_current`` presentation still runs over the
+    assembled list, so the current month's delta sees the prior (cached)
+    month (Codex F3). ``None`` preserves the CLI/share/cold behavior
+    byte-identically.
     """
     _agg = _load_lib("_lib_aggregators")
-    buckets = _agg._aggregate_monthly(entries, mode=mode, tz=display_tz)
+    if aggregated_override is not None:
+        buckets = list(aggregated_override)
+    else:
+        buckets = _agg._aggregate_monthly(entries, mode=mode, tz=display_tz)
     if not buckets:
         return MonthlyView(
             rows=(), aggregated=(),
@@ -535,7 +572,7 @@ class WeeklyView:
 
 
 def build_weekly_view(conn, entries, *, weeks, now_utc, display_tz=None,
-                      as_of_utc=None, mode="auto"):
+                      as_of_utc=None, mode="auto", aggregated_override=None):
     """Build a ``WeeklyView`` from subscription-week boundaries
     (spec §5.3).
 
@@ -552,10 +589,22 @@ def build_weekly_view(conn, entries, *, weeks, now_utc, display_tz=None,
 
     Output is newest-first across ``rows`` / ``aggregated`` /
     ``overlay`` — the CLI re-reverses for asc rendering.
+
+    ``aggregated_override`` (#268): when provided (a list/tuple of
+    ``BucketUsage`` in ascending bucket-key order — one per SubWeek WITH
+    data), skip the ``_aggregate_weekly(entries, weeks)`` re-costing and
+    run the overlay / delta / is_current presentation over those
+    pre-aggregated buckets. The overlay (``weekly_usage_snapshots``) is
+    always re-read fresh here, so a snapshot change is reflected even for a
+    cached bucket. ``None`` preserves the CLI/share/cold behavior
+    byte-identically.
     """
     _agg = _load_lib("_lib_aggregators")
     _cct_core = _load_lib("_cctally_core")
-    buckets_asc = _agg._aggregate_weekly(entries, weeks, mode=mode)
+    if aggregated_override is not None:
+        buckets_asc = list(aggregated_override)
+    else:
+        buckets_asc = _agg._aggregate_weekly(entries, weeks, mode=mode)
     if not buckets_asc:
         return WeeklyView(
             rows=(), aggregated=(), overlay=(),
@@ -709,7 +758,8 @@ class TrendView:
     display_tz_label: str = ""
 
 
-def build_trend_view(conn, *, now_utc, n=8, display_tz=None):
+def build_trend_view(conn, *, now_utc, n=8, display_tz=None, skip_sync=False,
+                     use_weekref_cost_cache=False):
     """Build a ``TrendView`` of the last ``n`` subscription weeks
     (spec §5.4).
 
@@ -721,6 +771,17 @@ def build_trend_view(conn, *, now_utc, n=8, display_tz=None):
     cmd_report path (``bin/cctally:~7969-7979``) and ``_tui_build_trend``
     (``bin/_cctally_tui.py:~1515-1524``).
 
+    ``skip_sync`` (default ``False``) threads through to
+    ``_compute_cost_for_weekref`` → ``_sum_cost_for_range`` so the
+    reset-event live-cost path can read the cache WITHOUT running a
+    JSONL ingest. The #268 dashboard/TUI sync-thread rebuild sets it
+    ``True`` (it ingests exactly once at the top of the rebuild); every
+    other caller — ``cmd_report``, ``_tui_build_trend`` panel, etc. —
+    keeps the default so their sync-on-read behavior is byte-identical.
+    At scale (~19 reset-event weeks over a 10K-file instance) the default
+    ran a full 10K-file glob PER reset week PER call site — the CPU peg
+    the #268 M1 sync-once refactor was meant to remove.
+
     Rows are emitted oldest-first (chronological); each row populates
     all 17 ``TuiTrendRow`` fields (7 historical + 10 extended).
     ``delta_dpp`` is computed against the prior chronological row's
@@ -800,7 +861,33 @@ def build_trend_view(conn, *, now_utc, n=8, display_tz=None):
         )
         usage_captured_at = usage["captured_at_utc"] if usage else None
         if c._week_ref_has_reset_event(conn, week_ref):
-            cost_usd = c._compute_cost_for_weekref(week_ref)
+            if (
+                use_weekref_cost_cache
+                and week_ref.week_start_at
+                and week_ref.week_end_at
+            ):
+                # #269 §4: a closed subscription week's cost is immutable, so
+                # route the reset-event live-cost through the shared per-weekref
+                # cache (the OPEN week is decided per call and never cached).
+                # `compute` is the from-scratch closure — invoked synchronously
+                # inside this iteration, so `week_ref` capture is safe — and
+                # `skip_sync=True` unconditionally (the dashboard already synced
+                # once at the top of the rebuild; the flag is only True there).
+                _sc = _load_lib("_lib_snapshot_cache")
+                cost_usd = _sc.cached_weekref_cost(
+                    week_start_at=parse_iso(
+                        week_ref.week_start_at, "week_start_at"
+                    ),
+                    week_end_at=parse_iso(week_ref.week_end_at, "week_end_at"),
+                    now_utc=now_utc,
+                    compute=lambda: c._compute_cost_for_weekref(
+                        week_ref, skip_sync=True
+                    ),
+                )
+            else:
+                cost_usd = c._compute_cost_for_weekref(
+                    week_ref, skip_sync=skip_sync
+                )
             cost_captured_at = (
                 usage_captured_at if cost_usd is not None else None
             )
@@ -1029,10 +1116,21 @@ class SessionsView:
     display_tz_label: str = ""
 
 
-def build_sessions_view(entries, *, now_utc, limit=None, display_tz=None, mode="auto"):
+def build_sessions_view(entries, *, now_utc, limit=None, display_tz=None,
+                        mode="auto", aggregated_override=None):
     """Build a ``SessionsView`` from joined Claude session entries
     (spec §5.5).
 
+    ``aggregated_override`` (#268 Group B): when provided, SKIP the
+    ``_aggregate_claude_sessions(entries)`` re-aggregation and use this
+    pre-aggregated ``list[ClaudeSessionUsage]`` verbatim (the caller has
+    already assembled + sorted-by-last_activity-desc the full session set
+    from the module-level ``SessionCache``). ``entries`` is then unused for
+    aggregation. The ``limit`` truncation + the per-row ``TuiSessionRow``
+    derivation below run identically over the override, so a cached rebuild
+    is byte-identical to the from-scratch pass. ``None`` (CLI ``session`` /
+    share / cold paths) is unchanged — the aggregator runs on ``entries``.
+
     ``entries`` is the ``list[_JoinedClaudeEntry]`` from
     ``get_claude_session_entries(range_start, range_end)``. The caller
     controls the date window + ``skip_sync`` semantics; the builder
@@ -1059,8 +1157,11 @@ def build_sessions_view(entries, *, now_utc, limit=None, display_tz=None, mode="
     is informational only.
     """
     import os as _os                # late: keep top-level imports lean.
-    _agg = _load_lib("_lib_aggregators")
-    aggregated = _agg._aggregate_claude_sessions(entries, mode=mode)
+    if aggregated_override is not None:
+        aggregated = list(aggregated_override)
+    else:
+        _agg = _load_lib("_lib_aggregators")
+        aggregated = _agg._aggregate_claude_sessions(entries, mode=mode)
     # Apply limit truncation up front so `rows` and `aggregated` stay
     # in lockstep (spec §4.3 invariant: `total_sessions == len(rows)
     # == len(aggregated)`). limit=None → keep everything.
@@ -1497,6 +1598,7 @@ def build_forecast_view(
     targets=(100, 90),
     skip_sync: bool = False,
     display_tz=None,
+    use_weekref_cost_cache: bool = False,
 ):
     """Build a ``ForecastView`` (issue #57).
 
@@ -1515,7 +1617,10 @@ def build_forecast_view(
     refresh skip).
     """
     c = _cctally()
-    inputs = c._load_forecast_inputs(conn, now_utc, skip_sync=skip_sync)
+    inputs = c._load_forecast_inputs(
+        conn, now_utc, skip_sync=skip_sync,
+        use_weekref_cost_cache=use_weekref_cost_cache,
+    )
     if inputs is None:
         return ForecastView(
             output=None,

package/bin/cctally

@@ -487,6 +487,26 @@ build_codex_weekly_view = _lib_view_models.build_codex_weekly_view
 CodexSessionView = _lib_view_models.CodexSessionView
 build_codex_session_view = _lib_view_models.build_codex_session_view
 
+# Snapshot-rebuild cache infrastructure (#268) — the composite data-version
+# signature, the new-entry watermark, the generation counter, the Group A/B
+# cache holders, and the Group A cached-bucket recompute helper. Registered
+# here (before _cctally_dashboard / _cctally_tui load) so those siblings can
+# `from _lib_snapshot_cache import ...` at module top under the _load_sibling
+# loader, which does not place bin/ on sys.path. _load_sibling dedups via
+# sys.modules, so this is the same instance pytest imports directly.
+_lib_snapshot_cache = _load_sibling("_lib_snapshot_cache")
+SnapshotSignature = _lib_snapshot_cache.SnapshotSignature
+compute_signature = _lib_snapshot_cache.compute_signature
+new_min_timestamp = _lib_snapshot_cache.new_min_timestamp
+bump_generation = _lib_snapshot_cache.bump_generation
+current_generation = _lib_snapshot_cache.current_generation
+BucketCache = _lib_snapshot_cache.BucketCache
+SessionCache = _lib_snapshot_cache.SessionCache
+cached_buckets = _lib_snapshot_cache.cached_buckets
+build_cached_group_a = _lib_snapshot_cache.build_cached_group_a
+group_a_cache = _lib_snapshot_cache.group_a_cache
+reset_group_a_state = _lib_snapshot_cache.reset_group_a_state
+
 _lib_render = _load_sibling("_lib_render")
 _CODEX_MONTHS = _lib_render._CODEX_MONTHS
 _render_blocks_table = _lib_render._render_blocks_table
@@ -665,6 +685,26 @@ _cctally_doctor = _load_sibling("_cctally_doctor")
 doctor_gather_state = _cctally_doctor.doctor_gather_state
 cmd_doctor = _cctally_doctor.cmd_doctor
 
+# Maintainer-local preview channel (hidden `__preview` subcommand). The pure
+# kernel `_lib_preview` loads FIRST so `_cctally_preview`'s late-bound `_lp()`
+# accessor resolves it via sys.modules; `cmd_preview` is the parser's
+# `set_defaults(func=c.cmd_preview)` target. Both modules are excluded from the
+# public mirror (maintainer-only, like the release tooling) — but the public
+# `bin/cctally` still carries THESE load lines (the mirror emits full public
+# file content on the next non-skip commit that touches this file). Tolerate
+# the modules being absent so a public npm/brew build never bricks at import:
+# on failure `cmd_preview` is None and the parser skips registering the hidden
+# `__preview` subcommand entirely (see `_cctally_parser.py`'s
+# `getattr(c, "cmd_preview", None)` guard). In the private tree the modules ARE
+# present, so this is a no-op — `cmd_preview` is defined and `__preview`
+# registers and works exactly as before.
+try:
+    _lib_preview = _load_sibling("_lib_preview")
+    _cctally_preview = _load_sibling("_cctally_preview")
+    cmd_preview = _cctally_preview.cmd_preview
+except Exception:
+    cmd_preview = None
+
 # config.json reader/writer/lock + validators + `cctally config` entry point.
 # Eager-loaded with per-symbol re-export so bare-name callers in cctally
 # (dashboard `/api/settings`, `cmd_record_usage` reading `load_config()`,
@@ -794,6 +834,9 @@ _discover_codex_session_files = _cctally_cache._discover_codex_session_files
 IngestStats = _cctally_cache.IngestStats
 _progress_stderr = _cctally_cache._progress_stderr
 _ensure_session_files_row = _cctally_cache._ensure_session_files_row
+_acquire_cache_flock = _cctally_cache._acquire_cache_flock
+PruneResult = _cctally_cache.PruneResult
+_prune_orphaned_cache_entries = _cctally_cache._prune_orphaned_cache_entries
 sync_cache = _cctally_cache.sync_cache
 backfill_conversation_messages = _cctally_cache.backfill_conversation_messages
 backfill_ai_titles = _cctally_cache.backfill_ai_titles
@@ -811,6 +854,7 @@ get_codex_entries = _cctally_cache.get_codex_entries
 _sum_codex_cost_for_range = _cctally_cache._sum_codex_cost_for_range
 get_entries = _cctally_cache.get_entries
 open_cache_db = _cctally_cache.open_cache_db
+_reset_orphan_warning_throttle = _cctally_cache._reset_orphan_warning_throttle
 cmd_cache_sync = _cctally_cache.cmd_cache_sync
 
 
@@ -1041,6 +1085,8 @@ snapshot_to_envelope = _cctally_dashboard.snapshot_to_envelope
 _session_detail_to_envelope = _cctally_dashboard._session_detail_to_envelope
 _DASHBOARD_SYNC_LOCK_TIMEOUT_SECONDS = _cctally_dashboard._DASHBOARD_SYNC_LOCK_TIMEOUT_SECONDS
 DashboardHTTPHandler = _cctally_dashboard.DashboardHTTPHandler
+_dashboard_self_heal_orphans = _cctally_dashboard._dashboard_self_heal_orphans
+_register_faulthandler_sigusr1 = _cctally_dashboard._register_faulthandler_sigusr1
 cmd_dashboard = _cctally_dashboard.cmd_dashboard
 
 
@@ -2707,6 +2753,11 @@ def main(argv: list[str] | None = None) -> int:
             base += f" (dev — {_cctally_core.APP_DIR})"
         elif _cctally_core._is_dev_checkout():
             base += f" (dev checkout, custom data dir — {_cctally_core.APP_DIR})"
+        # Preview channel (CCTALLY_CHANNEL=preview): append the channel marker
+        # so diagnostics reveal a preview-channel binary. Gated → prod output
+        # is byte-identical when the marker is unset.
+        if _cctally_core.is_preview_channel():
+            base += " (preview)"
         print(base)
         return 0
     if not getattr(args, "func", None):
@@ -2796,6 +2847,12 @@ def _post_command_update_hooks(command: str | None, args) -> None:
         return
     if command == "repair-symlinks":
         return
+    if command == "__preview":
+        # Maintainer-local dev tooling: must not load_config()/spawn a
+        # background update-check or write anything outside the preview dir
+        # (it runs before the wrapper sets CCTALLY_DATA_DIR, so APP_DIR is
+        # still cctally-dev at this point). Same rationale class as doctor.
+        return
     # Self-heal: reconcile current_version with the running binary's
     # CHANGELOG. Cheap (one CHANGELOG read, write only on the first
     # command after a manual upgrade). Runs before load_config so a