feat(worker): persisted scan worklist (O(N) scan, robust to mid-scan changes)

Replace scan_chunk's O(N^2) tree re-walk-and-skip-to-cursor with a
persisted ScanWorkItem worklist: build_worklist walks the tree once at
scan start and inserts one row per album (idempotent via ON CONFLICT),
scan_chunk pops up to `limit` not-done rows by indexed cursor and marks
them done, and clear_worklist drops the scan's rows once drained.
scan_library is reimplemented on top of the worklist (one-shot scan_id,
drain, clear) with an unchanged signature/behavior. main.py's
maybe_run_scan now drives a generated scan.id through Config
(scan.id/scan.inProgress/scan.progress/scan.result) instead of a
scan.cursor string, so a mid-scan library change no longer risks
skipping or re-walking albums.

worker/lyra_worker/main.py

@@ -1,5 +1,6 @@
 import os
 import time
+import uuid
 
 import psycopg
 
@@ -14,7 +15,7 @@ from lyra_worker.registry import (
     build_adapters, build_browser, build_probe, build_resolver,
     build_similarity_sources, build_tagger,
 )
-from lyra_worker.scan import scan_chunk
+from lyra_worker.scan import build_worklist, clear_worklist, scan_chunk
 
 IDLE_SLEEP = 2.0
 HEARTBEAT_SECONDS = 15.0  # how often to stamp worker.heartbeat (its updatedAt = liveness)
@@ -58,29 +59,39 @@ def _parse_progress(s: str) -> tuple[int, int]:
 def maybe_run_scan(conn, resolver, probe, browser, config, dest_root: str = DEST_ROOT) -> None:
     """Advance a chunked library scan by at most one chunk per call, so the worker loop
     keeps claiming jobs and ticking the monitor between chunks. `scan.requested` starts a
-    fresh scan; `scan.inProgress`/`scan.cursor`/`scan.progress` persist state until the walk
-    is exhausted, at which point `scan.result` is written (matching the old one-shot output)."""
+    fresh scan (walk once -> ScanWorkItem worklist); `scan.inProgress`/`scan.id`/`scan.progress`
+    persist state until the worklist drains, at which point `scan.result` is written."""
     requested = str(config.get("scan.requested", "")).strip().lower() in _TRUE
     in_progress = str(config.get("scan.inProgress", "")).strip().lower() in _TRUE
     if not requested and not in_progress:
         return
     if requested and not in_progress:  # start a fresh scan
+        scan_id = uuid.uuid4().hex
         _set_config(conn, "scan.inProgress", "true")
         _set_config(conn, "scan.requested", "false")
-        _set_config(conn, "scan.cursor", "")
+        _set_config(conn, "scan.id", scan_id)
         _set_config(conn, "scan.progress", "0/0")
-        cursor, imported_so_far, skipped_so_far = "", 0, 0
-    else:  # resume the in-progress scan from its persisted cursor
-        cursor = config.get("scan.cursor", "") or ""
+        try:
+            build_worklist(conn, scan_id, dest_root)
+        except Exception as e:  # a scan error must never kill the worker
+            print(f"worker: library scan worklist build failed: {e}", flush=True)
+            conn.rollback()
+            _set_config(conn, "scan.inProgress", "false")
+            _set_config(conn, "scan.requested", "false")
+            return
+        imported_so_far, skipped_so_far = 0, 0
+    else:  # resume the in-progress scan
+        scan_id = config.get("scan.id", "") or ""
         imported_so_far, skipped_so_far = _parse_progress(config.get("scan.progress", ""))
+        if not scan_id:  # corrupt/absent state -> abandon; a new request restarts it
+            _set_config(conn, "scan.inProgress", "false")
+            return
     try:
-        new_cursor, imp, skp, done = scan_chunk(
-            conn, resolver, probe, browser, dest_root, cursor, _scan_chunk_size(config)
-        )
+        imp, skp, done = scan_chunk(conn, resolver, probe, browser, scan_id, _scan_chunk_size(config))
     except Exception as e:  # a scan error must never kill the worker
         print(f"worker: library scan chunk failed: {e}", flush=True)
         conn.rollback()
-        _set_config(conn, "scan.inProgress", "false")  # abandon the scan; a new request restarts it
+        _set_config(conn, "scan.inProgress", "false")
         _set_config(conn, "scan.requested", "false")
         return
     imported_total = imported_so_far + imp
@@ -88,11 +99,11 @@ def maybe_run_scan(conn, resolver, probe, browser, config, dest_root: str = DEST
     if done:
         _set_config(conn, "scan.result", f"imported {imported_total}, skipped {skipped_total}")
         _set_config(conn, "scan.progress", "")
-        _set_config(conn, "scan.cursor", "")
         _set_config(conn, "scan.inProgress", "false")
+        clear_worklist(conn, scan_id)
+        _set_config(conn, "scan.id", "")
         print(f"worker: library scan done — {imported_total} imported, {skipped_total} skipped", flush=True)
     else:
-        _set_config(conn, "scan.cursor", new_cursor)
         _set_config(conn, "scan.progress", f"{imported_total}/{skipped_total}")