cctally 1.60.0 → 1.62.0

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,181 @@ 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 _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,
     *,
     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 +857,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 +1214,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 +1266,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
@@ -1261,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
@@ -1290,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
@@ -1303,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)
@@ -1319,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
@@ -2070,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):
@@ -2096,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,
@@ -2230,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()
 
@@ -2429,6 +2811,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 +2831,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 +3372,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 +3439,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 +3447,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 +3456,4 @@ def cmd_cache_sync(args: argparse.Namespace) -> int:
                 f"{stats.rows_changed} rows changed"
             )
 
-    return 0
+    return 1 if contended else 0