cctally 1.76.0 → 1.78.0

package/bin/_cctally_core.py

@@ -60,8 +60,10 @@ def _init_paths_from_env() -> None:
     `import _cctally_core`).
     """
     global APP_DIR, LEGACY_APP_DIR, LOG_DIR, DEV_MODE
-    global DB_PATH, CACHE_DB_PATH
+    global DB_PATH, CACHE_DB_PATH, CONVERSATIONS_DB_PATH
     global CACHE_LOCK_PATH, CACHE_LOCK_CODEX_PATH, CACHE_LOCK_MAINTENANCE_PATH
+    global CONVERSATIONS_LOCK_PATH, CONVERSATIONS_LOCK_CODEX_PATH
+    global CONVERSATIONS_LOCK_MAINTENANCE_PATH
     global CONFIG_LOCK_PATH
     global CONFIG_PATH, MIGRATION_ERROR_LOG_PATH, CHANGELOG_PATH
     global HOOK_TICK_LOG_DIR, HOOK_TICK_LOG_PATH, HOOK_TICK_LOG_ROTATED_PATH
@@ -101,6 +103,7 @@ def _init_paths_from_env() -> None:
 
     DB_PATH = APP_DIR / "stats.db"
     CACHE_DB_PATH = APP_DIR / "cache.db"
+    CONVERSATIONS_DB_PATH = APP_DIR / "conversations.db"
 
     CACHE_LOCK_PATH = APP_DIR / "cache.db.lock"
     CACHE_LOCK_CODEX_PATH = APP_DIR / "cache.db.codex.lock"
@@ -108,6 +111,14 @@ def _init_paths_from_env() -> None:
     # retention prune across processes, held ABOVE the two provider flocks so a
     # rebuild/reingest cannot land between candidate selection and deletion.
     CACHE_LOCK_MAINTENANCE_PATH = APP_DIR / "cache.db.maintenance.lock"
+    # #320: transcript ingest and maintenance are physically independent from
+    # the latency-sensitive token/quota cache.  Never reuse the cache.db flock
+    # namespace for conversations.db writes.
+    CONVERSATIONS_LOCK_PATH = APP_DIR / "conversations.db.lock"
+    CONVERSATIONS_LOCK_CODEX_PATH = APP_DIR / "conversations.db.codex.lock"
+    CONVERSATIONS_LOCK_MAINTENANCE_PATH = (
+        APP_DIR / "conversations.db.maintenance.lock"
+    )
     CONFIG_LOCK_PATH = APP_DIR / "config.json.lock"
 
     CONFIG_PATH = APP_DIR / "config.json"
@@ -241,9 +252,11 @@ def _real_prod_data_dir() -> pathlib.Path:
 # Internal (no config UI — YAGNI, spec §Out of scope); test injection only.
 # Spec 2026-07-17-usage-statusline-fallback-design.
 #
-# OAUTH_BACKFILL_STALE_SECONDS: the OAuth poll only backfills once the
-#   selected-freshness marker is at least this stale. The 30-second statusline
-#   transport tick does not run OAuth.
+# STATUSLINE_OAUTH_POLL_SECONDS: the account-wide authoritative confirmation
+#   cadence driven by Claude Code's 30-second statusline timer. Keep it below
+#   the timer so scheduling jitter does not skip every other tick.
+# OAUTH_BACKFILL_STALE_SECONDS: the matching selected-freshness gate shared by
+#   statusline-driven and hook-driven automatic OAuth refreshes.
 # OAUTH_BACKOFF_BASE_SECONDS / OAUTH_BACKOFF_CAP_SECONDS: the headerless
 #   exponential 429 backoff (base * 2**consecutive_429, capped).
 STATUSLINE_CANDIDATE_TTL_SECONDS = 90
@@ -259,7 +272,8 @@ STATUSLINE_TOMBSTONE_DOCUMENT_MAX_BYTES = 1024
 # session waits on a long subagent (event-driven updates go quiet then). MUST
 # Add-when-absent only; a user-set value is never mutated.
 STATUSLINE_REFRESH_INTERVAL_DEFAULT = 30
-OAUTH_BACKFILL_STALE_SECONDS = 300.0
+STATUSLINE_OAUTH_POLL_SECONDS = 25.0
+OAUTH_BACKFILL_STALE_SECONDS = STATUSLINE_OAUTH_POLL_SECONDS
 OAUTH_BACKOFF_BASE_SECONDS = 60.0
 OAUTH_BACKOFF_CAP_SECONDS = 3600.0
 

package/bin/_cctally_dashboard.py

@@ -356,10 +356,16 @@ from _lib_blocks import _group_entries_into_blocks
 # #279 S2 F3: stdlib-logging chokepoint — server errors reach stderr via
 # the real log_error override below (leaf import, no cycle).
 import _lib_log
+from _lib_dashboard_json import (
+    encode_dashboard_json,
+    encode_dashboard_json_bytes,
+)
 from _cctally_config import save_config, _load_config_unlocked
 from _cctally_db import _render_migration_error_banner
 from _cctally_cache import (
-    get_entries, iter_entries, iter_entries_with_id, open_cache_db, sync_cache,
+    get_entries, iter_entries, iter_entries_with_id, open_cache_db,
+    open_conversations_db, sync_cache, sync_claude_conversations,
+    sync_codex_conversations,
     _prune_orphaned_cache_entries,
 )
 from _lib_snapshot_cache import (
@@ -798,12 +804,20 @@ def _codex_partial_source_detail(snapshot, row: Mapping, *, resource: str,
     return detail
 
 
-def _source_safe_claude_session_detail(detail, *, key: str) -> dict[str, Any]:
+def _source_safe_claude_session_detail(
+    detail, *, key: str, project_key: str | None = None, label: str | None = None,
+) -> dict[str, Any]:
     """Adapt the existing Claude session detail builder to S4's safe route."""
     payload = _session_detail_to_envelope(detail)
     return {
         "detail_kind": "claude_session",
         "key": key,
+        "label": label or "Claude session",
+        "project_label": payload["project_label"],
+        "project_key": (
+            dashboard_resource_key("project", "claude", project_key)
+            if project_key else None
+        ),
         "started_utc": payload["started_utc"],
         "last_activity_utc": payload["last_activity_utc"],
         "duration_min": payload["duration_min"],
@@ -815,20 +829,32 @@ def _source_safe_claude_session_detail(detail, *, key: str) -> dict[str, Any]:
         "cache_hit_pct": payload["cache_hit_pct"],
         "cost_per_model": payload["cost_per_model"],
         "cost_total_usd": payload["cost_total_usd"],
+        "privacy_note": (
+            "Native session identity and source files are withheld to preserve "
+            "opaque identity. Cache rebuild history belongs to the private "
+            "conversation-detail surface and is intentionally not exposed by "
+            "this qualified accounting route."
+        ),
     }
 
 
-def _source_safe_claude_project_detail(detail: Mapping, *, key: str) -> dict[str, Any]:
+def _source_safe_claude_project_detail(
+    detail: Mapping, *, key: str, label: str,
+) -> dict[str, Any]:
     """Drop legacy raw bucket/session identifiers from a Claude project drill."""
     return {
         "detail_kind": "claude_project",
         "key": key,
+        "label": label,
         "window_weeks": detail.get("window_weeks"),
         "window_cost_usd": detail.get("window_cost_usd"),
         "window_attributed_pct": detail.get("window_attributed_pct"),
         "models": detail.get("models", []),
         "sessions": [
             {
+                "key": dashboard_resource_key(
+                    "session", "claude", item.get("session_id"),
+                ),
                 "started_at": item.get("started_at"),
                 "last_activity_at": item.get("last_activity_at"),
                 "primary_model": item.get("primary_model"),
@@ -857,13 +883,73 @@ def _source_safe_claude_block_detail(detail: Mapping, *, key: str) -> dict[str,
     }
 
 
-def _claude_session_id_for_source_key(snapshot, key: str) -> str | None:
+def _claude_session_row_for_source_key(snapshot, key: str):
     for row in getattr(snapshot, "sessions", ()) or ():
         session_id = getattr(row, "session_id", None)
         if isinstance(session_id, str) and session_id and (
             dashboard_resource_key("session", "claude", session_id) == key
         ):
-            return session_id
+            return row
+    return None
+
+
+def _claude_session_id_for_source_key(snapshot, key: str) -> str | None:
+    """Resolve a qualified session key without exposing its native identity.
+
+    The published source bundle contains the bounded dashboard rows.  A project
+    drill can legitimately link to a recent session outside that panel slice,
+    so fall back to the compact ``session_files`` identity index and compare
+    opaque hashes.  This never scans transcript entries or returns a raw ID to
+    the client.
+    """
+    row = _claude_session_row_for_source_key(snapshot, key)
+    if row is not None:
+        return getattr(row, "session_id", None)
+    try:
+        conn = open_cache_db()
+    except (sqlite3.DatabaseError, OSError):
+        return None
+    try:
+        rows = conn.execute(
+            "SELECT DISTINCT session_id FROM session_files "
+            "WHERE session_id IS NOT NULL AND session_id <> '' "
+            "ORDER BY session_id"
+        )
+        for (session_id,) in rows:
+            if (
+                isinstance(session_id, str)
+                and dashboard_resource_key(
+                    "session", "claude", session_id,
+                ) == key
+            ):
+                return session_id
+    except sqlite3.Error:
+        return None
+    finally:
+        conn.close()
+    return None
+
+
+def _claude_project_key_for_path(snapshot, project_path: object) -> str | None:
+    """Map one private project path back to its public display key."""
+    if not isinstance(project_path, str) or not project_path:
+        return None
+    env = getattr(snapshot, "projects_envelope", None)
+    if not isinstance(env, Mapping):
+        return None
+    candidates: list[object] = []
+    current = env.get("current_week")
+    if isinstance(current, Mapping):
+        candidates.extend(current.get("rows") or ())
+    trend = env.get("trend")
+    if isinstance(trend, Mapping):
+        candidates.extend(trend.get("projects") or ())
+    for row in candidates:
+        if not isinstance(row, Mapping) or row.get("bucket_path") != project_path:
+            continue
+        project_key = row.get("key")
+        if isinstance(project_key, str) and project_key:
+            return project_key
     return None
 
 
@@ -904,19 +990,39 @@ def _claude_block_start_for_source_key(snapshot, key: str) -> dt.datetime | None
     return None
 
 
-def _build_claude_source_detail(snapshot, *, resource: str, key: str) -> dict[str, Any]:
+def _build_claude_source_detail(
+    snapshot, *, resource: str, key: str, row: Mapping,
+    window_weeks: int = 4,
+) -> dict[str, Any]:
     """Map a bounded legacy row to its existing, cache-only detail builder."""
     now_utc = getattr(snapshot, "generated_at", None) or _command_as_of()
     if resource == "session":
-        session_id = _claude_session_id_for_source_key(snapshot, key)
-        if session_id is None:
+        session_row = _claude_session_row_for_source_key(snapshot, key)
+        session_id = (
+            getattr(session_row, "session_id", None)
+            if session_row is not None
+            else _claude_session_id_for_source_key(snapshot, key)
+        )
+        if not isinstance(session_id, str) or not session_id:
             raise SourceResourceNotFound()
         detail = sys.modules["cctally"]._tui_build_session_detail(
             session_id, now_utc=now_utc,
         )
         if detail is None:
             raise SourceResourceNotFound()
-        return _source_safe_claude_session_detail(detail, key=key)
+        project_key = (
+            getattr(session_row, "project_key", None)
+            if session_row is not None
+            else _claude_project_key_for_path(
+                snapshot, getattr(detail, "project_path", None),
+            )
+        )
+        return _source_safe_claude_session_detail(
+            detail,
+            key=key,
+            project_key=project_key,
+            label=str(row.get("title") or row.get("label") or "Claude session"),
+        )
 
     if resource == "project":
         project_key = _claude_project_key_for_source_key(snapshot, key)
@@ -930,7 +1036,7 @@ def _build_claude_source_detail(snapshot, *, resource: str, key: str) -> dict[st
             detail = _project_detail_for_window(
                 conn,
                 project_key=project_key,
-                weeks_back=1,
+                weeks_back=window_weeks,
                 now_utc=now_utc,
                 current_week=getattr(snapshot, "current_week", None),
                 projects_envelope=getattr(snapshot, "projects_envelope", None),
@@ -945,7 +1051,9 @@ def _build_claude_source_detail(snapshot, *, resource: str, key: str) -> dict[st
             conn.close()
         if detail is None:
             raise SourceResourceNotFound()
-        return _source_safe_claude_project_detail(detail, key=key)
+        return _source_safe_claude_project_detail(
+            detail, key=key, label=project_key,
+        )
 
     start_at = _claude_block_start_for_source_key(snapshot, key)
     if start_at is None:
@@ -982,7 +1090,7 @@ def _build_claude_source_detail(snapshot, *, resource: str, key: str) -> dict[st
 
 
 def build_source_detail(*, snapshot, source: str, resource: str,
-                        key: str) -> dict[str, Any]:
+                        key: str, window_weeks: int = 4) -> dict[str, Any]:
     """Resolve one qualified opaque key to a provider-native read-only detail.
 
     The frozen published bundle is the first bounded key index.  Claude then
@@ -990,9 +1098,24 @@ def build_source_detail(*, snapshot, source: str, resource: str,
     the native S1-S3 adapter detail without a Claude fallback or a rollout
     parse.  Every branch preserves the generic handler errors above it.
     """
-    row = source_detail_lookup(snapshot.source_bundle, source, resource, key)
+    try:
+        row = source_detail_lookup(snapshot.source_bundle, source, resource, key)
+    except SourceResourceNotFound:
+        # A Claude project drill can expose a recent session outside the
+        # dashboard panel's bounded published slice.  The provider adapter
+        # resolves that opaque key against session_files below; all other
+        # resources retain the strict frozen-bundle membership gate.
+        if source != "claude" or resource != "session":
+            raise
+        row = {}
     if source == "claude":
-        return _build_claude_source_detail(snapshot, resource=resource, key=key)
+        return _build_claude_source_detail(
+            snapshot,
+            resource=resource,
+            key=key,
+            row=row,
+            window_weeks=window_weeks,
+        )
     try:
         detail = _build_codex_source_detail(snapshot, resource=resource, key=key)
         if resource == "session":
@@ -1175,8 +1298,7 @@ def _dashboard_sync_loop(
 
 def _dashboard_maybe_prune_retention() -> None:
     """#313 P3 (F7): throttled transcript retention prune driven from the
-    dashboard sync thread. Runs once per iteration INSIDE the measured cooldown
-    work (Task 6), so its cost paces the deadline. Opens a dedicated cache
+    independent conversation sync thread. Opens a dedicated transcript
     connection (no provider flock, no open transaction) for the orchestrator.
     No-op when retention is disabled; never raises (a prune failure must not
     crash the sync thread)."""
@@ -1187,7 +1309,7 @@ def _dashboard_maybe_prune_retention() -> None:
         retention_days = resolve_retention_days(c.load_config())
         if retention_days <= 0:
             return
-        conn = c.open_cache_db()
+        conn = c.open_conversations_db(attach_cache=False)
         try:
             retention._maybe_prune_conversation_retention(
                 conn,
@@ -3933,7 +4055,7 @@ def _handle_get_project_detail_impl(handler, *,
     except (TypeError, ValueError):
         weeks = None
     if weeks not in {1, 4, 8, 12}:
-        body = json.dumps({"error": "invalid weeks param"}).encode("utf-8")
+        body = encode_dashboard_json_bytes({"error": "invalid weeks param"})
         handler.send_response(400)
         handler.send_header("Content-Type", "application/json; charset=utf-8")
         handler.send_header("Content-Length", str(len(body)))
@@ -3976,9 +4098,9 @@ def _handle_get_project_detail_impl(handler, *,
         )
     except Exception as exc:
         handler.log_error("/api/project failed: %r", exc)
-        body = json.dumps(
+        body = encode_dashboard_json_bytes(
             {"error": "project detail failed"}
-        ).encode("utf-8")
+        )
         handler.send_response(500)
         handler.send_header("Content-Type", "application/json; charset=utf-8")
         handler.send_header("Content-Length", str(len(body)))
@@ -3986,16 +4108,16 @@ def _handle_get_project_detail_impl(handler, *,
         handler.wfile.write(body)
         return
     if detail is None:
-        body = json.dumps(
+        body = encode_dashboard_json_bytes(
             {"error": "project not found", "key": project_key},
-        ).encode("utf-8")
+        )
         handler.send_response(404)
         handler.send_header("Content-Type", "application/json; charset=utf-8")
         handler.send_header("Content-Length", str(len(body)))
         handler.end_headers()
         handler.wfile.write(body)
         return
-    body = json.dumps(detail, ensure_ascii=False).encode("utf-8")
+    body = encode_dashboard_json_bytes(detail, ensure_ascii=False)
     handler.send_response(200)
     handler.send_header("Content-Type", "application/json; charset=utf-8")
     handler.send_header("Content-Length", str(len(body)))
@@ -4100,10 +4222,6 @@ def _qs_str(q: dict, key: str, default: str | None) -> str | None:
 _DEBUG_CACHE_TABLES = (
     "session_entries",
     "session_files",
-    "conversation_messages",
-    "conversation_sessions",
-    "conversation_ai_titles",
-    "conversation_file_touches",
     "codex_session_entries",
     "codex_session_files",
 )
@@ -4459,7 +4577,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         _respond_json plus an explicit Allow header.
         """
         if self.path.split("?", 1)[0] == "/api/settings":
-            encoded = json.dumps({"error": "method not allowed"}).encode("utf-8")
+            encoded = encode_dashboard_json_bytes(
+                {"error": "method not allowed"}
+            )
             self.send_response(405)
             self.send_header("Allow", "POST")
             self.send_header("Content-Type", "application/json")
@@ -5692,7 +5812,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
     # ---- helpers ----
 
     def _respond_json(self, status: int, body: dict) -> None:
-        encoded = json.dumps(body).encode("utf-8")
+        encoded = encode_dashboard_json_bytes(body)
         self.send_response(status)
         self.send_header("Content-Type", "application/json")
         self.send_header("Content-Length", str(len(encoded)))
@@ -5763,7 +5883,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             # transcriptsEnabled=false, never enabled-then-403 (the pass-2 P2
             # finding) — one predicate, two consumers, desync impossible.
             env["transcriptsEnabled"] = visible
-            body = json.dumps(env, ensure_ascii=False).encode("utf-8")
+            body = encode_dashboard_json_bytes(env, ensure_ascii=False)
             self.send_response(200)
             self.send_header("Content-Type", "application/json; charset=utf-8")
             self.send_header("Content-Length", str(len(body)))
@@ -5798,9 +5918,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 runtime_bind=type(self).cctally_host,
             )
             report = _ld.run_checks(state)
-            body = json.dumps(
+            body = encode_dashboard_json_bytes(
                 _ld.serialize_json(report), ensure_ascii=False,
-            ).encode("utf-8")
+            )
             self.send_response(200)
             self.send_header("Content-Type", "application/json; charset=utf-8")
             self.send_header("Content-Length", str(len(body)))
@@ -5848,9 +5968,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         if detail is None:
             self.send_error(404, "session not found")
             return
-        body = json.dumps(
+        body = encode_dashboard_json_bytes(
             _session_detail_to_envelope(detail), ensure_ascii=False
-        ).encode("utf-8")
+        )
         self.send_response(200)
         self.send_header("Content-Type", "application/json; charset=utf-8")
         self.send_header("Content-Length", str(len(body)))
@@ -5897,14 +6017,28 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 "error": "source capability unavailable",
             })
             return
-        try:
-            snap = self.snapshot_ref.get()
-            detail = build_source_detail(
-                snapshot=snap,
-                source=source,
-                resource=resource,
-                key=key,
+        detail_kwargs = {
+            "source": source,
+            "resource": resource,
+            "key": key,
+        }
+        if resource == "project":
+            query = _urlparse.parse_qs(
+                _urlparse.urlsplit(self.path).query,
+                keep_blank_values=True,
             )
+            raw_weeks = query.get("weeks")
+            if raw_weeks is not None:
+                if len(raw_weeks) != 1 or raw_weeks[0] not in {"1", "4", "8", "12"}:
+                    self._respond_json(400, {
+                        "code": "source_capability_unavailable",
+                        "error": "source capability unavailable",
+                    })
+                    return
+                detail_kwargs["window_weeks"] = int(raw_weeks[0])
+        try:
+            detail_kwargs["snapshot"] = self.snapshot_ref.get()
+            detail = build_source_detail(**detail_kwargs)
         except SourceResourceNotFound:
             self._respond_json(404, {
                 "code": "source_resource_not_found",
@@ -6052,7 +6186,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         try:
             start_at = parse_iso_datetime(decoded, "start_at")
         except ValueError:
-            body = json.dumps({"error": "invalid start_at"}).encode("utf-8")
+            body = encode_dashboard_json_bytes({"error": "invalid start_at"})
             self.send_response(400)
             self.send_header("Content-Type", "application/json; charset=utf-8")
             self.send_header("Content-Length", str(len(body)))
@@ -6100,7 +6234,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 None,
             )
             if target is None:
-                body = json.dumps({"error": "block not found"}).encode("utf-8")
+                body = encode_dashboard_json_bytes({"error": "block not found"})
                 self.send_response(404)
                 self.send_header("Content-Type", "application/json; charset=utf-8")
                 self.send_header("Content-Length", str(len(body)))
@@ -6130,7 +6264,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             self.log_error("/api/block failed: %r", exc)
             self.send_error(500, "block detail failed")
             return
-        body = json.dumps(detail, ensure_ascii=False).encode("utf-8")
+        body = encode_dashboard_json_bytes(detail, ensure_ascii=False)
         self.send_response(200)
         self.send_header("Content-Type", "application/json; charset=utf-8")
         self.send_header("Content-Length", str(len(body)))
@@ -6192,7 +6326,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 env["transcriptsEnabled"] = transcripts_enabled
                 msg = (
                     "event: update\n"
-                    + "data: " + json.dumps(env, ensure_ascii=False) + "\n\n"
+                    + "data: "
+                    + encode_dashboard_json(env, ensure_ascii=False)
+                    + "\n\n"
                 )
                 self.wfile.write(msg.encode("utf-8"))
                 self.wfile.flush()
@@ -6390,7 +6526,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         try:
             for ev in worker.stream(run_id):
                 ev_type = ev.get("type", "message")
-                ev_data = json.dumps(
+                ev_data = encode_dashboard_json(
                     {k: v for k, v in ev.items() if k != "type"},
                     ensure_ascii=False,
                 )
@@ -6769,11 +6905,6 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
                         and _time.monotonic() - last_heal[0] >= 60.0):
                     last_heal[0] = _time.monotonic()
                     _dashboard_self_heal_orphans(skip_sync=self._skip_sync)
-                # #313 P3 (F7): throttled transcript retention prune, inside the
-                # measured iteration so its cost is in the cooldown work. Gated
-                # off under --no-sync (frozen mode makes no cache writes).
-                if not self._skip_sync:
-                    _dashboard_maybe_prune_retention()
 
             # Work-proportional cooldown (F10): sleep to t0 + max(interval, work)
             # so a slow rebuild cannot peg a full core. The manual POST /api/sync
@@ -6797,6 +6928,47 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     if sync_thread is not None:
         sync_thread.start()
 
+    # #320: transcript/search ingestion runs on its own thread and SQLite file.
+    # A multi-GB first rebuild or a contended conversations.db therefore cannot
+    # delay `_run_sync_now`, its `last_sync_at` stamp, or core SSE publication.
+    conversation_sync_stop = threading.Event()
+
+    def _conversation_sync_loop() -> None:
+        interval = max(5.0, float(args.sync_interval))
+        while not conversation_sync_stop.is_set():
+            conn = None
+            try:
+                conn = open_conversations_db()
+                sync_claude_conversations(conn)
+                sync_codex_conversations(conn)
+                _dashboard_maybe_prune_retention()
+            except (OSError, sqlite3.DatabaseError) as exc:
+                eprint(f"[conversations] background sync unavailable: {exc}")
+            except Exception as exc:  # noqa: BLE001
+                # Transcript parsing/normalization is deliberately outside the
+                # core freshness loop. Keep this worker alive so a later clean
+                # tick can self-heal instead of permanently stopping after one
+                # malformed provider record.
+                eprint(
+                    "[conversations] background sync failed: "
+                    f"{type(exc).__name__}: {exc}"
+                )
+            finally:
+                if conn is not None:
+                    conn.close()
+            conversation_sync_stop.wait(interval)
+
+    conversation_sync_thread = (
+        None if args.no_sync
+        else threading.Thread(
+            target=_conversation_sync_loop,
+            daemon=True,
+            name="dashboard-conversations-sync",
+        )
+    )
+    if conversation_sync_thread is not None:
+        conversation_sync_thread.start()
+
     # Spec §3.5 (codex review fix #5): update-check thread runs even
     # under --no-sync (frozen-data sessions still surface new versions).
     # Dedicated stop event so we can join cleanly on shutdown without
@@ -6879,6 +7051,9 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     finally:
         if sync_thread is not None:
             sync_thread.stop()
+        conversation_sync_stop.set()
+        if conversation_sync_thread is not None:
+            conversation_sync_thread.join(timeout=2)
         update_check_stop.set()
         srv.shutdown()
         http_thread.join(timeout=2)