cctally 1.44.3 → 1.46.0

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) ====================
 
@@ -4912,6 +4918,20 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         "notifier":           _alerts_cfg.get("notifier", "auto"),
         "command_configured": _alerts_cfg.get("command_template") is not None,
     }
+    # Dashboard render-prefs mirror (cache-failure-markers opt-out, spec §5).
+    # Reuses the single `_cfg_for_alerts = load_config()` read above (no extra
+    # FS hit on the hot path). Default true — absence is treated as ON (opt-out,
+    # not opt-in); a hand-edited non-bool surfaces the default. The on/off toggle
+    # is honored entirely at client render time; the kernel + API always emit the
+    # marker data.
+    _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
     # so the dashboard's amber "Update available" badge repaints from
@@ -5149,6 +5169,12 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         "alerts":           alerts_array,
         "alerts_settings":  alerts_settings,
 
+        # Dashboard render-prefs mirror (cache-failure-markers opt-out, spec
+        # §5). Additive optional, like alerts_settings — envelope_version
+        # stays at 2. The client derives `markersEnabled` from this, defaulting
+        # to true when the field is undefined (older server / first tick).
+        "dashboard_prefs":  dashboard_prefs,
+
         # update-subcommand SSE mirror (see comment above the
         # `_load_update_state()` block). Shape matches GET
         # /api/update/status's payload (`{state, suppress}`) so the
@@ -5250,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
@@ -5388,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:
@@ -5685,7 +5739,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
 
         # Reject unknown top-level keys (forward-compat hygiene).
         allowed_top_keys = {
-            "display", "alerts", "update", "cache_report", "budget",
+            "display", "alerts", "update", "cache_report", "budget", "dashboard",
         }
         for k in payload.keys():
             if k not in allowed_top_keys:
@@ -5701,12 +5755,13 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             and "update" not in payload
             and "cache_report" not in payload
             and "budget" not in payload
+            and "dashboard" not in payload
         ):
             self._respond_json(
                 400,
                 {"error": (
                     "body must contain at least one of: "
-                    "display, alerts, update, cache_report, budget"
+                    "display, alerts, update, cache_report, budget, dashboard"
                 )},
             )
             return
@@ -5835,6 +5890,50 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 )
                 return
 
+        # Pre-validate the dashboard block (spec §5). Only
+        # ``cache_failure_markers`` is dashboard-writable — a JSON boolean
+        # (string/int rejected, mirroring the strict bool checks for
+        # ``alerts.enabled``). ``dashboard.bind`` / ``dashboard.expose_transcripts``
+        # are bind-time / privacy-gate settings, NOT live-mutable, so they are
+        # rejected explicitly here (rather than silently dropped). Outside the
+        # config_writer_lock so a 400 short-circuit doesn't take the lock.
+        dashboard_validated: "dict | None" = None
+        if "dashboard" in payload:
+            dashboard_block = payload["dashboard"]
+            if not isinstance(dashboard_block, dict):
+                self._respond_json(
+                    400,
+                    {"error": "dashboard must be an object", "field": "dashboard"},
+                )
+                return
+            for leaf in dashboard_block.keys():
+                if leaf in ("bind", "expose_transcripts"):
+                    self._respond_json(
+                        400,
+                        {"error": (f"dashboard.{leaf} is not settable via the "
+                                   "dashboard (bind-time / privacy-gate setting)"),
+                         "field": f"dashboard.{leaf}"},
+                    )
+                    return
+                if leaf not in ("cache_failure_markers", "live_tail"):
+                    self._respond_json(
+                        400,
+                        {"error": f"unknown dashboard settings key: {leaf}",
+                         "field": f"dashboard.{leaf}"},
+                    )
+                    return
+            dashboard_validated = {}
+            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`
         # is rejected so adding e.g. `update.banner.*` later is forward
@@ -6061,6 +6160,23 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 merged_cr.update(cache_report_validated)
                 merged["cache_report"] = merged_cr
 
+            if dashboard_validated is not None:
+                # Same hand-edited-junk guard as the other blocks: a non-dict
+                # stored ``dashboard`` block should surface as a recoverable
+                # 400, not a 500. Partial-merge so the (bind-time, CLI-only)
+                # ``bind`` / ``expose_transcripts`` siblings are PRESERVED —
+                # cache_failure_markers writes must never clobber them.
+                existing_dash = merged.get("dashboard")
+                if existing_dash is not None and not isinstance(existing_dash, dict):
+                    self._respond_json(
+                        400, {"error": "dashboard must be an object",
+                              "field": "dashboard"}
+                    )
+                    return
+                merged_dash = dict(existing_dash or {})
+                merged_dash.update(dashboard_validated)
+                merged["dashboard"] = merged_dash
+
             save_config(merged)
 
         # Build the response: subset of touched blocks.
@@ -6152,6 +6268,17 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             out["cache_report"] = {
                 "anomaly_threshold_pp": stored_threshold,
             }
+        if dashboard_validated is not None:
+            # 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)
             .strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -7389,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

@@ -285,6 +285,105 @@ def _entry_cost(model, inp, out, cc, cr, cost_usd_raw) -> float:
     return _calculate_entry_cost(model or "", usage, cost_usd=cost_usd_raw)
 
 
+# --- Cache-failure detection (spec §1) -------------------------------------
+# A prompt-cache "failure" is an assistant turn that re-creates the bulk of its
+# cached prefix instead of reading it: cache_read collapses while cache_creation
+# balloons, re-billing those tokens at the higher cache-WRITE rate. We flag only
+# clear mid-session prefix losses (the Conservative profile, ~1 per session).
+#
+# Thresholds (maintainer-tunable module constants, NOT user config). Rationale
+# from a scan of 58 recent sessions (spec Evidence): a 0.5 running-max-collapse
+# threshold sits in the wide empty gap between the worst healthy turn and the
+# mildest failure, and the recreated-fraction guard (0.75) sits in the matching
+# fraction gap (healthy max 0.723 < 0.75 <= failure min 0.759), both with margin.
+_CACHE_FAILURE_COLLAPSE_FRACTION = 0.5   # cache_read must fall to <= half the prior running-max
+_CACHE_FAILURE_RECREATE_FRACTION = 0.75  # >= 75% of THIS turn's context freshly created
+_CACHE_FAILURE_CACHE_FLOOR = 20_000      # prior cache must be meaningful to "lose"
+_CACHE_FAILURE_CREATE_FLOOR = 20_000     # the re-creation must be substantial / real cost
+
+
+def _cache_failure_wasted_usd(model, lost):
+    """Marginal extra paid by re-creating `lost` previously-cached tokens at the
+    cache-WRITE rate instead of reading them at the cache-READ rate. Reuses the
+    pricing chokepoint `_calculate_entry_cost` (zero on unknown models — the
+    helper emits its own one-shot stderr warning, never raises). NEVER summed into
+    any cost-snapshot / budget / reconciled figure — a display-only estimate."""
+    write = _calculate_entry_cost(model or "", {"cache_creation_input_tokens": lost})
+    read = _calculate_entry_cost(model or "", {"cache_read_input_tokens": lost})
+    return write - read
+
+
+def _stamp_cache_failures(items):
+    """Stamp ``item["cache_failure"]`` on each assistant turn that re-creates the
+    bulk of its cached prefix instead of reading it (spec §1). Mutates `items` in
+    place; healthy turns are left WITHOUT the key (absent, not zero — matching the
+    ``tokens?`` "absent, not zero" convention).
+
+    Walks items in DOCUMENT ORDER (the order `_assemble_session` produces),
+    maintaining a running-max of ``cache_read`` keyed by ``(subagent_key, model)``
+    — ``None`` subagent_key = main session. The key is per-thread AND per-model
+    because Anthropic prompt caches are model-specific: a model switch within a
+    thread legitimately starts a fresh cache (cr ~ 0) and must not read as a loss,
+    and the compound key makes that the first turn under its own key (no prior rm).
+    The per-key running-max is RESET when a context-compaction boundary is crossed
+    (a ``meta`` item whose ``meta_kind == "compaction"``), since compaction
+    legitimately invalidates the prefix and the post-compaction re-prime is not a
+    failure.
+
+    For each assistant item with a ``tokens`` dict — cc = tokens["cache_creation"],
+    cr = tokens["cache_read"], rm = the running-max for this key BEFORE this turn —
+    flag iff rm >= CACHE_FLOOR and cc >= CREATE_FLOOR and cr <= COLLAPSE_FRACTION*rm
+    and cc/(cc+cr) >= RECREATE_FRACTION. The fourth term keeps the rule aligned
+    with the Evidence: it requires that most of THIS turn's context was freshly
+    created, not merely that cache_read dipped. After the check, update
+    ``running_max[key] = max(rm, cr)`` (a failure's small cr never lowers the
+    high-water mark; the next healthy turn re-establishes it).
+
+    Payload (lost-prefix basis — NOT raw cc, which would over-count when the turn
+    also writes genuinely-new cacheable content that was never cached):
+        lost            = min(cc, max(0, rm - cr))
+        tokens_recreated = lost
+        prev_cached      = rm
+        est_wasted_usd   = write(lost) - read(lost)
+
+    Items lacking a ``tokens`` dict (no session_entries row, or non-assistant
+    items other than a compaction meta) are skipped and do NOT move the
+    running-max. Order-dependent by construction; run over document-ordered items.
+    """
+    running_max = {}   # (subagent_key, model) -> high-water cache_read
+    for it in items:
+        # Context-compaction boundary resets the per-key prefix high-water mark:
+        # the post-compaction re-prime is a legitimate fresh build, not a loss.
+        # Reset the whole map (compaction invalidates every thread's prefix in
+        # this session view; a per-key reset would need a thread tag the meta row
+        # does not reliably carry).
+        if it.get("kind") == "meta" and it.get("meta_kind") == "compaction":
+            running_max.clear()
+            continue
+        if it.get("kind") != "assistant":
+            continue
+        tok = it.get("tokens")
+        if not isinstance(tok, dict):
+            continue                      # no session_entries row -> skip, don't move max
+        cc = tok.get("cache_creation", 0) or 0
+        cr = tok.get("cache_read", 0) or 0
+        key = (it.get("subagent_key"), it.get("model"))
+        rm = running_max.get(key, 0)
+        total = cc + cr
+        if (rm >= _CACHE_FAILURE_CACHE_FLOOR
+                and cc >= _CACHE_FAILURE_CREATE_FLOOR
+                and cr <= _CACHE_FAILURE_COLLAPSE_FRACTION * rm
+                and total > 0
+                and cc / total >= _CACHE_FAILURE_RECREATE_FRACTION):
+            lost = min(cc, max(0, rm - cr))
+            it["cache_failure"] = {
+                "tokens_recreated": lost,
+                "prev_cached": rm,
+                "est_wasted_usd": _cache_failure_wasted_usd(it.get("model"), lost),
+            }
+        running_max[key] = max(rm, cr)
+
+
 def _session_cost_map(conn, session_ids):
     """{session_id: total_cost_usd} for the given sessions. Joins
     conversation_messages turn keys to the single deduped session_entries row
@@ -352,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
@@ -862,6 +975,12 @@ def _assemble_session(conn, session_id):
             it.pop("_has_prose", None)
     header_cost = round(header_cost, 6)
 
+    # Stamp cache-failure markers (spec §1) AFTER tokens are on each item and
+    # while `items` is still document-ordered (the running-max walk is
+    # order-dependent). Healthy turns get no key (absent, not zero). Shared
+    # assembly -> the flag reaches BOTH the reader detail and the outline.
+    _stamp_cache_failures(items)
+
     # Strip the internal Phase-4b threading key from EVERY item (meta/human items
     # carry it too, not just assistant turns) so it never surfaces in the public
     # item JSON.
@@ -995,6 +1114,12 @@ def get_conversation_outline(conn, session_id):
     tool_counts, models = {}, {}
     error_count = 0
     tokens = {"input": 0, "output": 0, "cache_creation": 0, "cache_read": 0}
+    # Cache-failure aggregate (spec §2): count + summed lost-prefix tokens +
+    # summed wasted-cost over the flagged turns. Emitted only when count > 0
+    # (the per-turn "absent, not zero" convention; ~65% of sessions have zero).
+    cf_count = 0
+    cf_tokens = 0
+    cf_wasted = 0.0
     for it in items:
         kind = it["kind"]
         turn_counts["total"] += 1
@@ -1036,6 +1161,15 @@ def get_conversation_outline(conn, session_id):
                 t["tokens"] = tok
                 for k in tokens:
                     tokens[k] += tok.get(k, 0)
+            # Copy the cache-failure marker onto the OutlineTurn exactly where
+            # tokens is copied (assistant-only, rides the same source row) and
+            # accumulate the session-level aggregate (spec §2).
+            cf = it.get("cache_failure")
+            if cf is not None:
+                t["cache_failure"] = cf
+                cf_count += 1
+                cf_tokens += cf.get("tokens_recreated", 0)
+                cf_wasted += cf.get("est_wasted_usd", 0.0)
         if kind == "meta":
             t["meta_kind"] = it.get("meta_kind")
             t["skill_name"] = it.get("skill_name")
@@ -1046,12 +1180,17 @@ def get_conversation_outline(conn, session_id):
     d0 = _parse_outline_ts(ts_vals[0] if ts_vals else None)
     d1 = _parse_outline_ts(ts_vals[-1] if ts_vals else None)
     duration = int((d1 - d0).total_seconds()) if d0 and d1 else None
+    stats = {"turns": turn_counts, "tool_counts": tool_counts,
+             "error_count": error_count, "models": models,
+             "duration_seconds": duration, "tokens": tokens,
+             "cost_usd": asm["header_cost"]}
+    if cf_count:
+        stats["cache_failures"] = {"count": cf_count,
+                                   "tokens_recreated": cf_tokens,
+                                   "est_wasted_usd": cf_wasted}
     return {"session_id": session_id,
             "subagent_meta": asm["subagent_meta"],
-            "stats": {"turns": turn_counts, "tool_counts": tool_counts,
-                      "error_count": error_count, "models": models,
-                      "duration_seconds": duration, "tokens": tokens,
-                      "cost_usd": asm["header_cost"]},
+            "stats": stats,
             "turns": turns}
 
 

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