cctally 1.45.0 → 1.46.0

package/CHANGELOG.md

@@ -5,6 +5,11 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.46.0] - 2026-06-15
+
+### Added
+- Conversation viewer: the open reader now live-tails an active conversation in near-real time — new turns appear within about a second of the session's file changing (instead of waiting for the periodic 5-second dashboard tick) via a dedicated per-conversation SSE stream that watches only the open session's transcript; the live-tail is on by default and can be turned off with the new `dashboard.live_tail` config key (or the dashboard's Settings → "Conversation viewer" toggle), and `--no-sync` keeps it passive so frozen-data debugging is unaffected.
+
 ## [1.45.0] - 2026-06-15
 
 ### Added

package/bin/_cctally_cache.py

@@ -465,6 +465,20 @@ class IngestStats:
     # new inserts.
     rows_changed: int = 0
     lock_contended: bool = False
+    # Targeted (only_paths) live-tail fast-path fields. Default-clean so the
+    # only_paths=None callers (every existing caller) read targeted_clean=True
+    # and are otherwise unaffected.
+    files_failed: int = 0
+    deferred_reason: "str | None" = None
+
+    @property
+    def targeted_clean(self) -> bool:
+        """True ⇔ a targeted ingest fully applied: not contended, not deferred,
+        and no per-file failure. The watch loop emits + advances `seen` only
+        when this is True."""
+        return (not self.lock_contended
+                and self.deferred_reason is None
+                and self.files_failed == 0)
 
 
 def _progress_stderr(stats: IngestStats, *, force: bool = False) -> None:
@@ -563,11 +577,43 @@ def _ensure_session_files_row(conn: sqlite3.Connection, source_path: str) -> Non
     conn.commit()
 
 
+# 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
+# a pending backfill would diverge from what a full sync produces (spec §
+# "Targeted ingest contract"). Enumerated against the flag-consumption blocks
+# guarded by the `if not rebuild and not targeted:` branch in sync_cache (the
+# full-sync-only `_consume_*` calls); keep this tuple in sync with those.
+_TARGETED_DECLINE_FLAGS = (
+    "conversation_backfill_pending",
+    "ai_titles_backfill_pending",
+    "conversation_reingest_pending",
+    "conversation_source_tool_use_reingest_pending",
+    "conversation_reingest_enrichment_pending",
+    "conversation_media_reingest_pending",
+    "conversation_search_split_pending",
+    "conversation_promote_command_args_pending",
+    "conversation_sessions_backfill_pending",
+)
+
+
+def _targeted_has_pending_global_work(conn) -> bool:
+    placeholders = ",".join("?" for _ in _TARGETED_DECLINE_FLAGS)
+    try:
+        row = conn.execute(
+            f"SELECT 1 FROM cache_meta WHERE key IN ({placeholders}) LIMIT 1",
+            _TARGETED_DECLINE_FLAGS).fetchone()
+    except sqlite3.OperationalError:
+        return False
+    return row is not None
+
+
 def sync_cache(
     conn: sqlite3.Connection,
     *,
     progress: Callable[[IngestStats], None] | None = None,
     rebuild: bool = False,
+    only_paths: "set[str] | None" = None,
 ) -> IngestStats:
     """Read-through delta ingest. Acquires an exclusive fcntl.flock; if
     another process holds it, returns immediately with lock_contended=True
@@ -592,6 +638,14 @@ def sync_cache(
             stats.lock_contended = True
             return stats
 
+        targeted = only_paths is not None
+        if targeted:
+            if rebuild:
+                raise ValueError("sync_cache: only_paths is incompatible with rebuild")
+            if _targeted_has_pending_global_work(conn):
+                stats.deferred_reason = "pending_global_flags"
+                return stats
+
         # Walk-complete sentinel gating (cctally-dev#93, D5b/D6b). Capture
         # whether cache 001 was already applied at the moment this sync
         # acquired the lock. The end-of-loop marker write is gated on this so
@@ -742,7 +796,7 @@ def sync_cache(
         # path, which already cleared the flag and repopulates via the normal
         # walk). A path-less/:memory: conn has no cache_meta only if the schema
         # was never applied; the try/except tolerates that.
-        if not rebuild:
+        if not rebuild and not targeted:
             try:
                 _pending = conn.execute(
                     "SELECT 1 FROM cache_meta "
@@ -865,7 +919,10 @@ def sync_cache(
             # HUMAN(text=args); the split-FTS UPDATE triggers re-index the args.
             _consume_promote_command_args(conn)
 
-        paths: list[pathlib.Path] = list(_iter_claude_jsonl_files())
+        if targeted:
+            paths = [pathlib.Path(p) for p in only_paths if pathlib.Path(p).is_file()]
+        else:
+            paths = list(_iter_claude_jsonl_files())
         stats.files_total = len(paths)
 
         # This SELECT does NOT open an implicit transaction (Python's
@@ -910,22 +967,29 @@ def sync_cache(
         # commit lands BEFORE the per-file read+parse loop, so no write
         # lock is held into that loop (same discipline as the truncation
         # escalation just below).
-        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()
-            walk_clean = False  # orphaned rows -> cache doesn't mirror disk (D5a)
+        # Targeted (only_paths) sync narrows `paths` to the requested file(s),
+        # so the orphan scan below — which infers "deleted from disk" from a
+        # tracked path's absence in `paths` — would mistake EVERY other tracked
+        # file for an orphan and nuke the walk-complete marker. Skip it entirely
+        # for targeted: the live-tail fast path never prunes orphans (the full
+        # background sync owns that).
+        if not targeted:
+            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()
+                walk_clean = False  # orphaned rows -> cache doesn't mirror disk (D5a)
 
         # Pre-scan for any truncation among tracked files. Under the
         # ccusage-parity ON CONFLICT DO UPDATE, source_path is PINNED to
@@ -958,6 +1022,14 @@ def sync_cache(
                 truncated_paths.add(str(jp))
 
         if truncated_paths:
+            if targeted:
+                # The targeted fast path must NEVER trigger the global
+                # full-cache wipe-and-re-ingest escalation below — that would
+                # turn a 1s live-tail tick into a multi-minute rebuild and drop
+                # every other session's rows. Decline and defer to the next full
+                # background sync, which owns the truncation escalation.
+                stats.deferred_reason = "truncation"
+                return stats
             eprint(
                 f"[cache-sync] truncation detected on {len(truncated_paths)} "
                 f"file(s) — re-ingesting all files (safe under ccusage-parity "
@@ -1035,6 +1107,7 @@ def sync_cache(
             except OSError as exc:
                 eprint(f"[cache] stat failed for {jp}: {exc}")
                 walk_clean = False  # skipped a file without ingesting (D5a)
+                stats.files_failed += 1
                 continue
 
             size = st.st_size
@@ -1118,6 +1191,7 @@ def sync_cache(
             except OSError as exc:
                 eprint(f"[cache] could not read {jp}: {exc}")
                 walk_clean = False  # skipped a file without ingesting (D5a)
+                stats.files_failed += 1
                 continue
 
             # Python's sqlite3 module starts an implicit transaction on the
@@ -1240,6 +1314,7 @@ def sync_cache(
                 eprint(f"[cache] db error on {jp}: {exc}")
                 conn.rollback()
                 walk_clean = False  # rolled back this file without ingesting (D5a)
+                stats.files_failed += 1
                 continue
 
             if progress is not None:
@@ -1280,7 +1355,7 @@ def sync_cache(
         # completeness. A lock-contended sync returned early above and never
         # reaches here. Presence (not the timestamp) is the gate signal; the
         # value stores the completion instant for doctor/debugging.
-        if walk_clean and applied_at_start:
+        if walk_clean and applied_at_start and not targeted:
             conn.execute(
                 "INSERT INTO cache_meta(key, value) "
                 "VALUES('claude_ingest_walk_complete', ?) "

package/bin/_cctally_config.py

@@ -303,6 +303,7 @@ ALLOWED_CONFIG_KEYS = (
     "dashboard.bind",
     "dashboard.expose_transcripts",
     "dashboard.cache_failure_markers",
+    "dashboard.live_tail",
     "update.check.enabled",
     "update.check.ttl_hours",
     "statusline.visual_burn_rate",
@@ -501,6 +502,24 @@ def _config_known_value(config: dict, key: str) -> "object":
             except ValueError:
                 return True
         return True
+    if key == "dashboard.live_tail":
+        # Boolean opt-OUT (spec §4.2). Default TRUE — absence is ON. A
+        # hand-edited junk value surfaces the True default. Mirrors
+        # dashboard.cache_failure_markers exactly.
+        block = config.get("dashboard") if isinstance(config, dict) else None
+        if not isinstance(block, dict):
+            block = {}
+        stored = block.get("live_tail")
+        if stored is None:
+            return True
+        if isinstance(stored, bool):
+            return stored
+        if isinstance(stored, str):
+            try:
+                return c._normalize_alerts_enabled_value(stored)
+            except ValueError:
+                return True
+        return True
     if key in ("update.check.enabled", "update.check.ttl_hours"):
         # Defaults mirror `_is_update_check_due` (True / 24 hours).
         # Hand-edited junk surfaces as the default — matches dashboard.bind.
@@ -930,6 +949,40 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                 f"{'true' if canonical else 'false'}"
             )
         return 0
+    if key == "dashboard.live_tail":
+        # Mirror dashboard.cache_failure_markers exactly: validate the bool
+        # first, then read-modify-write under config_writer_lock with
+        # _load_config_unlocked (load_config under the lock self-deadlocks).
+        # Preserves sibling dashboard.bind / expose_transcripts /
+        # cache_failure_markers. Re-message the shared normalizer's ValueError
+        # with the actual key name.
+        try:
+            canonical = c._normalize_alerts_enabled_value(raw)
+        except ValueError:
+            print(
+                f"cctally: invalid boolean value for dashboard.live_tail: "
+                f"{raw!r} (expected true|false|yes|no|1|0|on|off)",
+                file=sys.stderr,
+            )
+            return 2
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            existing = config.get("dashboard")
+            if existing is not None and not isinstance(existing, dict):
+                print(
+                    "cctally: dashboard config error: dashboard must be an object",
+                    file=sys.stderr,
+                )
+                return 2
+            block = dict(existing or {})
+            block["live_tail"] = canonical
+            config["dashboard"] = block
+            save_config(config)
+        if getattr(args, "emit_json", False):
+            print(json.dumps({"dashboard": {"live_tail": canonical}}, indent=2))
+        else:
+            print(f"dashboard.live_tail={'true' if canonical else 'false'}")
+        return 0
     if key in (
         "statusline.visual_burn_rate",
         "statusline.cost_source",
@@ -1318,6 +1371,21 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 save_config(config)
             # idempotent: silent on missing key
         return 0
+    if key == "dashboard.live_tail":
+        # Mirror the cache_failure_markers unset branch: drop only the
+        # live_tail leaf; if the dashboard block ends up empty, drop the parent
+        # too. Sibling dashboard.bind / expose_transcripts / cache_failure_markers
+        # survive. Unsetting restores the True (opt-out) default at read time.
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            block = config.get("dashboard")
+            if isinstance(block, dict) and "live_tail" in block:
+                del block["live_tail"]
+                if not block:
+                    config.pop("dashboard", None)
+                save_config(config)
+            # idempotent: silent on missing key
+        return 0
     if key in (
         "statusline.visual_burn_rate",
         "statusline.cost_source",

package/bin/_cctally_dashboard.py

@@ -317,7 +317,7 @@ from _lib_subscription_weeks import _compute_subscription_weeks
 from _lib_blocks import _group_entries_into_blocks
 from _cctally_config import save_config, _load_config_unlocked
 from _cctally_db import _render_migration_error_banner
-from _cctally_cache import get_entries, open_cache_db
+from _cctally_cache import get_entries, open_cache_db, sync_cache
 
 
 # === Module-level back-ref shims for helpers that STAY in bin/cctally ======
@@ -623,6 +623,12 @@ BLOCK_DURATION = sys.modules["cctally"].BLOCK_DURATION
 # === STATIC_DIR — dashboard static-asset root ==============================
 STATIC_DIR = pathlib.Path(__file__).resolve().parent.parent / "dashboard" / "static"
 
+# Conversation live-tail watch loop (spec §4.1). Single-file stat poll: cheap.
+_LIVE_TAIL_POLL_INTERVAL = 1.0      # seconds between stat polls of the open file(s)
+_LIVE_TAIL_DEBOUNCE = 0.25          # settle window after first detected growth
+_LIVE_TAIL_KEEPALIVE = 15.0         # idle keep-alive cadence (proxy guard)
+_LIVE_TAIL_FILE_RESET_EVERY = 10    # re-resolve the session file set every N cycles
+
 
 # === Dashboard bind validators (config + cmd_dashboard) ====================
 
@@ -4921,8 +4927,10 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     _dash_cfg = _cfg_for_alerts.get("dashboard") if isinstance(
         _cfg_for_alerts.get("dashboard"), dict) else {}
     _cfm = _dash_cfg.get("cache_failure_markers", True)
+    _lt = _dash_cfg.get("live_tail", True)
     dashboard_prefs = {
         "cache_failure_markers": _cfm if isinstance(_cfm, bool) else True,
+        "live_tail": _lt if isinstance(_lt, bool) else True,
     }
 
     # Mirror update-state.json + update-suppress.json into the envelope
@@ -5268,6 +5276,30 @@ def _qs_str(q: dict, key: str, default: str | None) -> str | None:
 _CONV_SEARCH_KINDS = ("all", "prompts", "assistant", "tools", "thinking")
 
 
+def _cached_file_sigs(conn, paths):
+    """{path: size_bytes} from session_files for the given paths — the cache's
+    own view of how far each file is ingested. Size-only by design, matching the
+    watch kernel's size-only signature (`file_sig`) and sync_cache's size-only
+    delta signal: mtime is NOT consulted, because a size-unchanged ingest does
+    not refresh session_files.mtime_ns and a stale mtime would re-detect
+    'changed' every cycle forever. Used to baseline the live-tail watch so a file
+    the cache hasn't caught up on reads as 'changed' on cycle 1 (spec §2.4).
+    Paths with no row are simply absent → treated as changed."""
+    out = {}
+    if not paths:
+        return out
+    placeholders = ",".join("?" for _ in paths)
+    try:
+        rows = conn.execute(
+            f"SELECT path, size_bytes FROM session_files "
+            f"WHERE path IN ({placeholders})", list(paths)).fetchall()
+    except sqlite3.OperationalError:
+        return out
+    for p, size in rows:
+        out[p] = size
+    return out
+
+
 class DashboardHTTPHandler(BaseHTTPRequestHandler):
     """Routes:
         GET /                       → dashboard.html
@@ -5406,6 +5438,10 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             # #177 S6: in-conversation find → rendered-turn anchors. Matched
             # BEFORE the <id> reader catch-all (same precedence as /outline).
             self._handle_get_conversation_find(path)
+        elif path.startswith("/api/conversation/") and path.endswith("/events"):
+            # Live-tail SSE for the open reader (spec §2). Matched BEFORE the
+            # <id> reader catch-all.
+            self._handle_get_conversation_events(path)
         elif path.startswith("/api/conversation/"):
             self._handle_get_conversation_detail(path)
         else:
@@ -5879,7 +5915,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                          "field": f"dashboard.{leaf}"},
                     )
                     return
-                if leaf != "cache_failure_markers":
+                if leaf not in ("cache_failure_markers", "live_tail"):
                     self._respond_json(
                         400,
                         {"error": f"unknown dashboard settings key: {leaf}",
@@ -5887,18 +5923,16 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     )
                     return
             dashboard_validated = {}
-            if "cache_failure_markers" in dashboard_block:
-                if not isinstance(dashboard_block["cache_failure_markers"], bool):
-                    self._respond_json(
-                        400,
-                        {"error": ("dashboard.cache_failure_markers must be a "
-                                   "JSON boolean"),
-                         "field": "dashboard.cache_failure_markers"},
-                    )
-                    return
-                dashboard_validated["cache_failure_markers"] = (
-                    dashboard_block["cache_failure_markers"]
-                )
+            for _leaf in ("cache_failure_markers", "live_tail"):
+                if _leaf in dashboard_block:
+                    if not isinstance(dashboard_block[_leaf], bool):
+                        self._respond_json(
+                            400,
+                            {"error": f"dashboard.{_leaf} must be a JSON boolean",
+                             "field": f"dashboard.{_leaf}"},
+                        )
+                        return
+                    dashboard_validated[_leaf] = dashboard_block[_leaf]
 
         # Pre-validate update shape. Only `update.check.{enabled,ttl_hours}`
         # is settable today; any other key under `update` or `update.check`
@@ -6235,14 +6269,15 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 "anomaly_threshold_pp": stored_threshold,
             }
         if dashboard_validated is not None:
-            # Echo the persisted cache_failure_markers (the only dashboard-
-            # writable leaf) so the SettingsOverlay can repaint without a
+            # Echo the persisted dashboard-writable leaves (cache_failure_markers
+            # + live_tail) so the SettingsOverlay can repaint without a
             # follow-up GET. Default true (opt-out) when nothing is persisted.
             persisted_dash = merged.get("dashboard") or {}
             out["dashboard"] = {
                 "cache_failure_markers": bool(
                     persisted_dash.get("cache_failure_markers", True)
                 ),
+                "live_tail": bool(persisted_dash.get("live_tail", True)),
             }
         out["saved_at"] = (
             dt.datetime.now(dt.timezone.utc)
@@ -7481,6 +7516,99 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return
         self._respond_json(200, body)
 
+    def _handle_get_conversation_events(self, path: str) -> None:
+        """``GET /api/conversation/<id>/events`` — per-conversation live-tail
+        SSE (spec §2). Fail-closed behind the same transcript privacy gate as
+        the other conversation routes. Watches only this session's file(s);
+        emits ``event: tail`` on growth, ``: keep-alive`` when idle. Passive
+        (no ingest, no emit) under ``--no-sync``."""
+        if not self._require_transcripts_allowed():
+            return
+        import time as _time
+        import urllib.parse as _u
+        watch = sys.modules["cctally"]._load_sibling("_lib_conversation_watch")
+        cq = self._conversation_query()
+        session_id = _u.unquote(path[len("/api/conversation/"):-len("/events")])
+        if not session_id:
+            self.send_error(404, "conversation not found")
+            return
+
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream; charset=utf-8")
+        self.send_header("Cache-Control", "no-cache")
+        self.send_header("Connection", "keep-alive")
+        self.send_header("X-Accel-Buffering", "no")
+        self.end_headers()
+
+        passive = bool(type(self).no_sync)
+
+        try:
+            conn = open_cache_db()
+        except (sqlite3.DatabaseError, OSError):
+            # Cache unavailable — degrade to keep-alive only; client backstop
+            # tick still surfaces turns. (Headers already sent; can't 500.)
+            passive = True
+            conn = None
+
+        def _resolve():
+            return cq.session_source_paths(conn, session_id) if conn else []
+
+        def _ingest(changed):
+            return sync_cache(conn, only_paths=set(changed))
+
+        try:
+            if passive:
+                # Frozen-data contract: no ingest, no emit. Keep-alive only.
+                while True:
+                    _time.sleep(_LIVE_TAIL_KEEPALIVE)
+                    self.wfile.write(b": keep-alive\n\n")
+                    self.wfile.flush()
+
+            files = _resolve()
+            # Best-effort connect ingest for immediacy, then baseline `seen`
+            # from the cache's own offsets (session_files) so any pre-connect
+            # growth the connect-ingest declined is still caught on cycle 1.
+            try:
+                if files:
+                    sync_cache(conn, only_paths=set(files))
+            except sqlite3.DatabaseError:
+                pass
+            seen = _cached_file_sigs(conn, files)
+
+            idle = 0.0
+            cycles = 0
+            while True:
+                _time.sleep(_LIVE_TAIL_POLL_INTERVAL)
+                cycles += 1
+                changed = watch.changed_paths(files, seen)
+                if changed:
+                    _time.sleep(_LIVE_TAIL_DEBOUNCE)
+                    new_seen, emitted = watch.watch_step(
+                        files, seen, ingest_fn=_ingest,
+                        committed_sig_fn=lambda p: _cached_file_sigs(conn, [p]).get(p))
+                    seen = new_seen
+                    if emitted:
+                        self.wfile.write(
+                            ("event: tail\ndata: "
+                             + json.dumps({"sessionId": session_id})
+                             + "\n\n").encode("utf-8"))
+                        self.wfile.flush()
+                        idle = 0.0
+                        continue
+                idle += _LIVE_TAIL_POLL_INTERVAL
+                if idle >= _LIVE_TAIL_KEEPALIVE:
+                    self.wfile.write(b": keep-alive\n\n")
+                    self.wfile.flush()
+                    idle = 0.0
+                if cycles % _LIVE_TAIL_FILE_RESET_EVERY == 0:
+                    files = _resolve()
+                    seen = {p: s for p, s in seen.items() if p in set(files)}
+        except (BrokenPipeError, ConnectionResetError):
+            pass            # client disconnect is normal
+        finally:
+            if conn is not None:
+                conn.close()
+
     def _handle_get_conversation_search(self) -> None:
         """``GET /api/conversation/search?q=...&kind=...`` — cross-session
         FTS/LIKE search (spec §3.3). Matched BEFORE the ``<id>`` reader in

package/bin/_lib_conversation_query.py

@@ -451,6 +451,20 @@ def _session_latest_meta_map(conn, session_ids):
     return meta
 
 
+def session_source_paths(conn, session_id):
+    """Distinct JSONL source files backing one session — the file-set the
+    live-tail watch loop polls (spec §2.3). Reads ``conversation_messages``,
+    the reader's own source of truth, NOT ``session_files`` (whose ``session_id``
+    is lazy / filename-fallback). Returns a list of path strings; empty for an
+    unknown or not-yet-ingested session.
+    """
+    rows = conn.execute(
+        "SELECT DISTINCT source_path FROM conversation_messages "
+        "WHERE session_id=? AND source_path IS NOT NULL",
+        (session_id,)).fetchall()
+    return [r[0] for r in rows]
+
+
 # Rail sort keys, in the rollup table's STRUCTURAL columns (Task A). ``recent``
 # rides idx_conv_sessions_recent(last_activity_utc DESC, session_id DESC) and
 # early-terminates at LIMIT with no temp B-tree; ``oldest`` scan-sorts the few

package/bin/_lib_conversation_watch.py

@@ -0,0 +1,67 @@
+"""Pure watch-step kernel for the conversation live-tail (spec §2.4).
+
+No I/O of its own — the filesystem `stat` and the targeted ingest are injected
+as callables so the cycle is unit-testable without real timing, threads, or a
+DB. The thin SSE/sleep/keep-alive driver lives in bin/_cctally_dashboard.py.
+"""
+
+
+def file_sig(path):
+    """Size-only signature (st_size, an int) for a path, or None if it can't be
+    stat'd (deleted / rotated). Size-only by design: it must match sync_cache's
+    own size-only delta signal (Claude Code's JSONL sessions are strictly
+    append-only, so a size change is sufficient) — mtime jitter must NOT drive a
+    re-emit, since a size-unchanged ingest does not refresh session_files.mtime_ns
+    and a stale mtime would otherwise re-detect "changed" every cycle forever.
+    Pure-ish — the only I/O, isolated here so callers can inject a fake in
+    tests."""
+    import os
+    try:
+        st = os.stat(path)
+    except OSError:
+        return None
+    return st.st_size
+
+
+def changed_paths(files, seen, stat_fn=file_sig):
+    """Paths whose current size-only signature differs from `seen` (matches
+    sync_cache's size-only delta; mtime jitter must not drive a re-emit). An
+    unstatable path (stat_fn → None) is skipped (dropped this cycle, re-resolved
+    later); a path absent from `seen` counts as changed (first observation /
+    pre-connect growth)."""
+    out = []
+    for p in files:
+        sig = stat_fn(p)
+        if sig is None:
+            continue
+        if seen.get(p) != sig:
+            out.append(p)
+    return out
+
+
+def watch_step(files, seen, *, stat_fn=file_sig, ingest_fn, committed_sig_fn=None):
+    """One watch cycle. Returns (new_seen, emitted).
+
+    Detect changed files (by size-only signature — matches sync_cache's
+    size-only delta; mtime jitter must not drive a re-emit) → run
+    ingest_fn(changed) (targeted sync_cache). Emit + advance `seen` ONLY on a
+    clean ingest (stats.targeted_clean). `seen` is advanced to the COMMITTED
+    cache cursor (committed_sig_fn) — NOT a fresh filesystem re-stat — so a file
+    that grew during the ingest is still seen as changed next cycle (the cache
+    cursor, in session_files, lags the new disk size). committed_sig_fn defaults
+    to stat_fn for pure unit tests with no cache. A contended/declined/failed
+    ingest leaves `seen` untouched so the next cycle retries (the 5s backstop is
+    the floor)."""
+    committed_sig_fn = committed_sig_fn or stat_fn
+    changed = changed_paths(files, seen, stat_fn)
+    if not changed:
+        return seen, False
+    stats = ingest_fn(changed)
+    if not getattr(stats, "targeted_clean", False):
+        return seen, False
+    new_seen = dict(seen)
+    for p in changed:
+        sig = committed_sig_fn(p)
+        if sig is not None:
+            new_seen[p] = sig
+    return new_seen, True