cctally 1.60.0 → 1.61.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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

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.