cctally 1.59.0 → 1.61.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.61.0] - 2026-07-05
+
+### Added
+- `cache-sync --prune-orphans` cleans up cache rows left behind when a session's transcript directory is removed — for example after you delete a git worktree — so stale sessions and projects don't linger in your reports. It's a fast, targeted alternative to a full `cache-sync --rebuild`, and only removes rows it can prove are safe to drop, leaving anything ambiguous in place.
+
+### Changed
+- The dashboard's 5-hour **Blocks** card is now a full-size half-width card the same size as the **Weekly** and **Monthly** cards, instead of a cramped third-width tile in the short bottom row where only a couple of its blocks were visible at a time. It moves up beside the other period cards — with the **Forecast** card promoted alongside it so the board stays a tidy grid — so you can see far more of the week's activity blocks at a glance, and the **Recent Alerts** card now spans the full width of the bottom row (#266).
+- The live dashboard's warm refreshes are now much faster on large, many-reset-week usage histories. A closed subscription week's totals never change, so the **$/1% Trend** card (and its weekly-history detail view), the **Forecast**, and the **Projects** panel no longer re-cost every closed week from scratch on each refresh — each closed week is computed once and reused until the underlying usage changes, and the Projects panel additionally stops re-resolving every session's project path on each refresh (it now resolves each distinct path once instead of once per session, and reuses each closed week's per-project totals), so on the largest histories the Projects rebuild drops from seconds to a fraction of a second while staying byte-for-byte identical (#269).
+
+### Fixed
+- The live dashboard no longer pegs a CPU core after long uptime or on a large usage history. It now recognises when nothing has changed since the last refresh and reuses the previous snapshot — so an idle dashboard sits near 0% CPU while its countdowns, freshness, and health checks stay live — and when new usage does land it recomputes only the current day/week/month (and the sessions that changed) instead of re-aggregating your entire history every few seconds, so each refresh stays fast even at hundreds of thousands of sessions (#268).
+- The dashboard now cleans up cache rows left behind by removed session directories (such as a deleted git worktree) on its own — once at startup and periodically while running — so those stale rows no longer linger until a manual rebuild, and the `[cache] N tracked file(s) no longer on disk` warning no longer repeats every few seconds.
+- `cache-sync --rebuild` now waits for the cache lock (up to 30 seconds) and reports a non-zero exit when it still can't acquire it, instead of silently doing nothing and reporting success while a dashboard is actively syncing.
+
+## [1.60.0] - 2026-07-03
+
+### Changed
+- Dashboard **Recent Sessions** is denser and more useful. When every recent session uses the same model, the redundant per-row model column is dropped entirely — it previously rendered as a column of dots under a still-labelled "Model" header, which read as broken — and a single "all · model" caption in the header says it instead; a mixed set of models still shows the column. Two columns that carry real signal take its place: a **Session** title for each row (its first prompt, or an AI-generated summary when one exists) and a **Cache** hit-rate. The title is private conversation content, so it appears only when transcript viewing is enabled for how you reached the dashboard (on your own machine, or on the LAN only if you have explicitly exposed transcripts) and shows a dash otherwise. All the columns now fit at a common laptop width without sideways scrolling, and a long title shortens with the full text available on hover (#264).
+- Dashboard **$/1% Trend** detail view reads better and gains a cost column. When there is too little history to compute a four-week median, the two formerly-empty "—" median tiles collapse into a single "needs 4 weeks" hint instead of looking broken. The weekly table gains a sortable **Cost** column (what you spent that week) and the whole view opens in a wider two-pane layout — the chart and its headline numbers on the left, the sortable weekly table on the right — so it fills the space instead of stacking tall and scrolling; sorting the table reorders only the pop-up, not the small card behind it (#264).
+- The dashboard's usage history is split back into three independent **Daily**, **Weekly**, and **Monthly** cards, each opening its own detail view — undoing an earlier consolidation that folded them into a single "History" card and hid Weekly and Monthly behind an easy-to-miss Day/Week/Month toggle. Every card now has a discoverable header and a keyboard shortcut, and the Weekly and Monthly views open in a wider two-pane layout — the period navigator across the top, the selected period's model-and-token breakdown on the left, and a sortable table of every period on the right — so the full history fits without scrolling. The daily heatmap still deep-links a clicked day straight into the Daily view (#264).
+- Dashboard board and hero redesigned to fix the wasted space the previous facelift left behind. The board is now a content-aware **bento grid** — cards sit in height-matched rows sized to their content and the layout goes full-width (fluid up to 2100px) instead of capping at 1600px — so a wide screen fills with data instead of stranding a tall column of half-empty full-width cards, roughly halving the page height, while still collapsing to a single column on mobile and keeping drag-to-reorder within each row. The hero is rebuilt into three zones so the two questions you actually ask each get a dominant number: weekly usage % (with 5-hour usage paired beside it and the reset countdown) and dollars spent this week (with $/1% as its sub-line), alongside a compact support column for the end-of-week forecast, the week-over-week $/1% trend, and a snapshot-freshness reading that now stays calm for a normal few-minute-old snapshot and only turns amber, then red, once the data is genuinely stale. Every card also gains a consistent ⤢ expand control in its header to open its detail view (previously some cards signalled "open" only via the share icon, and the Blocks card had no click-to-open at all), the Forecast card gains a pace bar toward its 100% cap, and the empty Alerts card shows a teaching gauge of your current usage against the configured alert thresholds (#264).
+- Dashboard desktop board fixes that finish the bento redesign. Cards whose content is taller than their row now scroll inside their own frame instead of overflowing and rendering on top of the card below them — previously the $/1% Trend chart could spill over the Daily card beneath it, and the Weekly and Monthly cards did the same. The 5-hour **Blocks** card now shows every block for the week (scroll inside the card to reach them all) instead of only the three most recent with no way to see the rest. The **Daily** heatmap shows each day's dollar amount again on the card, not just in its detail view. And the per-card collapse arrow — which did nothing on desktop once the board became height-matched — is removed there (the ⤢ expand control opens each card's detail); it still works on smaller stacked screens (#264).
+- Dashboard mobile fixes. The **Recent Sessions** panel title is no longer crushed to nothing on a phone; each session in the list now leads with its title (what the session was about) instead of hiding it; the at-a-glance hero is a compact card rather than three tall stacked zones; and the Daily card title no longer clips (#264).
+
+### Fixed
+- Dashboard: the empty **Recent Alerts** card no longer sits bottom-heavy with a band of empty space above it — it now shows the same "you're clear" gauge as the alerts detail view (your current usage against the configured alert thresholds), centered and sized to the card, so it reads as balanced as its Forecast and Blocks neighbours (#265).
+- Dashboard: the **$/1% Trend** card keeps its sparkline and "older ▸ newer" legend pinned in view and scrolls the weekly table beneath them, so with only a few weeks of history the chart is no longer half-hidden below the card's internal scroll fold (#265).
+- Dashboard: the **Blocks** card's expand (⤢) control is now disabled on a week with no activity blocks yet, instead of looking clickable but opening nothing when pressed (#265).
+- Dashboard: the **Weekly** and **Monthly** cards now list every week and month and scroll within the card, instead of showing only the three most recent behind a scrollbar that revealed nothing more — so the whole history is reachable without opening the detail view (#265).
+- Dashboard: the **Daily** heatmap no longer clips the top off each day-of-month number — the card row is a little taller so every day's number and its dollar amount are fully legible (#265).
+
 ## [1.59.0] - 2026-07-02
 
 ### Changed

package/bin/_cctally_cache.py

@@ -106,6 +106,7 @@ import os
 import pathlib
 import sqlite3
 import sys
+import time
 from dataclasses import dataclass, field
 from typing import Any, Callable, Iterator
 
@@ -341,22 +342,40 @@ def _resolve_project_key(
             is_unknown=True,
         )
 
+    # Win 1 (#269 §14, Codex-M4 P1): raw-`project_path` fast path. The
+    # normalized cache is keyed on ``os.path.realpath(...)``, so on the base
+    # code the expensive realpath/lstat walk runs once per ENTRY (~190K on a
+    # large instance) rather than once per DISTINCT raw spelling (~10K). A
+    # namespaced raw key (``("raw", project_path)``) — a tuple that can never
+    # collide with the normalized string keys — short-circuits the common case
+    # (the same raw spelling repeated across a project's entries). This does
+    # NOT replace the normalized cache: a raw MISS still consults/populates the
+    # normalized entry, so ``mode="full-path"`` symlink-alias collapse to the
+    # first spelling seen is preserved (a second alias misses the raw fast
+    # path, hits the normalized entry, and returns the first spelling's key).
+    # Byte-identical for ALL modes.
+    raw_key = ("raw", project_path)
+    raw_hit = cache.get(raw_key)
+    if raw_hit is not None:
+        return raw_hit
+
     if mode == "full-path":
         normalized = os.path.realpath(os.path.expanduser(project_path))
         key = cache.get(normalized)
-        if key is not None:
-            return key
-        key = ProjectKey(
-            bucket_path=normalized,
-            display_key=project_path,   # raw, so user sees what they typed
-            git_root=None,
-        )
-        cache[normalized] = key
+        if key is None:
+            key = ProjectKey(
+                bucket_path=normalized,
+                display_key=project_path,   # raw, so user sees what they typed
+                git_root=None,
+            )
+            cache[normalized] = key
+        cache[raw_key] = key
         return key
 
     normalized = os.path.realpath(os.path.expanduser(project_path))
     cached = cache.get(normalized)
     if cached is not None:
+        cache[raw_key] = cached
         return cached
 
     home = os.path.expanduser("~")
@@ -371,6 +390,7 @@ def _resolve_project_key(
                 git_root=cur,
             )
             cache[normalized] = key
+            cache[raw_key] = key
             return key
         cur = os.path.dirname(cur)
 
@@ -381,6 +401,7 @@ def _resolve_project_key(
         is_no_git=True,
     )
     cache[normalized] = key
+    cache[raw_key] = key
     return key
 
 
@@ -481,6 +502,19 @@ class IngestStats:
                 and self.files_failed == 0)
 
 
+@dataclass
+class PruneResult:
+    """Outcome of _prune_orphaned_cache_entries: how much of the derived Claude
+    surface was removed for safely-orphaned source paths, plus the orphan paths
+    left in place (residual — a gate failed, so `--rebuild` is the escape hatch)
+    and whether the flock was contended (nothing mutated)."""
+    pruned_files: int = 0
+    pruned_entries: int = 0
+    pruned_messages: int = 0
+    residual_paths: "list[str]" = field(default_factory=list)
+    contended: bool = False
+
+
 def _progress_stderr(stats: IngestStats, *, force: bool = False) -> None:
     """Default stderr progress callback. Every 200 files or when forced."""
     if not force and stats.files_processed % 200 != 0:
@@ -577,6 +611,25 @@ def _ensure_session_files_row(conn: sqlite3.Connection, source_path: str) -> Non
     conn.commit()
 
 
+# How long `cache-sync --rebuild` (and the --prune-orphans path) waits on the
+# cache.db flock before giving up. Routine auto-syncs stay non-blocking
+# (lock_timeout=None); an explicit rebuild is worth a bounded wait so a running
+# dashboard's background tick doesn't turn the rebuild into a silent no-op.
+# Read at call time in cmd_cache_sync so tests can monkeypatch it low.
+_REBUILD_LOCK_TIMEOUT_SECONDS = 30.0
+
+
+# Orphan-warning throttle: warn only when the detected orphan set CHANGES,
+# so a long-lived dashboard doesn't re-spam the "[cache] N tracked file(s) no
+# longer on disk" line every ~5s sync tick. Reset in tests.
+_LAST_WARNED_ORPHAN_SET: "frozenset[str]" = frozenset()
+
+
+def _reset_orphan_warning_throttle():
+    global _LAST_WARNED_ORPHAN_SET
+    _LAST_WARNED_ORPHAN_SET = frozenset()
+
+
 # Flags whose presence means the cache is mid-migration / mid-reingest. A
 # targeted (only_paths) ingest DECLINES when any is set and defers to the next
 # full background sync — inserting through a half-migrated FTS shape or skipping
@@ -612,12 +665,153 @@ def _targeted_has_pending_global_work(conn) -> bool:
     return row is not None
 
 
+def _acquire_cache_flock(lock_fh, *, timeout):
+    """Acquire the exclusive cache flock on ``lock_fh``.
+
+    ``timeout is None`` -> a single non-blocking attempt (today's behavior
+    for routine auto-syncs): returns False immediately on contention.
+    ``timeout > 0`` -> retry ``LOCK_NB`` every ~0.2s until acquired or the
+    deadline elapses. Returns True iff the lock is held on return.
+
+    A retry-with-sleep loop, NOT a SIGALRM-based blocking LOCK_EX: the
+    dashboard runs its sync on a background thread, where Python signals
+    never fire, so an alarm timeout would silently never trip.
+    """
+    deadline = None if timeout is None else (time.monotonic() + timeout)
+    while True:
+        try:
+            fcntl.flock(lock_fh, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            return True
+        except BlockingIOError:
+            if deadline is None or time.monotonic() >= deadline:
+                return False
+            time.sleep(0.2)
+
+
+def _prune_orphaned_cache_entries(conn, *, lock_timeout=None):
+    """Safely prune the FULL derived Claude cache surface for orphaned
+    (removed-from-disk) source paths. See the design spec
+    docs/superpowers/specs/2026-07-04-cache-orphan-prune-design.md §2.
+
+    Kept OUT of the shared sync_cache (which stays detect-only, fixture-safe):
+    only real runtimes call this — the CLI cache-sync --prune-orphans and the
+    dashboard self-heal — so synthetic /fake/… fixture paths never reach it.
+
+    Three gates decide safety per orphan path P (session_id sid):
+      A) sid is non-null and not shared by any surviving on-disk file
+         (cheap prefilter; "same session_id" is empirical, not proof).
+      B) coverage: every one of P's session_entries (msg_id, req_id) keys
+         has a conversation_messages row under P's OWN source_path (else
+         it is a uuid-less blind spot -> unprovable -> residual).
+      C) disjointness: none of P's keys appears in conversation_messages
+         under a surviving on-disk source_path (a survivor physically holds
+         the same turn -> deleting P's deduped cost row would lose it).
+    Anything failing A/B/C is left as residual (reported; for `--rebuild`).
+
+    Deletes the full derived surface for the safe set in ONE transaction
+    (conversation_file_touches -> conversation_messages [+FTS trigger] ->
+    conversation_ai_titles [+FTS trigger] -> session_entries -> session_files),
+    then recomputes the conversation_sessions rollup for exactly the pruned
+    session_ids (all their messages gone -> the stale rail rows drop). Does NOT
+    write the walk-complete marker: the next full sync_cache re-establishes it
+    on a clean walk. Acquires the cache.db.lock flock itself; a contended
+    lock_timeout returns a `contended` result without mutating.
+    """
+    result = PruneResult()
+    _cctally_core.APP_DIR.mkdir(parents=True, exist_ok=True)
+    _cctally_core.CACHE_LOCK_PATH.touch()
+    lock_fh = open(_cctally_core.CACHE_LOCK_PATH, "w")
+    try:
+        if not _acquire_cache_flock(lock_fh, timeout=lock_timeout):
+            result.contended = True
+            return result
+
+        tracked = conn.execute(
+            "SELECT path, size_bytes, session_id FROM session_files").fetchall()
+        on_disk = {p for (p, _sz, _sid) in tracked if os.path.isfile(p)}
+        surviving_sids = {sid for (p, _sz, sid) in tracked
+                          if p in on_disk and sid is not None}
+        orphan_cands = [(p, sid) for (p, sz, sid) in tracked
+                        if sz and p not in on_disk]
+        if not orphan_cands:
+            return result
+
+        safe_paths = []
+        pruned_sids = set()
+        for path, sid in orphan_cands:
+            if sid is None or sid in surviving_sids:          # Gate A
+                result.residual_paths.append(path)
+                continue
+            keys = conn.execute(
+                "SELECT DISTINCT msg_id, req_id FROM session_entries "
+                "WHERE source_path=? AND msg_id IS NOT NULL AND req_id IS NOT NULL",
+                (path,)).fetchall()
+            ok = True
+            for mid, rid in keys:
+                covered = conn.execute(                        # Gate B
+                    "SELECT 1 FROM conversation_messages "
+                    "WHERE msg_id=? AND req_id=? AND source_path=? LIMIT 1",
+                    (mid, rid, path)).fetchone() is not None
+                if not covered:
+                    ok = False
+                    break
+                shared = conn.execute(                         # Gate C
+                    "SELECT source_path FROM conversation_messages "
+                    "WHERE msg_id=? AND req_id=?", (mid, rid)).fetchall()
+                if any(sp in on_disk for (sp,) in shared):
+                    ok = False
+                    break
+            if not ok:
+                result.residual_paths.append(path)
+                continue
+            safe_paths.append(path)
+            pruned_sids.add(sid)
+
+        if not safe_paths:
+            return result
+
+        # No IN(...) chunking: safe_paths is bounded by the orphan count (a
+        # handful of removed files), well under SQLite's variable limit;
+        # _recompute_conversation_sessions chunks its own session-id list.
+        ph = ",".join("?" * len(safe_paths))
+        result.pruned_messages = conn.execute(
+            f"SELECT count(*) FROM conversation_messages WHERE source_path IN ({ph})",
+            safe_paths).fetchone()[0]
+        conn.execute("BEGIN")
+        try:
+            conn.execute(
+                f"DELETE FROM conversation_file_touches WHERE message_id IN "
+                f"(SELECT id FROM conversation_messages WHERE source_path IN ({ph}))",
+                safe_paths)
+            conn.execute(
+                f"DELETE FROM conversation_messages WHERE source_path IN ({ph})", safe_paths)
+            conn.execute(
+                f"DELETE FROM conversation_ai_titles WHERE source_path IN ({ph})", safe_paths)
+            result.pruned_entries = conn.execute(
+                f"DELETE FROM session_entries WHERE source_path IN ({ph})", safe_paths).rowcount
+            result.pruned_files = conn.execute(
+                f"DELETE FROM session_files WHERE path IN ({ph})", safe_paths).rowcount
+            _recompute_conversation_sessions(conn, list(pruned_sids))
+            conn.commit()
+        except BaseException:
+            conn.rollback()
+            raise
+        return result
+    finally:
+        try:
+            fcntl.flock(lock_fh, fcntl.LOCK_UN)
+        except OSError:
+            pass
+        lock_fh.close()
+
+
 def sync_cache(
     conn: sqlite3.Connection,
     *,
     progress: Callable[[IngestStats], None] | None = None,
     rebuild: bool = False,
     only_paths: "set[str] | None" = None,
+    lock_timeout: "float | None" = None,
 ) -> IngestStats:
     """Read-through delta ingest. Acquires an exclusive fcntl.flock; if
     another process holds it, returns immediately with lock_contended=True
@@ -635,9 +829,7 @@ def sync_cache(
 
     lock_fh = open(_cctally_core.CACHE_LOCK_PATH, "w")
     try:
-        try:
-            fcntl.flock(lock_fh, fcntl.LOCK_EX | fcntl.LOCK_NB)
-        except BlockingIOError:
+        if not _acquire_cache_flock(lock_fh, timeout=lock_timeout):
             eprint("[cache] sync already in progress; using existing cache")
             stats.lock_contended = True
             return stats
@@ -994,27 +1186,46 @@ def sync_cache(
         # tracked in session_files (with data already ingested) but no
         # longer present on disk leaves orphaned session_entries rows that
         # the per-file loop below never visits — it iterates only on-disk
-        # `paths`. sync_cache deliberately does NOT prune those orphans
-        # in-place: a deleted file shares the truncation hazard (under the
-        # sticky source_path dedup a surviving file may carry the same
-        # (msg_id, req_id) yet keep its size_bytes, so a per-orphan DELETE
-        # could drop a row the survivor still owns without re-ingesting
-        # it), and a blanket full-reset would wrongly fire on the
-        # legitimate "cache seeded with synthetic source paths" fixture
-        # pattern. Instead we INVALIDATE the walk-complete marker: an
-        # orphaned cache no longer faithfully mirrors disk, so it is — by
-        # the marker's own definition — not a complete walk. We must
-        # actively DELETE any marker a PRIOR clean walk left behind (not
-        # merely withhold THIS run's end-of-loop rewrite — that rewrite is
-        # gated on walk_clean, but a stale marker from a previous sync
-        # would otherwise survive and keep vouching for completeness).
-        # Setting walk_clean=False additionally suppresses the end-of-loop
-        # rewrite so the marker stays absent for this run. With the marker
-        # gone the upgrade gate DEFERs the 008/009/010 recomputes (rather
-        # than certifying aggregates that still include data from files no
-        # longer on disk); the operator clears the orphans by running
-        # `cache-sync --rebuild` (the documented re-derive path), which
-        # re-establishes the marker. Only paths whose row carried ingested
+        # `paths`. sync_cache stays DETECT-ONLY here — it never prunes
+        # orphans in-place. Two reasons it must not delete from this hot,
+        # shared path: (1) the truncation hazard — under the sticky
+        # source_path dedup a surviving file may carry the same
+        # (msg_id, req_id) yet keep its size_bytes, so a naive per-orphan
+        # DELETE could drop a deduped cost row the survivor still owns
+        # without re-ingesting it; (2) fixture safety — a blanket full-reset
+        # would wrongly fire on the legitimate "cache seeded with synthetic
+        # source paths" fixture pattern, and only sync_cache runs against
+        # those fixtures. So detection does two things and no more: it emits
+        # a THROTTLED warning (once per distinct orphan set — a removed
+        # worktree persists, so an unthrottled warn would re-spam every
+        # dashboard tick) and it INVALIDATES the walk-complete marker. An
+        # orphaned cache no longer faithfully mirrors disk, so it is — by the
+        # marker's own definition — not a complete walk. We actively DELETE
+        # any marker a PRIOR clean walk left behind (idempotently — only when
+        # one exists, so a repeated orphaned sync doesn't churn a no-op write
+        # txn every tick); merely withholding THIS run's end-of-loop rewrite
+        # is not enough, since a stale marker from a previous sync would
+        # otherwise survive and keep vouching for completeness. Setting
+        # walk_clean=False additionally suppresses the end-of-loop rewrite so
+        # the marker stays absent for this run. With the marker gone the
+        # upgrade gate DEFERs the 008/009/010 recomputes (rather than
+        # certifying aggregates that still include data from files no longer
+        # on disk). The safe CLEANUP lives OUT of sync_cache, in
+        # _prune_orphaned_cache_entries — it re-derives the safe orphan set
+        # independently and removes the full derived surface under three
+        # gates: A (session-id not shared by a survivor), B (coverage — every
+        # orphan (msg_id, req_id) key has a conversation_messages row under
+        # the orphan's OWN path), and C (disjointness — no key of the orphan
+        # appears in conversation_messages under a surviving path). B + C
+        # together close the truncation hazard soundly: C refuses to delete
+        # any key a survivor physically holds, and B refuses the uuid-less
+        # blind spot where coverage can't be proved (anything failing A/B/C
+        # is left as residual, cleared by `--rebuild`). That helper is
+        # invoked by `cache-sync --prune-orphans` and the dashboard
+        # self-heal, never from here (so fixtures never reach a destructive
+        # delete); `cache-sync --rebuild` remains the whole-cache re-derive.
+        # Both cleanup paths re-establish the marker on the next clean walk.
+        # Only paths whose row carried ingested
         # bytes (size_bytes > 0) count — a size_bytes=0 row holds no
         # session_entries, so its absence leaves no orphan. The DELETE +
         # commit lands BEFORE the per-file read+parse loop, so no write
@@ -1027,22 +1238,43 @@ def sync_cache(
         # for targeted: the live-tail fast path never prunes orphans (the full
         # background sync owns that).
         if not targeted:
+            global _LAST_WARNED_ORPHAN_SET
             on_disk_paths = {str(jp) for jp in paths}
             orphaned_tracked_paths = [
                 p for p, (size_bytes, _, _) in existing.items()
                 if size_bytes and p not in on_disk_paths
             ]
             if orphaned_tracked_paths:
-                eprint(
-                    f"[cache] {len(orphaned_tracked_paths)} tracked file(s) no "
-                    f"longer on disk; invalidating walk-complete marker "
-                    f"(run `cache-sync --rebuild` to prune orphaned entries)"
-                )
-                conn.execute(
-                    "DELETE FROM cache_meta WHERE key='claude_ingest_walk_complete'"
-                )
-                conn.commit()
+                # Throttle the warning: emit only when the orphan set CHANGES,
+                # not on every ~5s dashboard tick (a removed worktree persists,
+                # so an unthrottled warn re-spams indefinitely). The marker
+                # invalidation below stays UNCONDITIONAL — throttling the print
+                # must not weaken the D5a invariant.
+                cur = frozenset(orphaned_tracked_paths)
+                if cur != _LAST_WARNED_ORPHAN_SET:
+                    eprint(
+                        f"[cache] {len(orphaned_tracked_paths)} tracked file(s) no "
+                        f"longer on disk; invalidating walk-complete marker "
+                        f"(run `cache-sync --prune-orphans` to prune, or "
+                        f"`cache-sync --rebuild`)"
+                    )
+                    _LAST_WARNED_ORPHAN_SET = cur
+                # Idempotent marker invalidation: only DELETE (and commit) when a
+                # prior clean walk actually left the marker behind, so a repeated
+                # orphaned sync doesn't churn a no-op write transaction every tick.
+                if conn.execute(
+                    "SELECT 1 FROM cache_meta WHERE key='claude_ingest_walk_complete'"
+                ).fetchone() is not None:
+                    conn.execute(
+                        "DELETE FROM cache_meta WHERE key='claude_ingest_walk_complete'"
+                    )
+                    conn.commit()
                 walk_clean = False  # orphaned rows -> cache doesn't mirror disk (D5a)
+            else:
+                # No orphans this walk: clear the throttle memory so a LATER,
+                # distinct orphan episode (even one recreated at the same paths)
+                # warns again rather than being silently suppressed.
+                _LAST_WARNED_ORPHAN_SET = frozenset()
 
         # Pre-scan for any truncation among tracked files. Under the
         # ccusage-parity ON CONFLICT DO UPDATE, source_path is PINNED to
@@ -2429,6 +2661,7 @@ def sync_codex_cache(
     *,
     progress: Callable[[CodexIngestStats], None] | None = None,
     rebuild: bool = False,
+    lock_timeout: "float | None" = None,
 ) -> CodexIngestStats:
     """Read-through delta ingest of ~/.codex/sessions/**/*.jsonl.
 
@@ -2448,9 +2681,7 @@ def sync_codex_cache(
 
     lock_fh = open(_cctally_core.CACHE_LOCK_CODEX_PATH, "w")
     try:
-        try:
-            fcntl.flock(lock_fh, fcntl.LOCK_EX | fcntl.LOCK_NB)
-        except BlockingIOError:
+        if not _acquire_cache_flock(lock_fh, timeout=lock_timeout):
             eprint("[codex-cache] sync already in progress; using existing cache")
             stats.lock_contended = True
             return stats
@@ -2991,20 +3222,63 @@ def cmd_cache_sync(args: argparse.Namespace) -> int:
     source = getattr(args, "source", "all")
     conn = open_cache_db()
 
+    # --prune-orphans: fast, targeted cleanup of cache rows whose source
+    # JSONL was removed from disk (e.g. a deleted git worktree), without a
+    # full rebuild. Claude-only surface; runs the three-gate safe helper.
+    if getattr(args, "prune_orphans", False):
+        if source == "codex":
+            # The prune surface is Claude-only; Codex orphans are pruned
+            # automatically during codex sync (see sync_codex_cache). Respect
+            # the explicit --source codex rather than silently pruning Claude.
+            eprint(
+                "[cache-sync] --prune-orphans applies to the Claude cache only "
+                "(Codex orphans are pruned automatically during codex sync); "
+                "nothing to do for --source codex."
+            )
+            return 0
+        res = _prune_orphaned_cache_entries(
+            conn, lock_timeout=_REBUILD_LOCK_TIMEOUT_SECONDS
+        )
+        if res.contended:
+            eprint(
+                "[cache-sync] prune-orphans skipped: "
+                "another process holds the lock"
+            )
+            return 1
+        eprint(
+            f"[cache-sync] pruned {res.pruned_files} orphaned file(s), "
+            f"{res.pruned_entries} cost row(s), {res.pruned_messages} message(s)"
+        )
+        if res.residual_paths:
+            eprint(
+                f"[cache-sync] {len(res.residual_paths)} orphan(s) left in place "
+                f"(shared session or missing conversation evidence); "
+                f"run `cache-sync --rebuild` to clear them"
+            )
+        return 0
+
     # Note: when --rebuild is set we delegate the DELETE to sync_cache /
     # sync_codex_cache, which execute it AFTER acquiring the flock. A
     # pre-sync DELETE here would wipe the cache even when the subsequent
     # sync loses the lock race and bails — leaving the user with empty
-    # state. See sync_cache() / sync_codex_cache() docstrings.
+    # state. See sync_cache() / sync_codex_cache() docstrings. A rebuild
+    # is worth a bounded wait on the flock (vs the non-blocking auto-sync)
+    # so a running dashboard's background tick doesn't silently no-op it;
+    # if it still can't acquire, we report + exit non-zero rather than lie.
+    lt = _REBUILD_LOCK_TIMEOUT_SECONDS if args.rebuild else None
+    contended = False
 
     if source in ("claude", "all"):
-        stats = sync_cache(conn, progress=_progress_stderr, rebuild=args.rebuild)
+        stats = sync_cache(
+            conn, progress=_progress_stderr, rebuild=args.rebuild, lock_timeout=lt
+        )
         _progress_stderr(stats, force=True)
         if stats.lock_contended and args.rebuild:
             eprint(
                 "[cache-sync] rebuild skipped (claude): "
                 "another process holds the lock"
             )
+            contended = True
         elif not stats.lock_contended:
             eprint(
                 f"[cache-sync] claude done: {stats.files_processed} processed, "
@@ -3015,7 +3289,7 @@ def cmd_cache_sync(args: argparse.Namespace) -> int:
 
     if source in ("codex", "all"):
         stats = sync_codex_cache(
-            conn, progress=_progress_codex_stderr, rebuild=args.rebuild
+            conn, progress=_progress_codex_stderr, rebuild=args.rebuild, lock_timeout=lt
         )
         _progress_codex_stderr(stats, force=True)
         if stats.lock_contended and args.rebuild:
@@ -3023,6 +3297,7 @@ def cmd_cache_sync(args: argparse.Namespace) -> int:
                 "[cache-sync] rebuild skipped (codex): "
                 "another process holds the lock"
             )
+            contended = True
         elif not stats.lock_contended:
             eprint(
                 f"[cache-sync] codex done: {stats.files_processed} processed, "
@@ -3031,4 +3306,4 @@ def cmd_cache_sync(args: argparse.Namespace) -> int:
                 f"{stats.rows_changed} rows changed"
             )
 
-    return 0
+    return 1 if contended else 0

package/bin/_cctally_core.py

@@ -160,6 +160,14 @@ def _is_dev_checkout() -> bool:
     return (_repo_root() / ".git").exists()
 
 
+def is_preview_channel() -> bool:
+    """True when running under the maintainer-local preview channel
+    (the `cctally-preview` wrapper sets CCTALLY_CHANNEL=preview). Single
+    source of truth for every preview-marker surface (dashboard port +
+    envelope, TUI header, --version, doctor) so the gate can't drift."""
+    return os.environ.get("CCTALLY_CHANNEL") == "preview"
+
+
 def _real_prod_data_dir() -> pathlib.Path:
     """The REAL user's prod data dir (~/.local/share/cctally), resolved from
     the password database rather than $HOME so it is immune to a faked HOME.