cctally 1.60.0 → 1.62.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_doctor.py

@@ -516,6 +516,8 @@ def doctor_gather_state(
         dev_mode=_cctally_core.DEV_MODE,
         app_dir=str(_cctally_core.APP_DIR),
         is_dev_checkout=_cctally_core._is_dev_checkout(),
+        # Preview channel (CCTALLY_CHANNEL=preview): surfaced in install.mode.
+        channel=("preview" if _cctally_core.is_preview_channel() else "prod"),
         # Pricing-freshness check (spec §5.1): trailing-30d coverage gaps.
         pricing_coverage=pricing_coverage,
         # Conversation-sessions rollup consistency (#217 S1 / U9).

package/bin/_cctally_forecast.py

@@ -327,6 +327,7 @@ def _select_dollars_per_percent(
     spent_usd: float,
     *,
     skip_sync: bool = False,
+    use_weekref_cost_cache: bool = False,
 ) -> tuple[float, str]:
     """Return (dollars_per_percent, source_label). See spec §1 selection rule.
 
@@ -375,7 +376,26 @@ def _select_dollars_per_percent(
         import statistics
         values: list[float] = []
         for ws, we, final_pct in prior:
-            week_cost = c._sum_cost_for_range(ws, we, mode="auto", skip_sync=skip_sync)
+            if use_weekref_cost_cache:
+                # #269 §4: every `prior` week satisfies `we < now_utc` (an
+                # eligibility filter above), so all four are CLOSED and
+                # cacheable — this is the SAME immutable per-weekref cost the
+                # trend builder caches (B1↔B3 shared key). The `ws=ws, we=we`
+                # default-arg capture pins the loop variables (the closure is
+                # invoked lazily inside cached_weekref_cost). `skip_sync=True`
+                # unconditionally (the dashboard synced once at the top of the
+                # rebuild; the flag is only True there).
+                _sc = c._load_sibling("_lib_snapshot_cache")
+                week_cost = _sc.cached_weekref_cost(
+                    week_start_at=ws, week_end_at=we, now_utc=now_utc,
+                    compute=lambda ws=ws, we=we: c._sum_cost_for_range(
+                        ws, we, mode="auto", skip_sync=True
+                    ),
+                )
+            else:
+                week_cost = c._sum_cost_for_range(
+                    ws, we, mode="auto", skip_sync=skip_sync
+                )
             values.append(week_cost / final_pct)
         return statistics.median(values), "trailing_4wk_median"
 
@@ -422,6 +442,7 @@ def _load_forecast_inputs(
     now_utc: dt.datetime,
     *,
     skip_sync: bool = False,
+    use_weekref_cost_cache: bool = False,
 ) -> ForecastInputs | None:
     """Gather everything from the DB. Returns None if no current-week snapshot.
 
@@ -466,7 +487,8 @@ def _load_forecast_inputs(
     # re-syncs in downstream cost lookups (trailing-4wk-median loop hits
     # _sum_cost_for_range once per historical week).
     dpp, dpp_source = _select_dollars_per_percent(
-        conn, now_utc, week_start_at, p_now, spent_usd, skip_sync=True
+        conn, now_utc, week_start_at, p_now, spent_usd, skip_sync=True,
+        use_weekref_cost_cache=use_weekref_cost_cache,
     )
     confidence, reasons = _assess_forecast_confidence(elapsed_hours, p_now, len(samples))
     target_24h = now_utc - dt.timedelta(hours=24)

package/bin/_cctally_parser.py

@@ -1523,8 +1523,8 @@ def build_parser() -> argparse.ArgumentParser:
     dp.add_argument(
         "--port",
         type=int,
-        default=8789,
-        help="TCP port to bind (default: 8789).",
+        default=None,
+        help="TCP port to bind (default: 8789; 8790 under the preview channel).",
     )
     dp.add_argument(
         "--host",
@@ -1960,6 +1960,12 @@ def build_parser() -> argparse.ArgumentParser:
         default="all",
         help="Which ingest half to sync/rebuild (default: all).",
     )
+    p_cache_sync.add_argument(
+        "--prune-orphans",
+        action="store_true",
+        help="Prune cache rows for source files removed from disk "
+             "(e.g. a deleted git worktree) without a full rebuild.",
+    )
     p_cache_sync.set_defaults(func=c.cmd_cache_sync)
 
     # -- daily --
@@ -2533,6 +2539,26 @@ def build_parser() -> argparse.ArgumentParser:
                     help=argparse.SUPPRESS)  # JSON string fed to mock fetch (tests only)
     ht.set_defaults(func=c.cmd_hook_tick)
 
+    # ---- __preview (internal — maintainer-local preview channel) ----
+    # The preview modules are maintainer-only (excluded from the public
+    # mirror). On a public build `c.cmd_preview` is None — its load in
+    # bin/cctally is wrapped in a tolerant try/except — so skip registering
+    # the hidden subcommand entirely rather than wiring a None handler.
+    if getattr(c, "cmd_preview", None) is not None:
+        pv = sub.add_parser("__preview", help=argparse.SUPPRESS,
+                            formatter_class=CLIHelpFormatter,
+                            description="Internal: provision/manage the preview-channel data dir.")
+        pv_sub = pv.add_subparsers(dest="action", required=True)
+        pv_ensure = pv_sub.add_parser("ensure", help=argparse.SUPPRESS)
+        pv_ensure.add_argument("--no-refresh", action="store_true")
+        pv_ensure.add_argument("--reseed", action="store_true")
+        pv_ensure.set_defaults(func=c.cmd_preview)
+        pv_clean = pv_sub.add_parser("clean", help=argparse.SUPPRESS)
+        pv_clean.add_argument("--dry-run", action="store_true")
+        pv_clean.set_defaults(func=c.cmd_preview)
+        pv_status = pv_sub.add_parser("status", help=argparse.SUPPRESS)
+        pv_status.set_defaults(func=c.cmd_preview)
+
     # ---- update (user-facing self-update subcommand; spec §4) ----
     sub_update = sub.add_parser(
         "update",