test(restore): wait for the cancelled preview's worker before teardown (#350)

py3.13 on ubuntu-latest failed on PR #351 (run 40334794505) with
'Files still open at teardown: prompts.db, prompts.db-shm' in
test_cancel_while_reading_the_live_library. Cancelling the preview cannot
stop its executor thread, which goes on to open the live library; the test
returned without waiting, so that open could land between teardown's
close_all_instances() and assert_closed(). The test now waits for the
worker, as test_cancel_while_staging already does.

.github/workflows/code-quality.yml

@@ -19,6 +19,9 @@ jobs:
   security:
     name: bandit (high severity)
     runs-on: ubuntu-latest
+    # ceil(1.5 x slowest of three green main runs) + 3, never under 5 (test.yml): runs 40257217665,
+    # 40254137380, 40240706583 took 23s / 16s / 23s -> 5 min.
+    timeout-minutes: 5
 
     steps:
       - uses: actions/checkout@v7

.github/workflows/test.yml

@@ -19,10 +19,22 @@ concurrency:
 env:
   PYTHONFAULTHANDLER: "1"
 
+# Every job has a time limit: ceil(1.5 x the slowest of three recent green runs on main) + 3
+# minutes, never under 5. The 3 minutes leave room for the Python runner's watchdog (120 s, see
+# tests/run_suite.py) to print its stack dump before GitHub cancels the job. A limit changes only
+# with new measurements written here (TESTING.md "Time limits and hangs").
+# Measured 2026-10-26 on runs 40257217681 (3be0ada), 40240706568 (fb9134f), 40228167328 (f9835aa):
+#   py matrix, slowest py3.10 on windows-latest: 12m43s / 15m54s / 14m53s -> 27 min
+#     (ubuntu 5m27s-6m27s, macos 6m14s-8m30s, windows 11m42s-15m54s)
+#   real ComfyUI compatibility: 13m32s / 8m55s / 11m46s -> 24 min
+#   coverage gate (85%): 7m26s / 7m22s / 7m54s -> 15 min
+#   perf budget 30s / 29s / 27s, black and flake8 39s / 37s / 39s,
+#   frontend modules 23s / 19s / 29s -> 5 min (the floor)
 jobs:
   test:
     name: py${{ matrix.python-version }} on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 27
     strategy:
       fail-fast: false
       matrix:
@@ -45,12 +57,12 @@ jobs:
           pip install -r requirements-dev.txt
 
       - name: Run tests
-        run: python -m unittest discover -s tests -v
+        run: python -m tests.run_suite -v
 
   comfyui:
     name: real ComfyUI compatibility
     runs-on: ubuntu-latest
-    timeout-minutes: 25
+    timeout-minutes: 24
     steps:
       - uses: actions/checkout@v7
         with:
@@ -127,6 +139,7 @@ jobs:
   coverage:
     name: coverage gate (85%)
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v7
 
@@ -143,7 +156,7 @@ jobs:
 
       - name: Measure coverage
         run: |
-          python -m coverage run -m unittest discover -s tests
+          python -m coverage run -m tests.run_suite
           python -m coverage combine
           python -m coverage report --fail-under=85
 
@@ -154,6 +167,7 @@ jobs:
     name: perf budget
     if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - uses: actions/checkout@v7
 
@@ -176,6 +190,7 @@ jobs:
   lint:
     name: black and flake8
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-python@v7
@@ -188,6 +203,7 @@ jobs:
   js-test:
     name: frontend modules
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - uses: actions/checkout@v7
 

.gitignore

@@ -211,3 +211,6 @@ coverage/
 
 # Disposable upstream checkout for real-host CI
 .ci-comfyui/
+
+# Old library files a Move library renamed (never deleted; #249 S6b)
+*.moved-to-*

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
 
       - id: tests
         name: tests
-        entry: python -m unittest discover tests/ -v
+        entry: python -m tests.run_suite -q
         language: system
         pass_filenames: false
         stages: [pre-push]

README.md

@@ -501,6 +501,8 @@ To add your key:
 2. Paste it into the **CivitAI API Key** field in the Integrations settings
 3. Save and re-import to download any previously skipped images
 
+The key is sent only over HTTPS to CivitAI's own hosts. CivitAI serves images through a redirect to its storage host; PromptManager follows such a redirect only over HTTPS to a host on CivitAI's own `civitai.com`, `civitai.red` or `civitai.green` domains, at most three hops, and never sends the key with it. When downloads fail, the import's status line says how many; when none could be downloaded, it starts with a warning. The server log has one warning per failed image with the reason (HTTP status, refused redirect, size cap, unreadable image, timeout or network error).
+
 > **Note:** Re-importing is safe — PromptManager skips LoRAs that were already imported. To do a fresh import, the previous `lora-manager` data is cleared automatically before re-scanning.
 
 ### 🌐 Web Interface Features
@@ -751,9 +753,51 @@ ComfyUI_PromptManager/
 
 ## Configuration
 
+### Where your library lives
+
+New installs keep the library (`prompts.db`, `config.json` with the CivitAI key, the
+database backups and the logs) in ComfyUI's system user folder
+`ComfyUI/user/__promptmanager/`. An update, a reinstall or ComfyUI-Manager replacing
+the node folder no longer touches it, and ComfyUI's `/userdata` web API does not
+serve `__` system folders. Thumbnails stay in `output/thumbnails`.
+
+- **Upgrading from an earlier version:** your library stays where it is, in the node
+  folder, until you move it; nothing is moved on its own. The workspace shows a notice
+  above every page and System › Overview a "Library location" row. **Move library**
+  copies the database with SQLite's backup API, verifies the copy (integrity check, every
+  workflow document, the same rows in every table), copies `config.json` and the backups,
+  switches to the new folder without a restart and only then renames the old files
+  `prompts.db.moved-to-__promptmanager` and `config.json.moved-to-__promptmanager` (never
+  deleted; the old backups stay too). If anything fails, the library stays in the node
+  folder, unchanged. **Keep it here** stops the notice; the Overview row stays. Take a
+  backup first (System › Backup & export or the dashboard's Backup) as with any change.
+- **Your own folder:** set `PROMPT_MANAGER_DATA_DIR` to an absolute folder outside
+  ComfyUI's output, input and temp folders and your image sources. If it is empty and a
+  node-folder library exists, that library stays in use until you move it there.
+- **An explicit `database.default_path`** in `config.json` and `PROMPT_MANAGER_CONFIG_PATH`
+  keep working as before (described below); such a library is not offered a move.
+
+### Thumbnails
+
+Previews in `output/thumbnails` are written as **WebP, quality 80, 512 px** by default
+(System › Appearance › Thumbnails sets the format, quality and size limit for every
+preview). Previews from older versions keep their old format (usually PNG) until you
+run **Convert outdated** (System › Overview or Appearance): it rewrites each one from
+its original and then removes the old file. Nothing converts on its own.
+
+**JPEG XL** (smaller still) can be chosen once the server has an encoder. Install one
+of these, then restart ComfyUI:
+
+- `pip install pillow-jxl-plugin` in ComfyUI's Python environment (simplest), or
+- an `ffmpeg` on PATH built with `libjxl`, or
+- `cjxl` from [libjxl](https://github.com/libjxl/libjxl) on PATH.
+
+Browsers that cannot show JPEG XL see the original images in the grid instead.
+
 ### Database Settings
 
-You can customize the database path by creating a `config.json` file in the extension root:
+You can customize the database path by creating a `config.json` file in the library's
+folder (the node folder for a library that was not moved):
 
 ```json
 {
@@ -880,12 +924,12 @@ db.model.backup_database("backup_prompts.db")
 ```bash
 cd ComfyUI_PromptManager
 pip install -r requirements-dev.txt
-python -m unittest discover -s tests          # Python (what CI runs)
+python -m tests.run_suite                      # Python (what CI runs: unittest discovery plus a hang watchdog)
 node --test tests/js/*.test.js                 # frontend pure modules
-python -m coverage run -m unittest discover -s tests && python -m coverage combine && python -m coverage report
+python -m coverage run -m tests.run_suite && python -m coverage combine && python -m coverage report
 ```
 
-CI runs the suite on Linux, Windows and macOS for Python 3.10 to 3.12 with an 85% coverage gate. Tests that delete a database file first check that nothing in the process still holds it open (`tests/open_handles.py`), so a connection leak fails on Linux the way it would on Windows.
+CI runs the suite on Linux, Windows and macOS for Python 3.10 to 3.13 with an 85% coverage gate. `python -m unittest discover -s tests` still works; see `TESTING.md` ("Time limits and hangs") for the watchdog. Tests that delete a database file first check that nothing in the process still holds it open (`tests/open_handles.py`), so a connection leak fails on Linux the way it would on Windows.
 
 ### Code Style
 
@@ -970,6 +1014,15 @@ MIT License - see LICENSE file for details.
 
 ## Changelog
 
+### Unreleased (Library location)
+
+- **📁 Library outside the node folder**: new installs keep `prompts.db`, `config.json`, the database backups and the logs in `ComfyUI/user/__promptmanager/`, where an update or reinstall of the node cannot delete them and ComfyUI's `/userdata` API does not reach. An existing library stays in the node folder until you press **Move library** (a verified copy, then a live switch; the old files are renamed `*.moved-to-__promptmanager`, never deleted) or **Keep it here**. `PROMPT_MANAGER_DATA_DIR` names your own folder. After moving, restart ComfyUI once so the logs follow. Going back to an older version after a move: an older version does not look in `user/__promptmanager`, so stop ComfyUI and copy `user/__promptmanager/prompts.db` (with its `-wal` file, if one is left) and `config.json` into the node folder; the `*.moved-to-__promptmanager` files are the library as it was at the move, without later changes.
+
+### Unreleased (Workflows stored once)
+
+- **🗜️ Smaller database**: each distinct workflow and prompt graph is stored once, compressed, instead of again for every image. Images recorded by this version use it from the first start; the maintenance job "Store each workflow once" rewrites the existing records and then reclaims the space. A 20,000-image test library went from 1.4 GB to 60 MB. The job always takes a verified backup first: the first time, `prompts.db.pre-workflow-storage_<date time>` beside the database, kept until you delete it; on later runs, a normal pooled safety backup. No image or video file is opened or changed.
+- **⚠️ Downgrading**: images recorded by this version (and, after the job, all images) are stored in the new form. An older Prompt Manager version still opens and even restores such a database, but shows those images without workflows or prompt graphs until you update again. To go back to an older version, stop ComfyUI, delete `prompts.db-wal` and `prompts.db-shm`, and copy the **earliest** `prompts.db.pre-workflow-storage_<date time>` over `prompts.db`, or, if the job never ran, a backup taken before this update (records added since that backup are lost). Otherwise stay on this version.
+
 ### v3.3.1 (Proxy Routing Fix)
 
 - **🌐 Proxy support**: the dashboard, gallery, tag page and metadata viewer now work when ComfyUI is reached through a proxy mount such as SwarmUI's `/ComfyBackendDirect/`. Scripts, images, API calls, progress streams and gallery folder filters stay under the mount, and the canvas node's buttons use ComfyUI's `fileURL()`. Direct ComfyUI URLs are unchanged. Thanks to @ghosttigerllc-bit ([#164](https://github.com/ComfyAssets/ComfyUI_PromptManager/pull/164))

__init__.py

@@ -87,10 +87,22 @@ try:
     routes = config.routes
     api = PromptManagerAPI()
     api.add_routes(routes)
+    # Temp files of preview writes a crash interrupted (#317), off the
+    # import path: the walk may cover a large thumbnails folder.
+    import threading
+
+    threading.Thread(
+        target=api.sweep_thumbnail_temps,
+        name="PromptManagerPreviewTempSweep",
+        daemon=True,
+    ).start()
     host_app = getattr(config.server_instance, "app", None)
     if host_app is not None and hasattr(host_app, "on_cleanup"):
         host_app.on_cleanup.append(api.cleanup_history_reads)
         host_app.on_cleanup.append(api.cleanup_annotation_captures)
+    if host_app is not None and hasattr(host_app, "on_shutdown"):
+        # Open Needs review change streams end before the server waits on them.
+        host_app.on_shutdown.append(api.close_review_events)
 
 except Exception as e:
     # Log to internal logging system without console spam
@@ -122,6 +134,28 @@ try:
     _global_prompt_tracker = get_prompt_tracker(_global_db)
     _global_image_monitor = get_image_monitor(_global_db, _global_prompt_tracker)
 
+    # The Needs review pass for ambiguous new outputs runs through the API's
+    # capture store (the one the scan and the Tag dialog use): a linked output
+    # is never queued and its pending items leave the queue. It stops before
+    # that store is closed at shutdown.
+    _review_api = globals().get("api")
+    if _review_api is not None:
+        _global_image_monitor.set_review_recorder(_review_api.record_review_file)
+        # Every settled output's preview is queued for the API's background
+        # worker (#249): the workspace never asks to generate thumbnails.
+        _global_image_monitor.set_thumbnail_queue(_review_api.queue_capture_thumbnail)
+        _review_host = getattr(config.server_instance, "app", None)
+        if _review_host is not None and hasattr(_review_host, "on_cleanup"):
+
+            async def _stop_review_recording(
+                app, monitor=_global_image_monitor, api=_review_api
+            ):
+                monitor.set_review_recorder(None)
+                monitor.set_thumbnail_queue(None)
+                api.close_auto_thumbnails(final=True)
+
+            _review_host.on_cleanup.insert(0, _stop_review_recording)
+
     # Start monitoring
     _global_image_monitor.start_monitoring()
     _init_logger.info("Global image monitoring system started successfully")

database/category_import.py

@@ -0,0 +1,198 @@
+"""Atomic replacement of one imported category (#221, #249 System S10).
+
+The LoRA reference import used to delete its whole category and then save
+each record in its own transaction, so a failure part way left the previous
+collection deleted and the new one partial. ``replace_category_prompts``
+does both in one ``BEGIN IMMEDIATE`` transaction: the category's current
+prompts (with their tags and image links) are replaced by the staged
+records, or, on any error, nothing changes.
+
+A staged record is ``{text, hash, tags, images}``. A record whose hash a
+prompt outside the category already has links its images to that prompt
+(the legacy import did the same); a second record with the hash of an
+earlier one links its images to that one. Neither is a new prompt.
+"""
+
+from typing import Any, Dict, List, Optional, Sequence
+
+try:
+    from .maintenance import PlanChanged
+    from .pairs import PairDependencyError
+    from .workflow_documents import documents_of_rows, release_documents
+except ImportError:  # pragma: no cover - flat test imports
+    from database.maintenance import PlanChanged
+    from database.pairs import PairDependencyError
+    from database.workflow_documents import documents_of_rows, release_documents
+
+
+class EmptyReplacement(ValueError):
+    """The replacement has no record and would remove every current import."""
+
+
+# The category's prompt ids, as a subquery (one bound parameter).
+_IN_CATEGORY = "SELECT id FROM prompts WHERE category = ?"
+
+# Each record's outcome and the result counter it adds to.
+_COUNTERS = {"imported": "imported", "linked": "linked", "duplicate": "duplicates"}
+
+
+def _placeholders(values: Sequence[Any]) -> str:
+    return ",".join("?" * len(values))
+
+
+class CategoryImportOperations:
+    """Read the state of an imported category and replace it atomically."""
+
+    def category_import_state(self, category: str) -> Dict[str, Any]:
+        """``{ids, paired}``: the category's prompt ids (ascending) and how
+        many of them a saved pair uses (those block a replacement)."""
+        with self.model.get_connection() as conn:
+            ids = [
+                row[0]
+                for row in conn.execute(
+                    "SELECT id FROM prompts WHERE category = ? ORDER BY id",
+                    (category,),
+                ).fetchall()
+            ]
+            paired = conn.execute(
+                "SELECT COUNT(*) FROM prompts WHERE category = ? AND id IN "
+                "(SELECT positive_prompt_id FROM prompt_pairs UNION "
+                "SELECT negative_prompt_id FROM prompt_pairs)",
+                (category,),
+            ).fetchone()[0]
+        return {"ids": ids, "paired": paired}
+
+    def existing_prompt_hashes(
+        self, hashes: Sequence[str], exclude_category: str
+    ) -> set:
+        """The given hashes a prompt outside ``exclude_category`` already has."""
+        found = set()
+        wanted = list(dict.fromkeys(hashes))
+        with self.model.get_connection() as conn:
+            for start in range(0, len(wanted), 500):
+                chunk = wanted[start : start + 500]
+                rows = conn.execute(
+                    f"SELECT hash FROM prompts WHERE hash IN ({_placeholders(chunk)}) "
+                    "AND (category IS NULL OR category != ?)",
+                    [*chunk, exclude_category],
+                ).fetchall()
+                found.update(row[0] for row in rows)
+        return found
+
+    def replace_category_prompts(
+        self,
+        category: str,
+        records: List[Dict[str, Any]],
+        *,
+        expected_ids: Optional[List[int]] = None,
+        allow_empty: bool = False,
+    ) -> Dict[str, Any]:
+        """Replace every prompt of ``category`` with ``records`` in one transaction.
+
+        Raises (and changes nothing): ``PlanChanged`` when ``expected_ids`` is
+        given and the category's prompt ids differ from it;
+        ``PairDependencyError`` when a saved pair uses one of its prompts;
+        ``EmptyReplacement`` when ``records`` is empty while the category has
+        prompts, unless ``allow_empty`` (an empty replacement that was
+        reviewed). Any other error rolls everything back too.
+
+        Returns ``{removed, imported, linked, duplicates, images, rows}``:
+        prompts removed and created, records linked to an existing prompt or
+        to an earlier record with the same text, image links added, and per
+        record ``{name, outcome}`` (``imported``/``linked``/``duplicate``).
+        """
+        with self._pair_transaction() as conn:
+            ids = [
+                row[0]
+                for row in conn.execute(
+                    "SELECT id FROM prompts WHERE category = ? ORDER BY id",
+                    (category,),
+                ).fetchall()
+            ]
+            if expected_ids is not None and ids != list(expected_ids):
+                raise PlanChanged("The imported prompts changed since the review")
+            if not records and ids and not allow_empty:
+                raise EmptyReplacement(
+                    "Nothing to import; the previous imports were kept"
+                )
+            self._ensure_category_unpaired(conn, category)
+            removed = self._delete_category_rows(conn, category, ids)
+            result = {
+                "removed": removed,
+                "imported": 0,
+                "linked": 0,
+                "duplicates": 0,
+                "images": 0,
+                "rows": [],
+            }
+            created = {}
+            for record in records:
+                self._import_record(conn, category, record, created, result)
+            return result
+
+    def _delete_category_rows(self, conn, category: str, ids: List[int]) -> int:
+        """Delete the category's prompts with their image links and tags.
+
+        No commit. The rows are selected by category (just verified against
+        ``ids`` under the write lock), so no statement binds one parameter per
+        prompt and SQLite's variable limit never caps a collection.
+        """
+        if not ids:
+            return 0
+        documents = documents_of_rows(conn, "prompt_id", ids)  # chunked
+        conn.execute(
+            f"DELETE FROM generated_images WHERE prompt_id IN ({_IN_CATEGORY})",
+            (category,),
+        )
+        release_documents(conn, documents)
+        conn.execute(
+            f"DELETE FROM prompt_tags WHERE prompt_id IN ({_IN_CATEGORY})",
+            (category,),
+        )
+        return conn.execute(
+            "DELETE FROM prompts WHERE category = ?", (category,)
+        ).rowcount
+
+    @staticmethod
+    def _ensure_category_unpaired(conn, category: str) -> None:
+        """Raise PairDependencyError when a saved pair uses a category prompt."""
+        row = conn.execute(
+            f"SELECT id FROM prompt_pairs WHERE positive_prompt_id IN ({_IN_CATEGORY}) "
+            f"OR negative_prompt_id IN ({_IN_CATEGORY}) LIMIT 1",
+            (category, category),
+        ).fetchone()
+        if row:
+            raise PairDependencyError(
+                f"Prompt belongs to saved pair {row[0]}; delete the pair first "
+                "or save changed text as a new prompt"
+            )
+
+    def _import_record(self, conn, category, record, created, result) -> None:
+        """Save one staged record on ``conn``, or link it to the prompt it repeats."""
+        prompt_hash = record["hash"]
+        name = record.get("name") or record["text"]
+        if prompt_hash in created:
+            prompt_id, outcome = created[prompt_hash], "duplicate"
+        else:
+            row = conn.execute(
+                "SELECT id FROM prompts WHERE hash = ?", (prompt_hash,)
+            ).fetchone()
+            if row is not None:
+                prompt_id, outcome = row[0], "linked"
+            else:
+                prompt_id = self._insert_prompt(
+                    conn,
+                    record["text"],
+                    category,
+                    list(record.get("tags") or []),
+                    None,
+                    None,
+                    prompt_hash,
+                )
+                outcome = "imported"
+            created[prompt_hash] = prompt_id
+        result[_COUNTERS[outcome]] += 1
+        for image in record.get("images") or []:
+            if self._insert_image_link(conn, prompt_id, image):
+                result["images"] += 1
+        result["rows"].append({"name": name, "outcome": outcome})

database/duplicate_copies.py

@@ -0,0 +1,215 @@
+"""Records of duplicate image files: count them and move them (#249 S6, T17).
+
+A removed copy's records move to its verified kept copy before the copy is
+unlinked (``py/api/duplicate_files.py``), one file per short ``BEGIN
+IMMEDIATE`` transaction, so no row ever names a deleted file:
+
+- its image records (``generated_images``), found under every spelling the
+  file is linked by. A record moves to the kept copy, unless its prompt
+  already links the kept copy: then its saved-pair links join that record
+  and it is deleted;
+- its favorite;
+- its image tags (``media_image_tags`` of its byte record), joined onto the
+  kept copy's byte record as their union, in order;
+- its pending Needs review items, settled: only an item still ``pending`` at
+  revision 0 with no decision row is removed (``review._SETTLE_ITEM``), so a
+  decided item is never touched.
+
+Every statement is an index search (see ``FILE_LINK_SQL``).
+"""
+
+import os
+
+from .annotation_schema import BYTES_TABLE, FILES_TABLE
+from .annotations import _BUMP_INDEX
+from .models import normalize_image_path, utc_now_iso
+from .review import _BUMP_REVIEW_INDEX, _PENDING_OF_LOCATOR, _SETTLE_ITEM
+from .review_changes import notify_review_change
+from .workflow_documents import documents_of_rows, release_documents
+
+LINKS_BY_FILE_SQL = "SELECT id, prompt_id FROM generated_images WHERE file_path = ?"
+LEGACY_LINKS_SQL = (
+    "SELECT id, prompt_id FROM generated_images "
+    "WHERE image_path = ? AND file_path IS NULL"
+)
+KEEPER_LINK_SQL = (
+    "SELECT id FROM generated_images WHERE prompt_id = ? AND file_path = ?"
+)
+MOVE_PAIR_LINKS_SQL = (
+    "UPDATE OR IGNORE image_prompt_pairs SET image_id = ? WHERE image_id = ?"
+)
+MOVE_LINK_SQL = (
+    "UPDATE generated_images SET image_path = ?, filename = ?, file_path = ? "
+    "WHERE id = ?"
+)
+DELETE_LINK_SQL = "DELETE FROM generated_images WHERE id = ?"
+FAVORITE_SQL = (
+    "SELECT created_at FROM image_favorites WHERE root_key = ? AND relative_path = ?"
+)
+INSERT_FAVORITE_SQL = "INSERT OR IGNORE INTO image_favorites VALUES (?, ?, ?)"
+DELETE_FAVORITE_SQL = (
+    "DELETE FROM image_favorites WHERE root_key = ? AND relative_path = ?"
+)
+COPY_BYTE_SQL = (
+    f"SELECT b.id FROM {FILES_TABLE} f JOIN {BYTES_TABLE} b "  # nosec B608
+    "ON b.file_id=f.id WHERE f.locator=? AND b.sha256=?"
+)
+COPY_TAG_COUNT_SQL = (
+    "SELECT COUNT(*) FROM media_image_tags WHERE byte_id=?"  # nosec B608
+)
+PENDING_COUNT_SQL = (
+    f"SELECT COUNT(*) FROM {FILES_TABLE} f "  # nosec B608
+    f"JOIN {BYTES_TABLE} b ON b.file_id=f.id "
+    "JOIN media_review_items i ON i.byte_id=b.id "
+    "WHERE f.locator=? AND +i.state='pending' AND i.revision=0 "
+    "AND NOT EXISTS (SELECT 1 FROM media_review_decisions d WHERE d.item_id=i.id)"
+)
+FILE_LINK_SQL = (
+    LINKS_BY_FILE_SQL,
+    LEGACY_LINKS_SQL,
+    KEEPER_LINK_SQL,
+    MOVE_PAIR_LINKS_SQL,
+    MOVE_LINK_SQL,
+    DELETE_LINK_SQL,
+    FAVORITE_SQL,
+    DELETE_FAVORITE_SQL,
+    COPY_BYTE_SQL,
+    COPY_TAG_COUNT_SQL,
+    PENDING_COUNT_SQL,
+)
+
+
+def _file_link_rows(conn, spelled):
+    """``(id, prompt_id)`` of the image records linking one spelling."""
+    rows = list(conn.execute(LINKS_BY_FILE_SQL, (normalize_image_path(spelled),)))
+    rows += list(conn.execute(LEGACY_LINKS_SQL, (spelled,)))
+    return [tuple(row) for row in rows]
+
+
+def _copy_byte(conn, locator, sha256):
+    row = conn.execute(COPY_BYTE_SQL, (locator, sha256)).fetchone()
+    return row[0] if row else None
+
+
+class DuplicateCopyOperations:
+    """PromptDatabase mixin: the records of duplicate copies."""
+
+    def count_copy_records(self, copies) -> dict:
+        """``{path: {links, tags, review}}`` for each copy (one read snapshot).
+
+        ``copies`` maps each path to ``{spellings, locator, sha256}``:
+        ``links`` counts the image records under any spelling, ``tags`` the
+        image tags of its bytes and ``review`` its pending, undecided Needs
+        review items.
+        """
+        from .maintenance import _read_snapshot
+
+        def read(conn):
+            found = {}
+            for path, copy in copies.items():
+                ids = {
+                    row[0]
+                    for spelled in copy["spellings"]
+                    for row in _file_link_rows(conn, spelled)
+                }
+                byte_id = _copy_byte(conn, copy["locator"], copy["sha256"])
+                tags = (
+                    conn.execute(COPY_TAG_COUNT_SQL, (byte_id,)).fetchone()[0]
+                    if byte_id
+                    else 0
+                )
+                review = conn.execute(PENDING_COUNT_SQL, (copy["locator"],))
+                found[path] = {
+                    "links": len(ids),
+                    "tags": tags,
+                    "review": review.fetchone()[0],
+                }
+            return found
+
+        return _read_snapshot(self.model.db_path, read)
+
+    def move_copy_records(self, move) -> dict:
+        """Move one removed copy's records to its kept copy (one transaction).
+
+        ``move``: ``removed`` and ``kept`` (the spellings each file is linked
+        by), ``targets`` (``{removed spelling: kept spelling}``, the spelling
+        a moved record takes; else ``kept_path``), ``favorites`` (``(root key,
+        removed key, kept root key, kept key)`` per listed root holding the
+        file), ``removed_locator``,
+        ``kept_locator``, ``sha256`` and the kept copy's ``kept_size`` and
+        ``kept_mtime_ns``. Returns ``{moved, merged, favorites, tags,
+        review}``.
+        """
+        counts = dict.fromkeys(("moved", "merged", "favorites", "tags", "review"), 0)
+        kept_keys = [normalize_image_path(path) for path in move["kept"]]
+        with self._pair_transaction() as conn:
+            for spelled in dict.fromkeys(move["removed"]):
+                target = move["targets"].get(spelled, move["kept_path"])
+                keys = list(dict.fromkeys(kept_keys + [normalize_image_path(target)]))
+                for image_id, prompt_id in _file_link_rows(conn, spelled):
+                    existing = None
+                    for key in keys:
+                        existing = conn.execute(
+                            KEEPER_LINK_SQL, (prompt_id, key)
+                        ).fetchone()
+                        if existing is not None:
+                            break
+                    if existing is not None:
+                        conn.execute(MOVE_PAIR_LINKS_SQL, (existing[0], image_id))
+                        documents = documents_of_rows(conn, "id", [image_id])
+                        conn.execute(DELETE_LINK_SQL, (image_id,))
+                        release_documents(conn, documents)
+                        counts["merged"] += 1
+                        continue
+                    conn.execute(
+                        MOVE_LINK_SQL,
+                        (
+                            target,
+                            os.path.basename(target),
+                            normalize_image_path(target),
+                            image_id,
+                        ),
+                    )
+                    counts["moved"] += 1
+            for favorite in move.get("favorites", ()):
+                counts["favorites"] += _move_favorite(conn, *favorite)
+            counts["tags"] = self._move_copy_tags(conn, move)
+            for (item_id,) in conn.execute(
+                _PENDING_OF_LOCATOR, (move["removed_locator"],)
+            ).fetchall():
+                counts["review"] += conn.execute(_SETTLE_ITEM, (item_id,)).rowcount
+            if counts["review"]:
+                conn.execute(_BUMP_REVIEW_INDEX)
+        if counts["review"]:
+            notify_review_change(self.model.db_path)
+        return counts
+
+    def _move_copy_tags(self, conn, move):
+        """Join the removed copy's image tags onto the kept copy's; the count added."""
+        removed = _copy_byte(conn, move["removed_locator"], move["sha256"])
+        if removed is None:
+            return 0
+        tags = self._byte_tags(conn, removed)
+        if not tags:
+            return 0
+        now = utc_now_iso()
+        file_id = self._annotation_owner(conn, move["kept_locator"], now)
+        byte_id, _revision, created, moved = self._annotation_byte(
+            conn, file_id, move["sha256"], move["kept_size"], move["kept_mtime_ns"], now
+        )
+        current = self._byte_tags(conn, byte_id)
+        union = current + [tag for tag in tags if tag not in current]
+        if union != current:
+            self._write_image_tags(conn, byte_id, union)
+        elif created or moved:
+            conn.execute(_BUMP_INDEX)
+        return len(union) - len(current)
+
+
+def _move_favorite(conn, root_key, removed_key, kept_root, kept_key):
+    row = conn.execute(FAVORITE_SQL, (root_key, removed_key)).fetchone()
+    if row is None:
+        return 0
+    conn.execute(INSERT_FAVORITE_SQL, (kept_root, kept_key, row[0]))
+    conn.execute(DELETE_FAVORITE_SQL, (root_key, removed_key))
+    return 1

database/execution_history.py

@@ -196,3 +196,14 @@ class ExecutionHistoryOperations:
             .fetchone()
         )
         return dict(row) if row is not None else None
+
+
+def rekey_history_restore(old_path: str, new_path: str) -> None:
+    """Move the observers of ``old_path`` to ``new_path`` (Move library)."""
+    old, new = _database_identity(old_path), _database_identity(new_path)
+    if old == new:
+        return
+    with _restore_lock:
+        observers = _restore_observers.pop(old, None)
+        if observers:
+            _restore_observers.setdefault(new, {}).update(observers)

database/execution_outputs.py

@@ -4,6 +4,8 @@ import sqlite3
 from contextlib import ExitStack
 from typing import Callable, ContextManager
 
+from .run_attribution import notify_outputs_sealed
+
 try:
     from ..utils.execution_history_events import RunFinish, encode_command
     from ..utils.execution_outputs import OutputBundle, validate_output_bundle
@@ -113,6 +115,10 @@ class ExecutionOutputOperations:
                     "VALUES(?,?,?,?,?,?,?,?)",
                     [(run_id, *reference) for reference in prepared],
                 )
+        # Committed: images waiting for this run may now be attributed (#342)
+        notify_outputs_sealed(
+            run_id, [dict(zip(_REFERENCE_FIELDS, row)) for row in prepared]
+        )
         return True
 
     def get_execution_outputs(self, run_id: str) -> dict:

database/health.py

@@ -189,6 +189,33 @@ def _image_owner(image_path, file_path, prefixes):
     return owner
 
 
+def readable_roots(roots):
+    """Whether each source can be read now (an unmounted drive cannot)."""
+    return [_readable(root) for root in roots]
+
+
+def link_states(rows, roots, readable):
+    """``(row, owner, state)`` for each image row ``(id, image_path, filename,
+    file_path)``: ``owner`` is the index of the source it lies under (None
+    outside every source) and ``state`` is ``missing``, ``present``,
+    ``unavailable`` (its source cannot be read, so the file is not looked at)
+    or ``outside``. ``readable`` is ``readable_roots(roots)``. The health
+    check's ``missing_files`` and the maintenance missing-link plan both
+    judge links this way, so their counts agree.
+    """
+    prefixes = [_root_prefix(root) for root in roots]
+    for row in rows:
+        owner = _image_owner(row[1], row[3], prefixes)
+        if owner is None:
+            yield row, None, "outside"
+        elif not readable[owner]:
+            yield row, owner, "unavailable"
+        elif os.path.exists(row[1]):
+            yield row, owner, "present"
+        else:
+            yield row, owner, "missing"
+
+
 def _unavailable_line(unavailable, *, partial):
     noun = "source is" if unavailable == 1 else "sources are"
     effect = "its files were" if unavailable == 1 else "their files were"
@@ -224,7 +251,7 @@ def _missing_files(conn, roots):
 
 def _check_files(rows, roots):
     """The ``missing_files`` result of the image *rows*, from the file system."""
-    readable = [_readable(root) for root in roots]
+    readable = readable_roots(roots)
     sources = [
         {
             "name": _source_name(root, index),
@@ -239,13 +266,12 @@ def _check_files(rows, roots):
             None, [_unavailable_line(unavailable, partial=False)], status="unavailable"
         )
         return {**result, "partial": False, "sources": sources}
-    prefixes = [_root_prefix(root) for root in roots]
     outside, missing = 0, []
-    for image_id, image_path, filename, file_path in rows:
-        owner = _image_owner(image_path, file_path, prefixes)
-        if owner is None:
+    for row, owner, state in link_states(rows, roots, readable):
+        if state == "outside":
             outside += 1
-        elif readable[owner] and not os.path.exists(image_path):
+        elif state == "missing":
+            image_id, image_path, filename, _file_path = row
             sources[owner]["count"] += 1
             if len(missing) < MAX_DETAIL:
                 name = filename or os.path.basename(image_path)

database/library.py

@@ -637,7 +637,8 @@ class LibraryOperations:
         pairs (every pair's positive is eligible). ``images`` counts indexed
         ``generated_images`` rows, not files on disk. An image has no rating
         of its own (it shows its linked prompt's), so ``rated_images`` counts
-        the indexed images whose linked prompt is rated.
+        the indexed images whose linked prompt is rated. ``review_pending`` is
+        the Needs review queue's pending total.
         """
         with self.library_snapshot() as (conn, _epoch, _ceiling):
             row = conn.execute(
@@ -645,13 +646,15 @@ class LibraryOperations:
                 "(SELECT COUNT(*) FROM prompt_pairs WHERE archived=0),"
                 "(SELECT COUNT(*) FROM generated_images),"
                 "(SELECT COUNT(*) FROM generated_images gi JOIN prompts r "
-                "ON r.id=gi.prompt_id WHERE r.rating IS NOT NULL)"
+                "ON r.id=gi.prompt_id WHERE r.rating IS NOT NULL),"
+                "(SELECT COUNT(*) FROM media_review_items WHERE state='pending')"
             ).fetchone()
         return {
             "positive_prompts": row[0],
             "negative_variants": row[1],
             "images": row[2],
             "rated_images": row[3],
+            "review_pending": row[4],
         }
 
     def usage_by_category(self) -> list[dict]:

database/library_move.py

@@ -0,0 +1,805 @@
+"""Move library (#249 S6b): copy the node-folder library, verify it, switch.
+
+``plan_move`` checks a ``utils.library_location`` location can move and
+sizes the copy; ``move_library`` does it, in this order:
+
+1. **Disk check** on the target's volume (the copy, the backups and
+   config.json, plus a margin). The source is never renamed across folders,
+   so another drive is simply a copy.
+2. **Copy** with SQLite's backup API from a private connection holding one
+   read transaction: the per-table counts, the workflow documents' digest
+   and ``PRAGMA data_version`` describe exactly the copied snapshot. The copy
+   is a temp file in the target folder, made self-contained
+   (``journal_mode=DELETE``), fsynced and owner-only.
+3. **Verify**: ``verify_database_file`` (integrity check, schema, every
+   workflow document decompressed against its hash, #315), the same row
+   count in every table and the same documents.
+4. **Copy files**: every pooled safety backup and pre-migration backup,
+   checked by size and SHA-256 after the copy (their times are kept, so the
+   pool prunes in the same order).
+5. **Publish** under the old database's write lock (``BEGIN IMMEDIATE``) and
+   the config.json lock: if any other connection wrote since the snapshot
+   (``data_version``), steps 2–4 run again (``attempts``, then
+   ``library-busy``). Else config.json is copied (owner-only, checked), a
+   ``pending`` marker is written, the temp files take their final names
+   (``os.replace`` inside the target folder), the marker turns ``moved``
+   and ``switch`` points the process at the new library while the old file
+   is still locked, so no write can land in it.
+6. **Retire**: the old file's WAL is checkpointed and the old ``prompts.db``
+   and ``config.json`` are renamed ``*.moved-to-<folder>`` (never deleted;
+   the old backups stay where they are). A file still open elsewhere is left
+   in place and reported (``old-in-use``): the marker already makes a restart
+   use the new library.
+
+Any failure before the marker says ``moved`` removes everything the move
+wrote in the target folder and leaves the old library in use, untouched.
+A crash at any point leaves either the old library in use (the marker is
+absent or ``pending``; the next move replaces its own leftovers) or the new
+one (``moved``). ``MoveFailed`` carries a code and a message without paths.
+"""
+
+import contextlib
+import hashlib
+import json
+import os
+import shutil
+import sqlite3
+import time
+import types
+import uuid
+from pathlib import Path
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional, Tuple
+
+from .models import BUSY_TIMEOUT_SECONDS, PromptModel
+
+try:
+    from ..utils import library_location as ll
+    from ..utils.logging_config import get_logger
+except ImportError:
+    from utils import library_location as ll
+    from utils.logging_config import get_logger
+
+logger = get_logger("prompt_manager.database.library_move")
+
+TEMP_PREFIX = ".pm-move-"
+MOVED_INFIX = ".moved-to-"
+DISK_MARGIN_BYTES = 16 * 2**20
+DEFAULT_ATTEMPTS = 3
+_COPY_CHUNK = 4 * 2**20
+# Backups that live beside the database and move with it.
+BACKUP_INFIXES = (".backup_", ".pre-workflow-storage_")
+
+MESSAGES = {
+    "not-movable": (
+        "This library is not in the node folder, so there is nothing to move."
+    ),
+    "same-folder": "The new folder is the node folder itself.",
+    "target-invalid": "The new folder cannot hold the library.",
+    "target-has-library": (
+        "The new folder already holds a Prompt Manager library. Nothing was moved."
+    ),
+    "target-conflict": (
+        "The new folder already holds files with the same names. Nothing was moved."
+    ),
+    "insufficient-space": (
+        "There is not enough free space for the copy. Nothing was moved."
+    ),
+    "copy-failed": "The copy could not be written or did not match. Nothing was moved.",
+    "verify-failed": "The copy did not pass verification. Nothing was moved.",
+    "library-busy": (
+        "Prompt Manager kept writing to the library while it was copied. "
+        "Nothing was moved; try again when no workflow is running."
+    ),
+    "switch-failed": (
+        "Prompt Manager could not switch to the verified copy, so the copy was "
+        "removed. Nothing was moved."
+    ),
+}
+
+
+class MoveFailed(Exception):
+    """A move that did not happen (or did not finish), with a coded reason."""
+
+    def __init__(self, code: str, message: Optional[str] = None):
+        self.code = code
+        self.message = message or MESSAGES.get(code, "The library was not moved.")
+        super().__init__(self.message)
+
+
+@dataclass(frozen=True)
+class MovePlan:
+    location: "ll.LibraryLocation"
+    db_path: str
+    source_dir: str
+    target_dir: str
+    config_path: Optional[str]
+    backups: Tuple[str, ...]
+    db_bytes: int
+    files_bytes: int
+
+    @property
+    def required_bytes(self) -> int:
+        return self.db_bytes + self.files_bytes + DISK_MARGIN_BYTES
+
+    @property
+    def target_location(self) -> "ll.LibraryLocation":
+        """Where the library is once moved (an explicit config.json stays)."""
+        source = self.location.target_source or ll.SOURCE_DEFAULT
+        config = (
+            self.location.config_path
+            if self.location.config_explicit
+            else os.path.join(self.target_dir, ll.CONFIG_NAME)
+        )
+        return ll.LibraryLocation(
+            source,
+            os.path.join(self.target_dir, ll.DATABASE_NAME),
+            config,
+            self.target_dir,
+            self.target_dir,
+            None,
+            source,
+            self.location.config_explicit,
+        )
+
+
+@dataclass
+class MoveResult:
+    location: "ll.LibraryLocation"
+    counts: Dict[str, int]
+    files: List[str]
+    renamed: List[str] = field(default_factory=list)
+    retire_problem: Optional[str] = None
+
+
+def _size(path: str) -> int:
+    try:
+        return os.path.getsize(path)
+    except OSError:
+        return 0
+
+
+def _free_bytes(path: str) -> int:
+    return shutil.disk_usage(path).free
+
+
+def _existing_ancestor(path: str) -> str:
+    current = os.path.abspath(path)
+    while not os.path.isdir(current):
+        parent = os.path.dirname(current)
+        if parent == current:
+            break
+        current = parent
+    return current
+
+
+def backup_names(db_path: str) -> Tuple[str, ...]:
+    """The pooled and pre-migration backups beside ``db_path`` (names)."""
+    folder = os.path.dirname(os.path.abspath(db_path))
+    base = os.path.basename(db_path)
+    prefixes = tuple(base + infix for infix in BACKUP_INFIXES)
+    try:
+        names = os.listdir(folder)
+    except OSError:
+        return ()
+    return tuple(
+        sorted(
+            name
+            for name in names
+            if name.startswith(prefixes) and os.path.isfile(os.path.join(folder, name))
+        )
+    )
+
+
+def plan_move(location) -> MovePlan:
+    """Check ``location`` can move to its target; raises MoveFailed."""
+    if not location.movable:
+        raise MoveFailed("not-movable")
+    target = os.path.abspath(location.target_dir)
+    source_dir = os.path.dirname(os.path.abspath(location.db_path))
+    if ll.same_folder(target, source_dir) or os.path.normcase(
+        os.path.realpath(target)
+    ) == os.path.normcase(os.path.realpath(source_dir)):
+        raise MoveFailed("same-folder")
+    if os.path.exists(target) and not os.path.isdir(target):
+        raise MoveFailed("target-invalid")
+    backups = backup_names(location.db_path)
+    # config.json moves with a node-folder library; one named by
+    # PROMPT_MANAGER_CONFIG_PATH is the user's and stays where it is.
+    config = None if location.config_explicit else location.config_path
+    config = config if config and os.path.isfile(config) else None
+    if ll.read_marker(target).get("state") != ll.MARKER_PENDING:
+        if os.path.exists(os.path.join(target, ll.DATABASE_NAME)):
+            raise MoveFailed("target-has-library")
+        names = [ll.CONFIG_NAME] if config else []
+        if any(os.path.exists(os.path.join(target, n)) for n in names + list(backups)):
+            raise MoveFailed("target-conflict")
+    db_bytes = _size(location.db_path) + _size(location.db_path + "-wal")
+    files_bytes = sum(_size(os.path.join(source_dir, n)) for n in backups)
+    files_bytes += _size(config) if config else 0
+    return MovePlan(
+        location,
+        os.path.abspath(location.db_path),
+        source_dir,
+        target,
+        config,
+        backups,
+        db_bytes,
+        files_bytes,
+    )
+
+
+def space_problem(plan: MovePlan) -> Optional[Tuple[int, int]]:
+    """``(required, free)`` when the target's volume is short, else None."""
+    free = _free_bytes(_existing_ancestor(plan.target_dir))
+    if free < plan.required_bytes:
+        return plan.required_bytes, free
+    return None
+
+
+# ── copy and verify ───────────────────────────────────────────────────
+
+
+def _tables(conn) -> List[str]:
+    return [
+        row[0]
+        for row in conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' "
+            "AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        )
+    ]
+
+
+def _describe(conn) -> Tuple[Dict[str, int], str]:
+    """Row counts per table and a digest of the workflow documents."""
+    counts = {}
+    for table in _tables(conn):
+        # A name read from sqlite_master, quoted as an identifier.
+        quoted = '"' + table.replace('"', '""') + '"'
+        sql = f"SELECT COUNT(*) FROM {quoted}"  # nosec B608
+        counts[table] = conn.execute(sql).fetchone()[0]
+    digest = hashlib.sha256()
+    if "workflow_documents" in counts:
+        for row in conn.execute(
+            "SELECT id, sha256, byte_length FROM workflow_documents ORDER BY id"
+        ):
+            digest.update(repr((row[0], bytes(row[1]), row[2])).encode())
+    return counts, digest.hexdigest()
+
+
+def _fsync_file(path: str) -> None:
+    with open(path, "rb+") as handle:
+        os.fsync(handle.fileno())
+
+
+def _fsync_dir(path: str) -> None:
+    if os.name != "posix":
+        return
+    fd = os.open(path, os.O_RDONLY)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def _private(path: str) -> None:
+    if os.name == "posix":
+        os.chmod(path, 0o600)
+
+
+def _copy_snapshot(source: sqlite3.Connection, temp: str):
+    """Back up ``source``'s current snapshot to ``temp``; return what it holds."""
+    source.execute("BEGIN")
+    try:
+        version = source.execute("PRAGMA data_version").fetchone()[0]
+        counts, documents = _describe(source)
+        destination = sqlite3.connect(temp)
+        try:
+            source.backup(destination)
+        finally:
+            destination.close()
+    finally:
+        source.execute("COMMIT")
+    with contextlib.closing(sqlite3.connect(temp)) as conn:
+        conn.execute("PRAGMA journal_mode=DELETE").fetchone()
+    _fsync_file(temp)
+    _private(temp)
+    return version, counts, documents
+
+
+def _verify_copy(temp: str, counts, documents) -> None:
+    ok, reason = PromptModel.verify_database_file(temp)
+    if not ok:
+        logger.error(f"Library move: the copy did not verify: {reason}")
+        detail = reason if reason.startswith("Workflow document") else None
+        raise MoveFailed(
+            "verify-failed",
+            f"{MESSAGES['verify-failed']} {detail}" if detail else None,
+        )
+    uri = Path(os.path.abspath(temp)).as_uri() + "?mode=ro"
+    try:
+        with contextlib.closing(sqlite3.connect(uri, uri=True)) as conn:
+            copied = _describe(conn)
+    except sqlite3.Error as error:
+        logger.error(f"Library move: the copy could not be read: {error}")
+        raise MoveFailed("verify-failed") from error
+    if copied != (counts, documents):
+        logger.error("Library move: the copy's rows or documents differ")
+        raise MoveFailed("verify-failed")
+
+
+def _hash_copy(source: str, destination: str) -> Tuple[int, str]:
+    """Copy ``source`` to ``destination`` (fsynced, owner-only, times kept)."""
+    digest = hashlib.sha256()
+    size = 0
+    with open(source, "rb") as reader, open(destination, "wb") as writer:
+        while True:
+            chunk = reader.read(_COPY_CHUNK)
+            if not chunk:
+                break
+            digest.update(chunk)
+            size += len(chunk)
+            writer.write(chunk)
+        writer.flush()
+        os.fsync(writer.fileno())
+    stat = os.stat(source)
+    os.utime(destination, ns=(stat.st_atime_ns, stat.st_mtime_ns))
+    _private(destination)
+    return size, digest.hexdigest()
+
+
+def _file_digest(path: str) -> Tuple[int, str]:
+    digest = hashlib.sha256()
+    size = 0
+    with open(path, "rb") as reader:
+        while True:
+            chunk = reader.read(_COPY_CHUNK)
+            if not chunk:
+                return size, digest.hexdigest()
+            digest.update(chunk)
+            size += len(chunk)
+
+
+def _check_copies(copies) -> None:
+    for source, temp, expected in copies:
+        if _file_digest(temp) != expected or _file_digest(source) != expected:
+            logger.error(
+                f"Library move: {os.path.basename(source)} did not copy unchanged"
+            )
+            raise MoveFailed("copy-failed")
+
+
+def write_marker(
+    directory: str, state: str, source_db: str, source_config: Optional[str] = None
+) -> str:
+    """Atomically write the move marker; return its path.
+
+    ``from`` and ``config_from`` name the old files, so a restart after a
+    crash between the switch and the rename can finish the rename.
+    """
+    path = os.path.join(directory, ll.MARKER_NAME)
+    temp = os.path.join(directory, f"{TEMP_PREFIX}{uuid.uuid4().hex}.marker")
+    payload = json.dumps(
+        {
+            "version": 1,
+            "state": state,
+            "from": source_db,
+            "config_from": source_config,
+            "updated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        },
+        indent=2,
+    ).encode("utf-8")
+    fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+        _private(temp)
+        os.replace(temp, path)
+    except BaseException:
+        _remove(temp)
+        raise
+    _fsync_dir(directory)
+    return path
+
+
+def _remove(*paths) -> None:
+    for path in paths:
+        try:
+            if path and os.path.lexists(path):
+                os.remove(path)
+        except OSError:
+            logger.warning(f"Library move: could not remove {os.path.basename(path)}")
+
+
+def sweep_move_temps(directory: str) -> List[str]:
+    """Remove the temp files an interrupted move left in ``directory``."""
+    removed = []
+    try:
+        names = os.listdir(directory)
+    except OSError:
+        return removed
+    for name in names:
+        if name.startswith(TEMP_PREFIX):
+            _remove(os.path.join(directory, name))
+            removed.append(name)
+    return removed
+
+
+# ── the move ─────────────────────────────────────────────────────────
+
+
+def _noop(*_args, **_kwargs):
+    return None
+
+
+def switch_process(old_db: str, location, detached: list) -> None:
+    """Point this process at ``location``: resolver, every model, observers.
+
+    Adds the old file's connections, detached and still open, to
+    ``detached`` as soon as they are detached, so the mover retires them
+    (``PromptModel.retire_detached``) whether or not the rest succeeds.
+    """
+    from .execution_history import rekey_history_restore
+    from .review_changes import rekey_review_changes
+
+    ll.switch_to(location)
+    detached.extend(PromptModel.repoint_instances(old_db, location.db_path))
+    rekey_review_changes(old_db, location.db_path)
+    rekey_history_restore(old_db, location.db_path)
+
+
+def unswitch_process(old_db: str, new_db: str) -> list:
+    """Undo ``switch_process`` (any part of it); returns detached connections."""
+    from .execution_history import rekey_history_restore
+    from .review_changes import rekey_review_changes
+
+    ll.clear_override()
+    detached = PromptModel.repoint_instances(new_db, old_db)
+    rekey_review_changes(new_db, old_db)
+    rekey_history_restore(new_db, old_db)
+    return detached
+
+
+class _Move:
+    def __init__(self, plan, *, switch, config_lock, progress, checkpoint):
+        self.plan = plan
+        self.switch = switch
+        self.config_lock = config_lock
+        self.progress = progress
+        self.checkpoint = checkpoint
+        self.created_dir = False
+        self.temps: List[str] = []
+        self.published: List[str] = []
+        self.marker: Optional[str] = None
+        self.moved = False
+        # Retired connections still in use; awaited once the locks are free.
+        self.retiring: list = []
+
+    def temp(self, suffix: str) -> str:
+        path = os.path.join(
+            self.plan.target_dir, f"{TEMP_PREFIX}{uuid.uuid4().hex}{suffix}"
+        )
+        self.temps.append(path)
+        return path
+
+    def prepare_target(self) -> None:
+        target = self.plan.target_dir
+        self.created_dir = not os.path.isdir(target)
+        ll.ensure_private_dir(target)
+        sweep_move_temps(target)
+        if ll.read_marker(target).get("state") == ll.MARKER_PENDING:
+            # An earlier move stopped before it switched: its files are ours.
+            for name in (ll.DATABASE_NAME, ll.CONFIG_NAME) + self.plan.backups:
+                _remove(os.path.join(target, name))
+            for suffix in ("-wal", "-shm", "-journal"):
+                _remove(os.path.join(target, ll.DATABASE_NAME + suffix))
+
+    def copy_round(self, source):
+        """Steps 2–4 once: the verified temp copies and the snapshot version."""
+        self.progress("Copying the database")
+        temp_db = self.temp(".db")
+        version, counts, documents = _copy_snapshot(source, temp_db)
+        self.checkpoint("copied")
+        self.progress("Verifying the copy")
+        _verify_copy(temp_db, counts, documents)
+        self.checkpoint("verified")
+        copies = []
+        for name in self.plan.backups:
+            src = os.path.join(self.plan.source_dir, name)
+            temp = self.temp(".bak")
+            try:
+                expected = _hash_copy(src, temp)
+            except OSError as error:
+                logger.error(f"Library move: copying {name} failed: {error}")
+                raise MoveFailed("copy-failed") from error
+            copies.append((src, temp, expected, name))
+        if copies:
+            self.progress(f"Copied {len(copies)} backup file(s)")
+        self.checkpoint("files")
+        _check_copies([(s, t, e) for s, t, e, _ in copies])
+        return version, counts, temp_db, copies
+
+    def discard_round(self, temp_db, copies) -> None:
+        _remove(temp_db, *[temp for _s, temp, _e, _n in copies])
+
+    def publish(self, temp_db, copies) -> List[str]:
+        """Under the locks: config.json, marker, final names, marker moved."""
+        target = self.plan.target_dir
+        files = []
+        if self.plan.config_path:
+            temp = self.temp(".config")
+            try:
+                expected = _hash_copy(self.plan.config_path, temp)
+            except OSError as error:
+                raise MoveFailed("copy-failed") from error
+            _check_copies([(self.plan.config_path, temp, expected)])
+            copies = copies + [(self.plan.config_path, temp, expected, ll.CONFIG_NAME)]
+        self.marker = write_marker(
+            target, ll.MARKER_PENDING, self.plan.db_path, self.plan.config_path
+        )
+        self.checkpoint("pending")
+        for _src, temp, _expected, name in copies:
+            final = os.path.join(target, name)
+            os.replace(temp, final)
+            self.published.append(final)
+            files.append(name)
+        final_db = os.path.join(target, ll.DATABASE_NAME)
+        os.replace(temp_db, final_db)
+        self.published.append(final_db)
+        files.append(ll.DATABASE_NAME)
+        _fsync_dir(target)
+        self.checkpoint("published")
+        write_marker(target, ll.MARKER_MOVED, self.plan.db_path, self.plan.config_path)
+        self.moved = True
+        self.checkpoint("marked")
+        return files
+
+    def cleanup(self) -> None:
+        if self.moved:
+            return
+        _remove(*self.temps, *self.published, self.marker)
+        if self.created_dir:
+            try:
+                os.rmdir(self.plan.target_dir)
+            except OSError:
+                pass
+
+
+def _unique(path: str) -> str:
+    candidate, number = path, 1
+    while os.path.lexists(candidate):
+        candidate = f"{path}_{number}"
+        number += 1
+    return candidate
+
+
+def retire_old_files(plan: MovePlan) -> Tuple[List[str], Optional[str]]:
+    """Rename the old database and config.json; ``(renamed, problem code)``.
+
+    Every connection to the old file must be closed. The WAL is checkpointed
+    first; when it cannot be emptied (another process still has the file
+    open) nothing is renamed (``old-in-use``).
+    """
+    old = plan.db_path
+    folder = os.path.basename(os.path.normpath(plan.target_dir))
+    try:
+        with contextlib.closing(sqlite3.connect(old, timeout=1)) as conn:
+            busy = conn.execute("PRAGMA wal_checkpoint(TRUNCATE)").fetchone()[0]
+    except sqlite3.Error as error:
+        logger.warning(
+            f"Library move: the old database could not be checkpointed: {error}"
+        )
+        return [], "old-in-use"
+    if busy or _size(old + "-wal") > 0:
+        return [], "old-in-use"
+    renamed = []
+    try:
+        for path in (old, plan.config_path):
+            if not path or not os.path.isfile(path):
+                continue
+            new_name = _unique(path + MOVED_INFIX + folder)
+            os.rename(path, new_name)
+            renamed.append(os.path.basename(new_name))
+        for suffix in ("-wal", "-shm"):
+            if os.path.isfile(old + suffix) and _size(old + suffix) == 0:
+                os.remove(old + suffix)
+    except OSError as error:
+        logger.warning(f"Library move: the old files could not be renamed: {error}")
+        return renamed, "old-locked"
+    return renamed, None
+
+
+def finish_interrupted_move(location) -> List[str]:
+    """Rename old files a crash left between the switch and the rename.
+
+    The marker of the folder in use says ``moved`` and names the old files;
+    an old ``prompts.db`` (and config.json) still there under its own name is
+    renamed ``*.moved-to-<folder>`` now, never deleted. Returns the new
+    names (nothing when there is nothing to finish or the file is in use).
+    """
+    if location.source not in (ll.SOURCE_DEFAULT, ll.SOURCE_ENVIRONMENT):
+        return []
+    marker = ll.read_marker(location.data_dir)
+    old = marker.get("from")
+    if marker.get("state") != ll.MARKER_MOVED or not isinstance(old, str):
+        return []
+    if not os.path.isfile(old) or os.path.basename(old) != ll.DATABASE_NAME:
+        return []
+    if ll.same_folder(os.path.dirname(old), location.data_dir):
+        return []
+    config = marker.get("config_from")
+    if not (
+        isinstance(config, str)
+        and os.path.basename(config) == ll.CONFIG_NAME
+        and os.path.isfile(config)
+        and os.path.normcase(os.path.abspath(config))
+        != os.path.normcase(os.path.abspath(location.config_path))
+    ):
+        config = None
+    pending = types.SimpleNamespace(
+        db_path=old, config_path=config, target_dir=location.data_dir
+    )
+    renamed, problem = retire_old_files(pending)
+    if problem:
+        logger.warning(f"Library move: the old files are still in use ({problem})")
+    elif renamed:
+        logger.info(f"Library move finished: renamed {', '.join(renamed)}")
+    return renamed
+
+
+def move_library(
+    plan: MovePlan,
+    *,
+    switch: Callable = switch_process,
+    unswitch: Callable = unswitch_process,
+    after_switch: Callable = _noop,
+    config_lock=None,
+    progress: Callable[[str], None] = _noop,
+    checkpoint: Callable[[str], None] = _noop,
+    attempts: int = DEFAULT_ATTEMPTS,
+) -> MoveResult:
+    """Move the library as planned (blocking; see the module docstring).
+
+    ``switch(old_db, location, detached)`` points the process at the copy
+    and adds the old connections it detached to ``detached``; if it raises,
+    ``unswitch(old_db, new_db)`` undoes it while both files are still
+    locked, every detached connection is closed, the copy is removed and
+    the move fails (``switch-failed``). ``after_switch()`` runs
+    once the switch is final; it is best effort (logged, never fails the move).
+    """
+    short = space_problem(plan)
+    if short is not None:
+        raise MoveFailed("insufficient-space")
+    lock = config_lock if config_lock is not None else contextlib.nullcontext()
+    move = _Move(
+        plan,
+        switch=switch,
+        config_lock=lock,
+        progress=progress,
+        checkpoint=checkpoint,
+    )
+    move.unswitch = unswitch
+    location = plan.target_location
+    try:
+        move.prepare_target()
+        files, counts = _copy_and_switch(move, location, attempts)
+    except Exception:
+        move.cleanup()
+        raise
+    try:
+        after_switch()
+    except Exception:
+        logger.exception("Library move: a follow-up after the switch failed")
+    from .execution_history import notify_history_restore
+
+    notify_history_restore(location.db_path)
+    progress("Renaming the old files")
+    renamed, problem = retire_old_files(plan)
+    checkpoint("retired")
+    return MoveResult(location, counts, files, renamed, problem)
+
+
+def _switch_guarded(move: _Move, location) -> list:
+    """Switch while the copy is locked too; undo it all if any part fails.
+
+    The copy's write lock keeps every repointed thread from writing to it
+    until the switch is whole, so undoing a partial switch loses nothing.
+    Returns the old file's detached connections (still open). On failure
+    every detached connection is retired; those still in use are added to
+    ``move.retiring`` for the caller to await once the locks are released.
+    """
+    plan = move.plan
+    guard = sqlite3.connect(
+        location.db_path, timeout=BUSY_TIMEOUT_SECONDS, isolation_level=None
+    )
+    try:
+        guard.execute("BEGIN IMMEDIATE")
+        detached: list = []
+        try:
+            move.switch(plan.db_path, location, detached)
+        except Exception as error:
+            logger.exception("Library move: switching failed; undoing it")
+            move.moved = False  # the copy and its marker are removed
+            # Retire, never wait, here: a connection still in use may be
+            # waiting on the very locks this thread holds.
+            try:
+                undone = move.unswitch(plan.db_path, location.db_path)
+            except Exception:
+                logger.exception("Library move: undoing the switch failed")
+            else:
+                _retire(move, undone)
+            # The old file's connections a partial switch detached: the
+            # models reopen it on next use, so close them now, not at GC.
+            _retire(move, detached)
+            raise MoveFailed("switch-failed") from error
+        move.checkpoint("switched")
+        return detached
+    finally:
+        if guard.in_transaction:
+            guard.execute("ROLLBACK")
+        guard.close()
+
+
+def _copy_and_switch(move: _Move, location, attempts: int):
+    """Copy, then switch under both locks; retired connections are awaited.
+
+    A connection that was inside a statement when it was retired is closed
+    by its own thread once the statement ends, which may need the locks
+    released first; the old files are renamed (and a failed copy removed)
+    only after that, since Windows refuses to rename or delete an open file.
+    """
+    try:
+        return _copy_and_switch_locked(move, location, attempts)
+    finally:
+        try:
+            PromptModel.await_detached(move.retiring, logger)
+        except Exception:
+            logger.exception("Library move: waiting for old connections failed")
+
+
+def _retire(move: _Move, connections: list) -> None:
+    """Retire ``connections``, adding those still in use to ``move.retiring``.
+
+    Never raises: a switch that completed must not be reported as failed
+    because one of the old connections could not be retired (logged; the
+    rename then reports the old files as still in use).
+    """
+    try:
+        move.retiring.extend(PromptModel.retire_detached(connections, logger))
+    except Exception:
+        logger.exception("Library move: retiring the old connections failed")
+
+
+def _copy_and_switch_locked(move: _Move, location, attempts: int):
+    plan = move.plan
+    for attempt in range(1, attempts + 1):
+        source = sqlite3.connect(
+            plan.db_path, timeout=BUSY_TIMEOUT_SECONDS, isolation_level=None
+        )
+        try:
+            source.execute(f"PRAGMA busy_timeout = {BUSY_TIMEOUT_SECONDS * 1000}")
+            version, counts, temp_db, copies = move.copy_round(source)
+            source.execute("BEGIN IMMEDIATE")
+            try:
+                if source.execute("PRAGMA data_version").fetchone()[0] != version:
+                    move.progress("The library changed during the copy; copying again")
+                    move.discard_round(temp_db, copies)
+                    continue
+                move.checkpoint("locked")
+                with move.config_lock:
+                    files = move.publish(temp_db, copies)
+                    detached = _switch_guarded(move, location)
+                # Still holding the old file's lock: a write that was waiting
+                # on it is interrupted and cannot commit, so it fails (and
+                # runs again on the new library) instead of landing in the
+                # old file. Its own thread closes the connection.
+                _retire(move, detached)
+            finally:
+                if source.in_transaction:
+                    source.execute("ROLLBACK")
+            return files, counts
+        finally:
+            source.close()
+    raise MoveFailed("library-busy")

database/maintenance.py

@@ -0,0 +1,740 @@
+"""Reviewed maintenance plans: read-only previews and their exact apply (#249 S6).
+
+Four operations, each the native owner of a legacy ``/maintenance`` one and
+built on the same queries, so a preview counts what the legacy cleanup would
+change:
+
+- ``duplicate_prompts``: prompts whose text is equal ignoring case and outer
+  spaces (``DUPLICATE_PROMPTS_SQL``, legacy ``cleanup_duplicates``); each
+  group keeps its oldest prompt, which takes over the others' images and
+  metadata. A group with a member in a saved pair is kept whole.
+- ``optimize``: VACUUM (legacy ``vacuum``).
+- ``unused_components``: prompts nothing references (``ORPHANED_PROMPTS_SQL``,
+  legacy ``prune_orphaned_prompts``, with the #239 protections).
+- ``missing_links``: image rows whose file is gone (legacy
+  ``cleanup_orphaned_images``), counted only under a source that can be read
+  now, as the health check's ``missing_files`` judges them
+  (``health.link_states``). It deletes database rows only, never a file.
+
+``preview_maintenance`` reads one snapshot on its own ``mode=ro`` connection
+(``health.readonly_uri``) and closes it in ``finally``; files are looked at
+after the snapshot ended. It returns a ``MaintenanceDraft``: the public plan
+fields, the targets an apply needs and the fingerprint of exactly what was
+reviewed (ids, text hashes, metadata, tags, Library state and pair refs of
+every prompt involved, or each link's row and source). The fingerprint never
+leaves the server.
+
+``apply_maintenance`` recomputes that fingerprint on the write connection
+inside ``BEGIN IMMEDIATE`` and raises ``PlanChanged`` before writing anything
+when it differs; otherwise it applies the reviewed targets in batches of
+``ID_BATCH`` in that one transaction. VACUUM cannot run in a transaction, so
+``optimize`` binds to its database only (the caller checks that).
+"""
+
+import hashlib
+import json
+import os
+import shutil
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .execution_contexts import LIVE_HINT_CTES
+from .health import BATCH_ROWS, link_states, readable_roots, readonly_uri
+from .pairs import PairDependencyError
+from .workflow_documents import documents_of_rows, release_documents
+
+MAINTENANCE_OPERATIONS = (
+    "duplicate_prompts",
+    "optimize",
+    "unused_components",
+    "missing_links",
+    # Applied as its own batched job (database/workflow_storage.py).
+    "workflow_storage",
+)
+MAX_DETAILS = 50  # detail rows a plan lists
+MAX_RESULT_ROWS = 200  # changed records an apply describes (the job lists 200)
+EXCERPT_CHARS = 80
+# Ids bound per statement: the pair-reference read binds each id twice, which
+# stays under SQLite's historical 999-variable limit.
+ID_BATCH = 400
+
+# Why a prompt no image links to is kept (#239): predicates on ``p``, in the
+# order the plan names them. ORPHANED_PROMPTS_SQL is built from them, so the
+# reasons a plan lists are exactly the rules the prune applies.
+PROTECTIONS = (
+    (
+        "EXISTS (SELECT 1 FROM prompt_pairs pp "
+        "WHERE pp.positive_prompt_id = p.id OR pp.negative_prompt_id = p.id)",
+        "in saved pairs",
+        "in a saved pair",
+    ),
+    (
+        "EXISTS (SELECT 1 FROM prompt_tags pt JOIN tags t ON pt.tag_id = t.id "
+        "WHERE pt.prompt_id = p.id AND t.name = '__protected__')",
+        "tagged __protected__",
+        "tagged __protected__",
+    ),
+    (
+        "EXISTS (SELECT 1 FROM prompt_library_state ls WHERE ls.prompt_id = p.id)",
+        "with Library state (a title or an explicit parent)",
+        "with Library state (a title or an explicit parent)",
+    ),
+    (
+        "p.id IN (SELECT prompt_id FROM live_hint_prompts)",
+        "used by recorded runs",
+        "used by a recorded run",
+    ),
+)
+
+# Exempt references: images, pairs, the __protected__ tag, Library parent
+# state, and live recorded-run hints (computed once, see LIVE_HINT_CTES).
+ORPHANED_PROMPTS_SQL = (
+    "WITH "
+    + LIVE_HINT_CTES
+    + " SELECT p.id FROM prompts p"
+    + " LEFT JOIN generated_images gi ON p.id = gi.prompt_id"
+    + " WHERE gi.prompt_id IS NULL"
+    + "".join(f" AND NOT ({predicate})" for predicate, _many, _one in PROTECTIONS)
+)
+# The prompts no image links to, with which protections keep each one.
+_UNLINKED_PROTECTIONS_SQL = (
+    "WITH "
+    + LIVE_HINT_CTES
+    + " SELECT "
+    + ", ".join(
+        f"COALESCE(SUM({predicate}), 0)" for predicate, _many, _one in PROTECTIONS
+    )
+    + ", COALESCE(SUM("
+    + " OR ".join(f"({predicate})" for predicate, _many, _one in PROTECTIONS)
+    + "), 0) FROM prompts p WHERE NOT EXISTS "
+    "(SELECT 1 FROM generated_images gi WHERE gi.prompt_id = p.id)"
+)
+
+# Duplicate prompt groups, as the legacy cleanup finds them (case-insensitive
+# text; GROUP_CONCAT order is sorted by created_at afterwards).
+DUPLICATE_PROMPTS_SQL = """
+    SELECT LOWER(TRIM(text)) as normalized_text, COUNT(*) as count,
+           GROUP_CONCAT(id) as ids,
+           GROUP_CONCAT(created_at) as created_dates
+    FROM prompts
+    GROUP BY LOWER(TRIM(text))
+    HAVING COUNT(*) > 1
+"""
+
+_LINK_ROWS_SQL = (
+    "SELECT id, image_path, filename, file_path FROM generated_images ORDER BY id"
+)
+
+# What a prompt's fingerprint covers, per batch of ids.
+_PROMPT_STATE_SQL = (
+    "SELECT id, hash, text, category, rating, notes, created_at, updated_at "
+    "FROM prompts WHERE id IN ({marks}) ORDER BY id",
+    "SELECT prompt_id, tag_id FROM prompt_tags WHERE prompt_id IN ({marks}) "
+    "ORDER BY prompt_id, tag_id",
+    "SELECT * FROM prompt_library_state WHERE prompt_id IN ({marks}) "
+    "ORDER BY prompt_id",
+    "SELECT id, positive_prompt_id, negative_prompt_id FROM prompt_pairs "
+    "WHERE positive_prompt_id IN ({marks}) OR negative_prompt_id IN ({marks}) "
+    "ORDER BY id",
+)
+
+NO_FILES_DELETED = "No image file is deleted."
+LINKS_ONLY = "Database links only; no image file is deleted."
+UNUSED_DETAIL = "No image, saved pair, Library state or recorded run uses it"
+
+
+# Why a duplicate group is kept whole (``_duplicate_conflict``).
+CONFLICT_REASONS = {
+    "collision": ("group links one image twice", "groups link one image twice"),
+    "title": (
+        "group has its own Library title",
+        "groups have their own Library titles",
+    ),
+}
+CONFLICT_DETAILS = {
+    "collision": "Kept: two copies link the same image",
+    "title": "Kept: a copy has its own Library title",
+}
+OPTIMIZE_LOCK_NOTE = (
+    "Runs alone: the database is locked while it runs, and on a large library "
+    "this takes a while. Prompt runs counted and images captured meanwhile "
+    "wait up to 30 seconds each; anything that waits longer is not recorded."
+)
+
+
+class PlanChanged(Exception):
+    """What a plan was reviewed on changed before it was applied."""
+
+
+class MergeConflict(Exception):
+    """A strict duplicate merge would drop an image link or a Library title."""
+
+
+@dataclass
+class MaintenanceDraft:
+    """A preview: the public plan fields plus what only the server keeps."""
+
+    operation: str
+    fingerprint: str
+    targets: list
+    scope: dict
+    protected: dict
+    media: dict
+    details: list = field(default_factory=list)
+
+    def public(self):
+        """The plan fields a response may carry (no fingerprint, no targets)."""
+        return {
+            "operation": self.operation,
+            "scope": dict(self.scope),
+            "protected": {
+                "count": self.protected["count"],
+                "reasons": list(self.protected["reasons"]),
+            },
+            "media": dict(self.media),
+            "details": [dict(row) for row in self.details],
+        }
+
+
+def _plural(count, one, many=None):
+    return f"{count:,} {one if count == 1 else (many or one + 's')}"
+
+
+def _excerpt(text):
+    text = " ".join(str(text or "").split())
+    if len(text) <= EXCERPT_CHARS:
+        return text
+    return text[: EXCERPT_CHARS - 1].rstrip() + "…"
+
+
+def _megabytes(size):
+    return f"{size / 2**20:,.1f} MB"
+
+
+class _Fingerprint:
+    """A streaming sha256 over JSON-encoded parts."""
+
+    def __init__(self, operation):
+        self._hash = hashlib.sha256()
+        self.add(operation)
+
+    def add(self, part):
+        encoded = json.dumps(part, separators=(",", ":"), default=str)
+        self._hash.update(encoded.encode("utf-8") + b"\n")
+
+    def hexdigest(self):
+        return "sha256:" + self._hash.hexdigest()
+
+
+def _batches(ids):
+    ids = list(ids)
+    for start in range(0, len(ids), ID_BATCH):
+        yield ids[start : start + ID_BATCH]
+
+
+def _marks(batch):
+    return ",".join("?" for _ in batch)
+
+
+def _add_prompt_state(fingerprint, conn, ids):
+    """Fold every reviewed fact about the prompts ``ids`` into ``fingerprint``."""
+    for batch in _batches(sorted(ids)):
+        marks = _marks(batch)
+        for sql in _PROMPT_STATE_SQL:
+            params = batch * sql.count("{marks}")
+            for row in conn.execute(sql.format(marks=marks), params):
+                fingerprint.add(list(row))
+
+
+def _texts(conn, ids, limit=MAX_DETAILS):
+    """``{id: text}`` of the first ``limit`` prompts, for detail rows."""
+    ids = list(ids)[:limit]
+    if not ids:
+        return {}
+    rows = conn.execute(
+        f"SELECT id, text FROM prompts WHERE id IN ({_marks(ids)})", ids
+    )
+    return {row[0]: row[1] for row in rows}
+
+
+def _orphaned_ids(conn):
+    return sorted(row[0] for row in conn.execute(ORPHANED_PROMPTS_SQL))
+
+
+def _delete_ids(conn, table, ids):
+    """Delete ``table`` rows by id in batches; returns the rows removed.
+
+    The workflow documents only those rows referenced go with them (a
+    prompt's images go by cascade), in the same transaction.
+    """
+    if table not in ("prompts", "generated_images"):
+        raise ValueError(f"Unsupported table {table!r}")
+    removed = 0
+    for batch in _batches(ids):
+        documents = documents_of_rows(
+            conn, "id" if table == "generated_images" else "prompt_id", batch
+        )
+        cursor = conn.execute(
+            f"DELETE FROM {table} WHERE id IN ({_marks(batch)})",  # nosec B608
+            batch,
+        )
+        removed += cursor.rowcount
+        release_documents(conn, documents)
+    return removed
+
+
+def _read_snapshot(db_path, read):
+    """``read(conn)`` on one ``mode=ro`` snapshot; the connection always closes."""
+    conn = sqlite3.connect(readonly_uri(db_path), uri=True)
+    try:
+        conn.row_factory = sqlite3.Row
+        conn.execute("BEGIN")  # one read snapshot for the whole plan
+        return read(conn)
+    finally:
+        conn.close()
+
+
+def _relative(image_path, root):
+    try:
+        return Path(os.path.relpath(image_path, root)).as_posix()
+    except ValueError:  # another drive (Windows)
+        return os.path.basename(image_path)
+
+
+def _source_name(root, index):
+    return os.path.basename(str(root).rstrip("\\/")) or f"Source {index + 1}"
+
+
+class MaintenanceOperations:
+    """Mixin for PromptDatabase: maintenance previews and their apply."""
+
+    # ── shared with the legacy cleanup ───────────────────────────────
+
+    def _duplicate_groups(self, conn):
+        """``(groups, paired)``: duplicate id groups, oldest first.
+
+        ``paired`` are the groups with a member in a saved pair, which the
+        cleanup keeps whole.
+        """
+        groups, paired = [], []
+        for duplicate in conn.execute(DUPLICATE_PROMPTS_SQL).fetchall():
+            ids = duplicate["ids"].split(",")
+            created_dates = duplicate["created_dates"].split(",")
+            # Sort IDs by created_at date to keep the oldest
+            id_date_pairs = list(zip(ids, created_dates))
+            id_date_pairs.sort(key=lambda x: x[1])
+            sorted_ids = [int(pair[0]) for pair in id_date_pairs]
+            try:
+                self._ensure_prompts_unpaired(conn, sorted_ids)
+            except PairDependencyError:
+                paired.append(sorted_ids)
+                continue
+            groups.append(sorted_ids)
+        return groups, paired
+
+    @staticmethod
+    def _duplicate_conflict(conn, sorted_ids):
+        """Why merging the group would lose something, or None.
+
+        ``collision``: two members link the same file, so moving the images
+        to the oldest prompt would hit ``UNIQUE(prompt_id, file_path)``.
+        ``title``: a member that would be deleted has its own Library title.
+        """
+        marks = _marks(sorted_ids)
+        collision = conn.execute(
+            "SELECT 1 FROM generated_images WHERE prompt_id IN "  # nosec B608
+            f"({marks}) AND file_path IS NOT NULL GROUP BY file_path "
+            "HAVING COUNT(DISTINCT prompt_id) > 1 LIMIT 1",
+            sorted_ids,
+        ).fetchone()
+        if collision:
+            return "collision"
+        duplicates = sorted_ids[1:]
+        titled = conn.execute(
+            "SELECT 1 FROM prompt_library_state WHERE prompt_id IN "  # nosec B608
+            f"({_marks(duplicates)}) AND trim(coalesce(title, '')) != '' LIMIT 1",
+            duplicates,
+        ).fetchone()
+        return "title" if titled else None
+
+    def _merge_duplicate_group(self, conn, sorted_ids, strict=False):
+        """Keep the oldest prompt of a group; returns (removed, images moved).
+
+        ``strict`` (the reviewed apply): a merge that would drop an image
+        link or a Library title raises MergeConflict, and every helper error
+        propagates, so the transaction rolls back. The legacy cleanup keeps
+        its old, lenient behaviour.
+        """
+        primary_id, duplicate_ids = sorted_ids[0], sorted_ids[1:]
+        if strict:
+            conflict = self._duplicate_conflict(conn, sorted_ids)
+            if conflict:
+                raise MergeConflict(conflict)
+        self.logger.debug(
+            f"Merging duplicates: keeping {primary_id}, removing {duplicate_ids}"
+        )
+        primary = conn.execute(
+            "SELECT * FROM prompts WHERE id = ?", (primary_id,)
+        ).fetchone()
+        if not primary:
+            return 0, 0
+        merged_metadata = self._merge_duplicate_metadata(
+            conn, primary_id, duplicate_ids, strict=strict
+        )
+        moved = self._transfer_images_to_primary(
+            conn, primary_id, duplicate_ids, strict=strict
+        )
+        if merged_metadata:
+            self._update_primary_with_merged_metadata(
+                conn, primary_id, merged_metadata, strict=strict
+            )
+        removed = 0
+        # Images the lenient merge could not move go with their prompt.
+        documents = documents_of_rows(conn, "prompt_id", duplicate_ids)
+        for duplicate_id in duplicate_ids:
+            conn.execute("DELETE FROM prompts WHERE id = ?", (duplicate_id,))
+            removed += 1
+            self.logger.debug(f"Removed duplicate prompt {duplicate_id}")
+        release_documents(conn, documents)
+        return removed, moved
+
+    @staticmethod
+    def _missing_link_ids(rows, roots):
+        """Ids of the ``rows`` whose file is gone under a readable source."""
+        readable = readable_roots(roots)
+        return [
+            row[0]
+            for row, _owner, state in link_states(rows, roots, readable)
+            if state == "missing"
+        ]
+
+    # ── previews ──────────────────────────────────────────────────────
+
+    def preview_maintenance(self, operation, roots=()) -> MaintenanceDraft:
+        """The reviewed plan of ``operation``; writes nothing (blocking).
+
+        ``roots`` are the sources missing links are judged under (the health
+        check's: the effective sources plus configured ones that are gone).
+        """
+        if operation not in MAINTENANCE_OPERATIONS:
+            raise ValueError(f"Unknown maintenance operation {operation!r}")
+        roots = [str(root) for root in roots]
+        if operation == "optimize":
+            return self._plan_optimize()
+        if operation == "workflow_storage":
+            return self._plan_workflow_storage()
+        if operation == "missing_links":
+            rows = _read_snapshot(self.model.db_path, self._link_rows)
+            return self._plan_missing_links(rows, roots)
+        reader = (
+            self._plan_duplicate_prompts
+            if operation == "duplicate_prompts"
+            else self._plan_unused_components
+        )
+        return _read_snapshot(self.model.db_path, reader)
+
+    @staticmethod
+    def _link_rows(conn):
+        rows = []
+        cursor = conn.execute(_LINK_ROWS_SQL)
+        while batch := cursor.fetchmany(BATCH_ROWS):
+            rows.extend(tuple(row) for row in batch)
+        return rows
+
+    def _duplicates_fingerprint(self, conn):
+        """``(groups, paired, conflicted, fingerprint)`` of the duplicate merge.
+
+        ``conflicted`` holds ``(ids, reason)`` of the groups a merge would
+        lose an image link or a Library title in (``_duplicate_conflict``);
+        the plan protects them.
+        """
+        candidates, paired = self._duplicate_groups(conn)
+        groups, conflicted = [], []
+        for ids in candidates:
+            reason = self._duplicate_conflict(conn, ids)
+            if reason:
+                conflicted.append((ids, reason))
+            else:
+                groups.append(ids)
+        fingerprint = _Fingerprint("duplicate_prompts")
+        fingerprint.add({"groups": groups, "paired": paired, "conflicted": conflicted})
+        _add_prompt_state(fingerprint, conn, [i for group in groups for i in group])
+        return groups, paired, conflicted, fingerprint.hexdigest()
+
+    def _plan_duplicate_prompts(self, conn):
+        groups, paired, conflicted, fingerprint = self._duplicates_fingerprint(conn)
+        removed = sum(len(group) - 1 for group in groups)
+        held = [ids for ids, _reason in conflicted]
+        texts = _texts(conn, [group[0] for group in (groups + paired + held)])
+        details = (
+            [
+                {
+                    "label": _excerpt(texts.get(group[0])),
+                    "detail": f"Keeps the oldest of {len(group)} copies",
+                }
+                for group in groups
+            ]
+            + [
+                {
+                    "label": _excerpt(texts.get(group[0])),
+                    "detail": "Kept: belongs to a saved pair",
+                }
+                for group in paired
+            ]
+            + [
+                {
+                    "label": _excerpt(texts.get(ids[0])),
+                    "detail": CONFLICT_DETAILS[reason],
+                }
+                for ids, reason in conflicted
+            ]
+        )
+        if groups:
+            label = (
+                f"{_plural(removed, 'duplicate prompt')} in "
+                f"{_plural(len(groups), 'group')}"
+            )
+        else:
+            label = "No duplicate prompt text"
+        reasons = []
+        if len(paired) == 1:
+            reasons.append("1 group belongs to a saved pair")
+        elif paired:
+            reasons.append(f"{len(paired):,} groups belong to saved pairs")
+        for reason, (one, many) in CONFLICT_REASONS.items():
+            count = sum(1 for _ids, why in conflicted if why == reason)
+            if count:
+                reasons.append(f"{count:,} {one if count == 1 else many}")
+        return MaintenanceDraft(
+            operation="duplicate_prompts",
+            fingerprint=fingerprint,
+            targets=groups,
+            scope={"count": removed, "label": label},
+            protected={
+                "count": sum(len(group) for group in paired + held),
+                "reasons": reasons,
+            },
+            media={"deletes_files": False, "label": NO_FILES_DELETED},
+            details=details[:MAX_DETAILS],
+        )
+
+    def _unused_fingerprint(self, conn):
+        ids = _orphaned_ids(conn)
+        fingerprint = _Fingerprint("unused_components")
+        fingerprint.add(ids)
+        _add_prompt_state(fingerprint, conn, ids)
+        return ids, fingerprint.hexdigest()
+
+    def _plan_unused_components(self, conn):
+        ids, fingerprint = self._unused_fingerprint(conn)
+        *by_reason, kept = conn.execute(_UNLINKED_PROTECTIONS_SQL).fetchone()
+        reasons = [
+            f"{count:,} {many if count != 1 else one}"
+            for count, (_predicate, many, one) in zip(by_reason, PROTECTIONS)
+            if count
+        ]
+        texts = _texts(conn, ids)
+        count = len(ids)
+        return MaintenanceDraft(
+            operation="unused_components",
+            fingerprint=fingerprint,
+            targets=ids,
+            scope={
+                "count": count,
+                "label": (
+                    _plural(count, "unused prompt component")
+                    if count
+                    else "No unused prompt components"
+                ),
+            },
+            protected={"count": kept, "reasons": reasons},
+            media={"deletes_files": False, "label": NO_FILES_DELETED},
+            details=[
+                {"label": _excerpt(texts.get(prompt_id)), "detail": UNUSED_DETAIL}
+                for prompt_id in ids[:MAX_DETAILS]
+            ],
+        )
+
+    @staticmethod
+    def _links_fingerprint(candidates):
+        fingerprint = _Fingerprint("missing_links")
+        for row, owner in candidates:
+            fingerprint.add([row[0], row[1], row[3], owner])
+        return fingerprint.hexdigest()
+
+    def _plan_missing_links(self, rows, roots):
+        readable = readable_roots(roots)
+        candidates, unavailable, outside = [], 0, 0
+        for row, owner, state in link_states(rows, roots, readable):
+            if state == "missing":
+                candidates.append((row, owner))
+            elif state == "unavailable":
+                unavailable += 1
+            elif state == "outside":
+                outside += 1
+        reasons = []
+        if unavailable:
+            reasons.append(
+                _plural(
+                    unavailable,
+                    "link under an unavailable source",
+                    "links under unavailable sources",
+                )
+            )
+        if outside:
+            reasons.append(
+                _plural(
+                    outside,
+                    "link outside the image sources",
+                    "links outside the image sources",
+                )
+            )
+        count = len(candidates)
+        return MaintenanceDraft(
+            operation="missing_links",
+            fingerprint=self._links_fingerprint(candidates),
+            targets=[row[0] for row, _owner in candidates],
+            scope={
+                "count": count,
+                "label": (
+                    _plural(count, "link to a missing file", "links to missing files")
+                    if count
+                    else "No links to missing files"
+                ),
+            },
+            protected={"count": unavailable + outside, "reasons": reasons},
+            media={"deletes_files": False, "label": LINKS_ONLY},
+            details=[
+                {
+                    "label": _relative(row[1], roots[owner]),
+                    "detail": (
+                        f"{_source_name(roots[owner], owner)} · the file is missing"
+                    ),
+                }
+                for row, owner in candidates[:MAX_DETAILS]
+            ],
+        )
+
+    def _plan_optimize(self):
+        def read(conn):
+            return [
+                conn.execute(f"PRAGMA {name}").fetchone()[0]
+                for name in ("page_size", "page_count", "freelist_count")
+            ]
+
+        page_size, page_count, free_pages = _read_snapshot(self.model.db_path, read)
+        db_path = self.model.db_path
+        wal = db_path + "-wal"
+        size = page_size * page_count
+        wal_size = os.path.getsize(wal) if os.path.exists(wal) else 0
+        free = shutil.disk_usage(os.path.dirname(os.path.abspath(db_path))).free
+        # VACUUM writes the rebuilt database through the WAL beside it.
+        return MaintenanceDraft(
+            operation="optimize",
+            fingerprint=_Fingerprint("optimize").hexdigest(),
+            targets=[],
+            scope={"count": 1, "label": "The whole database"},
+            protected={"count": 0, "reasons": []},
+            media={"deletes_files": False, "label": NO_FILES_DELETED},
+            details=[
+                {
+                    "label": "Database file",
+                    "detail": f"{_megabytes(size)}, plus {_megabytes(wal_size)} "
+                    "not yet checkpointed",
+                },
+                {
+                    "label": "Free pages",
+                    "detail": f"About {_megabytes(free_pages * page_size)} "
+                    "can be reclaimed",
+                },
+                {
+                    "label": "Lock",
+                    "detail": OPTIMIZE_LOCK_NOTE,
+                },
+                {
+                    "label": "Free space needed",
+                    "detail": f"About {_megabytes(size)} beside the database and "
+                    f"{_megabytes(size)} in SQLite's temporary folder; "
+                    f"{_megabytes(free)} available beside the database",
+                },
+            ],
+        )
+
+    # ── apply ─────────────────────────────────────────────────────────
+
+    def apply_maintenance(self, operation, fingerprint, targets, roots=()) -> dict:
+        """Apply a reviewed plan exactly, or raise PlanChanged (blocking).
+
+        Inside ``BEGIN IMMEDIATE`` the fingerprint is computed again on the
+        write connection; when it differs nothing is written. ``targets`` and
+        ``roots`` are the plan's. Returns ``{changed, rows}``: how many
+        records changed and up to ``MAX_RESULT_ROWS`` descriptions of them
+        (``{prompt_id[, kept_id]}`` or ``{image_path}``).
+        """
+        if operation not in MAINTENANCE_OPERATIONS or operation == "workflow_storage":
+            raise ValueError(f"Unknown maintenance operation {operation!r}")
+        if operation == "optimize":
+            # VACUUM cannot run in a transaction; the plan binds the database.
+            if fingerprint != _Fingerprint("optimize").hexdigest():
+                raise PlanChanged("optimize")
+            self.model.vacuum_database()
+            return {"changed": 1, "rows": []}
+        appliers = {
+            "duplicate_prompts": self._apply_duplicate_prompts,
+            "unused_components": self._apply_unused_components,
+            "missing_links": self._apply_missing_links,
+        }
+        with self._pair_transaction() as conn:
+            return appliers[operation](conn, fingerprint, targets, roots)
+
+    def _apply_duplicate_prompts(self, conn, fingerprint, targets, _roots):
+        groups, _paired, _conflicted, current = self._duplicates_fingerprint(conn)
+        if current != fingerprint or groups != targets:
+            raise PlanChanged("duplicate_prompts")
+        changed, rows = 0, []
+        for sorted_ids in groups:
+            removed, _moved = self._merge_duplicate_group(conn, sorted_ids, strict=True)
+            changed += removed
+            rows.extend(
+                {"prompt_id": duplicate_id, "kept_id": sorted_ids[0]}
+                for duplicate_id in sorted_ids[1:]
+            )
+        return {"changed": changed, "rows": rows[:MAX_RESULT_ROWS]}
+
+    def _apply_unused_components(self, conn, fingerprint, targets, _roots):
+        ids, current = self._unused_fingerprint(conn)
+        if current != fingerprint or ids != targets:
+            raise PlanChanged("unused_components")
+        texts = _texts(conn, ids, limit=MAX_RESULT_ROWS)
+        changed = _delete_ids(conn, "prompts", ids)
+        rows = [
+            {"prompt_id": prompt_id, "text": _excerpt(texts.get(prompt_id))}
+            for prompt_id in ids[:MAX_RESULT_ROWS]
+        ]
+        return {"changed": changed, "rows": rows}
+
+    def _apply_missing_links(self, conn, fingerprint, targets, roots):
+        rows = []
+        for batch in _batches(sorted(targets)):
+            rows.extend(
+                tuple(row)
+                for row in conn.execute(
+                    "SELECT id, image_path, filename, file_path FROM generated_images "
+                    f"WHERE id IN ({_marks(batch)}) ORDER BY id",  # nosec B608
+                    batch,
+                )
+            )
+        readable = readable_roots(roots)
+        candidates = []
+        for row, owner, state in link_states(rows, roots, readable):
+            if state != "missing":  # back, or its source went away
+                raise PlanChanged("missing_links")
+            candidates.append((row, owner))
+        if self._links_fingerprint(candidates) != fingerprint:
+            raise PlanChanged("missing_links")
+        changed = _delete_ids(conn, "generated_images", [row[0] for row in rows])
+        return {
+            "changed": changed,
+            "rows": [{"image_path": row[1]} for row in rows[:MAX_RESULT_ROWS]],
+        }

database/managed_connection.py

@@ -0,0 +1,353 @@
+"""A SQLite connection that is never closed under the thread using it.
+
+``PromptModel`` gives each thread its own connection, but Move library and
+``close_all`` must retire every thread's connection from one thread. Closing
+a ``sqlite3.Connection`` while its owner is inside a statement (Python runs
+``sqlite3_step`` without the GIL) frees memory the owner then reads: on
+Windows the process dies with "access violation", elsewhere the owner sees
+garbage such as a ``MemoryError``.
+
+``ManagedConnection`` counts the calls its owner is inside. ``retire()`` is
+safe from any thread and never raises: an idle connection is closed at once;
+one in use is closed by its owner as the call ends. A retired connection
+refuses new work (cursors, statements, commits) with the error a closed
+connection raises.
+
+What retiring a connection in use does and does not do:
+
+- It calls ``sqlite3_interrupt`` (thread-safe). That ends a running
+  statement at its next step, but it does not wake a statement that is
+  waiting for another connection's lock: that one waits until the lock is
+  released (or the busy timeout ends it), and only then is it interrupted.
+  An interrupt that arrives between two statements, for example between the
+  implicit ``BEGIN`` and the DML or between ``executemany`` rows, is lost.
+- Writes are kept out of a file the process has switched away from because
+  a retired connection never commits: legacy-mode DML runs inside a
+  transaction that only ``commit()`` (refused) or ``close()`` (rolls back)
+  ends. A statement that commits by itself is not covered: DDL or a PRAGMA
+  write outside a transaction, or an explicit ``COMMIT`` passed to
+  ``execute``/``executescript`` (``executescript`` also commits first, in C,
+  on Python before 3.12). Managed connections must never be used that way
+  for library writes.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import threading
+import time
+import weakref
+from typing import Iterable, Iterator, List, Optional
+
+import sqlite3
+
+CLOSED_MESSAGE = "Cannot operate on a closed database."
+# Rows fetched per step when a cursor is iterated: the connection is marked
+# in use once per chunk instead of once per row (iteration costs about what
+# a plain cursor costs). A loop that stops early leaves up to this many rows
+# fetched; ``fetchone``/``fetchmany`` after a partial loop skip them.
+ITER_CHUNK = 128
+
+
+class ManagedCursor(sqlite3.Cursor):
+    """A cursor whose calls into SQLite count as its connection being in use."""
+
+    def execute(self, sql, parameters=(), /):
+        conn = self.connection
+        conn._enter()
+        try:
+            return super().execute(sql, parameters)
+        finally:
+            conn._leave()
+
+    def executemany(self, sql, seq_of_parameters, /):
+        conn = self.connection
+        conn._enter()
+        try:
+            return super().executemany(sql, seq_of_parameters)
+        finally:
+            conn._leave()
+
+    def executescript(self, sql_script, /):
+        conn = self.connection
+        conn._enter()
+        try:
+            return super().executescript(sql_script)
+        finally:
+            conn._leave()
+
+    def fetchone(self):
+        conn = self.connection
+        conn._enter()
+        try:
+            return super().fetchone()
+        finally:
+            conn._leave()
+
+    def fetchmany(self, *args, **kwargs):
+        conn = self.connection
+        conn._enter()
+        try:
+            return super().fetchmany(*args, **kwargs)
+        finally:
+            conn._leave()
+
+    def fetchall(self):
+        conn = self.connection
+        conn._enter()
+        try:
+            return super().fetchall()
+        finally:
+            conn._leave()
+
+    def __iter__(self) -> Iterator:
+        return self._chunks()
+
+    def _chunks(self) -> Iterator:
+        while True:
+            rows = self.fetchmany(ITER_CHUNK)
+            if not rows:
+                return
+            yield from rows
+
+    def __next__(self):
+        conn = self.connection
+        conn._enter()
+        try:
+            return super().__next__()
+        finally:
+            conn._leave()
+
+    def close(self):
+        conn = self.connection
+        try:
+            conn._enter()
+        except sqlite3.ProgrammingError:
+            return super().close()  # the connection is closed or closing
+        try:
+            return super().close()
+        finally:
+            conn._leave()
+
+
+class ManagedConnection(sqlite3.Connection):
+    """A connection only its owner closes while a call into it is running."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # Guards _depth, _retired, _closing and _cursors. Re-entrant so that
+        # code running in the closing thread while it holds the lock (a
+        # cursor() during the cursor-set copy) is refused instead of hanging.
+        self._use_lock = threading.RLock()
+        self._depth = 0
+        self._retired = False
+        self._closing = False
+        self._released = threading.Event()
+        # Python before 3.12 keeps the file open after close() while a cursor
+        # still holds a statement; these are closed first (see _close_now).
+        self._cursors: "weakref.WeakSet[sqlite3.Cursor]" = weakref.WeakSet()
+        self.close_logger: Optional[logging.Logger] = None
+
+    # ── in use ───────────────────────────────────────────────────────
+
+    def _enter(self) -> None:
+        with self._use_lock:
+            if self._retired:
+                raise sqlite3.ProgrammingError(CLOSED_MESSAGE)
+            self._depth += 1
+
+    def _leave(self) -> None:
+        with self._use_lock:
+            self._depth -= 1
+            close_now = self._retired and self._depth == 0
+        if close_now:
+            self._close_now()
+
+    @contextlib.contextmanager
+    def using(self):
+        """Mark the connection in use for a call this class cannot wrap.
+
+        For example as the *target* of another connection's ``backup()``.
+        """
+        self._enter()
+        try:
+            yield self
+        finally:
+            self._leave()
+
+    def cursor(self, factory=None):
+        with self._use_lock:
+            if self._retired:
+                raise sqlite3.ProgrammingError(CLOSED_MESSAGE)
+            cursor = super().cursor(factory or ManagedCursor)
+            self._cursors.add(cursor)
+        return cursor
+
+    def execute(self, sql, parameters=(), /):
+        return self.cursor().execute(sql, parameters)
+
+    def executemany(self, sql, seq_of_parameters, /):
+        return self.cursor().executemany(sql, seq_of_parameters)
+
+    def executescript(self, sql_script, /):
+        return self.cursor().executescript(sql_script)
+
+    def commit(self):
+        self._enter()
+        try:
+            return super().commit()
+        finally:
+            self._leave()
+
+    def rollback(self):
+        self._enter()  # a closed connection raises, as sqlite3's does
+        try:
+            return super().rollback()
+        finally:
+            self._leave()
+
+    def backup(self, target, **kwargs):
+        self._enter()
+        try:
+            return super().backup(target, **kwargs)
+        finally:
+            self._leave()
+
+    def create_function(self, *args, **kwargs):
+        self._enter()
+        try:
+            return super().create_function(*args, **kwargs)
+        finally:
+            self._leave()
+
+    @property
+    def in_transaction(self) -> bool:
+        self._enter()
+        try:
+            return super().in_transaction
+        finally:
+            self._leave()
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        # The C implementation calls its own commit/rollback, not these.
+        if exc_type is None:
+            try:
+                self.commit()
+            except BaseException:
+                with contextlib.suppress(sqlite3.Error):
+                    self.rollback()
+                raise
+        else:
+            self.rollback()
+        return False
+
+    # ── closing ──────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        """Close now if idle, else as soon as the running call ends.
+
+        Unlike ``sqlite3.Connection.close``, a call from another thread while
+        the owner is inside a call returns before the file is closed. A caller
+        that must know the file is closed (before renaming or deleting it)
+        waits for ``wait_closed`` (``PromptModel.close_detached`` does).
+        """
+        self.retire()
+
+    def retire(self) -> bool:
+        """Refuse new work and close; True when the connection is closed already.
+
+        Safe from any thread, and never raises: failures are logged.
+        """
+        try:
+            with self._use_lock:
+                if not self._retired:
+                    self._retired = True
+                    if self._depth:
+                        # Ends the running statement (see the module docstring
+                        # for what it does not end). The owner cannot start
+                        # closing the connection while this lock is held.
+                        self.interrupt()
+                        return False
+                elif self._depth:
+                    return False
+                else:
+                    return self._released.wait(0)
+        except Exception:
+            self._log_exception("Error retiring database connection")
+            return self._released.wait(0)
+        self._close_now()
+        return True
+
+    def wait_closed(self, timeout: float) -> bool:
+        return self._released.wait(timeout)
+
+    def _close_now(self) -> None:
+        # Only ever called with no call into the connection running, and a
+        # retired connection refuses new calls and cursors: its cursors are
+        # idle, and the set is copied under the lock that guards it.
+        with self._use_lock:
+            if self._closing:
+                return  # another thread closes it and sets _released
+            self._closing = True
+            cursors = list(self._cursors)
+        try:
+            for cursor in cursors:
+                with contextlib.suppress(sqlite3.Error):
+                    sqlite3.Cursor.close(cursor)
+            super().close()
+        except Exception:
+            self._log_exception("Error closing database connection")
+        finally:
+            self._released.set()
+
+    def _log_exception(self, message: str) -> None:
+        if self.close_logger is not None:
+            self.close_logger.exception(message)
+
+
+def retire_connections(
+    connections: Iterable[sqlite3.Connection], logger=None
+) -> List[ManagedConnection]:
+    """Retire every connection; return those whose owner has yet to close them.
+
+    Safe while holding a lock the owners wait on: nothing here waits for them.
+    One connection failing to retire is logged and never skips the rest.
+    """
+    pending = []
+    for conn in connections:
+        try:
+            if isinstance(conn, ManagedConnection):
+                if logger is not None:
+                    conn.close_logger = logger
+                if not conn.retire():
+                    pending.append(conn)
+            else:
+                conn.close()
+        except Exception:
+            if logger is not None:
+                logger.exception("Error closing database connection")
+    return pending
+
+
+def await_closed(
+    connections: Iterable[ManagedConnection], timeout: float, logger=None
+) -> bool:
+    """Wait until the owners closed ``connections`` (retired); False on timeout.
+
+    A connection still open after ``timeout`` (its owner is blocked, for
+    example on another process's lock after a lost interrupt) is logged and
+    left to close when its call ends; a Move library then reports the old
+    files as still in use instead of renaming them.
+    """
+    deadline = time.monotonic() + timeout
+    still_open = 0
+    for conn in connections:
+        if not conn.wait_closed(max(0.0, deadline - time.monotonic())):
+            still_open += 1
+    if still_open and logger is not None:
+        logger.warning(
+            f"{still_open} database connection(s) still in use after "
+            f"{timeout:g}s; they close when their statement ends"
+        )
+    return not still_open

database/models.py

@@ -9,20 +9,36 @@ import math
 import sqlite3
 import os
 import threading
-import tempfile
 import weakref
 from contextlib import closing
 from pathlib import Path
 from typing import Optional, Set, Tuple
 
+from .managed_connection import (
+    ManagedConnection,
+    await_closed,
+    retire_connections,
+)
+from . import restore_stage
 from .library_schema import library_schema_error, migrate_library_state
 from .image_favorites import image_favorites_schema_error, migrate_image_favorites
 from .annotation_schema import annotation_schema_error, migrate_annotation_state
+from .review_schema import (
+    migrate_review_state,
+    review_schema_error,
+    review_without_annotations_error,
+)
 from .saved_views import migrate_saved_views, saved_views_schema_error
+from .workflow_documents import (
+    DOCUMENT_ID_COLUMNS,
+    migrate_workflow_documents,
+    workflow_documents_schema_error,
+)
+
+
 from .execution_history_schema import (
     history_schema_error,
     migrate_execution_history,
-    rotate_history_epoch,
 )
 
 # Import logging system
@@ -45,6 +61,19 @@ MAX_PAIR_PROVENANCE_LENGTH = 4_000_000
 MAX_PAIR_PROVENANCE_DEPTH = 64
 
 
+def _refuse_rebuild_with_documents(columns) -> None:
+    """The legacy generated_images rebuilds copy a fixed column list.
+
+    A file that needs one (``prompt_id`` TEXT, no ``file_path``) but already
+    has the workflow document ids would lose them, so it is refused.
+    """
+    if any(column in columns for column in DOCUMENT_ID_COLUMNS):
+        raise sqlite3.DatabaseError(
+            "This database needs an old image table rebuild but already has "
+            "workflow document references; the rebuild would drop them"
+        )
+
+
 def pair_provenance_error(encoded: object) -> Optional[str]:
     """Validate the same bounded JSON object for live writes and restores."""
     if not isinstance(encoded, str):
@@ -303,7 +332,16 @@ class PromptModel:
         migrate_library_state(conn)
         migrate_image_favorites(conn)
         migrate_saved_views(conn)
+        # A review group without its annotation group is refused before the
+        # annotation install could make it look valid (catalog only; the rows
+        # are validated once, in migrate_review_state).
+        review_error = review_without_annotations_error(conn)
+        if review_error:
+            raise sqlite3.DatabaseError(review_error)
         migrate_annotation_state(conn)
+        migrate_review_state(conn)
+        # Last: the older generated_images rebuilds run only before file_path.
+        migrate_workflow_documents(conn)
 
     def _migrate_prompt_pairs(self, conn: sqlite3.Connection) -> None:
         conn.execute("SAVEPOINT prompt_pair_schema")
@@ -516,7 +554,10 @@ class PromptModel:
             "WHERE pp.positive_prompt_id IS NOT gi.prompt_id LIMIT 1"
         ).fetchone():
             return "Image pair association has a different positive prompt owner"
-        for row in conn.execute("SELECT provenance FROM image_prompt_pairs"):
+        # fetchone, not iteration: a managed connection's cursor prefetches
+        # ITER_CHUNK rows when iterated, and each provenance may be ~4 MB.
+        cursor = conn.execute("SELECT provenance FROM image_prompt_pairs")
+        while (row := cursor.fetchone()) is not None:
             error = pair_provenance_error(row[0])
             if error:
                 return error
@@ -575,19 +616,42 @@ class PromptModel:
         if conn is not None and self._local.generation == self._generation:
             return conn
 
-        # check_same_thread=False only so close_all can clean up other
-        # threads' connections; each connection is still used by one thread.
-        conn = sqlite3.connect(
-            self.db_path, check_same_thread=False, timeout=BUSY_TIMEOUT_SECONDS
-        )
-        conn.row_factory = sqlite3.Row
-        configure_connection(conn)
+        while True:
+            # The path and generation are read together, and the new
+            # connection is kept only if no Move library repointed the model
+            # meanwhile: otherwise it would write to the old file.
+            with self._conn_lock:
+                path, generation = self.db_path, self._generation
+            # check_same_thread=False only so close_all and Move library can
+            # retire other threads' connections; each connection is still
+            # used by one thread, and ManagedConnection never closes it under
+            # a running statement (see managed_connection).
+            conn = sqlite3.connect(
+                path,
+                check_same_thread=False,
+                timeout=BUSY_TIMEOUT_SECONDS,
+                factory=ManagedConnection,
+            )
+            try:
+                conn.row_factory = sqlite3.Row
+                configure_connection(conn)
+            except BaseException:
+                conn.close()
+                raise
+            with self._conn_lock:
+                if generation == self._generation:
+                    self._connections.add(conn)
+                    break
+            conn.close()
         self._local.conn = conn
-        self._local.generation = self._generation
-        with self._conn_lock:
-            self._connections.add(conn)
+        self._local.generation = generation
         return conn
 
+    @property
+    def generation(self) -> int:
+        """Bumped whenever every connection is closed or the model repointed."""
+        return self._generation
+
     @classmethod
     def close_all_instances(cls) -> None:
         """Close every connection of every live model in this process."""
@@ -596,22 +660,76 @@ class PromptModel:
         for model in models:
             model.close_all()
 
+    @classmethod
+    def repoint_instances(cls, old_path: str, new_path: str) -> list:
+        """Point every model of ``old_path`` at ``new_path`` (Move library).
+
+        Every thread opens the new file on its next ``get_connection``. The
+        old connections are detached, not closed, and returned: the caller
+        retires them (``retire_detached``) while it still holds the old
+        file's write lock. A write waiting on that lock is then interrupted
+        and can never commit, so it fails (and, through
+        ``PromptDatabase.survive_library_switch``, runs again on the new file).
+        """
+        old_key = os.path.normcase(os.path.realpath(old_path))
+        with cls._instances_lock:
+            models = list(cls._instances)
+        with cls._init_lock:
+            cls._initialized_paths.add(os.path.normcase(os.path.realpath(new_path)))
+        detached = []
+        for model in models:
+            if model._schema_key() == old_key:
+                detached.extend(model._detach_connections(new_path))
+        return detached
+
+    @staticmethod
+    def retire_detached(connections, logger=None) -> list:
+        """Retire detached connections without waiting for their owners.
+
+        Idle ones close now. One whose owner thread is inside a statement is
+        never closed from here (that frees memory the owner is using: an
+        access violation on Windows); it is interrupted, refuses to commit and
+        is closed by its owner as the statement ends. Returns those still
+        open, for ``await_detached`` once no lock the owners wait on is held.
+        """
+        return retire_connections(connections, logger)
+
+    @staticmethod
+    def await_detached(connections, logger=None) -> bool:
+        """Wait until retired connections are closed; False if some are not."""
+        return await_closed(connections, BUSY_TIMEOUT_SECONDS, logger)
+
+    @staticmethod
+    def close_detached(connections, logger=None) -> bool:
+        """Retire connections ``repoint_instances`` detached and await them.
+
+        Do not call it while holding a lock their owners may wait on; retire
+        them there (``retire_detached``) and await them after releasing it.
+        """
+        pending = retire_connections(connections, logger)
+        return await_closed(pending, BUSY_TIMEOUT_SECONDS, logger)
+
     def close_all(self) -> None:
         """Close every thread's connection; they reopen lazily on next use.
 
         Needed before deleting the database file (Windows keeps open files
         locked) and by tests that ran queries through executor threads.
         """
+        self.close_detached(self._detach_connections(), self.logger)
+
+    def _detach_connections(self, new_path: Optional[str] = None) -> list:
+        """Forget every connection (optionally pointing the model elsewhere).
+
+        Returns them for the caller to close; threads reopen on next use.
+        """
         with self._conn_lock:
+            if new_path is not None:
+                self.db_path = new_path
             connections = list(self._connections)
             self._connections.clear()
             self._generation += 1
         self._local.conn = None
-        for conn in connections:
-            try:
-                conn.close()
-            except sqlite3.Error as e:
-                self.logger.warning(f"Error closing database connection: {e}")
+        return connections
 
     def close(self) -> None:
         """Close the calling thread's connection, if it has one.
@@ -625,10 +743,7 @@ class PromptModel:
         self._local.conn = None
         with self._conn_lock:
             self._connections.discard(conn)
-        try:
-            conn.close()
-        except sqlite3.Error as e:
-            self.logger.warning(f"Error closing database connection: {e}")
+        self.close_detached([conn], self.logger)
 
     def _migrate_workflow_name_removal(self, conn: sqlite3.Connection) -> None:
         """
@@ -699,6 +814,7 @@ class PromptModel:
             columns = {column[1]: column[2] for column in cursor.fetchall()}
             if columns.get("prompt_id") != "TEXT":
                 return
+            _refuse_rebuild_with_documents(columns)
 
             self.logger.info("Migrating foreign key types: prompt_id TEXT -> INTEGER")
             with self._table_rebuild(conn):
@@ -864,6 +980,7 @@ class PromptModel:
             }
             if "file_path" in columns:
                 return
+            _refuse_rebuild_with_documents(columns)
 
             self.logger.info("Migrating database: image uniqueness by full path")
             with self._table_rebuild(conn):
@@ -929,6 +1046,10 @@ class PromptModel:
 
         Reclaims unused space and defragments the database file,
         improving query performance and reducing file size.
+
+        Raises:
+            Exception: whatever stopped VACUUM (logged first); the database is
+            then unchanged.
         """
         try:
             with closing(sqlite3.connect(self.db_path)) as conn:
@@ -936,6 +1057,7 @@ class PromptModel:
                 conn.commit()
         except Exception as e:
             self.logger.error(f"Error vacuuming database: {e}")
+            raise
 
     def get_database_info(self) -> dict:
         """
@@ -1012,7 +1134,7 @@ class PromptModel:
 
     @staticmethod
     def verify_database_file(
-        path: str, *, require_library_state: bool = False
+        path: str, *, require_library_state: bool = False, documents: bool = True
     ) -> Tuple[bool, str]:
         """
         Check that a file is a healthy prompts database before restoring it.
@@ -1023,9 +1145,12 @@ class PromptModel:
         Args:
             path: File to inspect
             require_library_state: Also require the tables every current
-                database has (Library state, image favorites, saved views
-                and image annotations), as a migrated restore stage must;
-                old backups may lack them.
+                database has (Library state, image favorites, saved views,
+                image annotations and the review queue), as a migrated
+                restore stage must; old backups may lack them.
+            documents: Read every workflow document and refuse a damaged
+                one. A restore checks its upload without it and repairs
+                damaged documents on the stage (``database/restore_stage.py``).
 
         Returns:
             (ok, reason): reason is "ok" when the file is acceptable, otherwise
@@ -1095,6 +1220,16 @@ class PromptModel:
             )
             if annotation_error:
                 return False, annotation_error
+            review_error = review_schema_error(
+                conn, allow_missing=not require_library_state
+            )
+            if review_error:
+                return False, review_error
+            documents_error = workflow_documents_schema_error(
+                conn, allow_missing=not require_library_state, documents=documents
+            )
+            if documents_error:
+                return False, documents_error
             return True, "ok"
         except sqlite3.Error as e:
             return False, f"Invalid SQLite database: {e}"
@@ -1117,21 +1252,51 @@ class PromptModel:
             Path(src_path).resolve().as_uri() + "?mode=ro", uri=True
         )
         try:
-            source.backup(self.get_connection())
+            target = self.get_connection()
+            # The target is written under backup's step too: mark it in use
+            # so a concurrent close_all retires it instead of closing it.
+            with target.using():
+                source.backup(target)
         finally:
             source.close()
 
+    def stage_restore(self, src_path: str):
+        """Stage ``src_path`` beside this database for a restore (blocking).
+
+        Returns a ``StagedRestore`` (``database/restore_stage.py``): a
+        migrated, repaired and verified copy in the library's folder, its
+        digest and what it holds. Neither the live database nor the source
+        is touched. Raises ValueError when either does not verify.
+        """
+        return restore_stage.stage_restore(PromptModel, self.db_path, src_path)
+
+    def publish_staged(self, staged) -> str:
+        """Replace the live database with ``staged``; return the safety backup.
+
+        See ``restore_stage.publish_staged``: the staged bytes are rechecked,
+        the current database is kept as ``<db_path>.backup_<stamp>`` and the
+        WAL is truncated afterwards.
+        """
+        backup_path = restore_stage.publish_staged(self, staged)
+        self.logger.info("Database restored from a staged copy")
+        from .execution_history import notify_history_restore
+
+        notify_history_restore(self.db_path)
+        return backup_path
+
     def restore_from_file(self, src_path: str) -> str:
         """
         Replace the live database with the file at src_path.
 
-        A disposable SQLite backup of the source is migrated and verified first.
-        Only then is the current database backed up next to itself as
-        ``<db_path>.backup_<YYYYmmdd_HHMMSS>`` (WAL content included), and the
-        staged pages replace the live pages through SQLite's backup API.
-        Migration failures never replace live content or modify the source.
-        An online replacement failure leaves the live database intact and
-        propagates; the completed safety backup remains available.
+        ``stage_restore`` then ``publish_staged``: a disposable copy of the
+        source is migrated, repaired and verified in the library's folder
+        first. Only then is the current database backed up next to itself as
+        ``<db_path>.backup_<YYYYmmdd_HHMMSS_ffffff>`` (WAL content included),
+        and the staged pages replace the live pages through SQLite's backup
+        API. Staging failures never replace live content or modify the
+        source. An online replacement failure leaves the live database intact
+        and propagates; the completed safety backup remains available. The
+        stage is removed either way.
 
         Args:
             src_path: SQLite file to restore
@@ -1141,55 +1306,14 @@ class PromptModel:
             there was no database to back up.
 
         Raises:
-            RuntimeError: If the previous database could not be backed up
+            ValueError: If the source or its migrated copy does not verify
+            SafetyBackupFailed: If the previous database could not be backed up
             sqlite3.OperationalError: If SQLite refuses online replacement
         """
-        ok, reason = self.verify_database_file(src_path)
-        if not ok:
-            raise ValueError(reason)
-        with tempfile.TemporaryDirectory(prefix="prompt-manager-restore-") as directory:
-            staged_path = str(Path(directory) / "staged.db")
-            source = sqlite3.connect(
-                Path(src_path).resolve().as_uri() + "?mode=ro", uri=True
-            )
-            try:
-                with closing(sqlite3.connect(staged_path)) as destination:
-                    source.backup(destination)
-            finally:
-                source.close()
-            staged = None
-            try:
-                staged = PromptModel(staged_path)
-                rotate_history_epoch(staged.get_connection())
-                ok, reason = self.verify_database_file(
-                    staged_path, require_library_state=True
-                )
-                if not ok:
-                    raise ValueError(reason)
-                staged.close_all()
-                backup_path = ""
-                if os.path.exists(self.db_path):
-                    timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
-                    backup_path = f"{self.db_path}.backup_{timestamp}"
-                    if not self.backup_database(backup_path):
-                        raise RuntimeError("Could not back up the current database")
-                    self.logger.info(f"Current database backed up to: {backup_path}")
-                try:
-                    self._replace_contents_from(staged_path)
-                except sqlite3.OperationalError as exc:
-                    exc._prompt_manager_restore_backup_created = bool(backup_path)
-                    raise
-                with PromptModel._init_lock:
-                    PromptModel._initialized_paths.add(self._schema_key())
-                self.logger.info(f"Database restored from {src_path}")
-                from .execution_history import notify_history_restore
-
-                notify_history_restore(self.db_path)
-                return backup_path
-            finally:
-                if staged is not None:
-                    staged.close_all()
-                with PromptModel._init_lock:
-                    PromptModel._initialized_paths.discard(
-                        os.path.normcase(os.path.realpath(staged_path))
-                    )
+        staged = self.stage_restore(src_path)
+        try:
+            backup_path = self.publish_staged(staged)
+        finally:
+            staged.discard()
+        self.logger.info(f"Database restored from {src_path}")
+        return backup_path

database/operations.py

@@ -4,28 +4,50 @@ Database operations for KikoTextEncode prompt storage and retrieval.
 
 import sqlite3
 import json
+import math
 import datetime
 import os
 from typing import Optional, List, Dict, Any, Set, Tuple
 
 from .models import PromptModel, normalize_image_path, utc_now_iso
-from .pairs import PairDependencyError, PairOperations
+from .pairs import PairDependencyError, PairOperations  # noqa: F401 (re-exported)
 from .library import LibraryOperations, titled
 from .image_favorites import ImageFavoriteOperations
 from .annotations import AnnotationOperations
+from .review import ReviewOperations
+from .review_decisions import ReviewDecisionOperations
 from .saved_views import SavedViewOperations
 from .library_commands import LibraryCommandOperations
 from .vocabulary import VocabularyOperations
 from .execution_history import ExecutionHistoryOperations
-from .execution_contexts import ExecutionContextOperations, LIVE_HINT_CTES
+from .execution_contexts import ExecutionContextOperations
 from .execution_outputs import ExecutionOutputOperations
 from .history_reads import HistoryReadOperations
 from .health import HealthOperations, iter_consistency_issues
+from .duplicate_copies import DuplicateCopyOperations
+from .workflow_storage import WorkflowStorageOperations
+from .category_import import CategoryImportOperations, EmptyReplacement  # noqa: F401
+from .workflow_documents import (
+    DocumentReader,
+    documents_of_rows,
+    release_documents,
+    resolve_image_row,
+    stored_values,
+)
+from .maintenance import (  # noqa: F401  (ORPHANED_PROMPTS_SQL is re-exported)
+    ORPHANED_PROMPTS_SQL,
+    _LINK_ROWS_SQL,
+    MaintenanceOperations,
+    _delete_ids,
+    _orphaned_ids,
+)
 
 # Import logging system
 try:
     from ..utils.logging_config import get_logger
     from ..utils.hashing import generate_prompt_hash
+    from ..utils.json_strict import dumps_strict
+    from ..utils import library_location
 except ImportError:
     import sys
 
@@ -33,6 +55,8 @@ except ImportError:
     sys.path.insert(0, current_dir)
     from utils.logging_config import get_logger
     from utils.hashing import generate_prompt_hash
+    from utils.json_strict import dumps_strict
+    from utils import library_location
 
 
 # Subquery to fetch tags from junction table, embedded in SELECT statements
@@ -78,40 +102,56 @@ def escape_like(term: str) -> str:
     )
 
 
-def _resolve_db_path(db_path: Optional[str] = None) -> str:
-    """Resolve the database path from config, falling back to defaults.
+def _configured_default_path():
+    """config.json's ``database.default_path``, or None.
 
-    When no explicit path is given, reads PromptManagerConfig.DEFAULT_DB_PATH
-    (set via config.json). Relative paths are resolved against the extension
-    root directory so the database location is predictable regardless of the
-    process working directory (important for Docker deployments).
+    The package-qualified config wins over a standalone ``py.config`` (a
+    custom-node package uses its own configuration).
+    """
+    try:
+        try:
+            from ..py.config import PromptManagerConfig
+        except ImportError:
+            from py.config import PromptManagerConfig
+    except Exception:
+        return None
+    return getattr(PromptManagerConfig, "DEFAULT_DB_PATH", None)
+
+
+def resolve_library_location():
+    """Where the library lives now (``utils.library_location``, #249 S6b).
+
+    The image sources that rule out a ``PROMPT_MANAGER_DATA_DIR`` are read by
+    the resolver itself, exactly as ``config_location`` reads them.
+    """
+    return library_location.resolve_library(_configured_default_path())
+
+
+def _resolve_db_path(db_path: Optional[str] = None) -> str:
+    """Resolve the database path through the one library resolver.
+
+    With no explicit path, ``utils.library_location.resolve_library`` decides
+    (``PROMPT_MANAGER_DATA_DIR``, an explicit ``database.default_path``, a
+    node-folder library not moved yet, else ComfyUI's ``user/__promptmanager``).
+    An explicit relative path is resolved against the extension root, as
+    before, so the location does not depend on the working directory.
 
     Args:
-        db_path: Explicit database path, or None to use config/default.
+        db_path: Explicit database path, or None to use the resolver.
 
     Returns:
-        Absolute path to the SQLite database file.
+        Absolute path to the SQLite database file; its folder exists (a new
+        data folder is created owner-only).
     """
-    extension_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
     if db_path is None:
-        try:
-            try:
-                from ..py.config import PromptManagerConfig
-            except ImportError:
-                from py.config import PromptManagerConfig
-
-            db_path = PromptManagerConfig.DEFAULT_DB_PATH
-        except Exception:
-            db_path = "prompts.db"
-
-    if not os.path.isabs(db_path):
+        db_path = resolve_library_location().db_path
+    elif not os.path.isabs(db_path):
+        extension_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
         db_path = os.path.normpath(os.path.join(extension_root, db_path))
 
-    # Ensure parent directory exists for custom paths
     parent = os.path.dirname(db_path)
     if parent:
-        os.makedirs(parent, exist_ok=True)
+        library_location.ensure_private_dir(parent)
 
     return db_path
 
@@ -161,28 +201,6 @@ def _coerce_file_info(metadata: Any) -> tuple:
     )
 
 
-# Exempt references: images, pairs, the __protected__ tag, Library parent
-# state, and live recorded-run hints (computed once, see LIVE_HINT_CTES).
-ORPHANED_PROMPTS_SQL = "WITH " + LIVE_HINT_CTES + """
-SELECT p.id FROM prompts p
-LEFT JOIN generated_images gi ON p.id = gi.prompt_id
-WHERE gi.prompt_id IS NULL
-AND NOT EXISTS (
-    SELECT 1 FROM prompt_pairs pp
-    WHERE pp.positive_prompt_id = p.id OR pp.negative_prompt_id = p.id
-)
-AND NOT EXISTS (
-    SELECT 1 FROM prompt_tags pt
-    JOIN tags t ON pt.tag_id = t.id
-    WHERE pt.prompt_id = p.id AND t.name = '__protected__'
-)
-AND NOT EXISTS (
-    SELECT 1 FROM prompt_library_state ls WHERE ls.prompt_id = p.id
-)
-AND p.id NOT IN (SELECT prompt_id FROM live_hint_prompts)
-"""
-
-
 # The scan's known set (#249 Activity-2): every image row, with its stored file
 # size and whether its pair link is resolved: exactly one distinct pair, the rule
 # _LINK_SUMMARY_SQL and get_image_prompt_info use. A file is known and resolved
@@ -342,8 +360,14 @@ class PromptDatabase(
     HistoryReadOperations,
     ImageFavoriteOperations,
     AnnotationOperations,
+    ReviewOperations,
+    ReviewDecisionOperations,
     SavedViewOperations,
     HealthOperations,
+    MaintenanceOperations,
+    DuplicateCopyOperations,
+    WorkflowStorageOperations,
+    CategoryImportOperations,
 ):
     """Database operations class for managing prompts."""
 
@@ -361,6 +385,25 @@ class PromptDatabase(
         self.model = PromptModel(db_path)
         self.logger.debug("Database operations initialized successfully")
 
+    def survive_library_switch(self, write):
+        """Run ``write()``; once more if it failed while the library moved.
+
+        A background write (run counting, the image monitor) that was waiting
+        on the old file when Move library switched fails when its connection
+        is closed. When the model's generation changed during the attempt,
+        the write runs again on a fresh connection, which is the new library;
+        any other failure is raised as it was. ``write`` must open its own
+        transaction (every PromptDatabase method does).
+        """
+        generation = self.model.generation
+        try:
+            return write()
+        except Exception:
+            if self.model.generation == generation:
+                raise
+            self.logger.info("Running a write again on the moved library")
+            return write()
+
     def close(self) -> None:
         """Close the calling thread's database connection (see PromptModel.close)."""
         self.model.close()
@@ -414,26 +457,9 @@ class PromptDatabase(
 
         try:
             with self.model.get_connection() as conn:
-                cursor = conn.execute(
-                    """
-                    INSERT INTO prompts (
-                        text, category, tags, rating, notes, hash, created_at,
-                        updated_at
-                    ) VALUES (?, ?, NULL, ?, ?, ?, ?, ?)
-                    """,
-                    (
-                        text.strip(),
-                        category,
-                        rating,
-                        notes,
-                        prompt_hash,
-                        datetime.datetime.now(datetime.timezone.utc).isoformat(),
-                        datetime.datetime.now(datetime.timezone.utc).isoformat(),
-                    ),
+                prompt_id = self._insert_prompt(
+                    conn, text, category, tags, rating, notes, prompt_hash
                 )
-                prompt_id = cursor.lastrowid
-                if tags:
-                    self._sync_prompt_tags(conn, prompt_id, tags)
                 conn.commit()
                 self.logger.debug(f"Successfully saved prompt with ID: {prompt_id}")
                 return prompt_id
@@ -449,6 +475,32 @@ class PromptDatabase(
             )
             return existing["id"]
 
+    def _insert_prompt(
+        self,
+        conn: sqlite3.Connection,
+        text: str,
+        category: Optional[str],
+        tags: Optional[List[str]],
+        rating: Optional[int],
+        notes: Optional[str],
+        prompt_hash: Optional[str],
+    ) -> int:
+        """Insert one prompt row and its tags on ``conn`` (no commit)."""
+        now = datetime.datetime.now(datetime.timezone.utc).isoformat()
+        cursor = conn.execute(
+            """
+            INSERT INTO prompts (
+                text, category, tags, rating, notes, hash, created_at,
+                updated_at
+            ) VALUES (?, ?, NULL, ?, ?, ?, ?, ?)
+            """,
+            (text.strip(), category, rating, notes, prompt_hash, now, now),
+        )
+        prompt_id = cursor.lastrowid
+        if tags:
+            self._sync_prompt_tags(conn, prompt_id, tags)
+        return prompt_id
+
     def record_prompt_use(self, prompt_id: int, times: int = 1) -> bool:
         """
         Count runs of a prompt and mark it as most recently used.
@@ -781,10 +833,12 @@ class PromptDatabase(
         """
         with self._pair_transaction() as conn:
             self._ensure_prompts_unpaired(conn, [prompt_id])
+            documents = documents_of_rows(conn, "prompt_id", [prompt_id])
             # First delete related images to avoid foreign key constraint
             conn.execute(
                 "DELETE FROM generated_images WHERE prompt_id = ?", (prompt_id,)
             )
+            release_documents(conn, documents)
             # Then delete the prompt
             cursor = conn.execute("DELETE FROM prompts WHERE id = ?", (prompt_id,))
             conn.commit()
@@ -808,10 +862,12 @@ class PromptDatabase(
                 return 0
             self._ensure_prompts_unpaired(conn, ids)
             placeholders = ",".join("?" * len(ids))
+            documents = documents_of_rows(conn, "prompt_id", ids)
             conn.execute(
                 f"DELETE FROM generated_images WHERE prompt_id IN ({placeholders})",
                 ids,
             )
+            release_documents(conn, documents)
             conn.execute(
                 f"DELETE FROM prompt_tags WHERE prompt_id IN ({placeholders})",
                 ids,
@@ -1534,80 +1590,14 @@ class PromptDatabase(
         self.logger.info("Starting duplicate cleanup process with image preservation")
         try:
             with self._pair_transaction() as conn:
-                # Find duplicates by text content (case-insensitive)
-                # Note: Removed ORDER BY from GROUP_CONCAT for SQLite compatibility
-                # We'll sort the IDs manually after fetching
-                cursor = conn.execute("""
-                    SELECT LOWER(TRIM(text)) as normalized_text, COUNT(*) as count,
-                           GROUP_CONCAT(id) as ids,
-                           GROUP_CONCAT(created_at) as created_dates
-                    FROM prompts
-                    GROUP BY LOWER(TRIM(text))
-                    HAVING COUNT(*) > 1
-                """)
-
-                duplicates = cursor.fetchall()
-                self.logger.debug(
-                    f"Found {len(duplicates)} groups of duplicate prompts"
-                )
+                groups, _paired = self._duplicate_groups(conn)
+                self.logger.debug(f"Found {len(groups)} groups of duplicate prompts")
                 total_removed = 0
                 total_images_transferred = 0
-
-                for duplicate in duplicates:
-                    ids = duplicate["ids"].split(",")
-                    created_dates = duplicate["created_dates"].split(",")
-
-                    # Sort IDs by created_at date to keep the oldest
-                    id_date_pairs = list(zip(ids, created_dates))
-                    id_date_pairs.sort(key=lambda x: x[1])  # Sort by date
-                    sorted_ids = [int(pair[0]) for pair in id_date_pairs]
-
-                    try:
-                        self._ensure_prompts_unpaired(conn, sorted_ids)
-                    except PairDependencyError:
-                        continue
-
-                    # Keep the oldest one (first), merge and delete the rest
-                    primary_id = sorted_ids[0]  # Keep the oldest
-                    duplicate_ids = sorted_ids[1:]
-
-                    self.logger.debug(
-                        f"Merging duplicates: keeping {primary_id}, removing "
-                        f"{duplicate_ids}"
-                    )
-
-                    # Get primary prompt details
-                    cursor = conn.execute(
-                        "SELECT * FROM prompts WHERE id = ?", (primary_id,)
-                    )
-                    primary_prompt = cursor.fetchone()
-                    if not primary_prompt:
-                        continue
-
-                    # Collect and merge metadata from all duplicates
-                    merged_metadata = self._merge_duplicate_metadata(
-                        conn, primary_id, duplicate_ids
-                    )
-
-                    # Transfer all images from duplicates to primary prompt
-                    images_transferred = self._transfer_images_to_primary(
-                        conn, primary_id, duplicate_ids
-                    )
-                    total_images_transferred += images_transferred
-
-                    # Update primary prompt with merged metadata
-                    if merged_metadata:
-                        self._update_primary_with_merged_metadata(
-                            conn, primary_id, merged_metadata
-                        )
-
-                    # Delete duplicate prompts (images already transferred)
-                    for duplicate_id in duplicate_ids:
-                        conn.execute(
-                            "DELETE FROM prompts WHERE id = ?", (duplicate_id,)
-                        )
-                        total_removed += 1
-                        self.logger.debug(f"Removed duplicate prompt {duplicate_id}")
+                for sorted_ids in groups:
+                    removed, moved = self._merge_duplicate_group(conn, sorted_ids)
+                    total_removed += removed
+                    total_images_transferred += moved
 
                 conn.commit()
 
@@ -1638,84 +1628,137 @@ class PromptDatabase(
             metadata: Optional metadata about the image
 
         Returns:
-            int: The ID of the created image record
+            int: The ID of the created image record, or 0 when nothing was
+            linked (invalid or unknown prompt, already linked, or an error,
+            which is logged)
         """
-        # Validate that prompt_id is a valid integer and exists in prompts table
         try:
-            # Convert prompt_id to integer if it's a string number
-            if isinstance(prompt_id, str) and prompt_id.isdigit():
-                prompt_id_int = int(prompt_id)
-            elif isinstance(prompt_id, int):
-                prompt_id_int = prompt_id
-            else:
-                # Handle temporary IDs like "temp_123456" - skip linking
-                if isinstance(prompt_id, str) and prompt_id.startswith("temp_"):
-                    self.logger.debug(
-                        f"Skipping image linking for temporary prompt ID: {prompt_id}"
-                    )
-                    return 0
-                else:
-                    self.logger.warning(
-                        f"Invalid prompt_id format: {prompt_id}, skipping image linking"
-                    )
-                    return 0
-
-            # Verify the prompt exists in the database
-            with self.model.get_connection() as conn:
-                cursor = conn.execute(
-                    "SELECT id FROM prompts WHERE id = ?", (prompt_id_int,)
-                )
-                if not cursor.fetchone():
-                    self.logger.warning(
-                        f"Prompt ID {prompt_id_int} not found in database, skipping "
-                        "image linking"
-                    )
-                    return 0
-
-                # Proceed with linking
-                if not isinstance(metadata, dict):
-                    metadata = {}
-                filename = os.path.basename(image_path)
-                file_path = normalize_image_path(image_path)
-                file_size, width, height, image_format = _coerce_file_info(metadata)
-
-                # INSERT OR IGNORE skips a file already linked to this prompt
-                # (same prompt_id + normalised full path)
-                cursor = conn.execute(
-                    """
-                    INSERT OR IGNORE INTO generated_images
-                    (prompt_id, image_path, filename, file_path, file_size, width,
-                     height, format, workflow_data, prompt_metadata, parameters)
-                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                    """,
-                    (
-                        prompt_id_int,
-                        image_path,
-                        filename,
-                        file_path,
-                        file_size,
-                        width,
-                        height,
-                        image_format,
-                        json.dumps(metadata.get("workflow", {})),
-                        json.dumps(metadata.get("prompt", {})),
-                        json.dumps(metadata.get("parameters", {})),
-                    ),
-                )
-                conn.commit()
-
-                if cursor.rowcount == 0:
-                    self.logger.debug(
-                        f"Image {file_path} already linked to prompt {prompt_id_int}"
-                    )
-                    return 0
-
-                return cursor.lastrowid
-
+            return self.link_image_to_prompt_or_raise(prompt_id, image_path, metadata)
         except Exception as e:
             self.logger.error(f"Error linking image to prompt {prompt_id}: {e}")
             return 0
 
+    def link_image_to_prompt_or_raise(
+        self, prompt_id: str, image_path: str, metadata: Optional[Dict[str, Any]] = None
+    ) -> int:
+        """``link_image_to_prompt`` that raises database errors.
+
+        The image monitor links through this so a write that failed because
+        Move library switched reaches ``survive_library_switch`` and runs
+        again on the new library (#249 S6b). Each call is one transaction:
+        a failed attempt rolls back, and a committed one does not raise.
+        Returns 0 for an invalid or unknown prompt or an image already linked.
+        """
+        # Validate that prompt_id is a valid integer and exists in prompts table
+        # Convert prompt_id to integer if it's a string number
+        if isinstance(prompt_id, str) and prompt_id.isdigit():
+            prompt_id_int = int(prompt_id)
+        elif isinstance(prompt_id, int):
+            prompt_id_int = prompt_id
+        else:
+            # Handle temporary IDs like "temp_123456" - skip linking
+            if isinstance(prompt_id, str) and prompt_id.startswith("temp_"):
+                self.logger.debug(
+                    f"Skipping image linking for temporary prompt ID: {prompt_id}"
+                )
+                return 0
+            else:
+                self.logger.warning(
+                    f"Invalid prompt_id format: {prompt_id}, skipping image linking"
+                )
+                return 0
+
+        # Verify the prompt exists in the database
+        with self.model.get_connection() as conn:
+            cursor = conn.execute(
+                "SELECT id FROM prompts WHERE id = ?", (prompt_id_int,)
+            )
+            if not cursor.fetchone():
+                self.logger.warning(
+                    f"Prompt ID {prompt_id_int} not found in database, skipping "
+                    "image linking"
+                )
+                return 0
+
+            # Proceed with linking
+            image_id = self._insert_image_link(
+                conn, prompt_id_int, image_path, metadata
+            )
+            conn.commit()
+
+            if not image_id:
+                self.logger.debug(
+                    f"Image {normalize_image_path(image_path)} already linked to "
+                    f"prompt {prompt_id_int}"
+                )
+                return 0
+
+            return image_id
+
+    def _insert_image_link(
+        self,
+        conn: sqlite3.Connection,
+        prompt_id_int: int,
+        image_path: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """Insert one image link on ``conn`` (no commit).
+
+        Returns the new image row's id, or 0 when the file is already linked
+        to this prompt (``INSERT OR IGNORE``).
+        """
+        if not isinstance(metadata, dict):
+            metadata = {}
+        filename = os.path.basename(image_path)
+        file_path = normalize_image_path(image_path)
+        file_size, width, height, image_format = _coerce_file_info(metadata)
+        # Each workflow and prompt graph is stored once (new form).
+        documents = stored_values(
+            conn,
+            {
+                "workflow_data": dumps_strict(metadata.get("workflow", {})),
+                "prompt_metadata": dumps_strict(metadata.get("prompt", {})),
+            },
+        )
+
+        # INSERT OR IGNORE skips a file already linked to this prompt
+        # (same prompt_id + normalised full path)
+        cursor = conn.execute(
+            """
+            INSERT OR IGNORE INTO generated_images
+            (prompt_id, image_path, filename, file_path, file_size, width,
+             height, format, workflow_data, prompt_metadata, parameters,
+             workflow_document_id, prompt_document_id)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                prompt_id_int,
+                image_path,
+                filename,
+                file_path,
+                file_size,
+                width,
+                height,
+                image_format,
+                documents["workflow_data"],
+                documents["prompt_metadata"],
+                dumps_strict(metadata.get("parameters", {})),
+                documents["workflow_document_id"],
+                documents["prompt_document_id"],
+            ),
+        )
+        if cursor.rowcount == 0:
+            # Already linked: a document made only for this row goes.
+            release_documents(
+                conn,
+                (
+                    documents["workflow_document_id"],
+                    documents["prompt_document_id"],
+                ),
+            )
+            return 0
+        return cursor.lastrowid
+
     def get_prompt_images(self, prompt_id: str) -> List[Dict[str, Any]]:
         """
         Get all images associated with a prompt.
@@ -1735,7 +1778,8 @@ class PromptDatabase(
                 """,
                 (prompt_id,),
             )
-            return [self._image_row_to_dict(row) for row in cursor.fetchall()]
+            reader = DocumentReader(conn)
+            return [self._image_row_to_dict(row, reader) for row in cursor]
 
     def get_recent_images(
         self, limit: int = 50, offset: int = 0
@@ -1761,7 +1805,8 @@ class PromptDatabase(
                 """,
                 (int(limit), max(0, int(offset))),
             )
-            return [self._image_row_to_dict(row) for row in cursor.fetchall()]
+            reader = DocumentReader(conn)
+            return [self._image_row_to_dict(row, reader) for row in cursor]
 
     def get_all_images(
         self,
@@ -1795,10 +1840,10 @@ class PromptDatabase(
 
         with self.model.get_connection() as conn:
             cursor = conn.execute(sql, params)
-            rows = cursor.fetchall()
+            reader = DocumentReader(conn)
             result = []
-            for row in rows:
-                data = self._image_row_to_dict(row)
+            for row in cursor:
+                data = self._image_row_to_dict(row, reader)
                 if row["_prompt_tags_list"]:
                     data["prompt_tags"] = row["_prompt_tags_list"].split("|||")
                 else:
@@ -1836,7 +1881,8 @@ class PromptDatabase(
                     max(0, int(offset)),
                 ),
             )
-            return [self._image_row_to_dict(row) for row in cursor.fetchall()]
+            reader = DocumentReader(conn)
+            return [self._image_row_to_dict(row, reader) for row in cursor]
 
     def get_image_by_id(self, image_id: int) -> Optional[Dict[str, Any]]:
         """
@@ -1853,7 +1899,7 @@ class PromptDatabase(
                 "SELECT * FROM generated_images WHERE id = ?", (image_id,)
             )
             row = cursor.fetchone()
-            return self._image_row_to_dict(row) if row else None
+            return self._image_row_to_dict(row, DocumentReader(conn)) if row else None
 
     def delete_image(self, image_id: int) -> bool:
         """
@@ -1866,31 +1912,54 @@ class PromptDatabase(
             bool: True if deletion was successful
         """
         with self.model.get_connection() as conn:
+            documents = documents_of_rows(conn, "id", [image_id])
             cursor = conn.execute(
                 "DELETE FROM generated_images WHERE id = ?", (image_id,)
             )
+            release_documents(conn, documents)
             conn.commit()
             return cursor.rowcount > 0
 
-    def cleanup_missing_images(self) -> int:
+    def cleanup_missing_images(self, roots=None) -> int:
         """
         Remove image records where the actual file no longer exists.
 
+        Args:
+            roots: The image sources links are judged under (the health
+                check's). When given, only a link under a source that can be
+                read now is removed: a link under an unavailable source (an
+                unmounted drive) or outside every source is kept. None keeps
+                the old rule: every link whose file does not exist.
+
         Returns:
             int: Number of orphaned records removed
         """
+        if roots is not None:
+            with self.model.get_connection() as conn:
+                rows = [tuple(row) for row in conn.execute(_LINK_ROWS_SQL)]
+            # Files are looked at before the write transaction starts.
+            ids = self._missing_link_ids(rows, [str(root) for root in roots])
+            if not ids:
+                return 0
+            with self._pair_transaction() as conn:
+                return _delete_ids(conn, "generated_images", ids)
+
         removed_count = 0
 
         with self.model.get_connection() as conn:
             cursor = conn.execute("SELECT id, image_path FROM generated_images")
             images = cursor.fetchall()
 
-            for image in images:
-                if not os.path.exists(image["image_path"]):
-                    conn.execute(
-                        "DELETE FROM generated_images WHERE id = ?", (image["id"],)
-                    )
-                    removed_count += 1
+            removed = [
+                image["id"]
+                for image in images
+                if not os.path.exists(image["image_path"])
+            ]
+            documents = documents_of_rows(conn, "id", removed)
+            for image_id in removed:
+                conn.execute("DELETE FROM generated_images WHERE id = ?", (image_id,))
+                removed_count += 1
+            release_documents(conn, documents)
 
             conn.commit()
 
@@ -1904,19 +1973,23 @@ class PromptDatabase(
             obj: The object to clean (dict, list, or scalar)
 
         Returns:
-            Cleaned object with NaN values replaced by None
+            Cleaned object with NaN and Infinity values replaced by None
         """
         if isinstance(obj, dict):
             return {key: self._clean_nan_values(value) for key, value in obj.items()}
         elif isinstance(obj, list):
             return [self._clean_nan_values(item) for item in obj]
-        elif isinstance(obj, float) and str(obj) == "nan":
+        elif isinstance(obj, float) and not math.isfinite(obj):
             return None
         else:
             return obj
 
     def _merge_duplicate_metadata(
-        self, conn: sqlite3.Connection, primary_id: int, duplicate_ids: List[int]
+        self,
+        conn: sqlite3.Connection,
+        primary_id: int,
+        duplicate_ids: List[int],
+        strict: bool = False,
     ) -> Dict[str, Any]:
         """
         Merge metadata from duplicate prompts, prioritizing non-empty values.
@@ -1976,11 +2049,17 @@ class PromptDatabase(
             return merged
 
         except Exception as e:
+            if strict:  # a reviewed apply rolls back instead
+                raise
             self.logger.error(f"Error merging metadata: {e}", exc_info=True)
             return {}
 
     def _transfer_images_to_primary(
-        self, conn: sqlite3.Connection, primary_id: int, duplicate_ids: List[int]
+        self,
+        conn: sqlite3.Connection,
+        primary_id: int,
+        duplicate_ids: List[int],
+        strict: bool = False,
     ) -> int:
         """
         Transfer all images from duplicate prompts to the primary prompt.
@@ -2012,11 +2091,17 @@ class PromptDatabase(
             return transferred_count
 
         except Exception as e:
+            if strict:  # a reviewed apply rolls back instead
+                raise
             self.logger.error(f"Error transferring images: {e}", exc_info=True)
             return 0
 
     def _update_primary_with_merged_metadata(
-        self, conn: sqlite3.Connection, primary_id: int, merged_metadata: Dict[str, Any]
+        self,
+        conn: sqlite3.Connection,
+        primary_id: int,
+        merged_metadata: Dict[str, Any],
+        strict: bool = False,
     ) -> None:
         """
         Update the primary prompt with merged metadata.
@@ -2047,6 +2132,8 @@ class PromptDatabase(
             )
 
         except Exception as e:
+            if strict:  # a reviewed apply rolls back instead
+                raise
             self.logger.error(
                 f"Error updating primary prompt metadata: {e}", exc_info=True
             )
@@ -2163,11 +2250,13 @@ class PromptDatabase(
         count = 0
         with self._pair_transaction() as conn:
             self._ensure_prompts_unpaired(conn, prompt_ids)
+            documents = documents_of_rows(conn, "prompt_id", prompt_ids)
             for pid in prompt_ids:
                 conn.execute("DELETE FROM generated_images WHERE prompt_id = ?", (pid,))
                 cursor = conn.execute("DELETE FROM prompts WHERE id = ?", (pid,))
                 if cursor.rowcount > 0:
                     count += 1
+            release_documents(conn, documents)
             conn.commit()
         return count
 
@@ -2241,7 +2330,8 @@ class PromptDatabase(
             cursor = conn.execute(
                 """SELECT gi.prompt_id, p.text, p.category, p.rating, p.notes,
                           gi.workflow_data, gi.prompt_metadata, gi.generation_time,
-                          gi.parameters, gi.id, gi.image_path, gi.file_path
+                          gi.parameters, gi.id, gi.image_path, gi.file_path,
+                          gi.workflow_document_id, gi.prompt_document_id
                    FROM generated_images gi
                    JOIN prompts p ON gi.prompt_id = p.id
                    WHERE gi.image_path = ? OR gi.file_path = ?
@@ -2321,12 +2411,21 @@ class PromptDatabase(
                         "text_source": source,
                     }
             tags = self._get_prompt_tags(conn, row[0])
+            texts = resolve_image_row(DocumentReader(conn), row)
             try:
-                workflow = json.loads(row[5]) if row[5] else None
+                workflow = (
+                    json.loads(texts["workflow_data"])
+                    if texts["workflow_data"]
+                    else None
+                )
             except (json.JSONDecodeError, TypeError):
                 workflow = None
             try:
-                prompt_meta = json.loads(row[6]) if row[6] else None
+                prompt_meta = (
+                    json.loads(texts["prompt_metadata"])
+                    if texts["prompt_metadata"]
+                    else None
+                )
             except (json.JSONDecodeError, TypeError):
                 prompt_meta = None
             return {
@@ -2560,16 +2659,12 @@ class PromptDatabase(
         Returns number of prompts removed.
         """
         with self._pair_transaction() as conn:
-            cursor = conn.execute(ORPHANED_PROMPTS_SQL)
-            orphaned = [row["id"] for row in cursor.fetchall()]
+            orphaned = _orphaned_ids(conn)
             if not orphaned:
                 return 0
-            placeholders = ",".join(["?"] * len(orphaned))
-            cursor = conn.execute(
-                f"DELETE FROM prompts WHERE id IN ({placeholders})", orphaned
-            )
+            removed = _delete_ids(conn, "prompts", orphaned)
             conn.commit()
-            return cursor.rowcount
+            return removed
 
     def check_consistency(self) -> List[str]:
         """Run consistency checks and return a list of issue descriptions.
@@ -2580,17 +2675,20 @@ class PromptDatabase(
         with self.model.get_connection() as conn:
             return list(iter_consistency_issues(conn))
 
-    def _image_row_to_dict(self, row: sqlite3.Row) -> Dict[str, Any]:
+    def _image_row_to_dict(
+        self, row: sqlite3.Row, reader: DocumentReader
+    ) -> Dict[str, Any]:
         """
         Convert an image database row to a dictionary with parsed JSON fields.
 
         Args:
             row: SQLite row object
+            reader: The workflow document reader of the row's connection
 
         Returns:
             Dictionary representation of the row
         """
-        data = dict(row)
+        data = resolve_image_row(reader, row)
 
         # Parse JSON fields
         for field in ["workflow_data", "prompt_metadata", "parameters"]:

database/pair_ingestion.py

@@ -1,136 +1,212 @@
 """Atomic metadata enrichment for a single known generation context."""
 
-import json
 import os
 from typing import Any, Dict
 
 from .models import normalize_image_path
 from .operations import _coerce_file_info
+from .workflow_documents import (
+    TEXT_COLUMNS,
+    DocumentReader,
+    release_documents,
+    resolve_image_row,
+    stored_values,
+)
 
 try:
     from ..utils.hashing import generate_prompt_hash
+    from ..utils.json_strict import dumps_strict
+    from ..utils.prompt_pair_resolver import RESOLVER_VERSION
 except ImportError:
     from utils.hashing import generate_prompt_hash
+    from utils.json_strict import dumps_strict
+    from utils.prompt_pair_resolver import RESOLVER_VERSION
+
+
+def blank_positive(resolution: Dict[str, Any]) -> bool:
+    """A resolved pair whose stored positive text is empty (#342).
+
+    A PromptManager node whose editor is empty encodes only its prepend and
+    append text, which is never stored as a prompt: such a result names no
+    prompt to link.
+    """
+    if resolution.get("state") != "resolved":
+        return False
+    positive = resolution.get("positive") or {}
+    text = positive.get("storage_text", positive.get("text"))
+    return not (isinstance(text, str) and text.strip())
 
 
 def ingest_resolved_pair(
     db: Any, image_path: str, metadata: Dict[str, Any], resolution: Dict[str, Any]
 ) -> Dict[str, Any]:
     state = resolution.get("state", "unresolved")
+    if state == "resolved" and blank_positive(resolution):
+        state = "unresolved"
     if state != "resolved":
         return {"status": state, "pairs_added": 0, "links_added": 0}
+    with db._pair_transaction() as conn:
+        return _ingest_resolved_pair_in(conn, db, image_path, metadata, resolution)
+
+
+def _conflict() -> Dict[str, Any]:
+    return {"status": "conflict", "pairs_added": 0, "links_added": 0}
+
+
+def _ingest_resolved_pair_in(
+    conn: Any,
+    db: Any,
+    image_path: str,
+    metadata: Dict[str, Any],
+    resolution: Dict[str, Any],
+    *,
+    provenance: Dict[str, Any] | None = None,
+) -> Dict[str, Any]:
+    """``ingest_resolved_pair`` inside the caller's open ``_pair_transaction``.
+
+    The compatible-only rules are the public ingester's: an image with more
+    than one exact row, another positive, or a prior pair with another
+    negative is a ``conflict`` and nothing is written. The caller owns the
+    transaction, so its own later failure rolls the link back too.
+    ``provenance`` replaces the link's default resolver provenance (Needs
+    review records the user's selection there).
+    """
     positive, negative = resolution["positive"], resolution["negative"]
     positive_text = positive.get("storage_text", positive["text"])
     negative_text = negative.get("storage_text", negative["text"])
     normalized = normalize_image_path(image_path)
-    provenance = {"resolver_version": 1, "positive": positive, "negative": negative}
-    encoded = json.dumps(
-        provenance, sort_keys=True, separators=(",", ":"), allow_nan=False
-    )
-    with db._pair_transaction() as conn:
-        images = conn.execute(
-            "SELECT gi.*,p.hash AS positive_hash FROM generated_images gi "
-            "JOIN prompts p ON p.id=gi.prompt_id "
-            "WHERE gi.file_path=? OR gi.image_path=?",
-            (normalized, image_path),
+    if provenance is None:
+        provenance = {
+            "resolver_version": RESOLVER_VERSION,
+            "positive": positive,
+            "negative": negative,
+        }
+    encoded = dumps_strict(provenance, sort_keys=True, separators=(",", ":"))
+    images = conn.execute(
+        "SELECT gi.*,p.hash AS positive_hash FROM generated_images gi "
+        "JOIN prompts p ON p.id=gi.prompt_id "
+        "WHERE gi.file_path=? OR gi.image_path=?",
+        (normalized, image_path),
+    ).fetchall()
+    if len(images) > 1 or (
+        images and images[0]["positive_hash"] != generate_prompt_hash(positive_text)
+    ):
+        return _conflict()
+    existing = images[0] if images else None
+    if existing:
+        prior = conn.execute(
+            "SELECT n.hash AS negative_hash FROM image_prompt_pairs ip "
+            "JOIN prompt_pairs pp ON pp.id=ip.pair_id "
+            "LEFT JOIN prompts n ON n.id=pp.negative_prompt_id WHERE ip.image_id=?",
+            (existing["id"],),
         ).fetchall()
-        if len(images) > 1 or (
-            images and images[0]["positive_hash"] != generate_prompt_hash(positive_text)
-        ):
-            return {"status": "conflict", "pairs_added": 0, "links_added": 0}
-        existing = images[0] if images else None
-        if existing:
-            prior = conn.execute(
-                "SELECT n.hash AS negative_hash FROM image_prompt_pairs ip "
-                "JOIN prompt_pairs pp ON pp.id=ip.pair_id "
-                "LEFT JOIN prompts n ON n.id=pp.negative_prompt_id WHERE ip.image_id=?",
-                (existing["id"],),
-            ).fetchall()
-            expected = (
-                generate_prompt_hash(negative_text) if negative_text.strip() else None
-            )
-            if any(row["negative_hash"] != expected for row in prior):
-                return {"status": "conflict", "pairs_added": 0, "links_added": 0}
-        prior_pair = conn.execute(
-            "SELECT pp.id FROM prompt_pairs pp "
-            "JOIN prompts p ON p.id=pp.positive_prompt_id "
-            "LEFT JOIN prompts n ON n.id=pp.negative_prompt_id "
-            "WHERE p.hash=? AND n.hash IS ?",
-            (
-                generate_prompt_hash(positive_text),
-                generate_prompt_hash(negative_text) if negative_text.strip() else None,
-            ),
-        ).fetchone()
-        pair_id = db._save_pair(conn, positive_text, negative_text)
-        pair = conn.execute(
-            "SELECT * FROM prompt_pairs WHERE id=?", (pair_id,)
-        ).fetchone()
-        pairs_added = int(prior_pair is None)
-        file_size, width, height, image_format = _coerce_file_info(metadata)
-        snapshots = {
-            column: json.dumps(metadata[key], sort_keys=True, allow_nan=False)
-            for column, key in (
-                ("workflow_data", "workflow"),
-                ("prompt_metadata", "prompt"),
-                ("parameters", "parameters"),
-            )
-            if key in metadata
-        }
-        info = {
-            "file_size": file_size,
-            "width": width,
-            "height": height,
-            "format": image_format,
-        }
-        snapshots.update(
-            {key: value for key, value in info.items() if value is not None}
+        expected = (
+            generate_prompt_hash(negative_text) if negative_text.strip() else None
         )
-        changed = False
-        if existing:
-            image_id = existing["id"]
-            updates = {
-                key: value for key, value in snapshots.items() if existing[key] != value
-            }
-            if updates:
-                conn.execute(
-                    "UPDATE generated_images SET "
-                    + ",".join(f"{key}=?" for key in updates)
-                    + " WHERE id=?",
-                    [*updates.values(), image_id],
-                )
-                changed = True
-        else:
-            columns = ["prompt_id", "image_path", "filename", "file_path", *snapshots]
-            values = [
-                pair["positive_prompt_id"],
-                image_path,
-                os.path.basename(image_path),
-                normalized,
-                *snapshots.values(),
+        if any(row["negative_hash"] != expected for row in prior):
+            return _conflict()
+    prior_pair = conn.execute(
+        "SELECT pp.id FROM prompt_pairs pp "
+        "JOIN prompts p ON p.id=pp.positive_prompt_id "
+        "LEFT JOIN prompts n ON n.id=pp.negative_prompt_id "
+        "WHERE p.hash=? AND n.hash IS ?",
+        (
+            generate_prompt_hash(positive_text),
+            generate_prompt_hash(negative_text) if negative_text.strip() else None,
+        ),
+    ).fetchone()
+    pair_id = db._save_pair(conn, positive_text, negative_text)
+    pair = conn.execute("SELECT * FROM prompt_pairs WHERE id=?", (pair_id,)).fetchone()
+    pairs_added = int(prior_pair is None)
+    file_size, width, height, image_format = _coerce_file_info(metadata)
+    # ComfyUI's NaN/Infinity are stored as null: the snapshot is strict JSON.
+    snapshots = {
+        column: dumps_strict(metadata[key], sort_keys=True)
+        for column, key in (
+            ("workflow_data", "workflow"),
+            ("prompt_metadata", "prompt"),
+            ("parameters", "parameters"),
+        )
+        if key in metadata
+    }
+    info = {
+        "file_size": file_size,
+        "width": width,
+        "height": height,
+        "format": image_format,
+    }
+    snapshots.update({key: value for key, value in info.items() if value is not None})
+    changed = False
+    if existing:
+        image_id = existing["id"]
+        # Compared as stored text, whichever form the row is in.
+        current = resolve_image_row(DocumentReader(conn), existing)
+        updates = {
+            key: value for key, value in snapshots.items() if current[key] != value
+        }
+        if updates:
+            replaced = [
+                existing[reference]
+                for column, reference in TEXT_COLUMNS
+                if column in updates
             ]
-            image_id = conn.execute(
-                "INSERT INTO generated_images("
-                + ",".join(columns)
-                + ") VALUES("
-                + ",".join("?" for _ in columns)
-                + ")",
-                values,
-            ).lastrowid
-        linked = conn.execute(
-            "SELECT 1 FROM image_prompt_pairs WHERE pair_id=? "
-            "AND image_id=? AND provenance=?",
-            (pair_id, image_id, encoded),
-        ).fetchone()
-        db._link_image_to_pair(conn, pair_id, image_id, provenance)
-        status = (
-            "added"
-            if existing is None
-            else "enriched" if changed or not linked else "unchanged"
-        )
-        return {
-            "status": status,
-            "pairs_added": pairs_added,
-            "links_added": int(not linked),
-            "pair_id": pair_id,
-            "image_id": image_id,
-        }
+            updates = _document_form(conn, updates)
+            conn.execute(
+                "UPDATE generated_images SET "
+                + ",".join(f"{key}=?" for key in updates)
+                + " WHERE id=?",
+                [*updates.values(), image_id],
+            )
+            release_documents(conn, replaced)
+            changed = True
+    else:
+        stored = _document_form(conn, snapshots)
+        columns = ["prompt_id", "image_path", "filename", "file_path", *stored]
+        values = [
+            pair["positive_prompt_id"],
+            image_path,
+            os.path.basename(image_path),
+            normalized,
+            *stored.values(),
+        ]
+        image_id = conn.execute(
+            "INSERT INTO generated_images("
+            + ",".join(columns)
+            + ") VALUES("
+            + ",".join("?" for _ in columns)
+            + ")",
+            values,
+        ).lastrowid
+    linked = conn.execute(
+        "SELECT 1 FROM image_prompt_pairs WHERE pair_id=? "
+        "AND image_id=? AND provenance=?",
+        (pair_id, image_id, encoded),
+    ).fetchone()
+    db._link_image_to_pair(conn, pair_id, image_id, provenance)
+    status = (
+        "added"
+        if existing is None
+        else "enriched" if changed or not linked else "unchanged"
+    )
+    return {
+        "status": status,
+        "pairs_added": pairs_added,
+        "links_added": int(not linked),
+        "pair_id": pair_id,
+        "image_id": image_id,
+    }
+
+
+def _document_form(conn: Any, values: Dict[str, Any]) -> Dict[str, Any]:
+    """``values`` with the workflow and prompt graph texts stored once.
+
+    Each of those columns becomes NULL beside its document id (new form);
+    every other column is unchanged.
+    """
+    texts = {
+        column: values[column]
+        for column, _reference in TEXT_COLUMNS
+        if column in values
+    }
+    rest = {key: value for key, value in values.items() if key not in texts}
+    return {**rest, **stored_values(conn, texts)}

database/restore_stage.py

@@ -0,0 +1,365 @@
+"""A restore in two steps: stage the upload, then publish it (#249 System S8).
+
+**Stage** (``stage_restore``) never touches the live database or the source.
+In a new folder ``.pm-restore-*`` in the library's own folder (#318: never
+the system temp folder, which may be another disk), it:
+
+1. checks the source (``verify_database_file`` without reading every
+   workflow document: a damaged one is repaired below, not refused);
+2. copies it with SQLite's backup API (a rollback-journal file and a WAL file
+   alike) and opens the copy as a ``PromptModel``, which migrates an older
+   schema;
+3. repairs damaged workflow documents (``repair_damaged_documents``),
+   rotates the history epoch and counts what the copy holds;
+4. makes the copy one self-contained file and verifies it fully (every
+   current table, every document);
+5. records the copy's SHA-256, so publishing binds exactly these bytes.
+
+**Publish** (``publish_staged``) re-hashes the stage (``StageChanged`` if it
+differs), keeps the current database as a uniquely named, standalone safety
+backup beside it (``database/safety_backup.py``; not verified, because the
+database being replaced may be the damaged one), copies the stage over the
+live pages through the backup API (no file is swapped under open handles; an
+``OperationalError`` there leaves the live data intact, #226), then
+checkpoints the WAL with TRUNCATE so the copied pages do not leave a
+database-sized ``-wal`` behind. A reader that keeps a snapshot past the busy
+wait is logged, not fatal: the restore itself is done.
+
+Every handle on the stage is closed before its folder is removed (Windows).
+``sweep_restore_temps`` removes what an interrupted restore left (startup).
+"""
+
+import hashlib
+import logging
+import os
+import sqlite3
+import tempfile
+from contextlib import closing
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, Optional
+
+from . import workflow_documents as wd
+from .execution_history_schema import rotate_history_epoch
+from .safety_backup import take_safety_backup
+
+logger = logging.getLogger("prompt_manager.database.restore_stage")
+
+STAGE_PREFIX = ".pm-restore-"
+UPLOAD_PREFIX = ".pm-restore-upload-"
+STAGED_NAME = "staged.db"
+# How long the post-restore TRUNCATE checkpoint waits for readers to leave.
+CHECKPOINT_BUSY_MS = 30_000
+_HASH_CHUNK = 1024 * 1024
+SUMMARY_KEYS = (
+    "prompts",
+    "positives",
+    "pairs",
+    "archived_pairs",
+    "image_links",
+    "runs",
+    "saved_views",
+)
+
+
+class StageChanged(ValueError):
+    """The staged file is no longer the bytes that were reviewed."""
+
+
+@dataclass
+class StagedRestore:
+    """A verified, migrated copy of an upload, ready to publish."""
+
+    path: str
+    digest: str
+    size: int
+    summary: Dict[str, int]
+    schema: Dict[str, bool]
+    documents: Dict[str, int] = field(
+        default_factory=lambda: {"repaired": 0, "cleared": 0, "images": 0}
+    )
+
+    @property
+    def directory(self) -> str:
+        return os.path.dirname(self.path)
+
+    def discard(self) -> None:
+        """Remove the stage folder (idempotent; its handles are all closed)."""
+        remove_stage_folder(self.directory)
+
+
+def remove_stage_folder(directory: str) -> None:
+    """Remove a stage folder and its files, logging what cannot be removed."""
+    if not directory or not os.path.isdir(directory):
+        return
+    for name in os.listdir(directory):
+        try:
+            os.remove(os.path.join(directory, name))
+        except OSError as error:
+            logger.warning(f"Could not remove restore stage file {name}: {error}")
+    try:
+        os.rmdir(directory)
+    except OSError as error:
+        logger.warning(f"Could not remove the restore stage folder: {error}")
+
+
+def file_digest(path: str) -> str:
+    """``sha256:<hex>`` of the file's bytes (blocking)."""
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        for chunk in iter(lambda: handle.read(_HASH_CHUNK), b""):
+            digest.update(chunk)
+    return "sha256:" + digest.hexdigest()
+
+
+def _readonly(path: str) -> sqlite3.Connection:
+    return sqlite3.connect(Path(path).resolve().as_uri() + "?mode=ro", uri=True)
+
+
+def _schema(path: str) -> list:
+    """The file's schema objects, to tell whether staging migrated it."""
+    with closing(_readonly(path)) as conn:
+        return sorted(
+            conn.execute(
+                "SELECT type, name, tbl_name, sql FROM sqlite_master "
+                "WHERE name NOT LIKE 'sqlite_%'"
+            ).fetchall(),
+            key=repr,
+        )
+
+
+def _count(conn: sqlite3.Connection, table: str, where: str = "") -> int:
+    exists = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (table,)
+    ).fetchone()
+    if not exists:
+        return 0
+    # ``table`` and ``where`` are constants of library_summary, never input.
+    return conn.execute(f"SELECT COUNT(*) FROM {table} {where}").fetchone()[0]  # nosec
+
+
+def library_summary(conn: sqlite3.Connection) -> Dict[str, int]:
+    """What a library holds, for a restore's review (reads only).
+
+    ``positives`` are the Library's prompts (``library_counts``'s
+    ``positive_prompts``); ``pairs`` the active saved pairs and
+    ``archived_pairs`` the archived ones; ``image_links`` the indexed image
+    rows; ``runs`` the recorded executions.
+    """
+    from .library import _ELIGIBLE
+
+    has_state = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND "
+        "name='prompt_library_state'"
+    ).fetchone()
+    has_pairs = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name='prompt_pairs'"
+    ).fetchone()
+    if has_state and has_pairs:
+        positives = conn.execute(
+            "SELECT COUNT(*) FROM prompts p WHERE " + _ELIGIBLE
+        ).fetchone()[0]
+    else:
+        positives = _count(conn, "prompts")
+    return {
+        "prompts": _count(conn, "prompts"),
+        "positives": positives,
+        "pairs": _count(conn, "prompt_pairs", "WHERE archived=0"),
+        "archived_pairs": _count(conn, "prompt_pairs", "WHERE archived<>0"),
+        "image_links": _count(conn, "generated_images"),
+        "runs": _count(conn, "execution_runs"),
+        "saved_views": _count(conn, "saved_views"),
+    }
+
+
+# The newest row of each table a restore would overwrite: with the counts,
+# a write after the review (a new run, image, prompt or edit) changes it.
+_FINGERPRINT_SQL = (
+    ("prompts", "SELECT MAX(id), MAX(updated_at), MAX(last_used_at) FROM prompts"),
+    ("generated_images", "SELECT MAX(id) FROM generated_images"),
+    ("prompt_pairs", "SELECT MAX(id), MAX(updated_at) FROM prompt_pairs"),
+    ("execution_runs", "SELECT COUNT(*), MAX(rowid) FROM execution_runs"),
+    ("saved_views", "SELECT MAX(rowid) FROM saved_views"),
+)
+
+
+def live_fingerprint(conn: sqlite3.Connection):
+    """``(summary, fingerprint)`` of a live library, read in one snapshot.
+
+    The fingerprint changes when rows are added to or removed from the
+    tables a restore replaces, or when a prompt, pair, run or saved view is
+    the newest edited (counts plus the newest row and edit of each table);
+    the apply refuses with ``plan-changed`` then. It does not see every
+    edit (a tag or favorite change on an older row); those are kept in the
+    restore's safety backup. A read transaction the caller already has is
+    used and left open; one opened here is ended here.
+    """
+    import json
+
+    opened = not conn.in_transaction
+    if opened:
+        conn.execute("BEGIN")  # one read snapshot for every count
+    try:
+        summary = library_summary(conn)
+        newest = []
+        for table, sql in _FINGERPRINT_SQL:
+            try:
+                newest.append([table, list(conn.execute(sql).fetchone())])
+            except sqlite3.OperationalError:
+                newest.append([table, None])  # no such table or column
+    finally:
+        if opened:
+            conn.rollback()  # it only read
+    text = json.dumps([summary, newest], sort_keys=True, default=str)
+    return summary, "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _copy(src_path: str, staged_path: str) -> None:
+    source = _readonly(src_path)
+    try:
+        with closing(sqlite3.connect(staged_path)) as destination:
+            source.backup(destination)
+    finally:
+        source.close()
+
+
+def _standalone(path: str) -> None:
+    with closing(sqlite3.connect(path)) as conn:
+        conn.execute("PRAGMA journal_mode=DELETE").fetchone()
+
+
+def stage_restore(model_cls, db_path: str, src_path: str) -> StagedRestore:
+    """Stage ``src_path`` beside ``db_path`` (blocking); see the module docstring.
+
+    Raises ValueError with a readable reason when the source or the migrated
+    stage does not verify; the stage folder is then already removed.
+    """
+    ok, reason = model_cls.verify_database_file(src_path, documents=False)
+    if not ok:
+        raise ValueError(reason)
+    before = _schema(src_path)
+    with closing(_readonly(src_path)) as conn:
+        library_state = bool(
+            conn.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' AND "
+                "name='prompt_library_state'"
+            ).fetchone()
+        )
+    folder = os.path.dirname(os.path.abspath(db_path))
+    directory = tempfile.mkdtemp(prefix=STAGE_PREFIX, dir=folder)
+    staged_path = os.path.join(directory, STAGED_NAME)
+    staged_key = os.path.normcase(os.path.realpath(staged_path))
+    try:
+        _copy(src_path, staged_path)
+        staged = None
+        try:
+            staged = model_cls(staged_path)
+            conn = staged.get_connection()
+            documents = wd.repair_damaged_documents(conn)
+            rotate_history_epoch(conn)
+            summary = library_summary(conn)
+        finally:
+            if staged is not None:
+                staged.close_all()
+        _standalone(staged_path)
+        ok, reason = model_cls.verify_database_file(
+            staged_path, require_library_state=True
+        )
+        if not ok:
+            raise ValueError(reason)
+        result = StagedRestore(
+            path=staged_path,
+            digest=file_digest(staged_path),
+            size=os.path.getsize(staged_path),
+            summary=summary,
+            schema={
+                "migrated": _schema(staged_path) != before,
+                "library_state": library_state,
+            },
+            documents=documents,
+        )
+    except BaseException:
+        remove_stage_folder(directory)
+        raise
+    finally:
+        with model_cls._init_lock:
+            model_cls._initialized_paths.discard(staged_key)
+    return result
+
+
+def checkpoint_truncate(conn: sqlite3.Connection) -> bool:
+    """Checkpoint the WAL and truncate it to 0 bytes; False when a reader held it."""
+    previous = conn.execute("PRAGMA busy_timeout").fetchone()[0]
+    try:
+        conn.execute(f"PRAGMA busy_timeout = {int(CHECKPOINT_BUSY_MS)}")
+        busy = conn.execute("PRAGMA wal_checkpoint(TRUNCATE)").fetchone()[0]
+    finally:
+        conn.execute(f"PRAGMA busy_timeout = {int(previous)}")
+    return not busy
+
+
+def publish_staged(model, staged: StagedRestore) -> str:
+    """Publish ``staged`` over ``model``'s database; return the safety backup path.
+
+    "" when there was no database to back up. Raises StageChanged before
+    anything is written when the stage's bytes changed since staging, and
+    SafetyBackupFailed when the current database could not be kept. An
+    ``OperationalError`` from the page copy propagates with
+    ``_prompt_manager_restore_backup_created`` set; the live data is intact.
+    """
+    if not os.path.isfile(staged.path) or file_digest(staged.path) != staged.digest:
+        raise StageChanged("The staged restore changed since it was reviewed")
+    backup_path = ""
+    if os.path.exists(model.db_path):
+        backup_path = take_safety_backup(model, verify=False)
+        logger.info(f"Current database backed up to: {os.path.basename(backup_path)}")
+    try:
+        model._replace_contents_from(staged.path)
+    except sqlite3.OperationalError as exc:
+        exc._prompt_manager_restore_backup_created = bool(backup_path)
+        raise
+    with model._init_lock:
+        model._initialized_paths.add(model._schema_key())
+    _truncate_wal(model)
+    return backup_path
+
+
+def _truncate_wal(model) -> Optional[bool]:
+    """TRUNCATE-checkpoint the live WAL after a publish (never raises)."""
+    try:
+        conn = model.get_connection()
+        with conn.using():
+            truncated = checkpoint_truncate(conn)
+    except sqlite3.Error as error:
+        logger.warning(f"The database log could not be truncated: {error}")
+        return None
+    if not truncated:
+        logger.warning(
+            "The database log could not be truncated after the restore: a "
+            "reader kept it open. It shrinks at the next checkpoint with no "
+            "reader."
+        )
+    return truncated
+
+
+def sweep_restore_temps(db_path: str) -> list:
+    """Remove the stages and uploads an interrupted restore left (startup)."""
+    folder = os.path.dirname(os.path.abspath(db_path))
+    removed = []
+    try:
+        names = os.listdir(folder)
+    except OSError:
+        return removed
+    for name in names:
+        path = os.path.join(folder, name)
+        if name.startswith(UPLOAD_PREFIX) and os.path.isfile(path):
+            try:
+                os.remove(path)
+                removed.append(name)
+            except OSError:
+                continue
+        elif name.startswith(STAGE_PREFIX) and os.path.isdir(path):
+            remove_stage_folder(path)
+            if not os.path.exists(path):
+                removed.append(name)
+    return removed

database/review.py

@@ -0,0 +1,648 @@
+"""Needs review items (#249): persist and read capture-bound ambiguous evidence.
+
+An item is one ambiguous resolver result for one annotation byte record (the
+whole-file SHA-256 of one physical file at one locator), keyed by
+``(byte_id, resolver_version, evidence_hash)``. Recording is idempotent: the
+same evidence for the same bytes is a duplicate and never touches an existing
+item, its state, revision or decisions. Changed bytes are a new byte record
+and therefore a new pending item; the old one stays.
+
+Callers pass verified facts (the capture's digest, size and ``mtime_ns``);
+nothing here reads the filesystem. Writes run in one ``_pair_transaction``
+fenced by the storage epoch the capture was taken under.
+"""
+
+import hashlib
+import json
+import os
+import re
+import sqlite3
+from typing import Iterator
+
+try:
+    from ..utils.hashing import generate_prompt_hash
+except ImportError:
+    from utils.hashing import generate_prompt_hash
+
+from .annotation_schema import (
+    BYTES_TABLE,
+    FILES_TABLE,
+    METADATA_TABLE as ANNOTATION_METADATA_TABLE,
+)
+from .annotations import _new_id, _validate_locator, _validate_target
+from .models import normalize_image_path, utc_now_iso
+from .review_changes import notify_review_change
+from .review_schema import (
+    DECISIONS_TABLE,
+    ITEMS_TABLE,
+    MAX_CANDIDATES,
+    MAX_SPELLED_PATH_BYTES,
+    METADATA_TABLE,
+    canonical_evidence,
+    evidence_digest,
+    evidence_offers_choice,
+)
+
+# Only this module's table constants are interpolated into the SQL below.
+_INSERT_ITEM = (
+    f"INSERT OR IGNORE INTO {ITEMS_TABLE}(id,byte_id,spelled_path,"  # nosec B608
+    "resolver_version,evidence_hash,evidence,candidate_count,limited,state,"
+    "revision,created_at,updated_at) VALUES(?,?,?,?,?,?,?,?,'pending',0,?,?)"
+)
+_BUMP_REVIEW_INDEX = (
+    f"UPDATE {METADATA_TABLE} SET "  # nosec B608
+    "review_index_revision=review_index_revision+1 WHERE singleton_id=1"
+)
+# A later spelling of the same locator (a case-only rename on a case-folding
+# filesystem) replaces the recorded one, so targets keep formatting.
+_REFRESH_SPELLING = (
+    f"UPDATE {ITEMS_TABLE} SET spelled_path=? "  # nosec B608
+    f"WHERE spelled_path<>? AND byte_id IN (SELECT b.id FROM {BYTES_TABLE} b "
+    f"JOIN {FILES_TABLE} f ON f.id=b.file_id WHERE f.locator=?)"
+)
+_REVIEW_INDEX = (
+    f"SELECT review_index_revision FROM {METADATA_TABLE} "  # nosec B608
+    "WHERE singleton_id=1"
+)
+_BUMP_IMAGE_INDEX = (
+    f"UPDATE {ANNOTATION_METADATA_TABLE} SET "  # nosec B608
+    "image_index_revision=image_index_revision+1 WHERE singleton_id=1"
+)
+_ITEMS_OF_LOCATOR = (
+    "SELECT i.id,i.byte_id,i.resolver_version,i.evidence_hash,"  # nosec B608
+    "i.evidence,i.candidate_count,i.limited,i.state,i.revision,i.created_at,"
+    f"i.updated_at,b.sha256 FROM {FILES_TABLE} f "
+    f"JOIN {BYTES_TABLE} b ON b.file_id=f.id "
+    f"JOIN {ITEMS_TABLE} i ON i.byte_id=b.id "
+    "WHERE f.locator=? ORDER BY i.created_at,i.id"
+)
+_QUEUED = (
+    f"SELECT 1 FROM {FILES_TABLE} f "  # nosec B608
+    f"JOIN {BYTES_TABLE} b ON b.file_id=f.id "
+    f"JOIN {ITEMS_TABLE} i ON i.byte_id=b.id "
+    "WHERE f.locator=? AND b.size=? AND b.mtime_ns=? AND i.resolver_version=? "
+    "LIMIT 1"
+)
+_PENDING_AT = (
+    f"SELECT 1 FROM {FILES_TABLE} f "  # nosec B608
+    f"JOIN {BYTES_TABLE} b ON b.file_id=f.id "
+    f"JOIN {ITEMS_TABLE} i ON i.byte_id=b.id "
+    "WHERE f.locator=? AND b.size=? AND b.mtime_ns=? AND i.resolver_version=? "
+    "AND i.state='pending' LIMIT 1"
+)
+# Bytes verified at this stat whose item carries a decision (any version).
+_DECIDED_AT = (
+    f"SELECT 1 FROM {FILES_TABLE} f "  # nosec B608
+    f"JOIN {BYTES_TABLE} b ON b.file_id=f.id "
+    f"JOIN {ITEMS_TABLE} i ON i.byte_id=b.id "
+    "WHERE f.locator=? AND b.size=? AND b.mtime_ns=? "
+    "AND (i.state<>'pending' OR i.revision<>0 OR EXISTS (SELECT 1 FROM "
+    f"{DECISIONS_TABLE} d WHERE d.item_id=i.id)) LIMIT 1"
+)
+# The other items of one byte record (another version or evidence), with
+# whether each may be superseded: pending, revision 0, no decision row.
+_OTHER_ITEMS_OF_BYTES = (
+    "SELECT i.id, (i.state='pending' AND i.revision=0 AND NOT EXISTS "  # nosec B608
+    f"(SELECT 1 FROM {DECISIONS_TABLE} d WHERE d.item_id=i.id)) "
+    f"FROM {ITEMS_TABLE} i WHERE i.byte_id=? "
+    "AND NOT (i.resolver_version=? AND i.evidence_hash=?)"
+)
+# Pending items of the bytes verified at one stat, with their versions.
+_PENDING_AT_STAT = (
+    f"SELECT i.id,i.resolver_version FROM {FILES_TABLE} f "  # nosec B608
+    f"JOIN {BYTES_TABLE} b ON b.file_id=f.id "
+    f"JOIN {ITEMS_TABLE} i ON i.byte_id=b.id "
+    "WHERE f.locator=? AND b.size=? AND b.mtime_ns=? AND i.state='pending'"
+)
+# Pending items of one file: the candidates a link settles.
+_PENDING_OF_LOCATOR = (
+    f"SELECT i.id FROM {FILES_TABLE} f "  # nosec B608
+    f"JOIN {BYTES_TABLE} b ON b.file_id=f.id "
+    f"JOIN {ITEMS_TABLE} i ON i.byte_id=b.id "
+    "WHERE f.locator=? AND i.state='pending'"
+)
+# Pending items of one file with their evidence: an untraced file's settle.
+_PENDING_EVIDENCE_OF_LOCATOR = (
+    f"SELECT i.id,i.evidence FROM {FILES_TABLE} f "  # nosec B608
+    f"JOIN {BYTES_TABLE} b ON b.file_id=f.id "
+    f"JOIN {ITEMS_TABLE} i ON i.byte_id=b.id "
+    "WHERE f.locator=? AND i.state='pending'"
+)
+# Only an undecided item goes: a decision row (RESTRICT) is never deleted.
+_SETTLE_ITEM = (
+    f"DELETE FROM {ITEMS_TABLE} WHERE id=? AND state='pending' "  # nosec B608
+    f"AND revision=0 AND NOT EXISTS (SELECT 1 FROM {DECISIONS_TABLE} d "
+    f"WHERE d.item_id={ITEMS_TABLE}.id)"
+)
+_EPOCH = "SELECT storage_epoch FROM execution_history_metadata WHERE singleton_id=1"
+_PENDING_COUNT = (
+    f"SELECT COUNT(*) FROM {ITEMS_TABLE} WHERE state='pending'"  # nosec B608
+)
+_QUEUE_COLUMNS = (
+    "id",
+    "state",
+    "revision",
+    "created_at",
+    "candidate_count",
+    "limited",
+    "spelled_path",
+    "locator",
+)
+_QUEUE_SELECT = (
+    "SELECT i.id,i.state,i.revision,i.created_at,i.candidate_count,"  # nosec B608
+    f"i.limited,i.spelled_path,f.locator FROM {ITEMS_TABLE} i "
+    f"JOIN {BYTES_TABLE} b ON b.id=i.byte_id "
+    f"JOIN {FILES_TABLE} f ON f.id=b.file_id "
+)
+_QUEUE_FIRST = _QUEUE_SELECT + (
+    "WHERE i.state='pending' ORDER BY i.created_at,i.id LIMIT ?"
+)
+_QUEUE_AFTER = _QUEUE_SELECT + (
+    "WHERE i.state='pending' AND (i.created_at,i.id)>(?,?) "
+    "ORDER BY i.created_at,i.id LIMIT ?"
+)
+_DETAIL_COLUMNS = _QUEUE_COLUMNS + (
+    "byte_id",
+    "resolver_version",
+    "evidence_hash",
+    "evidence",
+    "updated_at",
+    "sha256",
+)
+_DETAIL = (
+    "SELECT i.id,i.state,i.revision,i.created_at,i.candidate_count,"  # nosec B608
+    "i.limited,i.spelled_path,f.locator,i.byte_id,i.resolver_version,"
+    "i.evidence_hash,i.evidence,i.updated_at,b.sha256 "
+    f"FROM {ITEMS_TABLE} i JOIN {BYTES_TABLE} b ON b.id=i.byte_id "
+    f"JOIN {FILES_TABLE} f ON f.id=b.file_id WHERE i.id=?"
+)
+# The legacy rows and pair links the ingester's compatibility rules read.
+_DEPENDENT_IMAGES = (
+    "SELECT gi.id,p.hash,gi.image_path FROM generated_images gi "
+    "JOIN prompts p ON p.id=gi.prompt_id "
+    "WHERE gi.file_path=? OR gi.image_path=? ORDER BY gi.id"
+)
+_DEPENDENT_LINKS = (
+    "SELECT DISTINCT ip.pair_id,n.hash FROM image_prompt_pairs ip "
+    "JOIN prompt_pairs pp ON pp.id=ip.pair_id "
+    "LEFT JOIN prompts n ON n.id=pp.negative_prompt_id "
+    "WHERE ip.image_id=? ORDER BY ip.pair_id"
+)
+# Rows whose spelling ends with the file's name: the candidates for another
+# spelling of the same physical file (the link summaries' filename fallback).
+_SAME_NAME_ROWS = (
+    "SELECT id,image_path FROM generated_images "
+    "WHERE image_path LIKE ? ESCAPE '\\' ORDER BY id"
+)
+_TITLES = (
+    "SELECT p.hash,s.title FROM prompts p "
+    "JOIN prompt_library_state s ON s.prompt_id=p.id "
+    "WHERE p.hash IN ({marks}) AND s.title IS NOT NULL ORDER BY p.id"
+)
+_ITEM_ID = re.compile(r"[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}")
+_ITEM_COLUMNS = (
+    "id",
+    "byte_id",
+    "resolver_version",
+    "evidence_hash",
+    "evidence",
+    "candidate_count",
+    "limited",
+    "state",
+    "revision",
+    "created_at",
+    "updated_at",
+    "sha256",
+)
+
+
+def _validate_spelling(spelled_path: object, locator: str) -> None:
+    if (
+        not isinstance(spelled_path, str)
+        or not spelled_path
+        or len(spelled_path.encode("utf-8", "surrogatepass")) > MAX_SPELLED_PATH_BYTES
+        or os.path.normcase(spelled_path) != locator
+    ):
+        raise ValueError("spelled_path must be the file's spelling of its locator")
+
+
+def dependent_images(conn: sqlite3.Connection, spellings) -> list:
+    """``(id, image_path, positive_hash)`` of every legacy row of the file.
+
+    ``spellings`` are the paths the file is linked under (the Apply path and
+    every alias of the same physical file); each is matched as the ingester
+    matches one path. Rows are distinct and ordered by id.
+    """
+    found = {}
+    for spelled in dict.fromkeys(spellings):
+        for row in conn.execute(
+            _DEPENDENT_IMAGES, (normalize_image_path(spelled), spelled)
+        ):
+            found[row[0]] = (row[0], row[2], row[1])
+    return [found[key] for key in sorted(found)]
+
+
+def same_name_rows(conn: sqlite3.Connection, name: str) -> list:
+    """``(id, image_path)`` of rows whose spelling may end with ``name``."""
+    # Imported here: operations composes this module's mixin.
+    from .operations import escape_like
+
+    return [
+        (row[0], row[1])
+        for row in conn.execute(_SAME_NAME_ROWS, (f"%{escape_like(name)}",))
+    ]
+
+
+def dependency_fingerprint(
+    conn: sqlite3.Connection, image_path: str, aliases=()
+) -> str:
+    """SHA-256 of what Apply's compatibility depends on for ``image_path``.
+
+    The exact legacy rows of the file under ``image_path`` and every alias
+    spelling of it, with their positive hashes, and each row's pair links
+    with the negative hash, read as the ingester reads them. Unrelated prompt
+    changes (tags, titles) do not move it.
+    """
+    rows = []
+    for image_id, _spelled, positive_hash in dependent_images(
+        conn, (image_path, *aliases)
+    ):
+        links = conn.execute(_DEPENDENT_LINKS, (image_id,)).fetchall()
+        rows.append([image_id, positive_hash, [list(link) for link in links]])
+    text = canonical_evidence({"v": 1, "images": rows})
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+class ReviewOperations:
+    """PromptDatabase mixin: insert and read Needs review items."""
+
+    def record_review_item(
+        self,
+        *,
+        locator: str,
+        spelled_path: str,
+        sha256: str,
+        size: int,
+        mtime_ns: int,
+        epoch: str,
+        resolver_version: int,
+        evidence: dict,
+        candidate_count: int,
+        limited: bool,
+    ) -> bool:
+        """Store one ambiguous result for these exact bytes; True when new.
+
+        The byte record is created (or its verified fingerprint refreshed)
+        like an observe. ``spelled_path`` is the file's own spelling (it must
+        fold to ``locator``); targets are formatted from it. Raises
+        ``LibraryCommandError("storage-changed")`` when the storage epoch is
+        no longer ``epoch`` (a restore since the capture) and ``ValueError``
+        for invalid facts or evidence.
+
+        One file never holds two pending items for the same bytes: the new
+        item supersedes the byte record's other items (an older resolver or
+        semantics version) when every one is pending and undecided (the safe
+        delete of the self-heal); when one carries a decision or a later
+        revision, it is kept and nothing new is stored (False).
+        """
+        _validate_target(locator, sha256, size, mtime_ns)
+        _validate_spelling(spelled_path, locator)
+        if type(resolver_version) is not int or resolver_version < 1:
+            raise ValueError("resolver_version must be a positive integer")
+        if (
+            type(candidate_count) is not int
+            or not 0 <= candidate_count <= MAX_CANDIDATES
+        ):
+            raise ValueError(f"candidate_count must be between 0 and {MAX_CANDIDATES}")
+        if not isinstance(limited, bool) or (limited and candidate_count):
+            raise ValueError("A limited item carries no candidates")
+        text = canonical_evidence(evidence)
+        evidence_hash = evidence_digest(text)
+        with self._pair_transaction() as conn:
+            self._library_epoch(conn, epoch)
+            now = utc_now_iso()
+            file_id = self._annotation_owner(conn, locator, now)
+            byte_id, _revision, created, moved = self._annotation_byte(
+                conn, file_id, sha256, size, mtime_ns, now
+            )
+            if created or moved:
+                conn.execute(_BUMP_IMAGE_INDEX)
+            # The byte record is created or refreshed even when the item is
+            # refused below (an observe would do the same); that commits
+            # with the image index bump, and the review queue is unchanged.
+            others = conn.execute(
+                _OTHER_ITEMS_OF_BYTES, (byte_id, resolver_version, evidence_hash)
+            ).fetchall()
+            if any(not removable for _id, removable in others):
+                return False
+            superseded = sum(
+                conn.execute(_SETTLE_ITEM, (item_id,)).rowcount
+                for item_id, _removable in others
+            )
+            cursor = conn.execute(
+                _INSERT_ITEM,
+                (
+                    _new_id(),
+                    byte_id,
+                    spelled_path,
+                    resolver_version,
+                    evidence_hash,
+                    text,
+                    candidate_count,
+                    int(limited),
+                    now,
+                    now,
+                ),
+            )
+            inserted = cursor.rowcount > 0
+            refreshed = _refresh_spelling(conn, locator, spelled_path)
+            if inserted or refreshed or superseded:
+                conn.execute(_BUMP_REVIEW_INDEX)
+        if inserted or refreshed or superseded:
+            notify_review_change(self.model.db_path)
+        return inserted
+
+    def refresh_review_spelling(self, locator: str, spelled_path: str) -> bool:
+        """Record ``spelled_path`` as the spelling of every item at ``locator``.
+
+        The rescan's skip calls it for a file it does not copy again: a
+        case-only rename keeps size and ``mtime_ns``, and a target formatted
+        from the old spelling would be refused. True when a spelling changed
+        (the review index revision moves; item revisions do not, so an open
+        decision stays valid).
+        """
+        _validate_locator(locator)
+        _validate_spelling(spelled_path, locator)
+        with self._pair_transaction() as conn:
+            refreshed = _refresh_spelling(conn, locator, spelled_path)
+            if refreshed:
+                conn.execute(_BUMP_REVIEW_INDEX)
+        if refreshed:
+            notify_review_change(self.model.db_path)
+        return refreshed
+
+    def review_index_revision(self) -> int:
+        """The queue's revision (moved by every queue change)."""
+        row = self.model.get_connection().execute(_REVIEW_INDEX).fetchone()
+        if row is None:
+            raise sqlite3.DatabaseError("Missing review queue metadata")
+        return row[0]
+
+    def review_queue_version(self) -> dict:
+        """``{library_epoch, review_revision}`` of the queue, from one snapshot.
+
+        The pair a list read answers: equal pairs mean the same queue (a
+        restore moves the epoch, every queue change moves the revision).
+        """
+        with self._annotation_read() as conn:
+            epoch = conn.execute(_EPOCH).fetchone()
+            revision = conn.execute(_REVIEW_INDEX).fetchone()
+        if epoch is None or revision is None:
+            raise sqlite3.DatabaseError("Missing review queue metadata")
+        return {"library_epoch": epoch[0], "review_revision": revision[0]}
+
+    def review_items_for(self, locator: str) -> list:
+        """Every item of the file at ``locator``, oldest first, evidence parsed."""
+        _validate_locator(locator)
+        return list(self._iter_review_items(locator))
+
+    def _iter_review_items(self, locator: str) -> Iterator[dict]:
+        conn = self.model.get_connection()
+        for row in conn.execute(_ITEMS_OF_LOCATOR, (locator,)):
+            item = dict(zip(_ITEM_COLUMNS, tuple(row)))
+            item["evidence"] = json.loads(item["evidence"])
+            item["limited"] = bool(item["limited"])
+            yield item
+
+    # -- queue reads (#249 E3) -------------------------------------------------
+
+    def review_fingerprint_queued(
+        self, locator: str, size: int, mtime_ns: int, resolver_version: int
+    ) -> bool:
+        """True when an item cites a byte record verified at this exact stat.
+
+        A rescan uses it to skip the copy and hash of a file it already
+        queued: the same ``(size, mtime_ns)`` the bytes were verified with.
+        """
+        row = (
+            self.model.get_connection()
+            .execute(_QUEUED, (locator, size, mtime_ns, resolver_version))
+            .fetchone()
+        )
+        return row is not None
+
+    def review_decided_at(self, locator: str, size: int, mtime_ns: int) -> bool:
+        """True when bytes verified at this stat carry a decided item.
+
+        Any version: a newer resolver or table never adds an item beside a
+        decision, so the rescan need not copy those bytes again.
+        """
+        row = (
+            self.model.get_connection()
+            .execute(_DECIDED_AT, (locator, size, mtime_ns))
+            .fetchone()
+        )
+        return row is not None
+
+    def review_pending_at(
+        self, locator: str, size: int, mtime_ns: int, resolver_version: int
+    ) -> bool:
+        """True when a *pending* item cites bytes verified at this exact stat.
+
+        ``review_fingerprint_queued`` also matches decided items; a file whose
+        only item is decided is not in the queue.
+        """
+        row = (
+            self.model.get_connection()
+            .execute(_PENDING_AT, (locator, size, mtime_ns, resolver_version))
+            .fetchone()
+        )
+        return row is not None
+
+    def review_file_linked(self, spellings) -> bool:
+        """True when a saved row links the file under any of ``spellings``."""
+        with self._annotation_read() as conn:
+            return bool(dependent_images(conn, spellings))
+
+    def settle_linked_review_items(self, files) -> int:
+        """Remove the pending, undecided items of files that are now linked.
+
+        ``files`` holds ``(locator, spellings)`` per file. An item leaves the
+        queue only when it is still ``pending`` at revision 0 with no decision
+        row and a saved row links its file under one of ``spellings``; a
+        decided item is never touched. Files without a pending item cost one
+        indexed read and open no write transaction. Returns how many items
+        were removed (the review index revision moves when any was).
+        """
+        files = [(locator, tuple(spellings)) for locator, spellings in files]
+        for locator, _spellings in files:
+            _validate_locator(locator)
+        conn = self.model.get_connection()
+        candidates = [
+            (locator, spellings)
+            for locator, spellings in files
+            if conn.execute(_PENDING_OF_LOCATOR, (locator,)).fetchone() is not None
+        ]
+        if not candidates:
+            return 0
+        removed = 0
+        with self._pair_transaction() as conn:
+            for locator, spellings in candidates:
+                if not dependent_images(conn, spellings):
+                    continue
+                for (item_id,) in conn.execute(
+                    _PENDING_OF_LOCATOR, (locator,)
+                ).fetchall():
+                    removed += conn.execute(_SETTLE_ITEM, (item_id,)).rowcount
+            if removed:
+                conn.execute(_BUMP_REVIEW_INDEX)
+        if removed:
+            notify_review_change(self.model.db_path)
+        return removed
+
+    def settle_stale_review_items(
+        self, locator: str, size: int, mtime_ns: int, versions
+    ) -> int:
+        """Remove pending, undecided items of the bytes verified at this stat
+        whose ``resolver_version`` is not one of ``versions``.
+
+        The caller found these bytes untraced under the current versions, so
+        an older version's item could only refuse Apply. The same safe delete
+        as the other settles; one indexed read when nothing is pending.
+        """
+        _validate_locator(locator)
+        current = set(versions)
+        conn = self.model.get_connection()
+        stale = [
+            item_id
+            for item_id, version in conn.execute(
+                _PENDING_AT_STAT, (locator, size, mtime_ns)
+            )
+            if version not in current
+        ]
+        if not stale:
+            return 0
+        removed = 0
+        with self._pair_transaction() as conn:
+            for item_id in stale:
+                removed += conn.execute(_SETTLE_ITEM, (item_id,)).rowcount
+            if removed:
+                conn.execute(_BUMP_REVIEW_INDEX)
+        if removed:
+            notify_review_change(self.model.db_path)
+        return removed
+
+    def settle_untraced_review_items(self, locators) -> int:
+        """Remove the pending, undecided items that offer nothing to choose.
+
+        ``locators`` are files the caller found ambiguous without a choice
+        (fewer than two candidates carry a prompt). Of their items, one leaves
+        the queue only when its own stored evidence offers no choice either
+        (``evidence_offers_choice``) and it is still ``pending`` at revision 0
+        with no decision row, the same safe delete as
+        ``settle_linked_review_items``. Files without a pending item cost one
+        indexed read and open no write transaction. Returns how many items
+        were removed (the review index revision moves when any was).
+        """
+        locators = list(locators)
+        for locator in locators:
+            _validate_locator(locator)
+        conn = self.model.get_connection()
+        pending = [
+            locator
+            for locator in locators
+            if conn.execute(_PENDING_OF_LOCATOR, (locator,)).fetchone() is not None
+        ]
+        if not pending:
+            return 0
+        removed = 0
+        with self._pair_transaction() as conn:
+            for locator in pending:
+                rows = conn.execute(_PENDING_EVIDENCE_OF_LOCATOR, (locator,)).fetchall()
+                for item_id, evidence in rows:
+                    if evidence_offers_choice(json.loads(evidence)):
+                        continue
+                    removed += conn.execute(_SETTLE_ITEM, (item_id,)).rowcount
+            if removed:
+                conn.execute(_BUMP_REVIEW_INDEX)
+        return removed
+
+    def review_queue_page(self, *, limit: int, after: tuple | None = None) -> dict:
+        """One page of pending items, oldest first, from one snapshot.
+
+        ``after`` is the ``(created_at, id)`` keyset of the last item already
+        shown. Returns ``{epoch, revision, total, items, more}``; ``total`` is
+        the exact pending count and ``items`` carry their ``spelled_path`` and
+        ``locator`` (server-side only).
+        """
+        if type(limit) is not int or limit < 1:
+            raise ValueError("limit must be a positive integer")
+        with self._annotation_read() as conn:
+            epoch = conn.execute(_EPOCH).fetchone()
+            revision = conn.execute(_REVIEW_INDEX).fetchone()
+            if epoch is None or revision is None:
+                raise sqlite3.DatabaseError("Missing review queue metadata")
+            total = conn.execute(_PENDING_COUNT).fetchone()[0]
+            if after is None:
+                rows = conn.execute(_QUEUE_FIRST, (limit + 1,)).fetchall()
+            else:
+                rows = conn.execute(_QUEUE_AFTER, (*after, limit + 1)).fetchall()
+        items = [_queue_row(row, _QUEUE_COLUMNS) for row in rows[:limit]]
+        return {
+            "epoch": epoch[0],
+            "revision": revision[0],
+            "total": total,
+            "items": items,
+            "more": len(rows) > limit,
+        }
+
+    def review_item(self, item_id: str) -> dict | None:
+        """One item with its parsed evidence and the pending total, or None."""
+        if not isinstance(item_id, str) or _ITEM_ID.fullmatch(item_id) is None:
+            return None
+        with self._annotation_read() as conn:
+            epoch = conn.execute(_EPOCH).fetchone()
+            if epoch is None:
+                raise sqlite3.DatabaseError("Missing execution history metadata")
+            row = conn.execute(_DETAIL, (item_id,)).fetchone()
+            if row is None:
+                return None
+            item = _queue_row(row, _DETAIL_COLUMNS)
+            item["evidence"] = json.loads(item["evidence"])
+            item["epoch"] = epoch[0]
+            item["total"] = conn.execute(_PENDING_COUNT).fetchone()[0]
+        return item
+
+    def review_dependency_fingerprint(self, image_path: str, aliases=()) -> str:
+        with self._annotation_read() as conn:
+            return dependency_fingerprint(conn, image_path, aliases)
+
+    def review_same_name_rows(self, name: str) -> list:
+        """``(id, image_path)`` of legacy rows that may spell a file ``name``."""
+        with self._annotation_read() as conn:
+            return same_name_rows(conn, name)
+
+    def stored_prompt_titles(self, texts) -> dict:
+        """Library titles of saved prompts by text (dedup hash), when set."""
+        hashes = {generate_prompt_hash(text): text for text in texts if text.strip()}
+        if not hashes:
+            return {}
+        marks = ",".join("?" * len(hashes))
+        found: dict[str, tuple] = {}
+        conn = self.model.get_connection()
+        for prompt_hash, title in conn.execute(
+            _TITLES.format(marks=marks), list(hashes)
+        ):
+            text = hashes[prompt_hash]
+            found[text] = found.get(text, ()) + (title,)
+        return found
+
+
+def _refresh_spelling(conn: sqlite3.Connection, locator: str, spelled: str) -> bool:
+    return conn.execute(_REFRESH_SPELLING, (spelled, spelled, locator)).rowcount > 0
+
+
+def _queue_row(row, columns) -> dict:
+    item = dict(zip(columns, tuple(row)))
+    item["limited"] = bool(item["limited"])
+    return item

database/review_changes.py

@@ -0,0 +1,75 @@
+"""Needs review queue change notices (#249 PR F2).
+
+Every committed change to the pending queue (an item recorded by the scan or
+the monitor, a spelling refresh, a decision) calls ``notify_review_change``
+after its transaction, from whichever thread wrote it. The review event
+stream (``py/api/review_events.py``) subscribes, so an open Needs review page
+re-reads its queue when it changes instead of polling. Observers are keyed by
+the database file, like ``subscribe_history_restore``; an observer that fails
+is logged and never fails the write.
+"""
+
+import os
+import threading
+from typing import Callable
+
+try:
+    from ..utils.logging_config import get_logger
+except ImportError:
+    from utils.logging_config import get_logger
+
+_logger = get_logger("prompt_manager.database.review_changes")
+_lock = threading.Lock()
+_observers: dict[str, dict[object, Callable[[], None]]] = {}
+
+
+def _identity(db_path: str) -> str:
+    return os.path.normcase(os.path.realpath(db_path))
+
+
+def subscribe_review_changes(
+    db_path: str, callback: Callable[[], None]
+) -> Callable[[], None]:
+    """Call ``callback()`` after each committed queue change; return the unsubscribe."""
+    identity = _identity(db_path)
+    token = object()
+    with _lock:
+        _observers.setdefault(identity, {})[token] = callback
+
+    def unsubscribe() -> None:
+        with _lock:
+            observers = _observers.get(identity)
+            if observers is not None:
+                observers.pop(token, None)
+                if not observers:
+                    _observers.pop(identity, None)
+
+    return unsubscribe
+
+
+def observer_count(db_path: str) -> int:
+    """How many observers watch ``db_path`` (tests and diagnostics)."""
+    with _lock:
+        return len(_observers.get(_identity(db_path), {}))
+
+
+def notify_review_change(db_path: str) -> None:
+    """Tell every observer of ``db_path``; call it after the commit."""
+    with _lock:
+        callbacks = tuple(_observers.get(_identity(db_path), {}).values())
+    for callback in callbacks:
+        try:
+            callback()
+        except Exception:
+            _logger.warning("Needs review change observer failed", exc_info=True)
+
+
+def rekey_review_changes(old_path: str, new_path: str) -> None:
+    """Move the observers of ``old_path`` to ``new_path`` (Move library)."""
+    old, new = _identity(old_path), _identity(new_path)
+    if old == new:
+        return
+    with _lock:
+        observers = _observers.pop(old, None)
+        if observers:
+            _observers.setdefault(new, {}).update(observers)

database/review_decisions.py

@@ -0,0 +1,291 @@
+"""Needs review decisions (#249 E3): explicit, auditable and compatible-only.
+
+A decision is one row of ``media_review_decisions`` for one item revision.
+``selected`` links the chosen candidate's pair to the file through the public
+ingester's compatible-only rules (``_ingest_resolved_pair_in``) in the same
+``_pair_transaction`` as the decision row, the item's new state and revision
+and the review index revision; any conflict or later failure rolls all of it
+back. ``unresolved`` records the decision and links nothing. No decision
+counts a run, touches usage or calls an execution writer.
+
+Callers verify the file first (the capture must be the item's bytes and the
+current file must still hash to them); nothing here reads the filesystem.
+"""
+
+import os
+import sqlite3
+
+from .annotation_schema import BYTES_TABLE
+from .annotations import _new_id
+from .library_commands import LibraryCommandError
+from .models import utc_now_iso
+from .review import (
+    _BUMP_REVIEW_INDEX,
+    _DETAIL,
+    _DETAIL_COLUMNS,
+    _PENDING_COUNT,
+    _queue_row,
+    dependency_fingerprint,
+    dependent_images,
+    same_name_rows,
+)
+from .review_changes import notify_review_change
+from .review_schema import DECISIONS_TABLE, ITEMS_TABLE, canonical_evidence
+
+DECISION_KIND = "user-selection"
+_INSERT_DECISION = (
+    f"INSERT INTO {DECISIONS_TABLE}(id,item_id,decision_revision,"  # nosec B608
+    "created_at,outcome,candidate_hash,evidence,pair_id,image_id) "
+    "VALUES(?,?,?,?,?,?,?,?,?)"
+)
+_ADVANCE_ITEM = (
+    f"UPDATE {ITEMS_TABLE} SET state=?,revision=revision+1,"  # nosec B608
+    "updated_at=? WHERE id=? AND revision=?"
+)
+_ITEM_BYTES = (
+    f"SELECT b.sha256 FROM {ITEMS_TABLE} i "  # nosec B608
+    f"JOIN {BYTES_TABLE} b ON b.id=i.byte_id WHERE i.id=?"
+)
+
+
+class ReviewCommandError(LibraryCommandError):
+    """A decision lost a race or would rewrite an association.
+
+    ``code`` is ``review-conflict`` (the item was decided or changed since it
+    was read), ``association-conflict`` (the choice is not compatible with
+    the file's saved links, or those links changed), ``file-changed`` (the
+    item is not about these bytes) or ``review-missing``. ``item`` is the
+    current item read inside the transaction, ``total`` the pending count and
+    ``fingerprint`` the current dependency fingerprint, when known;
+    ``changed`` marks an association conflict caused by links that changed
+    since the reviewer read them (rather than an incompatible choice).
+    """
+
+    def __init__(
+        self, code, epoch, *, item=None, total=None, fingerprint=None, changed=False
+    ):
+        super().__init__(code, epoch)
+        self.item = item
+        self.total = total
+        self.fingerprint = fingerprint
+        self.changed = changed
+        # The public view of ``item``, set by the API when it formats one.
+        self.view = None
+
+
+class _Rollback(Exception):
+    """Raised inside the transaction so the context manager rolls back."""
+
+    def __init__(self, error: ReviewCommandError):
+        super().__init__(error.code)
+        self.error = error
+
+
+class ReviewDecisionOperations:
+    """PromptDatabase mixin: record one decision on one Needs review item."""
+
+    def decide_review_item(
+        self,
+        *,
+        item_id: str,
+        expected_epoch: str,
+        expected_revision: int,
+        sha256: str,
+        outcome: str,
+        candidate: dict | None = None,
+        image_path: str | None = None,
+        metadata: dict | None = None,
+        expected_fingerprint: str | None = None,
+        aliases: tuple = (),
+        known_rows: frozenset | None = None,
+    ) -> dict:
+        """Record the decision; return ``{item, total, pair}``.
+
+        ``selected`` needs the evidence ``candidate`` (with its ``hash``), the
+        ``image_path`` the scan and the monitor link under, the captured
+        ``metadata`` and the ``expected_fingerprint`` the reviewer saw.
+        ``aliases`` are the other spellings legacy rows of the same physical
+        file use (a symlinked, junctioned or mapped root) and ``known_rows``
+        the ids of every same-name row the caller classified; a same-name row
+        it did not see is a changed association.
+        Raises ``LibraryCommandError("storage-changed")`` after a restore and
+        :class:`ReviewCommandError` for every refused decision, with zero
+        writes either way.
+        """
+        if outcome not in ("selected", "unresolved"):
+            raise ValueError("outcome must be selected or unresolved")
+        if outcome == "selected" and (
+            not isinstance(candidate, dict) or not image_path
+        ):
+            raise ValueError("A selected decision needs a candidate and a file")
+        try:
+            with self._pair_transaction() as conn:
+                decided = self._decide_in(
+                    conn,
+                    item_id=item_id,
+                    expected_epoch=expected_epoch,
+                    expected_revision=expected_revision,
+                    sha256=sha256,
+                    outcome=outcome,
+                    candidate=candidate,
+                    image_path=image_path,
+                    metadata=metadata or {},
+                    expected_fingerprint=expected_fingerprint,
+                    aliases=tuple(aliases),
+                    known_rows=known_rows,
+                )
+        except _Rollback as rollback:
+            raise rollback.error from None
+        # After the commit: open Needs review pages re-read their queue.
+        notify_review_change(self.model.db_path)
+        return decided
+
+    def _decide_in(self, conn: sqlite3.Connection, **command) -> dict:
+        epoch = self._library_epoch(conn, command["expected_epoch"])
+        item_id = command["item_id"]
+        current = _current_item(conn, item_id)
+        if current is None:
+            raise _Rollback(ReviewCommandError("review-missing", epoch))
+        total = conn.execute(_PENDING_COUNT).fetchone()[0]
+        if (
+            current["state"] != "pending"
+            or current["revision"] != command["expected_revision"]
+        ):
+            raise _Rollback(
+                ReviewCommandError("review-conflict", epoch, item=current, total=total)
+            )
+        if conn.execute(_ITEM_BYTES, (item_id,)).fetchone()[0] != command["sha256"]:
+            raise _Rollback(ReviewCommandError("file-changed", epoch))
+        decision_id = _new_id()
+        pair = None
+        candidate = command["candidate"] if command["outcome"] == "selected" else None
+        if candidate is not None:
+            pair = self._apply_candidate(
+                conn, epoch, current, decision_id, total, **command
+            )
+        evidence = {
+            "kind": DECISION_KIND,
+            "decision_id": decision_id,
+            "outcome": command["outcome"],
+            "reviewed_digest": command["sha256"],
+            "item_evidence_hash": current["evidence_hash"],
+            "resolver_version": current["resolver_version"],
+            "candidate": candidate,
+            "dependency_fingerprint": command["expected_fingerprint"],
+            "pair": pair,
+        }
+        now = utc_now_iso()
+        self._insert_review_decision(
+            conn,
+            (
+                decision_id,
+                item_id,
+                current["revision"] + 1,
+                now,
+                command["outcome"],
+                candidate["hash"] if candidate is not None else None,
+                canonical_evidence(evidence),
+                pair["id"] if pair else None,
+                pair["image_id"] if pair else None,
+            ),
+        )
+        conn.execute(
+            _ADVANCE_ITEM, (command["outcome"], now, item_id, current["revision"])
+        )
+        conn.execute(_BUMP_REVIEW_INDEX)
+        return {
+            "item": _current_item(conn, item_id),
+            "total": conn.execute(_PENDING_COUNT).fetchone()[0],
+            "pair": pair,
+            "decision_id": decision_id,
+        }
+
+    def _apply_candidate(
+        self, conn, epoch, current, decision_id, total, **command
+    ) -> dict:
+        """Link the candidate's pair, compatible-only; raise on any conflict."""
+        # Imported here: pair_ingestion imports operations, which composes this.
+        from .pair_ingestion import _ingest_resolved_pair_in
+
+        image_path = command["image_path"]
+        aliases = command["aliases"]
+        fingerprint = dependency_fingerprint(conn, image_path, aliases)
+        known = command["known_rows"]
+        unseen = known is not None and any(
+            row_id not in known
+            for row_id, _path in same_name_rows(conn, os.path.basename(image_path))
+        )
+        if unseen or fingerprint != command["expected_fingerprint"]:
+            raise _Rollback(
+                ReviewCommandError(
+                    "association-conflict",
+                    epoch,
+                    item=current,
+                    total=total,
+                    fingerprint=fingerprint,
+                    changed=True,
+                )
+            )
+        rows = dependent_images(conn, (image_path, *aliases))
+        if len(rows) > 1:
+            # One file linked under several spellings: no single row to enrich.
+            raise _Rollback(
+                ReviewCommandError(
+                    "association-conflict",
+                    epoch,
+                    item=current,
+                    total=total,
+                    fingerprint=fingerprint,
+                )
+            )
+        if rows:
+            # Enrich the one row of this file under the spelling it was
+            # linked with, so the ingester's compatibility rules see it.
+            image_path = rows[0][1]
+        candidate = command["candidate"]
+        positive, negative = candidate["positive"], candidate["negative"]
+        provenance = {
+            "kind": DECISION_KIND,
+            "decision_id": decision_id,
+            "reviewed_digest": command["sha256"],
+            "candidate_hash": candidate["hash"],
+            "resolver_version": current["resolver_version"],
+            "positive": positive,
+            "negative": negative,
+        }
+        result = _ingest_resolved_pair_in(
+            conn,
+            self,
+            image_path,
+            command["metadata"],
+            {"state": "resolved", "positive": positive, "negative": negative},
+            provenance=provenance,
+        )
+        if result["status"] == "conflict":
+            raise _Rollback(
+                ReviewCommandError(
+                    "association-conflict",
+                    epoch,
+                    item=current,
+                    total=total,
+                    fingerprint=fingerprint,
+                )
+            )
+        return {
+            "id": result["pair_id"],
+            "image_id": result["image_id"],
+            "status": result["status"],
+        }
+
+    @staticmethod
+    def _insert_review_decision(conn: sqlite3.Connection, values: tuple) -> None:
+        conn.execute(_INSERT_DECISION, values)
+
+
+def _current_item(conn: sqlite3.Connection, item_id: str) -> dict | None:
+    row = conn.execute(_DETAIL, (item_id,)).fetchone()
+    if row is None:
+        return None
+    item = _queue_row(row, _DETAIL_COLUMNS)
+    item.pop("evidence")
+    return item

database/review_schema.py

@@ -0,0 +1,513 @@
+"""Needs review schema group (#249): capture-bound ambiguous items and decisions.
+
+The group installs like ``image_annotations``: optional in old backups,
+required once a database is current, and valid only beside a valid image
+annotation group, because every item cites one annotation byte record. It owns
+
+- ``media_review_metadata``: one row, the group's schema version and the
+  review index revision (moved by every queue change);
+- ``media_review_items``: one ambiguous resolver result for one byte record,
+  keyed by ``(byte_id, resolver_version, evidence_hash)``, with the file's
+  spelling when it was recorded (the locator is case-folded on Windows, a
+  target is not), its canonical evidence, candidate count, ``limited`` flag,
+  state and revision;
+- ``media_review_decisions``: the auditable decision history of an item, one
+  row per decision revision, with optional navigation to the pair and image
+  the decision linked (nulled, never cascaded, when those are deleted).
+
+Evidence is canonical JSON (:func:`canonical_evidence`): one object, sorted
+keys, no whitespace, ASCII only (so characters, bytes and the 8 MiB bound
+agree and lone surrogates survive), no NaN or infinity. ``evidence_hash`` is
+the SHA-256 of the item's evidence text.
+
+Installation never backfills anything and never touches the filesystem.
+Validation reads only: catalog objects compared after whitespace compaction,
+columns and foreign keys through the PRAGMAs, persisted values in single
+bounded SQL passes, then one streamed pass that re-canonicalizes each evidence
+document (one row in memory at a time).
+"""
+
+import hashlib
+import json
+import re
+import sqlite3
+from typing import Any, Optional
+
+from .annotation_schema import BYTES_TABLE
+from .annotation_schema import TABLES as ANNOTATION_TABLES
+from .annotation_schema import _catalog as _annotation_catalog
+from .annotation_schema import annotation_schema_error
+
+try:
+    from ..utils.json_strict import dumps_strict
+except ImportError:
+    from utils.json_strict import dumps_strict
+
+SCHEMA_VERSION = 1
+METADATA_TABLE = "media_review_metadata"
+ITEMS_TABLE = "media_review_items"
+DECISIONS_TABLE = "media_review_decisions"
+TABLES = (METADATA_TABLE, ITEMS_TABLE, DECISIONS_TABLE)
+MAX_EVIDENCE_BYTES = 8 * 1024 * 1024
+MAX_CANDIDATES = 16
+# The file's own spelling when it was recorded (bytes of UTF-8 text). Locators
+# are case-folded on Windows, so a target is formatted from this instead.
+MAX_SPELLED_PATH_BYTES = 16384
+ITEM_STATES = ("pending", "selected", "unresolved")
+DECISION_OUTCOMES = ("selected", "unresolved")
+_TIMESTAMP_BYTES = 64
+_HEX64 = "length({c})=64 AND {c} NOT GLOB '*[^0-9a-f]*'"
+_EVIDENCE_CHECK = f"CHECK(length(CAST(evidence AS BLOB)) <= {MAX_EVIDENCE_BYTES})"
+
+_TABLE_DDL = {
+    METADATA_TABLE: (
+        f"CREATE TABLE {METADATA_TABLE} (singleton_id INTEGER PRIMARY KEY "
+        "CHECK(singleton_id=1), schema_version INTEGER NOT NULL "
+        f"CHECK(schema_version={SCHEMA_VERSION}), "
+        "review_index_revision INTEGER NOT NULL DEFAULT 0 "
+        "CHECK(review_index_revision>=0))"
+    ),
+    ITEMS_TABLE: (
+        f"CREATE TABLE {ITEMS_TABLE} (id TEXT PRIMARY KEY CHECK(length(id)=36), "
+        f"byte_id TEXT NOT NULL REFERENCES {BYTES_TABLE}(id) ON DELETE RESTRICT, "
+        "spelled_path TEXT NOT NULL CHECK(length(CAST(spelled_path AS BLOB)) "
+        f"BETWEEN 1 AND {MAX_SPELLED_PATH_BYTES}), "
+        "resolver_version INTEGER NOT NULL, evidence_hash TEXT NOT NULL "
+        f"CHECK({_HEX64.format(c='evidence_hash')}), "
+        f"evidence TEXT NOT NULL {_EVIDENCE_CHECK}, "
+        "candidate_count INTEGER NOT NULL "
+        f"CHECK(candidate_count BETWEEN 0 AND {MAX_CANDIDATES}), "
+        "limited INTEGER NOT NULL CHECK(limited IN (0,1)), "
+        "state TEXT NOT NULL CHECK(state IN ('pending','selected','unresolved')), "
+        "revision INTEGER NOT NULL CHECK(revision>=0), created_at TEXT NOT NULL, "
+        "updated_at TEXT NOT NULL, UNIQUE(byte_id, resolver_version, evidence_hash))"
+    ),
+    DECISIONS_TABLE: (
+        f"CREATE TABLE {DECISIONS_TABLE} (id TEXT PRIMARY KEY "
+        "CHECK(length(id)=36), item_id TEXT NOT NULL "
+        f"REFERENCES {ITEMS_TABLE}(id) ON DELETE RESTRICT, "
+        "decision_revision INTEGER NOT NULL, created_at TEXT NOT NULL, "
+        "outcome TEXT NOT NULL CHECK(outcome IN ('selected','unresolved')), "
+        "candidate_hash TEXT CHECK(candidate_hash IS NULL OR "
+        f"({_HEX64.format(c='candidate_hash')})), "
+        f"evidence TEXT NOT NULL {_EVIDENCE_CHECK}, "
+        "pair_id INTEGER REFERENCES prompt_pairs(id) ON DELETE SET NULL, "
+        "image_id INTEGER REFERENCES generated_images(id) ON DELETE SET NULL, "
+        "UNIQUE(item_id, decision_revision), "
+        "CHECK((outcome='selected') = (candidate_hash IS NOT NULL)))"
+    ),
+}
+_INDEX_DDL = {
+    # The queue reads pending items oldest first with a stable tiebreak.
+    "idx_media_review_items_queue": (
+        "CREATE INDEX idx_media_review_items_queue ON "
+        f"{ITEMS_TABLE}(state, created_at, id)"
+    ),
+    # Deleting a pair or an image nulls decision navigation by index, not scan.
+    "idx_media_review_decisions_pair": (
+        "CREATE INDEX idx_media_review_decisions_pair ON " f"{DECISIONS_TABLE}(pair_id)"
+    ),
+    "idx_media_review_decisions_image": (
+        "CREATE INDEX idx_media_review_decisions_image ON "
+        f"{DECISIONS_TABLE}(image_id)"
+    ),
+}
+# ``sqlite_autoindex_<table>_<n>``: the TEXT primary key and the UNIQUE key.
+_AUTOINDEXES = {ITEMS_TABLE: 2, DECISIONS_TABLE: 2}
+# (name, declared type, not null, default, primary key position)
+_COLUMNS = {
+    METADATA_TABLE: (
+        ("singleton_id", "INTEGER", 0, None, 1),
+        ("schema_version", "INTEGER", 1, None, 0),
+        ("review_index_revision", "INTEGER", 1, "0", 0),
+    ),
+    ITEMS_TABLE: (
+        ("id", "TEXT", 0, None, 1),
+        ("byte_id", "TEXT", 1, None, 0),
+        ("spelled_path", "TEXT", 1, None, 0),
+        ("resolver_version", "INTEGER", 1, None, 0),
+        ("evidence_hash", "TEXT", 1, None, 0),
+        ("evidence", "TEXT", 1, None, 0),
+        ("candidate_count", "INTEGER", 1, None, 0),
+        ("limited", "INTEGER", 1, None, 0),
+        ("state", "TEXT", 1, None, 0),
+        ("revision", "INTEGER", 1, None, 0),
+        ("created_at", "TEXT", 1, None, 0),
+        ("updated_at", "TEXT", 1, None, 0),
+    ),
+    DECISIONS_TABLE: (
+        ("id", "TEXT", 0, None, 1),
+        ("item_id", "TEXT", 1, None, 0),
+        ("decision_revision", "INTEGER", 1, None, 0),
+        ("created_at", "TEXT", 1, None, 0),
+        ("outcome", "TEXT", 1, None, 0),
+        ("candidate_hash", "TEXT", 0, None, 0),
+        ("evidence", "TEXT", 1, None, 0),
+        ("pair_id", "INTEGER", 0, None, 0),
+        ("image_id", "INTEGER", 0, None, 0),
+    ),
+}
+# (column, parent table, parent column, on delete)
+_FOREIGN_KEYS = {
+    METADATA_TABLE: set(),
+    ITEMS_TABLE: {("byte_id", BYTES_TABLE, "id", "RESTRICT")},
+    DECISIONS_TABLE: {
+        ("item_id", ITEMS_TABLE, "id", "RESTRICT"),
+        ("pair_id", "prompt_pairs", "id", "SET NULL"),
+        ("image_id", "generated_images", "id", "SET NULL"),
+    },
+}
+
+
+class _NonCanonical(ValueError):
+    pass
+
+
+def _reject_constant(name: str) -> Any:
+    raise _NonCanonical(f"JSON constant {name} is not allowed")
+
+
+# Built once: validation re-encodes every stored document at startup.
+_ENCODER = json.JSONEncoder(
+    sort_keys=True, separators=(",", ":"), ensure_ascii=True, allow_nan=False
+)
+_DECODER = json.JSONDecoder(parse_constant=_reject_constant)
+
+
+def canonical_evidence(value: Any) -> str:
+    """Serialize one evidence object canonically; ``ValueError`` when invalid.
+
+    The text is a JSON object with sorted keys, no whitespace, ASCII only and
+    no NaN/infinity, at most ``MAX_EVIDENCE_BYTES`` bytes. A non-finite number
+    (ComfyUI stamps ``NaN`` into graphs) is written as ``null``, the store's
+    policy everywhere (``utils.json_strict.dumps_strict``).
+    """
+    if not isinstance(value, dict):
+        raise ValueError("Review evidence must be a JSON object")
+    try:
+        try:
+            text = _ENCODER.encode(value)
+        except ValueError as error:
+            if "Out of range float" not in str(error):
+                raise
+            text = dumps_strict(
+                value, sort_keys=True, separators=(",", ":"), ensure_ascii=True
+            )
+    except (TypeError, RecursionError) as error:
+        raise ValueError(f"Review evidence is not serializable: {error}") from None
+    if len(text) > MAX_EVIDENCE_BYTES:
+        raise ValueError("Review evidence is larger than 8 MiB")
+    return text
+
+
+def choosable(candidate: Any) -> bool:
+    """True when a candidate offers a prompt to choose: it is ``resolved`` and
+    its positive side carries non-blank text. The page disables any other
+    candidate, so it is never something to choose.
+    """
+    if not isinstance(candidate, dict) or candidate.get("state") != "resolved":
+        return False
+    positive = candidate.get("positive")
+    if not isinstance(positive, dict):
+        return False
+    text = positive.get("text")
+    return isinstance(text, str) and bool(text.strip())
+
+
+# An item is worth a decision only when at least this many candidates offer
+# a prompt; with fewer there is nothing to choose between (maintainer test of
+# #284/#288: 39 items whose candidates were all "unresolved").
+MIN_CHOOSABLE = 2
+
+
+def evidence_offers_choice(evidence: Any) -> bool:
+    """False when stored evidence provably offers nothing to choose.
+
+    Unlimited evidence must list ``MIN_CHOOSABLE`` choosable candidates. A
+    limited item stores none, only ``candidate_total``; it may offer a choice
+    (more than ``MAX_CANDIDATES`` prompts) unless that total is too small.
+    """
+    if not isinstance(evidence, dict):
+        return False
+    if evidence.get("limited"):
+        total = evidence.get("candidate_total")
+        return type(total) is int and total >= MIN_CHOOSABLE
+    candidates = evidence.get("candidates")
+    if not isinstance(candidates, list):
+        return False
+    return sum(1 for c in candidates if choosable(c)) >= MIN_CHOOSABLE
+
+
+def evidence_digest(text: str) -> str:
+    """SHA-256 of canonical evidence text (ASCII, hence UTF-8 identical)."""
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _is_canonical(text: Any) -> bool:
+    if not isinstance(text, str):
+        return False
+    try:
+        value = _DECODER.decode(text)
+        return canonical_evidence(value) == text
+    except (ValueError, RecursionError):
+        return False
+
+
+def _compact(sql: str) -> str:
+    return re.sub(r"\s+", "", sql).lower()
+
+
+def _uuid(column: str) -> str:
+    """SQL: *column* is a lowercase hyphenated 36-character UUID string."""
+    return (
+        f"typeof({column}) = 'text' AND length({column}) = 36 "
+        f"AND substr({column}, 9, 1) = '-' AND substr({column}, 14, 1) = '-' "
+        f"AND substr({column}, 19, 1) = '-' AND substr({column}, 24, 1) = '-' "
+        f"AND length(replace({column}, '-', '')) = 32 "
+        f"AND replace({column}, '-', '') NOT GLOB '*[^0-9a-f]*'"
+    )
+
+
+def _timestamp(column: str) -> str:
+    return (
+        f"typeof({column}) = 'text' "
+        f"AND length(CAST({column} AS BLOB)) <= {_TIMESTAMP_BYTES}"
+    )
+
+
+def _non_negative(column: str) -> str:
+    return f"typeof({column}) = 'integer' AND {column} >= 0"
+
+
+def _hex64(column: str) -> str:
+    return f"typeof({column}) = 'text' AND " + _HEX64.format(c=column)
+
+
+def _evidence(column: str) -> str:
+    # Type and size only: the streamed pass below proves the text canonical
+    # (which implies printable ASCII), so a pattern scan here would read every
+    # document a second time.
+    return (
+        f"typeof({column}) = 'text' "
+        f"AND length(CAST({column} AS BLOB)) BETWEEN 2 AND {MAX_EVIDENCE_BYTES}"
+    )
+
+
+def _nullable_integer(column: str) -> str:
+    return f"({column} IS NULL OR typeof({column}) = 'integer')"
+
+
+def _in(column: str, values: tuple) -> str:
+    return f"typeof({column}) = 'text' AND {column} IN ({repr(values)[1:-1]})"
+
+
+# Every row of a table must satisfy its predicate; one pass each, LIMIT 1.
+_ROW_PREDICATES = {
+    ITEMS_TABLE: " AND ".join(
+        (
+            _uuid("id"),
+            _uuid("byte_id"),
+            "typeof(spelled_path) = 'text' AND length(CAST(spelled_path AS BLOB)) "
+            f"BETWEEN 1 AND {MAX_SPELLED_PATH_BYTES}",
+            "typeof(resolver_version) = 'integer'",
+            _hex64("evidence_hash"),
+            _evidence("evidence"),
+            _non_negative("candidate_count"),
+            f"candidate_count <= {MAX_CANDIDATES}",
+            "typeof(limited) = 'integer' AND limited IN (0, 1)",
+            _in("state", ITEM_STATES),
+            _non_negative("revision"),
+            _timestamp("created_at"),
+            _timestamp("updated_at"),
+        )
+    ),
+    DECISIONS_TABLE: " AND ".join(
+        (
+            _uuid("id"),
+            _uuid("item_id"),
+            _non_negative("decision_revision"),
+            _timestamp("created_at"),
+            _in("outcome", DECISION_OUTCOMES),
+            "(CASE WHEN outcome = 'selected' THEN "
+            f"{_hex64('candidate_hash')} ELSE candidate_hash IS NULL END)",
+            _evidence("evidence"),
+            _nullable_integer("pair_id"),
+            _nullable_integer("image_id"),
+        )
+    ),
+}
+
+
+def _expected_catalog() -> set:
+    objects = {("table", name, _compact(sql)) for name, sql in _TABLE_DDL.items()}
+    objects |= {("index", name, _compact(sql)) for name, sql in _INDEX_DDL.items()}
+    objects |= {
+        ("index", f"sqlite_autoindex_{table}_{n}", "")
+        for table, count in _AUTOINDEXES.items()
+        for n in range(1, count + 1)
+    }
+    return objects
+
+
+def _catalog(conn: sqlite3.Connection) -> list:
+    names = TABLES + tuple(_INDEX_DDL)
+    marks = ",".join("?" * len(names))
+    table_marks = ",".join("?" * len(TABLES))
+    return conn.execute(  # only "?" placeholders are interpolated
+        "SELECT type,name,sql FROM sqlite_master "
+        f"WHERE name IN ({marks}) OR tbl_name IN ({table_marks})",  # nosec B608
+        names + TABLES,
+    ).fetchall()
+
+
+def _structure_error(conn: sqlite3.Connection) -> Optional[str]:
+    for table, expected in _COLUMNS.items():
+        columns = tuple(
+            (row[1], row[2].upper(), row[3], row[4], row[5])
+            for row in conn.execute(f"PRAGMA table_info({table})")
+        )
+        if columns != expected:
+            return f"Review queue table {table} has invalid columns"
+        foreign_keys = {
+            (row[3], row[2], row[4], row[6])
+            for row in conn.execute(f"PRAGMA foreign_key_list({table})")
+        }
+        if foreign_keys != _FOREIGN_KEYS[table]:
+            return f"Review queue table {table} has invalid foreign keys"
+        if conn.execute(f"PRAGMA foreign_key_check({table})").fetchone():
+            return f"Review queue table {table} contains foreign key violations"
+    return None
+
+
+def _evidence_error(conn: sqlite3.Connection) -> Optional[str]:
+    """Stream every evidence document once; one row is held at a time.
+
+    Rows are read with ``fetchone``: iterating a managed connection's cursor
+    would prefetch ``ITER_CHUNK`` (128) rows (``database/managed_connection.py``).
+    """
+    items = conn.execute(
+        f"SELECT evidence_hash, evidence FROM {ITEMS_TABLE}"  # nosec B608
+    )
+    while (row := items.fetchone()) is not None:
+        evidence_hash, text = row[0], row[1]
+        if not _is_canonical(text) or evidence_digest(text) != evidence_hash:
+            return f"Review queue table {ITEMS_TABLE} contains invalid evidence"
+    decisions = conn.execute(f"SELECT evidence FROM {DECISIONS_TABLE}")  # nosec B608
+    while (row := decisions.fetchone()) is not None:
+        text = row[0]
+        if not _is_canonical(text):
+            return f"Review queue table {DECISIONS_TABLE} contains invalid evidence"
+    return None
+
+
+def _value_error(conn: sqlite3.Connection) -> Optional[str]:
+    # Only this module's constants are interpolated into the SQL below.
+    rows = conn.execute(
+        "SELECT COUNT(*), MIN(typeof(singleton_id) = 'integer' "  # nosec B608
+        "AND singleton_id = 1 AND typeof(schema_version) = 'integer' "
+        f"AND schema_version = {SCHEMA_VERSION} "
+        f"AND {_non_negative('review_index_revision')}) FROM {METADATA_TABLE}"
+    ).fetchone()
+    if rows[0] != 1 or rows[1] != 1:
+        return "Review queue metadata is invalid"
+    for table, predicate in _ROW_PREDICATES.items():
+        if conn.execute(
+            f"SELECT 1 FROM {table} WHERE NOT ({predicate}) LIMIT 1"  # nosec B608
+        ).fetchone():
+            return f"Review queue table {table} contains invalid values"
+    return _evidence_error(conn)
+
+
+def review_without_annotations_error(conn: sqlite3.Connection) -> Optional[str]:
+    """Catalog only: a review group present without its annotation tables.
+
+    Startup asks this before the annotation group installs, which would make
+    a review group copied without it look valid. It reads no rows; the full
+    validation runs once in :func:`migrate_review_state`.
+    """
+    if not _catalog(conn):
+        return None
+    present = {
+        name for kind, name, _sql in _annotation_catalog(conn) if kind == "table"
+    }
+    if present != set(ANNOTATION_TABLES):
+        return (
+            "Review queue schema requires a valid image annotation schema: "
+            "Missing image annotation schema"
+        )
+    return None
+
+
+def review_schema_error(
+    conn: sqlite3.Connection,
+    *,
+    allow_missing: bool = True,
+    annotations_valid: bool = False,
+) -> Optional[str]:
+    """Reject partial or unsupported review schemas and invalid rows.
+
+    Reads only: nothing is ever repaired. A database without any of the
+    group's objects is acceptable for backups that predate it unless
+    ``allow_missing`` is false. A present group requires a present, valid
+    image annotation group; ``annotations_valid`` says the caller has just
+    validated it (startup's annotation install), so only its presence is
+    checked again.
+    """
+    objects = _catalog(conn)
+    if not objects:
+        return None if allow_missing else "Missing review queue schema"
+    if annotations_valid:
+        annotation_error = review_without_annotations_error(conn)
+    else:
+        annotation_error = annotation_schema_error(conn, allow_missing=False)
+        if annotation_error:
+            annotation_error = (
+                "Review queue schema requires a valid image annotation schema: "
+                + annotation_error
+            )
+    if annotation_error:
+        return annotation_error
+    present = {name for kind, name, _sql in objects if kind == "table"}
+    if present != set(TABLES):
+        return "Incomplete review queue schema"
+    actual = {(kind, name, _compact(sql or "")) for kind, name, sql in objects}
+    if actual != _expected_catalog():
+        return "Review queue has an invalid schema definition"
+    return _structure_error(conn) or _value_error(conn)
+
+
+def migrate_review_state(conn: sqlite3.Connection) -> None:
+    """Install the group atomically; validate before and after creating it.
+
+    Runs after ``migrate_annotation_state`` (which has just validated the
+    annotation group): the group is only valid beside the annotation group it
+    cites. A present group is validated once, evidence included.
+    """
+    conn.execute("SAVEPOINT media_review_schema")
+    try:
+        installed = bool(_catalog(conn))
+        error = review_schema_error(conn, annotations_valid=True)
+        if error:
+            raise sqlite3.DatabaseError(error)
+        if installed:
+            # Already complete and valid: nothing to create, and the evidence
+            # pass is the expensive part of validation, so it runs once.
+            conn.execute("RELEASE media_review_schema")
+            return
+        for sql in _TABLE_DDL.values():
+            conn.execute(sql.replace("CREATE TABLE", "CREATE TABLE IF NOT EXISTS", 1))
+        for sql in _INDEX_DDL.values():
+            conn.execute(sql.replace("INDEX", "INDEX IF NOT EXISTS", 1))
+        conn.execute(
+            f"INSERT OR IGNORE INTO {METADATA_TABLE} "
+            "(singleton_id, schema_version, review_index_revision) VALUES (1, ?, 0)",
+            (SCHEMA_VERSION,),
+        )
+        error = review_schema_error(conn, allow_missing=False, annotations_valid=True)
+        if error:
+            raise sqlite3.DatabaseError(error)
+        conn.execute("RELEASE media_review_schema")
+    except BaseException:
+        conn.execute("ROLLBACK TO media_review_schema")
+        conn.execute("RELEASE media_review_schema")
+        raise

database/run_attribution.py

@@ -0,0 +1,244 @@
+"""Attribute an output file to a stored prompt through recorded history (#342).
+
+Execution history records, per run, the files ComfyUI reported
+(``execution_run_outputs``) and the PromptManager texts the run used
+(``execution_run_contexts``, whose ``positive_prompt_id`` hint is set only
+while the raw text matches exactly one stored prompt). A file is attributed
+only when all of this holds:
+
+- exactly one recorded run reported the file's output location (same output
+  root, subfolder and name);
+- the file was last written while that run was executing, from its dequeue
+  to its terminal event (else the finish callback): a later run that history
+  did not record may have reused the name;
+- every positive context of that run names the same stored prompt.
+
+Anything else returns None: the caller leaves the file unlinked. Read-only.
+
+Lookups are batched (``stored_run_prompts``): one parameterized query per
+chunk of at most ``LOOKUP_CHUNK`` distinct file names, matched in memory. The
+history schema is left exactly as it is (no extra index), so older builds can
+still open the library.
+"""
+
+import logging
+import os
+import sqlite3
+import threading
+import weakref
+from typing import Any, Callable, Dict, Iterable, List, Optional
+
+try:
+    from ..utils.execution_outputs import snapshot_output_roots
+    from ..utils.library_location import import_folder_paths
+except ImportError:
+    from utils.execution_outputs import snapshot_output_roots
+    from utils.library_location import import_folder_paths
+
+# File times may trail or lead the recorded run times a little (coarse file
+# system clocks, the write finishing just after the host reported it).
+MTIME_SLACK_MS = 2000
+
+# Distinct file names per lookup query: well under SQLite's bound-parameter
+# limit (999 on old builds), so a scan batch costs one query per chunk.
+LOOKUP_CHUNK = 500
+
+_RUNS_FOR_NAMES = (
+    "SELECT DISTINCT o.filename, o.subfolder, o.root_key, o.path_style, o.run_id, "
+    "r.observed_dequeue_at, COALESCE(r.terminal_event_at, r.observed_callback_at) "
+    "FROM execution_run_outputs o JOIN execution_runs r ON r.run_id = o.run_id "
+    "WHERE o.folder_type = 'output' AND o.filename IN ({marks})"
+)
+
+
+def host_output_directory() -> Optional[str]:
+    """ComfyUI's output directory, or None outside ComfyUI."""
+    folder_paths = import_folder_paths()
+    if folder_paths is None:
+        return None
+    try:
+        value = folder_paths.get_output_directory()
+    except Exception:
+        return None
+    return value if isinstance(value, str) and value else None
+
+
+def _inside(image_path: str, output_root: str) -> Optional[str]:
+    """``image_path`` relative to ``output_root``, or None when outside it."""
+    try:
+        relative = os.path.relpath(image_path, output_root)
+    except ValueError:  # another drive on Windows
+        return None
+    if os.path.isabs(relative) or relative == os.pardir:
+        return None
+    if relative.startswith(os.pardir + os.sep):
+        return None
+    return relative
+
+
+def _resolved(path: str) -> str:
+    try:
+        return os.path.realpath(path)
+    except (OSError, ValueError):
+        return os.path.abspath(path)
+
+
+def _location(image_path: str, output_root: str, path_style: str):
+    """(root key, subfolder, filename) as history records them, or None.
+
+    The root key is always the host's own spelling of its output folder,
+    because history recorded that one. The file may be spelled through the
+    same folder or through its resolved path (a symlinked or junction output
+    folder, as scan roots are): the lexical spelling is tried first, then
+    both sides resolved.
+    """
+    root_key = snapshot_output_roots(path_style, output_root, output_root).output_key
+    if root_key is None:
+        return None
+    relative = _inside(os.path.abspath(image_path), os.path.abspath(output_root))
+    if relative is None:
+        relative = _inside(_resolved(image_path), _resolved(output_root))
+    if relative is None:
+        return None
+    subfolder, filename = os.path.split(relative)
+    if not filename:
+        return None
+    return root_key, subfolder, filename
+
+
+def in_output_folder(image_path: str, output_root: Optional[str]) -> bool:
+    """Whether history could ever attribute ``image_path`` (inside the host's
+    output folder, in either spelling)."""
+    if not image_path or not output_root:
+        return False
+    style = "windows" if os.name == "nt" else "posix"
+    return _location(image_path, output_root, style) is not None
+
+
+def _written_during(image_path: str, started: Any, finished: Any) -> bool:
+    if not isinstance(started, int) or not isinstance(finished, int):
+        return False
+    try:
+        written = os.stat(image_path).st_mtime_ns // 1_000_000
+    except OSError:
+        return False
+    return started - MTIME_SLACK_MS <= written <= finished + MTIME_SLACK_MS
+
+
+def stored_run_prompt(
+    db: Any,
+    image_path: str,
+    output_root: Optional[str],
+    path_style: Optional[str] = None,
+) -> Optional[int]:
+    """The stored prompt id history attributes to ``image_path``, else None."""
+    if not image_path:
+        return None
+    return stored_run_prompts(db, [image_path], output_root, path_style).get(image_path)
+
+
+def _runs_by_location(db: Any, names: List[str]) -> Optional[Dict[tuple, dict]]:
+    """``{(filename, subfolder, root_key, style): {run_id: (start, end)}}``.
+
+    One query per ``LOOKUP_CHUNK`` names; None without history tables.
+    """
+    found: Dict[tuple, dict] = {}
+    conn = db.model.get_connection()
+    for start in range(0, len(names), LOOKUP_CHUNK):
+        chunk = names[start : start + LOOKUP_CHUNK]
+        query = _RUNS_FOR_NAMES.format(marks=",".join("?" for _ in chunk))
+        try:
+            rows = conn.execute(query, chunk).fetchall()  # nosec B608
+        except sqlite3.Error:
+            return None  # no history tables (a library without history)
+        for name, subfolder, root_key, style, run_id, began, ended in rows:
+            runs = found.setdefault((name, subfolder, root_key, style), {})
+            runs[run_id] = (began, ended)
+    return found
+
+
+def _named_prompt(db: Any, run_id: str) -> Optional[int]:
+    contexts = db.get_execution_contexts(run_id).get("contexts") or []
+    named = {
+        context.get("positive_prompt_id")
+        for context in contexts
+        if context.get("positive") is not None
+    }
+    if len(named) != 1:
+        return None
+    (prompt_id,) = named
+    return prompt_id if isinstance(prompt_id, int) else None
+
+
+def stored_run_prompts(
+    db: Any,
+    image_paths: Iterable[str],
+    output_root: Optional[str],
+    path_style: Optional[str] = None,
+) -> Dict[str, Optional[int]]:
+    """``{path: stored prompt id or None}`` for many files in few queries.
+
+    The output lookup is one query per ``LOOKUP_CHUNK`` distinct names; each
+    run that alone reported a file is then read once for its contexts.
+    """
+    paths = list(dict.fromkeys(path for path in image_paths if path))
+    result: Dict[str, Optional[int]] = dict.fromkeys(paths)
+    if not paths or not output_root:
+        return result
+    style = path_style or ("windows" if os.name == "nt" else "posix")
+    located = {}
+    for path in paths:
+        location = _location(path, output_root, style)
+        if location is not None:
+            located[path] = location
+    if not located:
+        return result
+    names = sorted({filename for _key, _sub, filename in located.values()})
+    runs = _runs_by_location(db, names)
+    if not runs:
+        return result
+    prompts: Dict[str, Optional[int]] = {}
+    for path, (root_key, subfolder, filename) in located.items():
+        reported = runs.get((filename, subfolder, root_key, style), {})
+        if len(reported) != 1:
+            continue
+        ((run_id, (began, ended)),) = reported.items()
+        if not _written_during(path, began, ended):
+            continue
+        if run_id not in prompts:
+            prompts[run_id] = _named_prompt(db, run_id)
+        result[path] = prompts[run_id]
+    return result
+
+
+_LOGGER = logging.getLogger("prompt_manager.run_attribution")
+_SEALED_LISTENERS: List[weakref.WeakMethod] = []
+_SEALED_LOCK = threading.Lock()
+
+
+def subscribe_outputs_sealed(method: Callable[[str, List[dict]], None]) -> None:
+    """Call bound ``method(run_id, references)`` after a run's outputs are recorded.
+
+    Held weakly: a listener that is garbage collected is dropped.
+    """
+    with _SEALED_LOCK:
+        _SEALED_LISTENERS.append(weakref.WeakMethod(method))
+
+
+def notify_outputs_sealed(run_id: str, references: Iterable[dict]) -> None:
+    """Tell listeners a run's output references were just committed.
+
+    A listener failure is logged and never reaches the history writer.
+    """
+    references = list(references)
+    with _SEALED_LOCK:
+        alive = [ref for ref in _SEALED_LISTENERS if ref() is not None]
+        _SEALED_LISTENERS[:] = alive
+        listeners = [ref() for ref in alive]
+    for listener in listeners:
+        if listener is None:
+            continue
+        try:
+            listener(run_id, references)
+        except Exception:
+            _LOGGER.warning("Output seal listener failed", exc_info=True)

database/safety_backup.py

@@ -0,0 +1,185 @@
+"""Safety backups beside the live database: one writer for every caller.
+
+A safety backup is ``<db>.<label>_<YYYYmmdd_HHMMSS_ffffff>[_n]`` in the
+library's own folder. It is written by SQLite's backup API into a temp file
+beside the database (``SAFETY_TEMP_PREFIX``, swept at startup after a crash),
+made one self-contained file (rollback journal), optionally verified, fsynced,
+made private (``0o600`` on POSIX) and only then given its unique name, so a
+backup name never carries a half-written file. The names are unique within
+one second (microseconds, then a counter): on Windows two backups in the same
+second must not overwrite each other.
+
+Maintenance applies take a verified backup (``py/api/maintenance.py``); a
+restore takes an unverified one, because the database it replaces may be the
+damaged one the user is recovering from (``database/restore_stage.py``).
+"""
+
+import datetime
+import os
+import sqlite3
+import tempfile
+from contextlib import closing
+
+SAFETY_TEMP_PREFIX = ".pm-safety-"
+_NAME_ATTEMPTS = 1000
+
+
+class SafetyBackupFailed(Exception):
+    """The safety backup could not be written, verified or put in place.
+
+    ``reason`` is the verify reason when the copy did not verify.
+    """
+
+    def __init__(self, message, reason=None):
+        super().__init__(message)
+        self.reason = reason
+
+
+def _now():
+    return datetime.datetime.now()
+
+
+def remove_quietly(*paths):
+    """Remove each existing path, ignoring errors (cleanup after a failure)."""
+    for path in paths:
+        try:
+            if path and os.path.exists(path):
+                os.remove(path)
+        except OSError:
+            pass
+
+
+def backup_names(db_path, label="backup"):
+    """Candidate names, unique within one second (microseconds, then ``_n``)."""
+    base = f"{db_path}.{label}_{_now().strftime('%Y%m%d_%H%M%S_%f')}"
+    for attempt in range(_NAME_ATTEMPTS):
+        yield base if attempt == 0 else f"{base}_{attempt}"
+
+
+def reserve_backup_name(db_path, label="backup"):
+    """Create and return an unused ``<db>.<label>_<stamp>[_n]`` (O_EXCL)."""
+    for candidate in backup_names(db_path, label):
+        try:
+            fd = os.open(candidate, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        except FileExistsError:
+            continue
+        os.close(fd)
+        return candidate
+    raise SafetyBackupFailed("No free backup name")
+
+
+def place_backup(temp, db_path, label="backup"):
+    """Give the finished ``temp`` its unique backup name; return that path.
+
+    ``os.link`` is atomic and refuses an existing name, so no empty or half
+    file ever carries a backup name, even across a crash. A filesystem
+    without hard links falls back to reserving the name (``O_EXCL``) and
+    ``os.replace``. The temp file is removed by the caller.
+    """
+    for candidate in backup_names(db_path, label):
+        try:
+            os.link(temp, candidate)
+        except FileExistsError:
+            continue
+        except (OSError, NotImplementedError):
+            break  # no hard links here
+        else:
+            return candidate
+    else:
+        raise SafetyBackupFailed("No free backup name")
+    final = reserve_backup_name(db_path, label)
+    try:
+        os.replace(temp, final)
+    except OSError:
+        remove_quietly(final)
+        raise
+    return final
+
+
+def sweep_safety_temps(db_path):
+    """Remove the temp copies an interrupted safety backup left (blocking).
+
+    Called once at startup, before any job can take a backup. Returns the
+    names removed.
+    """
+    folder = os.path.dirname(os.path.abspath(db_path))
+    removed = []
+    try:
+        names = os.listdir(folder)
+    except OSError:
+        return removed
+    for name in names:
+        if not (name.startswith(SAFETY_TEMP_PREFIX) and ".tmp" in name):
+            continue
+        try:
+            os.remove(os.path.join(folder, name))
+            removed.append(name)
+        except OSError:
+            continue
+    return removed
+
+
+def make_standalone(path):
+    """Make the copy one self-contained file (rollback journal, not WAL).
+
+    The backup API copies the live database's WAL flag; a WAL file opened
+    read-only later (a verify, a restore preview) would leave ``-wal`` and
+    ``-shm`` sidecars beside it.
+    """
+    try:
+        with closing(sqlite3.connect(path)) as conn:
+            conn.execute("PRAGMA journal_mode=DELETE").fetchone()
+    except sqlite3.Error as exc:
+        raise SafetyBackupFailed("The backup could not be finished") from exc
+
+
+def fsync_file(path):
+    with open(path, "rb+") as handle:
+        os.fsync(handle.fileno())
+
+
+def safety_temp(db_path):
+    """A new, closed temp file beside the database (``SAFETY_TEMP_PREFIX``)."""
+    fd, temp = tempfile.mkstemp(
+        dir=os.path.dirname(os.path.abspath(db_path)),
+        prefix=SAFETY_TEMP_PREFIX,
+        suffix=".tmp",
+    )
+    os.close(fd)
+    return temp
+
+
+def take_safety_backup(model, label="backup", *, verify=True):
+    """Write (and by default verify) a safety backup; return its path (blocking).
+
+    The copy is made in a temp file beside the database and only renamed
+    onto its final, unique name ``<db>.<label>_<stamp>`` once it is complete
+    (and verified), so a backup file on disk is always a whole one. ``label``
+    "backup" joins the pruned pool; another label (the workflow storage
+    migration's ``pre-workflow-storage``) is kept until the user removes it.
+    Raises SafetyBackupFailed, leaving no file.
+    """
+    db_path = os.path.abspath(model.db_path)
+    temp = safety_temp(db_path)
+    final = None
+    try:
+        if not model.backup_database(temp):
+            raise SafetyBackupFailed("The backup could not be written")
+        make_standalone(temp)
+        if verify:
+            ok, reason = model.verify_database_file(temp)
+            if not ok:
+                raise SafetyBackupFailed("The backup did not verify", reason)
+        fsync_file(temp)
+        if os.name != "nt":
+            os.chmod(temp, 0o600)
+        final = place_backup(temp, db_path, label)
+        return final
+    except OSError as exc:
+        remove_quietly(final)
+        raise SafetyBackupFailed("The backup could not be put in place") from exc
+    except SafetyBackupFailed:
+        remove_quietly(final)
+        raise
+    finally:
+        remove_quietly(temp, temp + "-journal", temp + "-wal", temp + "-shm")

database/workflow_documents.py

@@ -0,0 +1,652 @@
+"""Each workflow and prompt graph stored once, compressed (#249 S6 carry-over).
+
+``generated_images.workflow_data`` (the UI workflow) and ``prompt_metadata``
+(the API prompt graph) used to hold the same large JSON text again for every
+image of a run. Now each distinct text is one ``workflow_documents`` row:
+
+- ``sha256``: the SHA-256 of the text's exact UTF-8 bytes (unique key);
+- ``byte_length``: the length of those bytes;
+- ``data``: ``zlib.compress`` of those bytes.
+
+An image row references its texts through ``workflow_document_id`` and
+``prompt_document_id``. Two forms coexist until the migration has rewritten
+every row, and both stay readable forever:
+
+- old form: the text inline in ``workflow_data`` / ``prompt_metadata``, no id;
+- new form: the inline column NULL and the document id set.
+
+The text is stored and hashed exactly as written, never parsed and
+re-serialized, because a JSON round trip can change bytes (key order,
+spacing, number spelling, duplicate keys, ComfyUI's ``NaN`` tokens).
+
+``read_stored_text`` is the one decoder. Inline text, when present, wins (a
+row an older app version rewrote inline stays right); otherwise the document
+is read by its rowid, decompressed within its recorded length and checked
+against its length and hash. A document that fails a check reads as
+unreadable (None, logged), never as other text. ``resolve_image_row`` puts
+the texts back into a ``generated_images`` row and drops the id keys, so
+every payload keeps its shape.
+
+No trigger: every restore validator refuses triggers in a restored file. A
+document is removed in code: ``release_documents`` in the same transaction
+that drops a row's last reference, and ``sweep_documents`` (at startup, after
+the migration and before Reclaim space) for anything a path missed.
+"""
+
+import hashlib
+import logging
+import re
+import sqlite3
+import zlib
+from collections import OrderedDict
+from typing import Any, Dict, Iterable, Optional, Set
+
+logger = logging.getLogger("prompt_manager.database.workflow_documents")
+
+TABLE = "workflow_documents"
+# (inline text column, document id column) on generated_images.
+TEXT_COLUMNS = (
+    ("workflow_data", "workflow_document_id"),
+    ("prompt_metadata", "prompt_document_id"),
+)
+DOCUMENT_ID_COLUMNS = tuple(reference for _column, reference in TEXT_COLUMNS)
+INDEXES = {
+    "workflow_document_id": "idx_image_workflow_document",
+    "prompt_document_id": "idx_image_prompt_document",
+}
+COMPRESSION_LEVEL = 6
+# A text larger than this stays inline: a document is decompressed in one
+# piece, and its recorded length bounds that (a restored file cannot make a
+# small row expand without limit).
+MAX_DOCUMENT_BYTES = 256 * 2**20
+ID_BATCH = 400  # ids bound per statement (under SQLite's old 999 limit)
+
+_DDL = (
+    f"CREATE TABLE {TABLE} (id INTEGER PRIMARY KEY, sha256 BLOB NOT NULL UNIQUE, "
+    "byte_length INTEGER NOT NULL, data BLOB NOT NULL)"
+)
+_AUTOINDEX = f"sqlite_autoindex_{TABLE}_1"
+_REFERENCE_TYPE = f"INTEGER REFERENCES {TABLE}(id)"
+
+_UNREFERENCED = (
+    "NOT EXISTS (SELECT 1 FROM generated_images g "
+    "WHERE g.workflow_document_id=workflow_documents.id) "
+    "AND NOT EXISTS (SELECT 1 FROM generated_images g "
+    "WHERE g.prompt_document_id=workflow_documents.id)"
+)
+LOOKUP_SQL = (
+    "SELECT id, sha256, byte_length, data FROM workflow_documents WHERE sha256=?"
+)
+REPAIR_SQL = "UPDATE workflow_documents SET byte_length=?, data=? WHERE id=?"
+ALL_DOCUMENTS_SQL = "SELECT sha256, byte_length, data, id FROM workflow_documents"
+READ_SQL = "SELECT sha256, byte_length, data FROM workflow_documents WHERE id=?"
+INSERT_SQL = (
+    "INSERT INTO workflow_documents (sha256, byte_length, data) VALUES (?, ?, ?)"
+)
+# Built from constants only; the ids are bound as "?" marks.
+RELEASE_SQL = "DELETE FROM workflow_documents WHERE id IN ({marks}) AND "
+RELEASE_SQL += _UNREFERENCED
+# The sweep walks the ids through the small unique index, not the blobs.
+SWEEP_SQL = (
+    "DELETE FROM workflow_documents WHERE id IN (SELECT id FROM workflow_documents "
+    "INDEXED BY sqlite_autoindex_workflow_documents_1 WHERE "
+)
+SWEEP_SQL += _UNREFERENCED + ")"
+IMAGE_DOCUMENTS_SQL = (
+    "SELECT workflow_document_id, prompt_document_id FROM generated_images WHERE "
+)
+
+# Statements whose query plans tests/test_workflow_documents.py records.
+QUERY_PLAN_STATEMENTS = {
+    "lookup by hash": (LOOKUP_SQL, (b"\0" * 32,)),
+    "read by id": (READ_SQL, (1,)),
+    "release": (RELEASE_SQL.format(marks="?,?"), (1, 2)),
+    "sweep": (SWEEP_SQL, ()),
+    "documents of images": (IMAGE_DOCUMENTS_SQL + "id IN (?,?)", (1, 2)),
+    "documents of prompts": (IMAGE_DOCUMENTS_SQL + "prompt_id IN (?,?)", (1, 2)),
+}
+
+
+class DocumentMismatch(Exception):
+    """A document would not give back exactly the text it was made from."""
+
+
+def _compact(sql: str) -> str:
+    return re.sub(r"\s+", "", sql or "").lower()
+
+
+# ── schema ────────────────────────────────────────────────────────────
+
+
+def _reference_columns(conn: sqlite3.Connection) -> Dict[str, tuple]:
+    return {
+        row[1]: tuple(row)
+        for row in conn.execute("PRAGMA table_info(generated_images)")
+        if row[1] in DOCUMENT_ID_COLUMNS
+    }
+
+
+def _reference_error(conn: sqlite3.Connection, columns: Dict[str, tuple]):
+    for name, info in columns.items():
+        # (cid, name, type, notnull, default, pk)
+        if (str(info[2]).upper(), info[3], info[4], info[5]) != ("INTEGER", 0, None, 0):
+            return "Workflow document references have an invalid column"
+    keys = {
+        (row[3], row[2], row[4])
+        for row in conn.execute("PRAGMA foreign_key_list(generated_images)")
+        if row[3] in DOCUMENT_ID_COLUMNS
+    }
+    if keys != {(name, TABLE, "id") for name in DOCUMENT_ID_COLUMNS}:
+        return "Workflow document references have invalid foreign keys"
+    for column, index in INDEXES.items():
+        info = conn.execute(f'PRAGMA index_info("{index}")').fetchall()
+        owner = conn.execute(
+            "SELECT tbl_name FROM sqlite_master WHERE type='index' AND name=?",
+            (index,),
+        ).fetchone()
+        if [row[2] for row in info] != [column] or not owner:
+            return "Workflow document references are missing their index"
+        if owner[0] != "generated_images":
+            return "Workflow document references are missing their index"
+    return None
+
+
+def _value_error(conn: sqlite3.Connection):
+    if conn.execute(
+        "SELECT 1 FROM workflow_documents WHERE typeof(sha256)!='blob' "
+        "OR length(sha256)!=32 OR typeof(byte_length)!='integer' OR byte_length<0 "
+        "OR byte_length>? OR typeof(data)!='blob' LIMIT 1",
+        (MAX_DOCUMENT_BYTES,),
+    ).fetchone():
+        return "Workflow documents contain invalid values"
+    for column in DOCUMENT_ID_COLUMNS:
+        # typeof() reads no overflow page; a dangling id is a rowid probe.
+        # ``column`` is one of DOCUMENT_ID_COLUMNS, never caller data.
+        sql = (
+            f"SELECT 1 FROM generated_images g WHERE typeof(g.{column}) "  # nosec B608
+            f"NOT IN ('null','integer') OR (g.{column} IS NOT NULL AND NOT EXISTS "
+            f"(SELECT 1 FROM workflow_documents d WHERE d.id=g.{column})) LIMIT 1"
+        )
+        if conn.execute(sql).fetchone():
+            return "Workflow document references point at missing documents"
+    return None
+
+
+def damaged_message(document_id: int) -> str:
+    """The verify reason for a damaged document: which one, and what to do."""
+    return (
+        f"Workflow document {document_id} is damaged: its text no longer matches "
+        "its checksum, and the images that use it show no workflow. To fix it, "
+        "restore a backup from before the damage, or store a new image with the "
+        "same workflow (that repairs it)."
+    )
+
+
+def _damaged_document(conn: sqlite3.Connection) -> Optional[int]:
+    """The first document failing its length or hash check, or None."""
+    for row in conn.execute(ALL_DOCUMENTS_SQL):
+        if _decode(row[:3], row[3], quiet=True) is None:
+            return row[3]
+    return None
+
+
+def workflow_documents_schema_error(
+    conn: sqlite3.Connection, *, allow_missing: bool = True, documents: bool = False
+) -> Optional[str]:
+    """Reject an unsupported document schema or invalid stored values (reads only).
+
+    A database from before the dedupe has neither the table nor the id
+    columns; that is acceptable unless ``allow_missing`` is false. Half of
+    the schema never is.
+    """
+    objects = conn.execute(
+        "SELECT type,name,sql FROM sqlite_master WHERE name=? "
+        "OR (type IN ('index','trigger') AND tbl_name=?)",
+        (TABLE, TABLE),
+    ).fetchall()
+    has_images = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name='generated_images'"
+    ).fetchone()
+    columns = _reference_columns(conn) if has_images else {}
+    if not objects and not columns:
+        if allow_missing or not has_images:
+            return None
+        return "Missing workflow document schema"
+    if not objects or set(columns) != set(DOCUMENT_ID_COLUMNS):
+        return "Incomplete workflow document schema"
+    tables = [sql for kind, _name, sql in objects if kind == "table"]
+    others = {(kind, name, sql) for kind, name, sql in objects if kind != "table"}
+    if len(tables) != 1 or others != {("index", _AUTOINDEX, None)}:
+        return "Workflow documents name is reserved by an unsupported schema object"
+    # The exact definition fixes the columns, their types and constraints.
+    if _compact(tables[0]) != _compact(_DDL):
+        return "Workflow documents have an invalid table definition"
+    error = _reference_error(conn, columns) or _value_error(conn)
+    if error is None and documents:
+        # Restore and backup verification only: every document is read.
+        damaged = _damaged_document(conn)
+        if damaged is not None:
+            return damaged_message(damaged)
+    return error
+
+
+def migrate_workflow_documents(conn: sqlite3.Connection) -> None:
+    """Install the table, the id columns and their indexes atomically.
+
+    Runs after every older migration (the table rebuilds only run on
+    databases without ``file_path``, before this). Validates before and
+    after, then sweeps documents no row references.
+    """
+    conn.execute("SAVEPOINT workflow_documents_schema")
+    try:
+        error = workflow_documents_schema_error(conn)
+        if error:
+            raise sqlite3.DatabaseError(error)
+        conn.execute(_DDL.replace("CREATE TABLE", "CREATE TABLE IF NOT EXISTS", 1))
+        present = _reference_columns(conn)
+        for column in DOCUMENT_ID_COLUMNS:
+            if column not in present:
+                conn.execute(
+                    f"ALTER TABLE generated_images ADD COLUMN {column} "
+                    f"{_REFERENCE_TYPE}"
+                )
+        for column, index in INDEXES.items():
+            conn.execute(
+                f"CREATE INDEX IF NOT EXISTS {index} ON generated_images({column})"
+            )
+        error = workflow_documents_schema_error(conn, allow_missing=False)
+        if error:
+            raise sqlite3.DatabaseError(error)
+        sweep_documents(conn)
+        conn.execute("RELEASE workflow_documents_schema")
+    except BaseException:
+        conn.execute("ROLLBACK TO workflow_documents_schema")
+        conn.execute("RELEASE workflow_documents_schema")
+        raise
+
+
+# ── write ─────────────────────────────────────────────────────────────
+
+
+def storable(text: Any) -> bool:
+    """Whether ``text`` can be a document (text within MAX_DOCUMENT_BYTES)."""
+    if not isinstance(text, str):
+        return False
+    # UTF-8 takes at most 4 bytes a character: most texts need no encoding.
+    if len(text) * 4 <= MAX_DOCUMENT_BYTES:
+        return True
+    return len(text.encode("utf-8")) <= MAX_DOCUMENT_BYTES
+
+
+def store_text(
+    conn: sqlite3.Connection, text: Optional[str], verified: Optional[set] = None
+) -> Optional[int]:
+    """The id of the document holding exactly ``text``; None for None.
+
+    Reuses the document with the same hash, or inserts a new one whose
+    compressed bytes were checked to decompress to ``text``'s bytes. A reused
+    document is decompressed and checked first; a damaged one (a restored
+    file's corruption under a valid hash) is repaired from ``text``, whose
+    hash is its key, so every row that references it reads right again.
+    ``verified``, when given, holds the ids already checked (a migration
+    batch), which are then not read again. Opens a write transaction first
+    when none is open, so a concurrent ``release_documents`` cannot remove a
+    reused document before the caller references it. Raises TypeError for a
+    non-text value and ValueError for a text over MAX_DOCUMENT_BYTES.
+    """
+    if text is None:
+        return None
+    if not isinstance(text, str):
+        raise TypeError("Only text is stored as a workflow document")
+    raw = text.encode("utf-8")
+    if len(raw) > MAX_DOCUMENT_BYTES:
+        raise ValueError("Text is too large for a workflow document")
+    digest = hashlib.sha256(raw).digest()
+    if not conn.in_transaction:
+        conn.execute("BEGIN IMMEDIATE")
+    row = conn.execute(LOOKUP_SQL, (digest,)).fetchone()
+    if row is not None and verified is not None and row[0] in verified:
+        return row[0]
+    data = zlib.compress(raw, COMPRESSION_LEVEL)
+    if zlib.decompress(data) != raw:  # pragma: no cover - zlib is exact
+        raise DocumentMismatch("Compression did not round-trip")
+    if row is None:
+        document_id = conn.execute(INSERT_SQL, (digest, len(raw), data)).lastrowid
+    else:
+        document_id = row[0]
+        if _decode(row[1:], document_id, quiet=True) != text:
+            logger.warning(f"Workflow document {document_id} was damaged; repaired")
+            conn.execute(REPAIR_SQL, (len(raw), data, document_id))
+    if verified is not None:
+        verified.add(document_id)
+    return document_id
+
+
+def stored_values(
+    conn: sqlite3.Connection, texts: Dict[str, Optional[str]]
+) -> Dict[str, Any]:
+    """New-form column values for ``{text column: text}`` (writers).
+
+    Each text becomes ``{column: None, id column: document id}``; None
+    stays ``{column: None, id column: None}``; a value that cannot be a
+    document (not text, or too large) stays inline with no id.
+    """
+    references = dict(TEXT_COLUMNS)
+    values: Dict[str, Any] = {}
+    for column, text in texts.items():
+        reference = references[column]
+        if text is None or not storable(text):
+            values[column], values[reference] = text, None
+        else:
+            values[column], values[reference] = None, store_text(conn, text)
+    return values
+
+
+# ── read ──────────────────────────────────────────────────────────────
+
+
+def _decode(row, document_id, quiet=False) -> Optional[str]:
+    """``(sha256, byte_length, data)`` as checked text, or None (logged)."""
+    if row is None:
+        logger.warning(f"Workflow document {document_id} is missing")
+        return None
+    digest, length, data = bytes(row[0]), row[1], row[2]
+    try:
+        if not isinstance(length, int) or not 0 <= length <= MAX_DOCUMENT_BYTES:
+            raise ValueError("invalid length")
+        inflater = zlib.decompressobj()
+        raw = inflater.decompress(bytes(data), length + 1)
+        if len(raw) != length or inflater.unconsumed_tail or not inflater.eof:
+            raise ValueError("length differs")
+        if hashlib.sha256(raw).digest() != digest:
+            raise ValueError("hash differs")
+        return raw.decode("utf-8")
+    except (zlib.error, ValueError, TypeError) as error:
+        if not quiet:
+            logger.warning(f"Workflow document {document_id} is unreadable: {error}")
+        return None
+
+
+def read_stored_text(
+    conn: sqlite3.Connection, inline: Any, document_id: Optional[int]
+) -> Any:
+    """The stored text of one column: inline when present, else the document.
+
+    Returns None when there is neither, or when the document is missing or
+    fails its checks (logged). An inline value is returned unchanged.
+    """
+    if inline is not None:
+        return inline
+    if document_id is None:
+        return None
+    return _decode(conn.execute(READ_SQL, (document_id,)).fetchone(), document_id)
+
+
+class DocumentReader:
+    """``read_stored_text`` with a small memo for list reads on one connection."""
+
+    MEMO = 32
+
+    def __init__(self, conn: sqlite3.Connection):
+        self.conn = conn
+        self._memo: "OrderedDict[int, Optional[str]]" = OrderedDict()
+
+    def text(self, inline: Any, document_id: Optional[int]) -> Any:
+        if inline is not None or document_id is None:
+            return read_stored_text(self.conn, inline, document_id)
+        if document_id in self._memo:
+            self._memo.move_to_end(document_id)
+            return self._memo[document_id]
+        text = read_stored_text(self.conn, None, document_id)
+        self._memo[document_id] = text
+        if len(self._memo) > self.MEMO:
+            self._memo.popitem(last=False)
+        return text
+
+
+def resolve_image_row(reader: DocumentReader, row) -> Dict[str, Any]:
+    """A ``generated_images`` row as a dict with its texts read back.
+
+    The id columns are dropped, so a payload built from it has the shape it
+    had before the dedupe. Columns the row did not select stay absent.
+    """
+    data = dict(row)
+    for column, reference in TEXT_COLUMNS:
+        has_reference = reference in data
+        document_id = data.pop(reference, None)
+        if column in data or has_reference:
+            data[column] = reader.text(data.get(column), document_id)
+    return data
+
+
+# ── garbage ───────────────────────────────────────────────────────────
+
+
+def _chunks(values):
+    values = list(values)
+    for start in range(0, len(values), ID_BATCH):
+        yield values[start : start + ID_BATCH]
+
+
+def image_documents(conn: sqlite3.Connection, where: str, params) -> Set[int]:
+    """The document ids the image rows matching ``where`` reference.
+
+    ``where`` is a fixed condition written in this package (``id IN (...)``,
+    ``prompt_id IN (...)``), never caller data; values go in ``params``.
+    """
+    ids: Set[int] = set()
+    sql = IMAGE_DOCUMENTS_SQL + where
+    for row in conn.execute(sql, list(params)):  # nosec B608
+        ids.update(value for value in row if value is not None)
+    return ids
+
+
+def documents_of_rows(
+    conn: sqlite3.Connection, column: str, values: Iterable[Any]
+) -> Set[int]:
+    """Document ids of the image rows whose ``column`` is in ``values``.
+
+    ``column`` is ``id`` or ``prompt_id`` (the rows a prompt delete cascades to).
+    """
+    if column not in ("id", "prompt_id"):
+        raise ValueError(f"Unsupported column {column!r}")
+    ids: Set[int] = set()
+    for chunk in _chunks(values):
+        marks = ",".join("?" for _ in chunk)
+        ids |= image_documents(conn, f"{column} IN ({marks})", chunk)
+    return ids
+
+
+def release_documents(conn: sqlite3.Connection, ids: Iterable[Optional[int]]) -> int:
+    """Delete the documents in ``ids`` that no image row references now.
+
+    Runs in the caller's transaction, right after the delete or update that
+    dropped the references. Returns how many documents were removed.
+    """
+    removed = 0
+    for chunk in _chunks(sorted({i for i in ids if i is not None})):
+        marks = ",".join("?" for _ in chunk)
+        # Only "?" marks are interpolated.
+        sql = RELEASE_SQL.format(marks=marks)
+        removed += conn.execute(sql, chunk).rowcount  # nosec B608
+    return removed
+
+
+def sweep_documents(conn: sqlite3.Connection) -> int:
+    """Delete every document no image row references; returns the count."""
+    return conn.execute(SWEEP_SQL).rowcount
+
+
+# ── repair (a restore's stage) ────────────────────────────────────────
+
+INLINE_TEXTS_SQL = (
+    "SELECT workflow_data, prompt_metadata FROM generated_images "
+    "WHERE workflow_data IS NOT NULL OR prompt_metadata IS NOT NULL"
+)
+REKEY_SQL = "UPDATE workflow_documents SET sha256=?, byte_length=? WHERE id=?"
+
+
+def _rows(conn: sqlite3.Connection, sql: str, params=()):
+    """Each row of ``sql``, read one at a time.
+
+    Iterating a managed connection's cursor prefetches ``ITER_CHUNK`` (128)
+    rows, and a document or inline text can be megabytes.
+    """
+    cursor = conn.execute(sql, params)
+    while (row := cursor.fetchone()) is not None:
+        yield row
+
+
+def _inflated(data) -> Optional[bytes]:
+    """The complete text bytes ``data`` inflates to, or None.
+
+    Complete means the zlib stream ends (its Adler-32 checked) within
+    MAX_DOCUMENT_BYTES with nothing after it: the body is intact even when
+    the row's recorded hash or length is not.
+    """
+    try:
+        inflater = zlib.decompressobj()
+        raw = inflater.decompress(bytes(data), MAX_DOCUMENT_BYTES + 1)
+        if not inflater.eof or inflater.unconsumed_tail or inflater.unused_data:
+            return None
+        if len(raw) > MAX_DOCUMENT_BYTES:
+            return None
+        raw.decode("utf-8")
+        return raw
+    except (zlib.error, TypeError, UnicodeDecodeError):
+        return None
+
+
+def _one_column_off(row, raw: bytes) -> bool:
+    """Whether only the recorded hash or only the recorded length is wrong.
+
+    The two columns check the body independently. When the body inflates
+    completely and one of them still agrees with it, that column vouches for
+    the body and the other one is the damaged value. When both disagree, the
+    body itself is the suspect (another valid stream), so it is not trusted.
+    """
+    hash_ok = hashlib.sha256(raw).digest() == bytes(row[0])
+    length_ok = row[1] == len(raw)
+    return hash_ok != length_ok
+
+
+def _inline_copies(conn: sqlite3.Connection, wanted: Dict[bytes, int]):
+    """``{document id: text}`` for each wanted hash an inline row still holds."""
+    found: Dict[int, str] = {}
+    for row in _rows(conn, INLINE_TEXTS_SQL):
+        for text in row:
+            if not isinstance(text, str) or not storable(text):
+                continue
+            document_id = wanted.get(hashlib.sha256(text.encode("utf-8")).digest())
+            if document_id is not None and document_id not in found:
+                found[document_id] = text
+        if len(found) == len(wanted):
+            break
+    return found
+
+
+def _rekey(conn: sqlite3.Connection, document_id: int, raw: bytes) -> Optional[int]:
+    """Give an intact body its true key, or merge it into the document that has it.
+
+    Returns the holder's id when its own body was damaged and has just been
+    rewritten from ``raw`` (it is repaired, never to be cleared), else None.
+    """
+    digest = hashlib.sha256(raw).digest()
+    holder = conn.execute(LOOKUP_SQL, (digest,)).fetchone()
+    if holder is None or holder[0] == document_id:
+        conn.execute(REKEY_SQL, (digest, len(raw), document_id))
+        return None
+    for column in DOCUMENT_ID_COLUMNS:
+        # ``column`` is one of DOCUMENT_ID_COLUMNS, never caller data.
+        conn.execute(
+            f"UPDATE generated_images SET {column}=? WHERE {column}=?",  # nosec B608
+            (holder[0], document_id),
+        )
+    conn.execute("DELETE FROM workflow_documents WHERE id=?", (document_id,))
+    if _decode(holder[1:], holder[0], quiet=True) is None:
+        conn.execute(
+            REPAIR_SQL, (len(raw), zlib.compress(raw, COMPRESSION_LEVEL), holder[0])
+        )
+        return holder[0]
+    return None
+
+
+def repair_damaged_documents(conn: sqlite3.Connection) -> Dict[str, int]:
+    """Repair or clear every document failing its checks; commit (writes).
+
+    For a restore's stage only, never the live library. In order:
+
+    1. A document whose body inflates completely and whose recorded hash or
+       length (not both) disagrees is re-keyed from its text, or merged
+       into the document that already holds that text (``_one_column_off``).
+    2. A damaged body whose exact text an inline row still holds (the same
+       SHA-256, its key) is stored again from that text.
+    3. Any other damaged document is unreadable for good: its images'
+       references are cleared (they already showed no workflow) and the
+       document is removed, so the stage verifies.
+
+    Returns ``{repaired, cleared, images}``: documents repaired (1 and 2),
+    documents cleared and the distinct image rows whose reference was
+    cleared. Rows are read one at a time.
+    """
+    damaged: Dict[bytes, int] = {}
+    intact: Dict[int, bytes] = {}
+    for row in _rows(conn, ALL_DOCUMENTS_SQL):
+        if _decode(row[:3], row[3], quiet=True) is None:
+            raw = _inflated(row[2])
+            if raw is not None and _one_column_off(row, raw):
+                intact[row[3]] = raw
+            else:
+                damaged[bytes(row[0])] = row[3]
+    result = {"repaired": 0, "cleared": 0, "images": 0}
+    if not damaged and not intact:
+        return result
+    with conn:
+        healed = []
+        for document_id, raw in intact.items():
+            holder = _rekey(conn, document_id, raw)
+            if holder is not None and holder in damaged.values():
+                # Rewritten from the merged body: repaired, not to be cleared
+                # (it now also holds the merged images' references).
+                damaged = {k: v for k, v in damaged.items() if v != holder}
+                healed.append(holder)
+        copies = _inline_copies(conn, damaged) if damaged else {}
+        for document_id, text in copies.items():
+            raw = text.encode("utf-8")
+            data = zlib.compress(raw, COMPRESSION_LEVEL)
+            conn.execute(REPAIR_SQL, (len(raw), data, document_id))
+        lost = sorted(set(damaged.values()) - set(copies))
+        images: Set[int] = set()
+        for chunk in _chunks(lost):
+            marks = ",".join("?" * len(chunk))
+            # ``marks`` is only "?" placeholders; the ids are bound.
+            for (image_id,) in _rows(
+                conn,
+                "SELECT id FROM generated_images WHERE "  # nosec B608
+                f"workflow_document_id IN ({marks}) OR prompt_document_id IN ({marks})",
+                chunk + chunk,
+            ):
+                images.add(image_id)
+            for column in DOCUMENT_ID_COLUMNS:
+                conn.execute(
+                    f"UPDATE generated_images SET {column}=NULL "  # nosec B608
+                    f"WHERE {column} IN ({marks})",
+                    chunk,
+                )
+            conn.execute(
+                f"DELETE FROM workflow_documents WHERE id IN ({marks})",  # nosec B608
+                chunk,
+            )
+    for document_id in list(intact) + healed + list(copies):
+        logger.warning(f"Workflow document {document_id} was damaged; repaired")
+    if lost:
+        logger.warning(
+            f"{len(lost)} damaged workflow document(s) could not be repaired; "
+            f"{len(images)} image(s) show no workflow"
+        )
+    result.update(
+        repaired=len(intact) + len(healed) + len(copies),
+        cleared=len(lost),
+        images=len(images),
+    )
+    return result

database/workflow_storage.py

@@ -0,0 +1,455 @@
+"""The workflow storage migration and Reclaim space (#249 S6 carry-over).
+
+``migrate_workflow_storage`` rewrites old-form image rows (workflow and
+prompt graph text inline) to the new form (a ``workflow_documents`` id,
+``database/workflow_documents.py``) in batches:
+
+- each batch is one ``BEGIN IMMEDIATE`` transaction over at most
+  ``BATCH_ROWS`` rows or about ``BATCH_BYTES`` of text, found by a rowid
+  range search (``NEXT_IDS_SQL``) and read one row at a time, so memory is
+  bounded by one row plus the batch's distinct documents;
+- each text is stored (or its document reused) and read back through the
+  one accessor before its row changes; a text that would not come back
+  identical fails the batch (``DocumentMismatch``) and rolls it back whole;
+- a value that is not text (or is over ``MAX_DOCUMENT_BYTES``) stays inline
+  and is counted as protected;
+- each row runs in its own savepoint: one that cannot be rewritten (text
+  SQLite cannot decode, a text that would not come back) stays inline and
+  is listed, and the rest of the batch goes on;
+- a batch ends after ``BATCH_SECONDS``, and the write lock is then left
+  free for ``BATCH_PAUSE``, so other writers are never starved.
+
+A crash or a stop between batches leaves committed batches in the new form
+and the rest in the old form; both read the same, and a rerun continues
+from the first old-form row. Only database rows change: no image or video
+file is opened.
+
+``reclaim_space`` is the VACUUM afterwards: it sweeps unreferenced
+documents, rebuilds the file and checkpoints the WAL with TRUNCATE, so the
+freed pages go back to the disk.
+"""
+
+import logging
+import os
+import sqlite3
+import time
+from contextlib import closing
+
+from .workflow_documents import (
+    TEXT_COLUMNS,
+    DocumentMismatch,
+    read_stored_text,
+    release_documents,
+    storable,
+    store_text,
+    sweep_documents,
+)
+
+OPERATION = "workflow_storage"
+# The first apply's backup: ``<db>.pre-workflow-storage_<stamp>``, outside the
+# pruned ``<db>.backup_*`` pool. Only one is ever made; later applies take a
+# pooled safety backup.
+PRE_MIGRATION_LABEL = "pre-workflow-storage"
+BATCH_ROWS = 200
+BATCH_BYTES = 16 * 2**20  # characters of text rewritten per transaction
+# A batch holds the write lock: it ends after this long, and the loop then
+# leaves the lock free for BATCH_PAUSE, longer than SQLite's longest busy
+# poll (100 ms), so the image monitor and the run counting get in between.
+BATCH_SECONDS = 0.5
+BATCH_PAUSE = 0.15
+
+
+def _row_error(error) -> bool:
+    """Whether ``error`` is one row's own cause, which keeps only that row inline.
+
+    Text SQLite cannot decode for Python, and a text that would not come
+    back identical. Anything else (a full disk, an I/O error, a malformed
+    database, a bug) fails the whole batch. The decode error is matched by
+    its message: ``sqlite_errorcode`` needs Python 3.11.
+    """
+    if isinstance(error, (DocumentMismatch, UnicodeError)):
+        return True
+    return isinstance(error, sqlite3.OperationalError) and str(error).startswith(
+        "Could not decode"
+    )
+
+
+logger = logging.getLogger("prompt_manager.database.workflow_storage")
+_clock = time.monotonic
+
+# typeof() reads a column's type from the record header: no overflow page.
+NEXT_IDS_SQL = (
+    "SELECT id FROM generated_images WHERE id>? AND "
+    "(typeof(workflow_data)!='null' OR typeof(prompt_metadata)!='null') "
+    "ORDER BY id LIMIT ?"
+)
+ROW_SQL = (
+    "SELECT workflow_data, prompt_metadata, workflow_document_id, "
+    "prompt_document_id FROM generated_images WHERE id=?"
+)
+UPDATE_SQL = (
+    "UPDATE generated_images SET {assignments} WHERE id=?"  # columns are constants
+)
+# One pass over the record headers: rows with inline text, and inline
+# values that are not text (they stay inline).
+INLINE_COUNTS_SQL = (
+    "SELECT "
+    "SUM(typeof(workflow_data)='text' OR typeof(prompt_metadata)='text'), "
+    "SUM(typeof(workflow_data) NOT IN ('null','text')) "
+    "+ SUM(typeof(prompt_metadata) NOT IN ('null','text')) "
+    "FROM generated_images"
+)
+# octet_length() (SQLite 3.43+) reads no overflow page either.
+INLINE_BYTES_SQL = (
+    "SELECT SUM(octet_length(workflow_data)), SUM(octet_length(prompt_metadata)) "
+    "FROM generated_images"
+)
+
+QUERY_PLAN_STATEMENTS = {
+    "next old-form rows": (NEXT_IDS_SQL, (0, BATCH_ROWS)),
+    "one row": (ROW_SQL, (1,)),
+}
+
+
+def _rewrite_row(conn, image_id, row, verified, checked):
+    """Store the row's inline texts as documents; returns (changed, protected, size).
+
+    ``verified`` maps document ids already read back in this batch to their
+    text, and ``checked`` holds the reused ids ``store_text`` already
+    checked, so a document shared by many rows is decompressed once.
+    """
+    changes, replaced = {}, []
+    protected = size = 0
+    for index, (column, reference) in enumerate(TEXT_COLUMNS):
+        value, current = row[index], row[index + len(TEXT_COLUMNS)]
+        if value is None:
+            continue
+        if not storable(value):
+            protected += 1
+            continue
+        document_id = store_text(conn, value, checked)
+        if document_id not in verified:
+            verified[document_id] = read_stored_text(conn, None, document_id)
+        if verified[document_id] != value:
+            raise DocumentMismatch(f"Image {image_id}: {column} would change")
+        changes[column], changes[reference] = None, document_id
+        if current is not None and current != document_id:
+            replaced.append(current)
+        size += len(value)
+    if changes:
+        assignments = ",".join(f"{key}=?" for key in changes)
+        conn.execute(
+            UPDATE_SQL.format(assignments=assignments),
+            [*changes.values(), image_id],
+        )
+    release_documents(conn, replaced)
+    return bool(changes), protected, size
+
+
+def migrate_batch(
+    conn,
+    after_id,
+    max_rows=BATCH_ROWS,
+    max_bytes=BATCH_BYTES,
+    max_seconds=BATCH_SECONDS,
+):
+    """Rewrite the next batch after ``after_id`` in one transaction.
+
+    The batch ends after ``max_rows`` rows, about ``max_bytes`` of text or
+    ``max_seconds``, whichever comes first. Each row runs in its own
+    savepoint: a row that cannot be rewritten (``_row_error``) is rolled
+    back alone, stays inline and is listed in ``errors``; anything else rolls
+    the whole batch back and propagates. Returns ``{last_id, rows,
+    protected, errors, done}``: the last row looked at, rows rewritten,
+    inline values kept (not text), the ids kept by an error and whether
+    there was nothing left to look at.
+    """
+    if conn.in_transaction:
+        raise RuntimeError("The migration needs its own transaction")
+    started = _clock()
+    conn.execute("BEGIN IMMEDIATE")
+    try:
+        ids = [row[0] for row in conn.execute(NEXT_IDS_SQL, (after_id, max_rows))]
+        result = {
+            "last_id": after_id,
+            "rows": 0,
+            "protected": 0,
+            "errors": [],
+            "done": not ids,
+        }
+        verified, checked, size = {}, set(), 0
+        for image_id in ids:
+            conn.execute("SAVEPOINT workflow_row")
+            try:
+                row = conn.execute(ROW_SQL, (image_id,)).fetchone()
+                changed, protected, row_size = _rewrite_row(
+                    conn, image_id, row, verified, checked
+                )
+            except Exception as error:
+                if not _row_error(error):
+                    raise
+                conn.execute("ROLLBACK TO workflow_row")
+                conn.execute("RELEASE workflow_row")
+                verified.clear()  # the row's documents were rolled back too
+                checked.clear()
+                logger.warning(f"Image record {image_id} kept inline: {error}")
+                result["errors"].append(image_id)
+                changed, protected, row_size = False, 0, 0
+            else:
+                conn.execute("RELEASE workflow_row")
+            result["rows"] += int(changed)
+            result["protected"] += protected
+            result["last_id"] = image_id
+            size += row_size
+            if size >= max_bytes or _clock() - started >= max_seconds:
+                break
+        conn.commit()
+        return result
+    except BaseException:
+        conn.rollback()
+        raise
+
+
+def pre_migration_backups(db_path):
+    """The kept pre-migration backups beside ``db_path``, earliest first."""
+    db_path = os.path.abspath(db_path)
+    prefix = os.path.basename(db_path) + "." + PRE_MIGRATION_LABEL + "_"
+    folder = os.path.dirname(db_path)
+    try:
+        names = os.listdir(folder)
+    except OSError:
+        return []
+    return sorted(
+        name
+        for name in names
+        if name.startswith(prefix) and os.path.isfile(os.path.join(folder, name))
+    )
+
+
+def _file_bytes(db_path):
+    return sum(
+        os.path.getsize(path)
+        for path in (db_path, db_path + "-wal")
+        if os.path.exists(path)
+    )
+
+
+class WorkflowStorageOperations:
+    """PromptDatabase mixin: the workflow storage migration and Reclaim space."""
+
+    def migrate_workflow_storage(
+        self,
+        *,
+        on_batch=None,
+        should_stop=None,
+        max_rows=BATCH_ROWS,
+        max_bytes=BATCH_BYTES,
+    ) -> dict:
+        """Rewrite every old-form row, batch by batch (blocking).
+
+        ``on_batch(progress)`` runs after each committed batch with the
+        running totals ``{rows, protected, batches, last_id}``;
+        ``should_stop()`` is asked before each batch. Each committed batch is
+        followed by ``BATCH_PAUSE`` with the write lock free. Returns
+        ``{rows, protected, batches, stopped, errors, documents_removed}``
+        (``errors``: the ids of rows kept inline by an error). Unreferenced
+        documents are swept once every row was looked at.
+        """
+        totals = {"rows": 0, "protected": 0, "batches": 0, "last_id": 0}
+        errors = []
+        stopped = False
+        while True:
+            if should_stop is not None and should_stop():
+                stopped = True
+                break
+            batch = self.migrate_workflow_batch(totals["last_id"], max_rows, max_bytes)
+            if batch["done"]:
+                break
+            time.sleep(BATCH_PAUSE)  # leave the write lock to other writers
+            errors += batch["errors"]
+            totals["rows"] += batch["rows"]
+            totals["protected"] += batch["protected"]
+            totals["batches"] += 1
+            totals["last_id"] = batch["last_id"]
+            if on_batch is not None:
+                on_batch(dict(totals))
+        removed = 0 if stopped else self.sweep_workflow_documents()
+        return {
+            "rows": totals["rows"],
+            "protected": totals["protected"],
+            "batches": totals["batches"],
+            "stopped": stopped,
+            "errors": errors,
+            "documents_removed": removed,
+        }
+
+    def migrate_workflow_batch(
+        self, after_id, max_rows=BATCH_ROWS, max_bytes=BATCH_BYTES
+    ) -> dict:
+        """One batch on the calling thread's connection (``migrate_batch``)."""
+        return migrate_batch(self.model.get_connection(), after_id, max_rows, max_bytes)
+
+    def sweep_workflow_documents(self) -> int:
+        """Remove every document no image row references (one transaction)."""
+        conn = self.model.get_connection()
+        with conn:
+            return sweep_documents(conn)
+
+    def workflow_storage_status(self) -> dict:
+        """``workflow_storage_counts`` on one read-only snapshot (blocking)."""
+        from .maintenance import _read_snapshot
+
+        return _read_snapshot(self.model.db_path, self.workflow_storage_counts)
+
+    def workflow_storage_counts(self, conn) -> dict:
+        """``{rows, protected, documents, inline_bytes}`` on ``conn`` (reads only).
+
+        ``inline_bytes`` is None where SQLite has no ``octet_length``.
+        """
+        rows, protected = conn.execute(INLINE_COUNTS_SQL).fetchone()
+        documents = conn.execute("SELECT COUNT(*) FROM workflow_documents").fetchone()
+        inline_bytes = None
+        if sqlite3.sqlite_version_info >= (3, 43, 0):
+            row = conn.execute(INLINE_BYTES_SQL).fetchone()
+            inline_bytes = sum(value or 0 for value in row)
+        return {
+            "rows": rows or 0,
+            "protected": protected or 0,
+            "documents": documents[0],
+            "inline_bytes": inline_bytes,
+        }
+
+    def reclaim_space(self) -> dict:
+        """Sweep, VACUUM and truncate the WAL (blocking); file bytes before/after.
+
+        The caller holds the registry's ``exclusive`` slot. Raises whatever
+        stopped VACUUM; the database is then unchanged.
+        """
+        db_path = self.model.db_path
+        removed = self.sweep_workflow_documents()
+        before = _file_bytes(db_path)
+        self.model.vacuum_database()
+        with closing(sqlite3.connect(db_path)) as checkpoint:
+            busy = checkpoint.execute("PRAGMA wal_checkpoint(TRUNCATE)").fetchone()[0]
+        return {
+            "before_bytes": before,
+            "after_bytes": _file_bytes(db_path),
+            "documents_removed": removed,
+            "checkpoint_busy": bool(busy),
+        }
+
+    # ── preview ───────────────────────────────────────────────────────
+
+    def _plan_workflow_storage(self):
+        """The reviewed plan of the migration (one read-only snapshot)."""
+        from .maintenance import (
+            MaintenanceDraft,
+            _Fingerprint,
+            _megabytes,
+            _plural,
+            _read_snapshot,
+        )
+
+        def read(conn):
+            sizes = [
+                conn.execute(f"PRAGMA {name}").fetchone()[0]
+                for name in ("page_size", "page_count", "freelist_count")
+            ]
+            return sizes, self.workflow_storage_counts(conn)
+
+        (page_size, page_count, free_pages), counts = _read_snapshot(
+            self.model.db_path, read
+        )
+        size = page_size * page_count
+        details = [
+            {
+                "label": "Database file",
+                "detail": f"{_megabytes(size)}, of which "
+                f"{_megabytes(free_pages * page_size)} is free pages",
+            },
+            {
+                "label": "Image records",
+                "detail": f"{_plural(counts['rows'], 'record')} keep their workflow "
+                "or prompt graph inline; each distinct text is stored once, "
+                "compressed",
+            },
+        ]
+        if not counts["rows"]:
+            details[1]["detail"] = NOTHING_TO_DO
+        if counts["inline_bytes"] is not None:
+            details.append(
+                {
+                    "label": "Inline text",
+                    "detail": f"{_megabytes(counts['inline_bytes'])} now",
+                }
+            )
+        if counts["documents"]:
+            details.append(
+                {
+                    "label": "Already stored once",
+                    "detail": _plural(counts["documents"], "workflow document"),
+                }
+            )
+        name = os.path.basename(self.model.db_path)
+        kept = pre_migration_backups(self.model.db_path)
+        backup = (
+            POOLED_BACKUP_NOTE.format(
+                name=f"{name}.backup_<date and time>", kept=kept[0]
+            )
+            if kept
+            else BACKUP_NOTE.format(
+                name=f"{name}.{PRE_MIGRATION_LABEL}_<date and time>"
+            )
+        )
+        details += [
+            {"label": "Backup", "detail": backup},
+            {"label": "Reclaim space", "detail": RECLAIM_NOTE},
+            {"label": "Older versions", "detail": OLDER_VERSIONS_NOTE},
+        ]
+        protected = counts["protected"]
+        return MaintenanceDraft(
+            operation=OPERATION,
+            fingerprint=_Fingerprint(OPERATION).hexdigest(),
+            targets=[],
+            scope={
+                "count": counts["rows"],
+                "label": (
+                    _plural(counts["rows"], "image record") + " to rewrite"
+                    if counts["rows"]
+                    else "Nothing to rewrite"
+                ),
+            },
+            protected={
+                "count": protected,
+                "reasons": (
+                    [f"{_plural(protected, 'stored value')} not text; kept as is"]
+                    if protected
+                    else []
+                ),
+            },
+            media={"deletes_files": False, "label": MEDIA_NOTE},
+            details=details,
+        )
+
+
+MEDIA_NOTE = "No image or video file is opened or changed; only the database."
+RECLAIM_NOTE = (
+    "When every record is rewritten, Reclaim space runs alone to give the freed "
+    "space back to the disk (VACUUM). The database is locked while it runs."
+)
+BACKUP_NOTE = (
+    "Always taken first, whatever the safety backup setting: {name} beside "
+    "the database, verified, and kept until you remove it (it is never pruned)."
+)
+POOLED_BACKUP_NOTE = (
+    "A safety backup is taken first, whatever the safety backup setting: {name} "
+    "among the pooled backups; the pre-migration backup {kept} is already kept."
+)
+NOTHING_TO_DO = "Every image record already stores its workflow once."
+OLDER_VERSIONS_NOTE = (
+    "This version stores the workflows of images it records in the new form, "
+    "whether or not this job runs, and this job rewrites the rest. An older "
+    "Prompt Manager version shows those images without their workflow until you "
+    "update again. The way back to an older version is the earliest "
+    "pre-workflow-storage backup."
+)

prompt_manager.py

@@ -238,6 +238,9 @@ class PromptManager(PromptManagerBase, ComfyNodeABC):
             except Exception as e:
                 # Log error but don't fail the encoding
                 self.logger.warning(f"Failed to save prompt to database: {e}")
+                self._mark_untracked(prompt, unique_id)
+        else:
+            self._skip_empty_prompt(prompt, unique_id)
 
         # Perform standard CLIP text encoding using the combined text
         self.logger.debug(

prompt_manager_base.py

@@ -24,6 +24,7 @@ try:
     from .utils.prompt_tracker import get_prompt_tracker
     from .utils.hashing import generate_prompt_hash
     from .utils.prompt_graph import resolve_text, run_prompt_nodes
+    from .utils.run_keys import executing_run_id, prompt_node_key
     from .utils.usage_tracking import PENDING_FIRST_USE
 except ImportError:
     import sys
@@ -35,6 +36,7 @@ except ImportError:
     from utils.prompt_tracker import get_prompt_tracker
     from utils.hashing import generate_prompt_hash
     from utils.prompt_graph import resolve_text, run_prompt_nodes
+    from utils.run_keys import executing_run_id, prompt_node_key
     from utils.usage_tracking import PENDING_FIRST_USE
 
 
@@ -168,14 +170,67 @@ class PromptManagerBase:
         prompt_id = self._save_prompt_to_database(
             text=text, category=category, tags=tags, count_run=batch_item
         )
-        if prompt_id and role["is_run_prompt"]:
+        if role["is_run_prompt"] and not prompt_id:
+            # The save failed: an older entry of this key must not stand in (#342)
+            self._mark_untracked(prompt_graph, unique_id)
+        elif role["is_run_prompt"]:
             self.prompt_tracker.set_current_prompt(
                 prompt_text=encoding_text,
                 additional_data={**additional_data, "prompt_id": prompt_id},
                 push_to_queue=batch_item or not role["known"],
+                **self._run_identity(prompt_graph, unique_id),
             )
         return prompt_id
 
+    @staticmethod
+    def _run_identity(prompt_graph: Any, unique_id: Any) -> Dict[str, Any]:
+        """The tracker's proof that an image belongs to this execution (#342)."""
+        return {
+            "run_key": prompt_node_key(prompt_graph, unique_id),
+            "run_id": executing_run_id(),
+        }
+
+    def _skip_empty_prompt(self, prompt_graph: Any, unique_id: Any) -> None:
+        """The ``text`` editor is empty: save and track nothing (#342).
+
+        Prepend and append text are deliberately never stored as the prompt, so
+        an empty editor has no prompt to save, count or link. For the run's
+        positive node this is logged at info and the node's run key is marked
+        empty (``_mark_untracked``).
+        """
+        self._mark_untracked(
+            prompt_graph,
+            unique_id,
+            "Prompt text is empty (prepend and append text are not stored): "
+            "nothing saved or tracked, and this run's images stay unlinked",
+        )
+
+    def _mark_untracked(
+        self, prompt_graph: Any, unique_id: Any, message: Optional[str] = None
+    ) -> None:
+        """This execution of a positive node has no prompt to link (#342).
+
+        An empty editor, or a save or tracking failure. The node's run key is
+        marked with a placeholder, so no earlier prompt of that key can be
+        linked to this run's images, and a batch item keeps its queue place.
+        ``message`` is logged at info for a positive node.
+        """
+        try:
+            role = self._prompt_role(prompt_graph, unique_id, "")
+            if not role["is_run_prompt"]:
+                if message:
+                    self.logger.debug("Empty text on a non-positive node; not saved")
+                return
+            if message:
+                self.logger.info(message)
+            self.prompt_tracker.mark_empty(
+                push_to_queue=role["known"],
+                **self._run_identity(prompt_graph, unique_id),
+            )
+        except Exception as error:
+            # Tracking must never block generation
+            self.logger.warning(f"Could not mark the untracked prompt: {error}")
+
     def _record_use(self, prompt_id: int, times: int = 1) -> None:
         """Count runs; a tracking failure must never block generation."""
         try:

prompt_manager_pair.py

@@ -117,85 +117,29 @@ class PromptManagerPair(PromptManagerFocused):
         )
         is_positive = "text" in used_fields
         pair_used = node_id in intrinsic_pair_nodes(prompt) if known else True
-        try:
-            pair_id = self.db.save_prompt_pair(
-                text,
-                negative_text,
-                category=category.strip() or None,
-                tags=self._parse_tags(tags),
-            )
-            pair = self.db.get_prompt_pair(pair_id)
-            prompt_id = pair["positive_prompt_id"]
-            resolved_positive = (
-                resolve_text_input(prompt, node_id, "text") if known else None
-            )
-            resolved_negative = (
-                resolve_text_input(prompt, node_id, "negative_text") if known else None
-            )
-            positive_seen = resolved_positive is not None and generate_prompt_hash(
-                resolved_positive
-            ) == generate_prompt_hash(text)
-            pair_seen = (
-                positive_seen
-                and resolved_negative is not None
-                and generate_prompt_hash(resolved_negative)
-                == generate_prompt_hash(negative_text)
-            )
-            positive_pending = getattr(self, "pending_first_use", PENDING_FIRST_USE)
-            pair_pending = getattr(
-                self, "pending_pair_first_use", PENDING_PAIR_FIRST_USE
-            )
-            counted = set()
-            for field, component_text, resolved_text, component_id in (
-                ("text", text, resolved_positive, prompt_id),
-                (
-                    "negative_text",
+        if not text.strip():
+            # Nothing to store: prepend/append are never the stored prompt (#342)
+            self._skip_empty_prompt(prompt, unique_id)
+        else:
+            try:
+                pair_id, prompt_id = self._save_and_track_pair(
+                    text,
                     negative_text,
-                    resolved_negative,
-                    pair["negative_prompt_id"],
-                ),
-            ):
-                component_hash = generate_prompt_hash(component_text)
-                if (
-                    field not in used_fields
-                    or not component_id
-                    or component_hash in counted
-                ):
-                    continue
-                counted.add(component_hash)
-                seen_at_queue = (
-                    resolved_text is not None
-                    and generate_prompt_hash(resolved_text) == component_hash
+                    positive,
+                    category=category,
+                    tags=tags,
+                    prepend_text=prepend_text,
+                    append_text=append_text,
+                    prompt=prompt,
+                    unique_id=unique_id,
+                    used_fields=used_fields,
+                    is_positive=is_positive,
+                    pair_used=pair_used,
                 )
-                runs = positive_pending.consume(component_hash) + int(not seen_at_queue)
-                if runs:
-                    self.db.record_prompt_use(component_id, times=runs)
-            if pair_used:
-                runs = pair_pending.consume(pair_run_key(text, negative_text)) + int(
-                    not pair_seen
-                )
-                if runs:
-                    self.db.record_prompt_pair_use(pair_id, times=runs)
-            if is_positive:
-                self.prompt_tracker.set_current_prompt(
-                    prompt_text=positive,
-                    additional_data={
-                        "prompt_id": prompt_id,
-                        "pair_id": pair_id if pair_used else None,
-                        "positive_text": positive,
-                        "negative_text": negative_text,
-                        "positive_storage_text": text.strip(),
-                        "negative_storage_text": negative_text.strip(),
-                        "prepend_text": prepend_text.strip(),
-                        "append_text": append_text.strip(),
-                        "final_text": positive,
-                        "category": category.strip() or None,
-                        "tags": self._parse_tags(tags) or [],
-                    },
-                    push_to_queue=not positive_seen or (pair_used and not pair_seen),
-                )
-        except Exception as error:
-            self.logger.warning(f"Could not save or track paired prompt: {error}")
+            except Exception as error:
+                self.logger.warning(f"Could not save or track paired prompt: {error}")
+                if is_positive:
+                    self._mark_untracked(prompt, unique_id)
         try:
             self.comfyui_integration.register_prompt(
                 f"promptmanager_pair_{time.time_ns()}",
@@ -223,6 +167,102 @@ class PromptManagerPair(PromptManagerFocused):
         )
         return result
 
+    def _save_and_track_pair(
+        self,
+        text: str,
+        negative_text: str,
+        positive: str,
+        *,
+        category: str,
+        tags: str,
+        prepend_text: str,
+        append_text: str,
+        prompt: Optional[Dict[str, Any]],
+        unique_id: Optional[str],
+        used_fields: set,
+        is_positive: bool,
+        pair_used: bool,
+    ) -> Tuple[Optional[int], Optional[int]]:
+        """Save the recipe, count its runs and register the positive for linking."""
+        known = isinstance(prompt, dict) and unique_id is not None
+        node_id = str(unique_id)
+        pair_id = self.db.save_prompt_pair(
+            text,
+            negative_text,
+            category=category.strip() or None,
+            tags=self._parse_tags(tags),
+        )
+        pair = self.db.get_prompt_pair(pair_id)
+        prompt_id = pair["positive_prompt_id"]
+        resolved_positive = (
+            resolve_text_input(prompt, node_id, "text") if known else None
+        )
+        resolved_negative = (
+            resolve_text_input(prompt, node_id, "negative_text") if known else None
+        )
+        positive_seen = resolved_positive is not None and generate_prompt_hash(
+            resolved_positive
+        ) == generate_prompt_hash(text)
+        pair_seen = (
+            positive_seen
+            and resolved_negative is not None
+            and generate_prompt_hash(resolved_negative)
+            == generate_prompt_hash(negative_text)
+        )
+        positive_pending = getattr(self, "pending_first_use", PENDING_FIRST_USE)
+        pair_pending = getattr(self, "pending_pair_first_use", PENDING_PAIR_FIRST_USE)
+        counted = set()
+        for field, component_text, resolved_text, component_id in (
+            ("text", text, resolved_positive, prompt_id),
+            (
+                "negative_text",
+                negative_text,
+                resolved_negative,
+                pair["negative_prompt_id"],
+            ),
+        ):
+            component_hash = generate_prompt_hash(component_text)
+            if (
+                field not in used_fields
+                or not component_id
+                or component_hash in counted
+            ):
+                continue
+            counted.add(component_hash)
+            seen_at_queue = (
+                resolved_text is not None
+                and generate_prompt_hash(resolved_text) == component_hash
+            )
+            runs = positive_pending.consume(component_hash) + int(not seen_at_queue)
+            if runs:
+                self.db.record_prompt_use(component_id, times=runs)
+        if pair_used:
+            runs = pair_pending.consume(pair_run_key(text, negative_text)) + int(
+                not pair_seen
+            )
+            if runs:
+                self.db.record_prompt_pair_use(pair_id, times=runs)
+        if is_positive:
+            self.prompt_tracker.set_current_prompt(
+                prompt_text=positive,
+                additional_data={
+                    "prompt_id": prompt_id,
+                    "pair_id": pair_id if pair_used else None,
+                    "positive_text": positive,
+                    "negative_text": negative_text,
+                    "positive_storage_text": text.strip(),
+                    "negative_storage_text": negative_text.strip(),
+                    "prepend_text": prepend_text.strip(),
+                    "append_text": append_text.strip(),
+                    "final_text": positive,
+                    "category": category.strip() or None,
+                    "tags": self._parse_tags(tags) or [],
+                },
+                push_to_queue=not positive_seen or (pair_used and not pair_seen),
+                **self._run_identity(prompt, unique_id),
+            )
+        return pair_id, prompt_id
+
     @classmethod
     def IS_CHANGED(
         cls,

prompt_manager_text.py

@@ -216,6 +216,9 @@ class PromptManagerText(PromptManagerBase, ComfyNodeABC):
             except Exception as e:
                 # Log error but don't fail the processing
                 self.logger.warning(f"Failed to save prompt to database: {e}")
+                self._mark_untracked(prompt, unique_id)
+        else:
+            self._skip_empty_prompt(prompt, unique_id)
 
         # Register with ComfyUI integration for standard metadata compatibility
         node_id = f"promptmanagertext_{int(time.time() * 1000)}"

py/api/__init__.py

@@ -8,7 +8,18 @@ Split into domain-specific mixins for maintainability:
 - AutotagRoutesMixin: auto-tagging model management and tagging
 - JobRoutesMixin: the session job registry behind Activity (py/api/jobs.py)
 - ImageTagJobsMixin: bulk Add tags / Auto-tag as image-tags jobs
+- ThumbnailJobsMixin: thumbnail plan, thumbnail job and the gallery stream on it
+- ThumbnailConvertMixin: Convert outdated thumbnails (#317), a thumbnail job mode
+- AutoThumbnailMixin: previews made on first view, on capture and after a scan
+- ReviewRoutesMixin: the Needs review queue, item detail and decisions
+- ReviewRecordingMixin: Needs review recording for the scan and the monitor
+- ReviewEventsMixin: the Needs review change stream an open page re-reads on
 - SystemRoutesMixin: System health check, Overview and usage statistics
+- LibraryLocationRoutesMixin: where the library lives, Move library, Keep it here
+- MaintenanceRoutesMixin: reviewed maintenance plans (preview, apply)
+- WorkflowStorageRoutesMixin: store each workflow once, then Reclaim space
+- DuplicateFilesMixin: duplicate image files as find and removal jobs
+- LoraImportRoutesMixin: the reviewed, staged LoRA reference import job
 """
 
 import asyncio
@@ -16,6 +27,7 @@ import datetime
 import functools
 import gzip as gzip_module
 import json
+import math
 import ntpath
 import os
 import re
@@ -29,6 +41,9 @@ from .pairs import PairRoutesMixin
 from .library import LibraryRoutesMixin
 from .vocabulary import VocabularyRoutesMixin
 from .annotations import AnnotationRoutesMixin
+from .review import ReviewRoutesMixin
+from .review_recording import ReviewRecordingMixin
+from .review_events import ReviewEventsMixin
 from .saved_views import SavedViewRoutesMixin
 from .history import HistoryRoutesMixin
 from .images import ImageRoutesMixin
@@ -36,11 +51,21 @@ from .admin import AdminRoutesMixin
 from .settings_routes import SettingsRoutesMixin
 from .job_routes import JobRoutesMixin
 from .image_tag_jobs import ImageTagJobsMixin
+from .thumbnail_jobs import ThumbnailJobsMixin
+from .thumbnail_convert import ThumbnailConvertMixin
+from .thumbnail_auto import AutoThumbnailMixin
 from .system import SystemRoutesMixin
+from .library_location import LibraryLocationRoutesMixin
+from .maintenance import MaintenanceRoutesMixin
+from .backup_restore import BackupRestoreRoutesMixin
+from .workflow_storage import WorkflowStorageRoutesMixin
+from .duplicate_files import DuplicateFilesMixin
+from .maintenance_plans import PlanStore
 from .jobs import JobRegistry
 from .logging_routes import LoggingRoutesMixin
 from .autotag_routes import AutotagRoutesMixin
 from .lora_integration import LoraIntegrationMixin
+from .lora_import_routes import LoraImportRoutesMixin
 
 try:
     from ...database.operations import PromptDatabase
@@ -263,6 +288,9 @@ class PromptManagerAPI(
     LibraryRoutesMixin,
     VocabularyRoutesMixin,
     AnnotationRoutesMixin,
+    ReviewRoutesMixin,
+    ReviewRecordingMixin,
+    ReviewEventsMixin,
     SavedViewRoutesMixin,
     HistoryRoutesMixin,
     PromptRoutesMixin,
@@ -271,10 +299,19 @@ class PromptManagerAPI(
     SettingsRoutesMixin,
     JobRoutesMixin,
     ImageTagJobsMixin,
+    ThumbnailJobsMixin,
+    ThumbnailConvertMixin,
+    AutoThumbnailMixin,
     SystemRoutesMixin,
+    LibraryLocationRoutesMixin,
+    MaintenanceRoutesMixin,
+    BackupRestoreRoutesMixin,
+    WorkflowStorageRoutesMixin,
+    DuplicateFilesMixin,
     LoggingRoutesMixin,
     AutotagRoutesMixin,
     LoraIntegrationMixin,
+    LoraImportRoutesMixin,
 ):
     """REST API handler for PromptManager operations and web interface.
 
@@ -303,6 +340,8 @@ class PromptManagerAPI(
         # created on first use with their restore subscription.
         self._captures = None
         self._captures_unsubscribe = None
+        # Set by close_annotation_captures (shutdown): no store is recreated.
+        self._captures_closed = False
         self._cached_output_dir = None  # Lazy-cached by _find_comfyui_output_dir()
         self._html_cache = {}  # Cached HTML file contents keyed by path
         self._gallery_cache = {}  # dict: path_str -> (files, timestamp)
@@ -326,13 +365,34 @@ class PromptManagerAPI(
         self._jobs = JobRegistry(self.logger)
         # The latest metadata scan job (also in self._jobs), if one was started.
         self._scan_job = None
-        # The current duplicate scan (a py/api/jobs.Job outside the registry).
-        self._duplicate_job = None
+        # Duplicate-file finds by job id, with the groups each one holds for
+        # review (py/api/duplicate_files.py); the last few only.
+        self._duplicate_finds = {}
         # The last System health report this session and the database
         # generation it describes, bumped when a restore replaces self.db
         # (py/api/system.py).
         self._health_report = None
         self._db_generation = 0
+        # Reviewed maintenance plans under single-use tokens; a restart
+        # forgets them (py/api/maintenance.py).
+        self._maintenance_plans = PlanStore()
+
+        # A safety backup interrupted by a crash leaves its temp copy behind.
+        try:
+            from .maintenance import sweep_safety_temps
+
+            from .backup_restore import restore_stage
+
+            swept = sweep_safety_temps(self.db.model.db_path)
+            swept += restore_stage.sweep_restore_temps(self.db.model.db_path)
+            if swept:
+                self.logger.info(f"Removed {len(swept)} interrupted backup copies")
+        except Exception as e:
+            self.logger.warning(f"Could not sweep interrupted backup copies: {e}")
+
+        # A crash between Move library's switch and its rename left the old
+        # node-folder files under their own names (#249 S6b): rename them now.
+        self.finish_interrupted_library_move()
 
         # Run cleanup on initialization to remove any existing duplicates
         try:
@@ -483,6 +543,8 @@ class PromptManagerAPI(
         self._register_library_routes(routes)
         self._register_vocabulary_routes(routes)
         self._register_annotation_routes(routes)
+        self._register_review_routes(routes)
+        self._register_review_event_routes(routes)
         self._register_saved_view_routes(routes)
         self._register_history_routes(routes)
         self._register_prompt_routes(routes)
@@ -491,9 +553,14 @@ class PromptManagerAPI(
         self._register_settings_routes(routes)
         self._register_job_routes(routes)
         self._register_system_routes(routes)
+        self._register_library_location_routes(routes)
+        self._register_maintenance_routes(routes)
+        self._register_backup_restore_routes(routes)
+        self._register_duplicate_routes(routes)
         self._register_logging_routes(routes)
         self._register_autotag_routes(routes)
         self._register_lora_routes(routes)
+        self._register_lora_import_routes(routes)
 
         # Register gzip compression middleware (once)
         global _gzip_registered
@@ -584,16 +651,20 @@ class PromptManagerAPI(
                         f"{url_quote(rel_path.as_posix(), safe='/')}"
                     )
 
-                    # Check for thumbnail
-                    rel_no_ext = rel_path.with_suffix("")
-                    thumb_rel = (
-                        f"thumbnails/{rel_no_ext.as_posix()}_thumb{rel_path.suffix}"
-                    )
+                    # Any preview the file owns, the current format first (#317)
+                    from . import thumbnail_settings
                     from .prompts import thumbnail_url_for
 
-                    thumbnail_url = thumbnail_url_for(
-                        thumb_rel, output_path / thumb_rel
+                    existing = thumbnail_settings.existing_thumbnail(
+                        output_path, rel_path
                     )
+                    thumbnail_url = None
+                    if existing is not None:
+                        thumb_rel = (
+                            thumbnail_settings.thumbnail_stem_rel(rel_path)
+                            + existing.suffix
+                        )
+                        thumbnail_url = thumbnail_url_for(thumb_rel, existing)
                     if thumbnail_url:
                         image["thumbnail_url"] = thumbnail_url
                     break  # Found matching root, stop searching
@@ -609,12 +680,12 @@ class PromptManagerAPI(
         return prompts
 
     def _clean_nan_recursive(self, obj):
-        """Recursively clean NaN values from nested data structures."""
+        """Recursively replace NaN and Infinity in nested data with None."""
         if isinstance(obj, dict):
             return {key: self._clean_nan_recursive(value) for key, value in obj.items()}
         elif isinstance(obj, list):
             return [self._clean_nan_recursive(item) for item in obj]
-        elif isinstance(obj, float) and str(obj) == "nan":
+        elif isinstance(obj, float) and not math.isfinite(obj):
             return None
         else:
             return obj

py/api/annotations.py

@@ -13,6 +13,7 @@ import datetime
 import functools
 import os
 import re
+import threading
 from pathlib import Path
 
 from aiohttp import web
@@ -73,6 +74,9 @@ _HEX64 = re.compile(r"[0-9a-f]{64}")
 _UUID = re.compile(r"[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}")
 # secrets.token_urlsafe(32) is 43 characters; the bound only rejects junk.
 _TOKEN = re.compile(r"[A-Za-z0-9_-]{1,128}")
+# The store is created on first use by the event loop, the scan's executor or
+# the monitor's worker (Needs review), so its creation is serialized.
+_CAPTURE_STORE_LOCK = threading.Lock()
 
 _PREVIEW_TYPES = {
     ".png": "image/png",
@@ -259,31 +263,46 @@ class AnnotationRoutesMixin:
         Created lazily so an API object that never observes a file (most tests,
         a server that never opens the Tag dialog) owns no temp directory. A
         restore of the database dooms every capture (``invalidate_all``).
+        Thread-safe: Needs review recording calls it off the event loop.
+        Raises ``CaptureError`` after ``close_annotation_captures``.
         """
-        if self._captures is None:
-            self._captures = CaptureStore()
-        if self._captures_unsubscribe is None:
-            self._captures_unsubscribe = subscribe_history_restore(
-                self.db.model.db_path, self._invalidate_captures
-            )
-        return self._captures
+        with _CAPTURE_STORE_LOCK:
+            if getattr(self, "_captures_closed", False):
+                # A recording still in flight at shutdown must not create a
+                # new temp directory after the cleanup removed the old one.
+                raise CaptureError("The capture store is closed")
+            if self._captures is None:
+                self._captures = CaptureStore()
+            if self._captures_unsubscribe is None:
+                self._captures_unsubscribe = subscribe_history_restore(
+                    self.db.model.db_path, self._invalidate_captures
+                )
+            return self._captures
 
     def _invalidate_captures(self) -> None:
         store = self._captures
         if store is not None:
             store.invalidate_all()
 
-    def close_annotation_captures(self) -> None:
-        """Remove every capture file and the owned directory. Idempotent."""
-        unsubscribe, self._captures_unsubscribe = self._captures_unsubscribe, None
+    def close_annotation_captures(self, *, final: bool = False) -> None:
+        """Remove every capture file and the owned directory. Idempotent.
+
+        Taken under the store lock. ``final`` (the shutdown cleanup) also makes
+        ``_capture_store`` refuse to create another store, so a recording
+        still in flight cannot leak a new temp directory after it.
+        """
+        with _CAPTURE_STORE_LOCK:
+            if final:
+                self._captures_closed = True
+            unsubscribe, self._captures_unsubscribe = self._captures_unsubscribe, None
+            store, self._captures = self._captures, None
         if unsubscribe is not None:
             unsubscribe()
-        store, self._captures = self._captures, None
         if store is not None:
             store.close()
 
     async def cleanup_annotation_captures(self, app: web.Application) -> None:
-        self.close_annotation_captures()
+        self.close_annotation_captures(final=True)
 
     # -- shared request steps --------------------------------------------------
 
@@ -329,7 +348,10 @@ class AnnotationRoutesMixin:
         root, error = self._scoped_root(index, scope)
         if error is not None:
             return error
-        store = self._capture_store()
+        try:
+            store = self._capture_store()
+        except CaptureError as exc:  # the server is shutting down
+            return _capture_error(exc)
         try:
             epoch = await self._run_in_executor(self.db.get_execution_epoch)
             capture = await _settled(

py/api/autotag_routes.py

@@ -10,6 +10,7 @@ from urllib.parse import quote
 
 from .jobs import AUTOTAG_BATCH_JOB_KIND
 from .prompts import thumbnail_url_for
+from . import thumbnail_settings
 from .. import model_gate
 
 from aiohttp import web
@@ -792,13 +793,16 @@ class AutotagRoutesMixin:
                 rel_path = image_path.relative_to(output_path)
                 thumbnail_url = None
                 if has_thumbnails:
-                    thumb_rel = (
-                        f"thumbnails/{rel_path.with_suffix('').as_posix()}"
-                        f"_thumb{image_path.suffix}"
-                    )
-                    thumbnail_url = thumbnail_url_for(
-                        thumb_rel, output_path / thumb_rel
+                    # Any preview the file owns, the current format first (#317)
+                    existing = thumbnail_settings.existing_thumbnail(
+                        output_path, rel_path
                     )
+                    if existing is not None:
+                        thumb_rel = (
+                            thumbnail_settings.thumbnail_stem_rel(rel_path)
+                            + existing.suffix
+                        )
+                        thumbnail_url = thumbnail_url_for(thumb_rel, existing)
                 images.append(
                     {
                         "filename": image_path.name,

py/api/backup_restore.py

@@ -0,0 +1,942 @@
+"""Database backup and restore routes (#249 System S8).
+
+Legacy routes, responses unchanged:
+
+- ``GET /prompt_manager/backup`` downloads a consistent copy of the library.
+  While the copy is made it holds the registry as ``backup`` ("Database
+  backup", ``guarded``): it is refused while a restore, maintenance apply or
+  other record-changing job runs. The copy is written in the library's
+  folder and made one standalone file; the hold ends there, so a slow or
+  stalled download never keeps other work waiting. A copy that fails its
+  integrity check is a 500 with no bytes. One that fails only a semantic
+  check (``verify_database_file``) is still sent: a user can always get a
+  backup. The reason is logged and sent as ``X-PromptManager-Verify``
+  (``ok`` otherwise), and the status records it as not verified. The file
+  is streamed, then closed and removed.
+- ``POST /prompt_manager/restore`` (multipart ``database_file``) restores in
+  one request through the same stage and publish as the restore job, holding
+  the registry as ``restore`` (``exclusive``).
+
+Reviewed restore (new routes answer errors as ``{success:false, code, error}``):
+
+- ``POST /prompt_manager/restore/preview`` (multipart ``database_file``, the
+  same disk-space cap) stages the upload in the library's folder
+  (``database/restore_stage.py``) and answers what it holds beside the live
+  library: ``{token, expires_at, summary, schema:{migrated, library_state},
+  integrity:"ok", documents:{repaired, cleared, images}, live, size,
+  safety_backup:{destination_label}}``. Nothing live is written or backed
+  up. At most two previews are held (``too-large``, 429).
+- ``DELETE /prompt_manager/restore/preview/{token}`` discards a stage.
+- ``POST /prompt_manager/restore/apply {token}`` starts the restore job (202
+  ``{job}``): kind ``restore``, "Database restore", ``exclusive`` (it runs
+  alone, like Move library), not cancellable, indeterminate. The runner waits
+  for request leases to end, rechecks the live fingerprint (``plan-changed``),
+  publishes the exact staged bytes, swaps ``self.db``, prunes old safety
+  backups and logs what was restored. Once the copy replaced the library,
+  the restore is done: the later steps only log their failures.
+- ``GET /prompt_manager/backup/status``: the safety backups on disk
+  (``<db>.backup_*``, newest first, names only) and this session's last
+  verified download (Q9: no sidecar file).
+"""
+
+import asyncio
+import datetime
+import os
+import sqlite3
+import tempfile
+from contextlib import closing
+from pathlib import Path
+
+from aiohttp import web
+
+from . import admin as _admin
+from .job_routes import busy_response
+from .jobs import RESTORE_JOB_KIND, JobBusy
+from .maintenance_plans import PlanExpired, PlanUsed
+from .restore_plans import RestorePlanStore
+
+try:
+    from ...database import restore_stage
+    from ...database.operations import PromptDatabase
+    from ...database.safety_backup import (
+        SafetyBackupFailed,
+        fsync_file,
+        make_standalone,
+        remove_quietly,
+        safety_temp,
+    )
+except ImportError:
+    from database import restore_stage
+    from database.operations import PromptDatabase
+    from database.safety_backup import (
+        SafetyBackupFailed,
+        fsync_file,
+        make_standalone,
+        remove_quietly,
+        safety_temp,
+    )
+
+BACKUP_JOB_KIND = "backup"
+BACKUP_HOLD_TITLE = "Database backup"
+LEGACY_RESTORE_TITLE = "Database restore (admin page)"
+RESTORE_JOB_TITLE = "Database restore"
+RESTORE_GROUPS = ("errors",)
+MAX_TOKEN_LENGTH = 128
+APPLY_BODY_MAX = 1024
+STREAM_CHUNK = 1024 * 1024
+MAX_LISTED_BACKUPS = 10
+SIDECARS = ("", "-wal", "-shm", "-journal")
+REQUESTS_BUSY = (
+    "Other requests are still reading the library; nothing was changed. "
+    "Try again in a moment."
+)
+# S9 I1: the review goes back to the page that started the restore
+# (``scope.review_kept``), which opens it again with Restore and Discard; no
+# other place can start a kept review, so the line says where it is.
+REVIEW_KEPT = (
+    "Other requests are still reading the library; nothing was changed. "
+    "The review was reopened in the page that started the restore: restore it "
+    "again there, or discard it."
+)
+VERIFY_HEADER = "X-PromptManager-Verify"
+SQLITE_HEADER = b"SQLite format 3\x00"
+PLAN_CHANGED = (
+    "The library changed since the review; nothing was changed. "
+    "Review the restore again."
+)
+NOT_RESTORED = "The restore failed; the library was not changed."
+
+
+def _failure(message, status, code=None, **extra):
+    return web.json_response(
+        {"success": False, "code": code, "error": message, **extra}, status=status
+    )
+
+
+def _iso(timestamp):
+    return datetime.datetime.fromtimestamp(timestamp, datetime.timezone.utc).isoformat()
+
+
+def _plural(count, word):
+    return f"{count:,} {word}" + ("" if count == 1 else "s")
+
+
+def documents_line(documents):
+    """The repair report's sentence, or "" when nothing was damaged."""
+    repaired, cleared = documents.get("repaired", 0), documents.get("cleared", 0)
+    parts = []
+    if repaired:
+        parts.append(f"repaired {_plural(repaired, 'damaged workflow document')}")
+    if cleared:
+        images = documents.get("images", 0)
+        parts.append(
+            f"could not repair {_plural(cleared, 'workflow document')}: "
+            f"{_plural(images, 'image')} {'shows' if images == 1 else 'show'} "
+            "no workflow"
+        )
+    if not parts:
+        return ""
+    text = "; ".join(parts)
+    return text[0].upper() + text[1:] + "."
+
+
+def restored_line(summary):
+    return (
+        f"Restored {_plural(summary['prompts'], 'prompt')}, "
+        f"{_plural(summary['image_links'], 'image link')}, "
+        f"{_plural(summary['pairs'], 'saved pair')} and "
+        f"{_plural(summary['runs'], 'run')}"
+    )
+
+
+def safety_backups(db_path, limit=MAX_LISTED_BACKUPS):
+    """``<db>.backup_*`` files beside the database, newest first (blocking)."""
+    db_path = os.path.abspath(db_path)
+    folder = os.path.dirname(db_path)
+    prefix = os.path.basename(db_path) + ".backup_"
+    found = []
+    try:
+        names = os.listdir(folder)
+    except OSError:
+        return []
+    for name in names:
+        if not name.startswith(prefix):
+            continue
+        try:
+            stat = os.stat(os.path.join(folder, name))
+        except OSError:
+            continue
+        if not os.path.isfile(os.path.join(folder, name)):
+            continue
+        found.append((stat.st_mtime, name, stat.st_size))
+    found.sort(key=lambda item: (item[0], item[1]), reverse=True)
+    return [
+        {"name": name, "bytes": size, "modified_at": _iso(mtime)}
+        for mtime, name, size in found[:limit]
+    ]
+
+
+def snapshot_corruption(path):
+    """Why the snapshot file is corrupt, or None (blocking).
+
+    Only physical damage refuses a download: not a SQLite file, or a failed
+    ``PRAGMA integrity_check``.
+    """
+    try:
+        with open(path, "rb") as handle:
+            if handle.read(len(SQLITE_HEADER)) != SQLITE_HEADER:
+                return "Not a SQLite database file"
+        uri = Path(os.path.abspath(path)).as_uri() + "?mode=ro"
+        with closing(sqlite3.connect(uri, uri=True)) as conn:
+            row = conn.execute("PRAGMA integrity_check").fetchone()
+    except (OSError, sqlite3.Error) as error:
+        return f"Invalid SQLite database: {error}"
+    verdict = row[0] if row else "no result"
+    return None if verdict == "ok" else f"Integrity check failed: {verdict}"
+
+
+def write_backup_snapshot(model):
+    """A standalone copy of the library beside it: ``(path, warning)`` (blocking).
+
+    Raises SafetyBackupFailed with nothing left on disk when the copy cannot
+    be written or is corrupt (``snapshot_corruption``). ``warning`` is the
+    reason a semantic check (``verify_database_file``, workflow documents
+    not read) refused the copy, or None. The caller removes the file.
+    """
+    temp = safety_temp(model.db_path)
+    try:
+        if not model.backup_database(temp):
+            raise SafetyBackupFailed("The backup could not be written")
+        make_standalone(temp)
+        corrupt = snapshot_corruption(temp)
+        if corrupt is not None:
+            raise SafetyBackupFailed("The backup is corrupt", corrupt)
+        ok, reason = model.verify_database_file(temp, documents=False)
+        fsync_file(temp)
+        return temp, (None if ok else reason)
+    except BaseException:
+        remove_quietly(*(temp + suffix for suffix in SIDECARS))
+        raise
+
+
+def _header_text(text):
+    """A reason as a one-line, latin-1 header value."""
+    flat = " ".join(str(text).split())[:300]
+    return flat.encode("latin-1", "replace").decode("latin-1")
+
+
+class BackupRestoreRoutesMixin:
+    """Mixin providing the backup and restore endpoints."""
+
+    def _register_backup_restore_routes(self, routes):
+        @routes.post("/prompt_manager/restore/preview")
+        async def restore_preview_route(request):
+            return await self.preview_restore(request)
+
+        @routes.delete("/prompt_manager/restore/preview/{token}")
+        async def restore_discard_route(request):
+            return await self.discard_restore_preview(request)
+
+        @routes.post("/prompt_manager/restore/apply")
+        async def restore_apply_route(request):
+            return await self.apply_restore(request)
+
+        @routes.get("/prompt_manager/backup/status")
+        async def backup_status_route(request):
+            return await self.backup_status(request)
+
+    @property
+    def _restore_plans(self):
+        store = getattr(self, "_restore_plan_store", None)
+        if store is None:
+            store = self._restore_plan_store = RestorePlanStore()
+        return store
+
+    # ── backup ────────────────────────────────────────────────────────
+
+    async def backup_database(self, request):
+        """Download a copy of the prompts database (WAL included)."""
+        return await self._stream_backup(request)
+
+    async def _stream_backup(self, request):
+        model = self.db.model
+        if not os.path.exists(model.db_path):
+            return web.json_response(
+                {"success": False, "error": "Database file not found"}, status=404
+            )
+        made = await self._run_held(
+            BACKUP_JOB_KIND,
+            BACKUP_HOLD_TITLE,
+            "guarded",
+            lambda: self._make_backup_snapshot(model),
+        )
+        if isinstance(made, web.StreamResponse):
+            return made  # refused, or the snapshot failed
+        temp, warning = made
+        return await self._send_snapshot(request, temp, warning)
+
+    async def _make_backup_snapshot(self, model):
+        """``(path, warning)``, or the error response (inside the hold)."""
+        loop = asyncio.get_running_loop()
+        future = loop.run_in_executor(None, write_backup_snapshot, model)
+        try:
+            temp, warning = await asyncio.shield(future)
+        except asyncio.CancelledError:
+            # The worker cannot be stopped: remove what it writes once it is
+            # done (#335 re-review R4).
+            future.add_done_callback(
+                lambda done: loop.create_task(self._remove_finished_snapshot(done))
+            )
+            raise
+        except SafetyBackupFailed as failed:
+            self.logger.error(f"Backup failed: {failed} {failed.reason or ''}")
+            return web.json_response(
+                {"success": False, "error": "Failed to create database backup"},
+                status=500,
+            )
+        except Exception as e:
+            self.logger.error(f"Backup error: {e}", exc_info=True)
+            return web.json_response(
+                {
+                    "success": False,
+                    "error": f"Failed to backup database: {self._public_error(e)}",
+                },
+                status=500,
+            )
+        if warning is not None:
+            self.logger.warning(f"Backup sent with a failed check: {warning}")
+        return temp, warning
+
+    async def _remove_finished_snapshot(self, future):
+        """Remove the snapshot a cancelled download's worker finished."""
+        if future.cancelled() or future.exception() is not None:
+            return  # nothing was left on disk
+        temp, _warning = future.result()
+        await self._run_in_executor(
+            remove_quietly, *(temp + suffix for suffix in SIDECARS)
+        )
+
+    async def _send_snapshot(self, request, temp, warning):
+        """Stream the snapshot (outside the hold), then close and remove it."""
+        timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+        handle = None
+        try:
+            size = os.path.getsize(temp)
+            handle = open(temp, "rb")
+            response = web.StreamResponse(
+                headers={
+                    "Content-Type": "application/octet-stream",
+                    "Content-Disposition": (
+                        f'attachment; filename="prompts_backup_{timestamp}.db"'
+                    ),
+                    "Content-Length": str(size),
+                    VERIFY_HEADER: "ok" if warning is None else _header_text(warning),
+                }
+            )
+            await response.prepare(request)
+            while True:
+                chunk = await self._run_in_executor(handle.read, STREAM_CHUNK)
+                if not chunk:
+                    break
+                await response.write(chunk)
+            await response.write_eof()
+            self._last_backup_download = {
+                "at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+                "bytes": size,
+                "verified": warning is None,
+            }
+            return response
+        finally:
+            if handle is not None:
+                handle.close()  # before the unlink (Windows)
+            await self._run_in_executor(
+                remove_quietly, *(temp + suffix for suffix in SIDECARS)
+            )
+
+    async def backup_status(self, request):
+        try:
+            backups = await self._run_in_executor(safety_backups, self.db.model.db_path)
+        except Exception:
+            self.logger.exception("Backup status failed")
+            return _failure("Failed to read the backup status", 500)
+        return web.json_response(
+            {
+                "success": True,
+                "safety_backups": backups,
+                "last_download": getattr(self, "_last_backup_download", None),
+            },
+            headers={"Cache-Control": "no-store"},
+        )
+
+    # ── the upload ────────────────────────────────────────────────────
+
+    def _restore_refusal(self, size, ceiling, room, *, known):
+        """``400 too-large`` past the ceiling, else ``507 insufficient-space``."""
+        from .maintenance import restore_space_message
+
+        if size > ceiling:
+            return web.json_response(
+                {
+                    "success": False,
+                    "code": "too-large",
+                    "error": (
+                        "File too large. Maximum size is "
+                        f"{ceiling // (1024 * 1024)}MB"
+                    ),
+                },
+                status=400,
+            )
+        return web.json_response(
+            {
+                "success": False,
+                "code": "insufficient-space",
+                "error": restore_space_message(size, room, known=known),
+            },
+            status=507,
+        )
+
+    async def _receive_restore_upload(self, request, uploads):
+        """Stream ``database_file`` into the library's folder.
+
+        Returns ``(path, None)`` or ``(None, refusal)``. Each temp path is
+        appended to ``uploads`` as soon as it exists, so the caller removes
+        it (and its sidecars) whatever happens.
+        """
+        from .maintenance import RESTORE_MAX_BYTES, restore_room
+
+        ceiling = getattr(self, "restore_max_bytes", RESTORE_MAX_BYTES)
+        db_path = self.db.model.db_path
+        # Free disk space decides how large a backup may be (#313): the
+        # upload, its staged copy and the swap must all fit.
+        room = await self._run_in_executor(restore_room, db_path)
+        max_bytes = min(ceiling, room)
+        length = request.content_length
+        if length is not None and length > max_bytes:
+            return None, self._restore_refusal(length, ceiling, room, known=True)
+        reader = await request.multipart()
+        field = await reader.next()
+        if not field or field.name != "database_file":
+            return None, web.json_response(
+                {
+                    "success": False,
+                    "error": (
+                        "No database file uploaded. "
+                        "Expected field name: database_file"
+                    ),
+                },
+                status=400,
+            )
+        fd, temp_path = tempfile.mkstemp(
+            prefix=restore_stage.UPLOAD_PREFIX,
+            suffix=".tmp",
+            dir=os.path.dirname(os.path.abspath(db_path)),
+        )
+        uploads.append(temp_path)
+        size = 0
+        with os.fdopen(fd, "wb") as out:
+            while True:
+                chunk = await field.read_chunk()
+                if not chunk:
+                    break
+                size += len(chunk)
+                if size > max_bytes:
+                    return None, self._restore_refusal(size, ceiling, room, known=False)
+                out.write(chunk)
+        if size == 0:
+            return None, web.json_response(
+                {"success": False, "error": "Uploaded file is empty"}, status=400
+            )
+        return temp_path, None
+
+    async def _upload_problem(self, path):
+        """None when the upload may be staged, else a readable reason."""
+        ok, reason = await self._run_in_executor(
+            self.db.model.verify_database_file, path, documents=False
+        )
+        if ok:
+            reason = await self._run_in_executor(_admin._inspect_restore_upload, path)
+            ok = reason is None
+        return None if ok else reason
+
+    async def _remove_uploads(self, uploads):
+        for path in uploads:
+            await self._run_in_executor(
+                remove_quietly, *(path + suffix for suffix in SIDECARS)
+            )
+
+    async def _prune_after(self, db_path, *, failed=False):
+        """Prune old safety backups; a failure is only logged (never raises).
+
+        It runs after a restore replaced the library, or after one failed:
+        either way the restore's outcome stands.
+        """
+        try:
+            removed = await self._run_in_executor(_admin._prune_safety_backups, db_path)
+        except Exception as error:
+            when = "failed" if failed else "completed"
+            self.logger.warning(
+                f"Could not prune safety backups after a {when} restore: "
+                f"{type(error).__name__}"
+            )
+            return
+        if removed:
+            self.logger.info(f"Removed {len(removed)} old safety backups")
+
+    async def _publish(self, model, staged):
+        """Publish ``staged``; on a page-copy failure prune and re-raise."""
+        try:
+            return await self._run_in_executor(model.publish_staged, staged)
+        except sqlite3.OperationalError as exc:
+            if getattr(exc, "_prompt_manager_restore_backup_created", False) is True:
+                await self._prune_after(model.db_path, failed=True)
+            raise
+
+    async def _after_publish(self, db_path):
+        """Everything after the copy replaced the library: best effort, logged.
+
+        The restore is done once the copy succeeded, so nothing here fails it
+        (#335 review I1). The library is adopted as ``self.db`` (the previous
+        object, which points at the same file, stays when a new one cannot
+        be opened), the generation is bumped (so the health report and
+        reviewed plans of the old library are dropped), held restore
+        previews are dropped and the previous object's connections closed.
+        """
+        await self._prune_after(db_path)
+        previous = self.db
+        try:
+            self.db = PromptDatabase(db_path)
+        except Exception:
+            self.logger.exception("Could not reopen the restored library")
+        try:
+            self._database_replaced()
+        except Exception:
+            self.logger.exception("Could not drop the old library's reports")
+        try:
+            await self._discard_held(self._restore_plans.pop_all())
+        except Exception:
+            self.logger.exception("Could not remove the old restore previews")
+        if previous is not self.db:
+            try:
+                # Its connections would otherwise linger (a lock on Windows).
+                await self._run_in_executor(previous.close_all)
+            except Exception:
+                self.logger.exception("Could not close the previous library")
+
+    async def _discard_held(self, held):
+        """Remove the stage folders of dropped store entries (off the loop)."""
+        for entry in held:
+            try:
+                await self._run_in_executor(entry.staged.discard)
+            except Exception:
+                self.logger.exception("Could not remove a restore stage")
+
+    async def _discard_popped(self, token):
+        """Drop ``token`` and remove its stage, only if the store still held it.
+
+        A stage another apply's job has taken is not this request's to remove
+        (#335 re-review R2).
+        """
+        popped = self._restore_plans.pop(token)
+        if popped is not None:
+            await self._discard_held([popped])
+
+    async def _drop_expired_restores(self):
+        """Drop expired previews from the store (on the loop), then their files."""
+        await self._discard_held(self._restore_plans.pop_expired())
+
+    def _schedule_restore_expiry(self):
+        """Remove each preview's stage when it expires, without a request.
+
+        A loop timer (``call_later``), so a server that stops with previews
+        held leaves nothing pending; the startup sweep removes the folders.
+        """
+        store = self._restore_plans
+        expires = store.next_expiry()
+        if expires is None:
+            return
+        handle = getattr(self, "_restore_expiry_handle", None)
+        if handle is not None:
+            handle.cancel()
+        loop = asyncio.get_running_loop()
+
+        def fire():
+            self._restore_expiry_handle = None
+            task = loop.create_task(self._expire_restores())
+            self._restore_expiry_task = task
+
+        delay = max(0.0, expires - store.now())
+        self._restore_expiry_handle = loop.call_later(delay, fire)
+
+    async def _expire_restores(self):
+        await self._drop_expired_restores()
+        self._schedule_restore_expiry()
+
+    # ── legacy one-step restore ───────────────────────────────────────
+
+    async def restore_database(self, request):
+        """Restore the prompts database from an uploaded SQLite file.
+
+        The upload is streamed to a temp file in the library's folder. Free
+        disk space decides how large it may be (``maintenance.restore_room``),
+        under a 64 GiB ceiling (``restore_max_bytes``): a request whose
+        Content-Length does not fit is refused before anything is written,
+        and one without is refused as soon as its running size does not. The
+        file is checked, staged, repaired and verified, then published over
+        the live database, which is backed up first. The whole request holds
+        the registry as ``restore`` (``exclusive``): it is refused while any
+        job runs, and every job and request lease is refused while it runs.
+        """
+        return await self._run_held(
+            RESTORE_JOB_KIND,
+            LEGACY_RESTORE_TITLE,
+            "exclusive",
+            lambda: self._restore_database(request),
+        )
+
+    async def _restore_database(self, request):
+        uploads = []
+        try:
+            temp_path, refused = await self._receive_restore_upload(request, uploads)
+            if refused is not None:
+                return refused
+            reason = await self._upload_problem(temp_path)
+            if reason is not None:
+                return web.json_response(
+                    {"success": False, "error": reason}, status=400
+                )
+            if not await self._jobs.drain_leases():
+                return web.json_response(
+                    {"success": False, "error": REQUESTS_BUSY}, status=409
+                )
+            model = self.db.model
+            staged = await self._run_in_executor(model.stage_restore, temp_path)
+            try:
+                backup_path = await self._publish(model, staged)
+            finally:
+                await self._run_in_executor(staged.discard)
+            # The library is replaced: from here on the restore succeeded.
+            await self._after_publish(model.db_path)
+            try:
+                prompt_count = await self._run_in_executor(
+                    lambda: self.db.model.get_database_info().get("total_prompts", 0)
+                )
+            except Exception:
+                self.logger.exception("Could not count the restored prompts")
+                prompt_count = staged.summary.get("prompts", 0)
+            message = f"Database restored successfully. Found {prompt_count} prompts."
+            body = {
+                "success": True,
+                "message": message,
+                "prompt_count": prompt_count,
+                "backup_created": (
+                    self._public_path(backup_path) if backup_path else None
+                ),
+            }
+            repaired = documents_line(staged.documents)
+            if repaired:
+                body["message"] = f"{message} {repaired}"
+                body["workflow_documents"] = dict(staged.documents)
+            return web.json_response(body)
+        except Exception as e:
+            self.logger.error(f"Restore error: {e}", exc_info=True)
+            return web.json_response(
+                {
+                    "success": False,
+                    "error": f"Failed to restore database: {self._public_error(e)}",
+                },
+                status=500,
+            )
+        finally:
+            await self._remove_uploads(uploads)
+
+    # ── reviewed restore ──────────────────────────────────────────────
+
+    def _live_fingerprint(self, db):
+        return restore_stage.live_fingerprint(db.model.get_connection())
+
+    async def preview_restore(self, request):
+        """Stage an upload for review; nothing live is written (see module)."""
+        await self._drop_expired_restores()
+        if self._restore_plans.full():
+            return _too_many_reviews()
+        uploads = []
+        try:
+            db = self.db
+            identity = self._database_identity(db)
+            temp_path, refused = await self._receive_restore_upload(request, uploads)
+            if refused is not None:
+                return refused
+            return await self._review_upload(db, identity, temp_path, uploads)
+        except Exception:
+            self.logger.exception("Restore preview failed")
+            return _failure("Failed to review the restore", 500)
+        finally:
+            await self._remove_uploads(uploads)
+
+    async def _stage_for_review(self, db, temp_path, uploads):
+        """Stage ``temp_path`` in the executor; a cancel discards the result.
+
+        A cancelled handler (shutdown, a dropped client) cannot stop the
+        worker thread: the stage it finishes is removed when it is done, and
+        so is the upload it reads (``_orphan_stage_cleanup``).
+        """
+        loop = asyncio.get_running_loop()
+        future = loop.run_in_executor(None, db.model.stage_restore, temp_path)
+        try:
+            return await asyncio.shield(future)
+        except asyncio.CancelledError:
+            orphans = getattr(self, "_orphan_stages", None)
+            if orphans is None:
+                orphans = self._orphan_stages = set()
+            entry = (future, tuple(uploads))
+            orphans.add(entry)
+            uploads.clear()  # still being read: removed with the stage
+            future.add_done_callback(
+                lambda _f: loop.create_task(self._orphan_stage_cleanup())
+            )
+            raise
+
+    async def _orphan_stage_cleanup(self):
+        """Remove what cancelled previews staged, once their workers are done."""
+        for entry in list(getattr(self, "_orphan_stages", ()) or ()):
+            future, uploads = entry
+            if not future.done():
+                continue
+            self._orphan_stages.discard(entry)
+            if not future.cancelled() and future.exception() is None:
+                await self._discard_held([_Orphan(future.result())])
+            await self._remove_uploads(uploads)
+
+    async def _review_upload(self, db, identity, temp_path, uploads=None):
+        """Check, stage and compare an upload; the preview response.
+
+        Only the read of the live library takes a lease (#335 review M2):
+        the upload and the staging never touch it, and a lease held for a
+        long staging would make a restore's drain fail. A stage that is not
+        handed to the store (a refusal, an error, a cancel) is removed.
+        """
+        uploads = [] if uploads is None else uploads  # the caller removes them
+        reason = await self._upload_problem(temp_path)
+        if reason is not None:
+            return _failure(reason, 400, "invalid-backup")
+        staged = None
+        issued = False
+        try:
+            try:
+                staged = await self._stage_for_review(db, temp_path, uploads)
+            except ValueError as invalid:
+                return _failure(str(invalid), 400, "invalid-backup")
+            try:
+                async with self._jobs.lease("Restore preview"):
+                    live, fingerprint = await self._run_in_executor(
+                        self._live_fingerprint, db
+                    )
+            except JobBusy as busy:
+                return busy_response(busy)
+            store = self._restore_plans
+            if identity != self._database_identity(self.db):
+                return _failure(
+                    "The database was replaced while the restore was reviewed. "
+                    "Review again.",
+                    409,
+                    "storage-changed",
+                )
+            if store.full():
+                return _too_many_reviews()
+            token = store.issue(staged, fingerprint, identity, live)
+            issued = True
+            self._schedule_restore_expiry()
+        finally:
+            if staged is not None and not issued:
+                await self._discard_held([_Orphan(staged)])
+        held = store.entry(token)
+        name = os.path.basename(db.model.db_path)
+        return web.json_response(
+            {
+                "success": True,
+                "token": token,
+                "expires_at": _iso(held.expires_at),
+                "summary": dict(staged.summary),
+                "schema": dict(staged.schema),
+                "integrity": "ok",
+                "documents": dict(staged.documents),
+                "live": dict(live),
+                "size": staged.size,
+                "safety_backup": {
+                    "destination_label": f"{name}.backup_<date and time>"
+                },
+            },
+            headers={"Cache-Control": "no-store"},
+        )
+
+    async def discard_restore_preview(self, request):
+        token = request.match_info.get("token", "")
+        if not 0 < len(token) <= MAX_TOKEN_LENGTH:
+            return _failure("Unknown restore review.", 410, "plan-expired")
+        held = self._restore_plans.pop(token)
+        if held is None:
+            await self._drop_expired_restores()
+            return _failure("Unknown restore review.", 410, "plan-expired")
+        await self._discard_held([held])
+        return web.json_response({"success": True})
+
+    def _peek_restore(self, token):
+        try:
+            return self._restore_plans.peek(token), None
+        except PlanUsed as used:
+            job = self._jobs.get(used.job_id)
+            return None, _failure(
+                "This restore was already started.",
+                409,
+                "plan-used",
+                job={"id": used.job_id, "title": job.title if job else None},
+            )
+        except PlanExpired:
+            return None, _failure(
+                "This review expired. Review the restore again.",
+                410,
+                "plan-expired",
+            )
+
+    async def apply_restore(self, request):
+        data, error = await self._read_json_body(request, max_bytes=APPLY_BODY_MAX)
+        if error is not None:
+            if error.status == 413:
+                return _failure("Request body too large", 413, "too-large")
+            return _failure(
+                "Request body must be a JSON object", 400, "invalid-request"
+            )
+        token = data.get("token")
+        if set(data) != {"token"} or not isinstance(token, str):
+            return _failure("token must be the review's token", 400, "invalid-request")
+        if not 0 < len(token) <= MAX_TOKEN_LENGTH:
+            return _failure("token must be the review's token", 400, "invalid-request")
+        await self._drop_expired_restores()
+        held, refused = self._peek_restore(token)
+        if refused is not None:
+            await self._drop_expired_restores()  # one peek found expired
+            return refused
+        db = self.db
+        if held.db_identity != self._database_identity(db):
+            await self._discard_popped(token)
+            return _failure(
+                "The database was replaced since the review. Review again.",
+                409,
+                "storage-changed",
+            )
+        try:
+            async with self._jobs.lease("Restore review check"):
+                _live, fingerprint = await self._run_in_executor(
+                    self._live_fingerprint, db
+                )
+        except JobBusy as busy:
+            return busy_response(busy)
+        if fingerprint != held.fingerprint:
+            # It can never match again: free the stage for a new review.
+            await self._discard_popped(token)
+            return _failure(PLAN_CHANGED, 409, "plan-changed")
+        # The token may have been used, expired or discarded meanwhile.
+        held, refused = self._peek_restore(token)
+        if refused is not None:
+            await self._drop_expired_restores()
+            return refused
+        if db is not self.db:
+            return _failure(
+                "The database was replaced since the review. Review again.",
+                409,
+                "storage-changed",
+            )
+        try:
+            job = self._jobs.start(
+                RESTORE_JOB_KIND,
+                RESTORE_JOB_TITLE,
+                # It replaces the whole database: it runs alone, beside no
+                # job of any class, like Move library.
+                admission="exclusive",
+                cancellable=False,
+                scope={},
+                groups=RESTORE_GROUPS,
+                runner=lambda job: self._run_restore(job, db, held, token),
+            )
+        except JobBusy as busy:
+            return busy_response(busy)  # the token stays usable
+        # Same loop turn as the peek and the start: the runner has not run.
+        self._restore_plans.take(token, job.id)
+        return web.json_response({"success": True, "job": job.summary()}, status=202)
+
+    async def _run_restore(self, job, db, held, token=None):
+        from .maintenance import _fail_job
+
+        staged = held.staged
+        keep_stage = False
+        try:
+            job.update(status_line="Waiting for other requests to finish")
+            if not await self._jobs.drain_leases():
+                # Nothing ran: the reviewed stage stays usable (#335 M2),
+                # unless it expired meanwhile or its slot was reused.
+                if token is not None and self._restore_plans.give_back(token, held):
+                    keep_stage = True
+                    self._schedule_restore_expiry()
+                    job.scope["review_kept"] = True
+                    return _fail_job(job, "busy", REVIEW_KEPT)
+                return _fail_job(job, "busy", REQUESTS_BUSY)
+            job.update(status_line="Checking the library")
+            _live, fingerprint = await self._run_in_executor(self._live_fingerprint, db)
+            if db is not self.db or fingerprint != held.fingerprint:
+                return _fail_job(job, "plan-changed", PLAN_CHANGED)
+            job.update(status_line="Restoring the database")
+            job.log_line("Restoring the reviewed backup")
+            model = db.model
+            try:
+                backup_path = await self._publish(model, staged)
+            except restore_stage.StageChanged:
+                return _fail_job(job, "plan-changed", PLAN_CHANGED)
+            except SafetyBackupFailed:
+                return _fail_job(
+                    job,
+                    "backup-failed",
+                    "The current library could not be backed up; nothing was "
+                    "changed.",
+                )
+            except sqlite3.OperationalError as error:
+                kept = (
+                    " The safety backup was kept."
+                    if getattr(error, "_prompt_manager_restore_backup_created", False)
+                    else ""
+                )
+                self.logger.error(f"Restore failed: {error}")
+                return _fail_job(job, "restore-failed", NOT_RESTORED + kept)
+        except Exception:
+            self.logger.exception("Restore job failed")
+            return _fail_job(job, None, NOT_RESTORED)
+        finally:
+            if not keep_stage:
+                await self._discard_held([_Orphan(staged)])
+        # The copy replaced the library: the restore is done (#335 review I1).
+        # Every later step only logs a failure.
+        await self._after_publish(model.db_path)
+        if backup_path:
+            job.log_line(f"Safety backup {os.path.basename(backup_path)}")
+        else:
+            job.log_line("No safety backup: there was no library to keep")
+        repaired = documents_line(staged.documents)
+        if repaired:
+            job.log_line(repaired)
+        line = restored_line(staged.summary)
+        job.log_line(line)
+        job.update(progress=100, status_line=line)
+
+
+class _Orphan:
+    """A stage with no store entry, in the shape ``_discard_held`` takes."""
+
+    def __init__(self, staged):
+        self.staged = staged
+
+
+def _too_many_reviews():
+    return _failure(
+        "Two restores are already being reviewed. Discard one first.",
+        429,
+        "too-large",
+    )

py/api/duplicate_files.py

@@ -0,0 +1,779 @@
+"""Duplicate image files on the job registry (#249 System S6, Task 17).
+
+- ``POST /prompt_manager/jobs/duplicates`` starts the find (202 ``{job}``):
+  kind ``duplicates``, "Find duplicate image files", admission ``read``,
+  cancellable, outcome group ``groups_found``. It hashes the media files of
+  every effective source (``_hash_media_groups``, shared with the legacy
+  scan) and the server keeps the groups it found under the job id: content
+  hash, root-relative paths and each file's source index. A find is refused
+  while a duplicate removal runs, and one find runs at a time.
+- ``GET /prompt_manager/maintenance/duplicates/{job_id}?offset&limit`` pages
+  those groups, at most ``MAX_GROUP_PAGE`` at a time: ``{success, job:{id,
+  state}, total, offset, limit, groups:[{group_id, size, count, files}]}``.
+  Each file names its root-relative ``path``, its source's public label and
+  index and the Images serve URLs; never an absolute path.
+- ``POST /prompt_manager/maintenance/preview {operation:"duplicate_files",
+  options:{job_id, keep:[{group_id, root_index, path}]}}`` reviews a removal:
+  in each group named, the files kept are the ones listed and every other
+  copy is removed. Each keeper and each removal is checked against the held
+  group, with containment decided as text before any filesystem access
+  (``file_problem``): inside its source, a media file outside
+  ``thumbnails``, then a regular file (not a link) whose resolved path is
+  still inside the source, with the same size and content hash. A removal
+  that fails, or whose kept copy fails, is protected and listed with the
+  reason. The plan carries the files' database links, which move to the
+  kept copy.
+- ``POST /prompt_manager/maintenance/apply {token}`` runs the reviewed plan
+  as the ``duplicate_cleanup`` job: admission ``records``, not cancellable,
+  groups ``removed``, ``kept`` and ``errors``. It checks the sources are
+  unchanged, takes the safety backup the policy promises (the database only;
+  removed files are not in it), then for each removal rechecks its kept copy
+  and the file itself (``file_problem``) and removes it with every handle
+  closed (``_unlink``), together with its thumbnail. A file that changed is
+  kept; the first unlink that fails stops the job, a locked file with the
+  coded ``LOCKED_FILE`` message (never the OS text), and the files after it
+  are not attempted. The database links of the files actually removed then
+  move to their kept copy (``PromptDatabase.move_file_links``).
+
+The legacy gallery routes (``/scan_duplicates``, its stream and status, and
+``/delete_duplicate_images``) keep their shapes on the same registry kinds;
+see ``py/api/admin.py``.
+"""
+
+import asyncio
+import os
+from pathlib import Path
+
+from aiohttp import web
+
+from .admin import DUPLICATE_FIND_LEGACY_TITLE, _remove_thumbnail
+from .duplicate_review import (  # noqa: F401 (CHANGED, OUTSIDE_SOURCE: public)
+    CHANGED,
+    DELETE_FAILED,
+    FIND_CANCELLED,
+    FIND_ERROR_EVENT,
+    FIND_FAILED,
+    GONE,
+    KEEPER,
+    KEEPER_CHANGED,
+    KEEPER_GONE,
+    KEEPER_WENT,
+    KEPT_COPY,
+    LOCKED_FILE,
+    MAYBE_SAME_FILE,
+    NO_FILE_ID_ROW,
+    NOT_ATTEMPTED,
+    OUTSIDE_SOURCE,
+    RECORDS_FAILED,
+    ROW_DETAILS,
+    SAME_FILE,
+    SOURCES_CHANGED,
+    SOURCES_CHANGED_REVIEW,
+    HeldFind,
+    SourcesChanged,
+    _fingerprint,
+    _group_order,
+    _identity,
+    _parse_options,
+    _plural,
+    _public_plan,
+    _select,
+    file_problem,
+    human_bytes,
+    still_kept,
+)
+from .duplicate_spellings import Spellings, copy_move
+from .images import _favorite_root_key, _output_image_entry
+from .job_routes import busy_response
+from .jobs import (
+    DUPLICATE_CLEANUP_GROUP_NAMES,
+    DUPLICATE_CLEANUP_JOB_KIND,
+    DUPLICATE_GROUP_NAMES,
+    DUPLICATES_JOB_KIND,
+    JobBusy,
+)
+from .maintenance import DUPLICATE_FILES, _fail_job, _failure, _invalid, backup_note
+
+try:
+    from ...database.duplicate_copies import FILE_LINK_SQL
+except ImportError:
+    from database.duplicate_copies import FILE_LINK_SQL
+
+DUPLICATE_FIND_TITLE = "Find duplicate image files"
+DUPLICATE_CLEANUP_TITLE = "Remove duplicate image files"
+MAX_GROUP_PAGE = 10  # groups a page lists (D69: ten at a time)
+MAX_HELD_FINDS = 3  # finds whose groups the server keeps for review
+favorite_root_key = _favorite_root_key
+
+
+def query_plan_sql():
+    """The link reconciliation's statements (EXPLAIN QUERY PLAN checks)."""
+    return list(FILE_LINK_SQL)
+
+
+def _unlink(path):
+    """Remove one file (the caller closed every handle on it)."""
+    os.remove(path)
+
+
+class DuplicateFilesMixin:
+    """Mixin providing the duplicate-file find, its groups and its removal."""
+
+    def _register_duplicate_routes(self, routes):
+        @routes.post("/prompt_manager/jobs/duplicates")
+        async def start_duplicate_find_route(request):
+            return await self.start_duplicate_find(request)
+
+        @routes.get("/prompt_manager/maintenance/duplicates/{job_id}")
+        async def duplicate_groups_route(request):
+            return await self.duplicate_groups(request)
+
+    # ── find ──────────────────────────────────────────────────────────
+
+    async def start_duplicate_find(self, request):
+        """Start the duplicate find (202), or 409 naming the job in the way."""
+        try:
+            job = self._start_duplicate_find(origin="workspace")
+        except JobBusy as busy:
+            return busy_response(busy)
+        return web.json_response({"success": True, "job": job.summary()}, status=202)
+
+    def _start_duplicate_find(self, origin):
+        """Register a find job (on the loop); raises JobBusy.
+
+        A workspace find walks every effective source; a gallery one the
+        gallery's output folder, as the legacy scan did. Both resolve their
+        folders when the job begins, so a source change later cannot move it.
+        """
+        cleanup = self._jobs.active(DUPLICATE_CLEANUP_JOB_KIND)
+        if cleanup is not None:
+            raise JobBusy(cleanup)
+        held = HeldFind(origin)
+        if origin == "workspace":
+            title = DUPLICATE_FIND_TITLE
+        else:
+            title = DUPLICATE_FIND_LEGACY_TITLE
+        job = self._jobs.start(
+            DUPLICATES_JOB_KIND,
+            title,
+            admission="read",
+            cancellable=True,
+            groups=DUPLICATE_GROUP_NAMES,
+            runner=lambda job: self._run_duplicate_find(job, held),
+        )
+        held.job_id = job.id
+        self._remember_find(held)
+        return job
+
+    def _remember_find(self, held):
+        finds = self._duplicate_finds
+        finds[held.job_id] = held
+        for job_id in list(finds):
+            if self._jobs.get(job_id) is None:
+                del finds[job_id]
+        while len(finds) > MAX_HELD_FINDS:
+            del finds[next(iter(finds))]
+
+    def _find_covers(self, job, legacy_dir):
+        held = self._duplicate_finds.get(job.id)
+        return held is not None and held.covers(legacy_dir)
+
+    def _latest_duplicate_find(self):
+        """The running find, else the newest finished one this session."""
+        for job in self._jobs.list():
+            if job.kind == DUPLICATES_JOB_KIND and job.id in self._duplicate_finds:
+                return job
+        return None
+
+    def _resolve_find_roots(self, held):
+        """Fill in where a find looks (blocking): sources and the gallery folder."""
+        listed = [os.path.abspath(str(d)) for d in self._get_all_output_dirs()]
+        held.legacy_dir = self._find_comfyui_output_dir()
+        if held.origin == "workspace":
+            held.roots = list(enumerate(listed))
+            return
+        if not held.legacy_dir or not os.path.isdir(held.legacy_dir):
+            self.logger.warning("ComfyUI output directory not found")
+            held.roots = []
+            return
+        legacy = os.path.abspath(held.legacy_dir)
+        index = next(
+            (i for i, d in enumerate(listed) if _identity(d) == _identity(legacy)),
+            None,
+        )
+        held.roots = [(index, legacy)]
+
+    def _find_progress(self, job, done, total):
+        if done < job.processed:
+            return  # hashing threads report out of order; keep the count rising
+        pct = int(done / total * 100) if total else 100
+        job.update(
+            processed=done,
+            total=total,
+            status_line=f"Hashing file {done:,} of {total:,}",
+        )
+        job.publish(
+            {
+                "type": "progress",
+                "progress": pct,
+                "status": f"Hashing file {done}/{total}...",
+                "processed": done,
+                "found": 0,
+            }
+        )
+
+    async def _run_duplicate_find(self, job, held):
+        loop = asyncio.get_running_loop()
+
+        def report(done, total):  # from the hashing threads
+            loop.call_soon_threadsafe(self._find_progress, job, done, total)
+
+        try:
+            job.update(status_line="Looking for media files")
+            job.publish(
+                {
+                    "type": "progress",
+                    "progress": 0,
+                    "status": "Collecting media files...",
+                    "processed": 0,
+                    "found": 0,
+                }
+            )
+            await self._run_in_executor(self._resolve_find_roots, held)
+            job.scope["output_folders"] = len(held.roots)
+            job.log_line(f"Searching {_plural(len(held.roots), 'source')}")
+            groups = await self._run_in_executor(
+                self._hash_media_groups,
+                [root for _index, root in held.roots],
+                report,
+                lambda: job.cancelled,
+            )
+            if job.cancelled:
+                job.update(status_line="Cancelled; nothing was changed.")
+                job.publish({"type": "error", "message": FIND_CANCELLED})
+                job.finish("cancelled")
+                return
+            await self._finish_find(job, held, groups)
+        except Exception:
+            self.logger.exception("Duplicate search failed")
+            job.update(status_line=FIND_FAILED)
+            job.publish({"type": "error", "message": FIND_ERROR_EVENT})
+            job.finish("failed")
+
+    async def _finish_find(self, job, held, groups):
+        for group in groups:
+            group["group_id"] = group["hash"]
+            for record in group["files"]:
+                index, root = held.roots[record.pop("slot")]
+                record["root_index"] = index
+                record["root"] = root
+        groups.sort(key=_group_order)
+        held.groups = groups
+        labels = {root: self._public_path(root) for _index, root in held.roots}
+        rows = [
+            {
+                "path": group["files"][0]["rel"],
+                "root": labels[group["files"][0]["root"]],
+                "root_index": group["files"][0]["root_index"],
+                "detail": f"{len(group['files'])} identical files · "
+                f"{human_bytes(group['size'])} each",
+            }
+            for group in groups
+        ]
+        job.record_counted("groups_found", len(groups), rows)
+        line = f"Found {_plural(len(groups), 'group')} of duplicate files"
+        job.log_line(line)
+        legacy = []
+        if held.covers(held.legacy_dir) and held.legacy_dir:
+            legacy = await self._run_in_executor(
+                self._legacy_duplicate_groups, groups, held.legacy_dir
+            )
+        # Every file was read by now (the last reports may still be queued).
+        job.update(progress=100, status_line=line, processed=job.total)
+        job.publish(
+            {
+                "type": "complete",
+                "processed": job.processed,
+                "found": len(legacy),
+                "duplicates": legacy,
+                "message": f"Found {len(legacy)} groups of duplicate images",
+            }
+        )
+
+    # ── groups ────────────────────────────────────────────────────────
+
+    def _held_result(self, job_id):
+        """``(held, None)`` for a finished find's groups, else an error reply."""
+        held = self._duplicate_finds.get(job_id)
+        job = self._jobs.get(job_id)
+        if held is None or job is None or job.kind != DUPLICATES_JOB_KIND:
+            return None, _failure(
+                "No duplicate search with this id. Search again.", 404, "not-found"
+            )
+        if job.running:
+            return None, _failure(
+                "The duplicate search is still running.", 409, "job-running"
+            )
+        if held.groups is None:
+            return None, _failure(
+                "This search did not finish. Search again.", 409, "no-groups"
+            )
+        return held, None
+
+    async def duplicate_groups(self, request):
+        """One page of a finished find's groups (at most MAX_GROUP_PAGE)."""
+        try:
+            offset = int(request.query.get("offset", "0"))
+            limit = int(request.query.get("limit", str(MAX_GROUP_PAGE)))
+        except ValueError:
+            return _invalid("offset and limit must be whole numbers")
+        if offset < 0 or not 0 < limit <= MAX_GROUP_PAGE:
+            return _invalid(f"limit must be 1 to {MAX_GROUP_PAGE}; offset 0 or more")
+        job_id = request.match_info["job_id"]
+        held, error = self._held_result(job_id)
+        if error is not None:
+            return error
+        page = held.groups[offset : offset + limit]
+        groups = await self._run_in_executor(self._describe_groups, page)
+        job = self._jobs.get(job_id)
+        return web.json_response(
+            {
+                "success": True,
+                "job": {"id": job.id, "state": job.state},
+                "total": len(held.groups),
+                "offset": offset,
+                "limit": limit,
+                "groups": groups,
+            },
+            headers={"Cache-Control": "no-store"},
+        )
+
+    def _describe_groups(self, groups):
+        """Public group rows (blocking: one stat per file)."""
+        return [
+            {
+                "group_id": group["group_id"],
+                "size": group["size"],
+                "count": len(group["files"]),
+                "files": [self._describe_copy(record) for record in group["files"]],
+            }
+            for group in groups
+        ]
+
+    def _describe_copy(self, record):
+        label = self._public_path(record["root"])
+        base = {
+            "filename": os.path.basename(record["rel"]),
+            "path": record["rel"],
+            "root": label,
+            "root_index": record["root_index"],
+            "url": None,
+            "thumbnail_url": None,
+            "size": record["size"],
+            "modified_time": record["mtime"],
+            "media_type": "image",
+            "missing": False,
+        }
+        if record["root_index"] is None:
+            return base
+        try:
+            entry = _output_image_entry(
+                Path(record["abs"]), Path(record["root"]), record["root_index"], label
+            )
+        except (OSError, ValueError):
+            return {**base, "missing": True}
+        return {
+            **base,
+            "url": entry["url"],
+            "thumbnail_url": entry["thumbnail_url"],
+            "size": entry["size"],
+            "modified_time": entry["modified_time"],
+            "media_type": entry["media_type"],
+        }
+
+    # ── review ────────────────────────────────────────────────────────
+
+    def _listed_sources(self):
+        """``{identity: index}`` of the effective sources now (blocking)."""
+        return {
+            _identity(d): index for index, d in enumerate(self._get_all_output_dirs())
+        }
+
+    @staticmethod
+    def _source_listed(listed, index, root):
+        return index is not None and listed.get(_identity(root)) == index
+
+    async def preview_duplicate_files(self, options):
+        """The ``duplicate_files`` plan for one finished find and its keepers."""
+        job_id, keep, message = _parse_options(options)
+        if message:
+            return _invalid(message)
+        held, error = self._held_result(job_id)
+        if error is not None:
+            return error
+        selection, message = _select(held, keep)
+        if message:
+            return _invalid(message)
+        db = self.db
+        identity = self._database_identity(db)
+        try:
+            review = await self._run_in_executor(
+                self._review_duplicate_files, db, selection
+            )
+        except SourcesChanged:
+            return _failure(SOURCES_CHANGED_REVIEW, 409, "sources-changed")
+        except Exception:
+            self.logger.exception("Duplicate file review failed")
+            return _failure("Failed to review maintenance", 500)
+        return await self._plan_response(
+            db,
+            identity,
+            DUPLICATE_FILES,
+            review["fingerprint"],
+            review["public"],
+            {
+                "targets": review["targets"],
+                "kept": review["kept"],
+                "protected": review["public"]["protected"]["count"],
+            },
+        )
+
+    def _review_duplicate_files(self, db, selection):
+        """Check every keeper and removal now (blocking); the plan's parts.
+
+        No file is read: each copy is bound to what the search saw by its
+        size, mtime and inode, and never to its kept copy itself. The removal
+        job hashes each file again right before it unlinks it.
+        """
+        listed = self._listed_sources()
+        targets, kept, protected = [], [], {}
+        for group, keepers in selection.values():
+            removals = [r for r in group["files"] if r not in keepers]
+            for record in removals:
+                if record["root_index"] is not None and not self._source_listed(
+                    listed, record["root_index"], record["root"]
+                ):
+                    raise SourcesChanged(record["root"])
+            keeper = next(
+                (k for k in keepers if _bound_problem(k, group) is None), None
+            )
+            reviewed = []
+            for record in removals:
+                if keeper is None:
+                    problem = KEEPER
+                elif record["root_index"] is None:
+                    problem = OUTSIDE_SOURCE
+                else:
+                    problem = _bound_problem(record, group, keeper)
+                if problem:
+                    protected[problem] = protected.get(problem, 0) + 1
+                    continue
+                reviewed.append(self._target(group, record, keeper))
+            if reviewed:
+                targets.extend(reviewed)
+                kept.append(self._copy_row(keeper, KEPT_COPY))
+        records = {}
+        if targets:
+            spellings = self._source_spellings()
+            records = db.count_copy_records(
+                {
+                    t["abs"]: {
+                        "spellings": list(spellings.of(t["abs"]).values()),
+                        "locator": t["locator"],
+                        "sha256": t["hash"],
+                    }
+                    for t in targets
+                }
+            )
+        return {
+            "targets": targets,
+            "kept": kept,
+            "fingerprint": _fingerprint(targets),
+            "public": _public_plan(targets, protected, records),
+        }
+
+    def _source_spellings(self):
+        """The folder spellings records may name files by (blocking).
+
+        The search walks each source's real path, while a record names a file
+        as it was seen when written: under the folder the image monitor
+        watches, the configured spelling, ComfyUI's output folder, a symlink
+        to it, or a parent of a source added later. ``Spellings`` matches
+        them to each file by containment (``py/api/duplicate_spellings.py``).
+        """
+        from ..config import GalleryConfig
+
+        listed = [os.path.abspath(str(d)) for d in self._get_all_output_dirs()]
+        candidates = list(self._monitored_directories())
+        candidates += list(GalleryConfig.MONITORING_DIRECTORIES)
+        try:
+            import folder_paths
+
+            candidates.append(folder_paths.get_output_directory())
+        except Exception:  # nosec B110 - outside ComfyUI there is none
+            pass
+        candidates.append(self._find_comfyui_output_dir())
+        folders = [
+            os.path.abspath(str(c)) for c in candidates if c and os.path.isabs(str(c))
+        ]
+        return Spellings(folders + listed, listed)
+
+    def _target(self, group, record, keeper):
+        return {
+            "group_id": group["group_id"],
+            "hash": group["hash"],
+            "size": record["size"],
+            "root_index": record["root_index"],
+            "root": record["root"],
+            "root_label": self._public_path(record["root"]),
+            "abs": record["abs"],
+            "rel": record["rel"],
+            "keeper_abs": keeper["abs"],
+            "keeper_rel": keeper["rel"],
+            "keeper_root": keeper["root"],
+            "keeper_size": keeper["size"],
+            "locator": os.path.normcase(record["abs"]),
+            "keeper_locator": os.path.normcase(keeper["abs"]),
+        }
+
+    def _copy_row(self, record, detail):
+        return {
+            "path": record["rel"],
+            "root": self._public_path(record["root"]),
+            "root_index": record["root_index"],
+            "detail": detail,
+        }
+
+    # ── removal ───────────────────────────────────────────────────────
+
+    def _start_duplicate_cleanup(self, db, plan, backup_on):
+        """Register the removal job for a reviewed plan (on the loop)."""
+        find = self._jobs.active(DUPLICATES_JOB_KIND)
+        if find is not None:
+            raise JobBusy(find)
+        return self._jobs.start(
+            DUPLICATE_CLEANUP_JOB_KIND,
+            DUPLICATE_CLEANUP_TITLE,
+            admission="records",
+            cancellable=False,
+            scope={"operation": DUPLICATE_FILES},
+            groups=DUPLICATE_CLEANUP_GROUP_NAMES,
+            runner=lambda job: self._run_duplicate_cleanup(job, db, plan, backup_on),
+        )
+
+    def _sources_unchanged(self, targets):
+        listed = self._listed_sources()
+        return all(
+            self._source_listed(listed, t["root_index"], t["root"]) for t in targets
+        )
+
+    async def _run_duplicate_cleanup(self, job, db, plan, backup_on):
+        targets = plan.payload["targets"]
+        unchanged = await self._run_in_executor(self._sources_unchanged, targets)
+        if not unchanged:
+            return _fail_job(job, "sources-changed", SOURCES_CHANGED)
+        ok, backup = await self._safety_backup_step(job, db, backup_on)
+        if not ok:
+            return
+        try:
+            await self._remove_duplicates(job, db, plan, backup)
+        finally:
+            if backup:
+                await self._prune_backup_pool(job, db)
+
+    async def _remove_duplicates(self, job, db, plan, backup):
+        targets = plan.payload["targets"]
+        for row in plan.payload["kept"]:
+            job.record("kept", row, f"= {row['root']}/{row['path']} · {KEPT_COPY}")
+        job.update(total=len(targets), status_line="Removing duplicate files")
+        spellings = await self._run_in_executor(self._source_spellings)
+        removed, failure, keepers = 0, None, {}
+        totals = dict.fromkeys(("moved", "merged", "favorites", "tags", "review"), 0)
+        for done, target in enumerate(targets, start=1):
+            if failure is not None:
+                self._record_target(job, "kept", target, NOT_ATTEMPTED)
+                continue
+            outcome, detail, counts = await self._run_in_executor(
+                self._remove_one_duplicate, db, target, keepers, spellings
+            )
+            for key, value in (counts or {}).items():
+                totals[key] += value
+            if outcome == "removed":
+                removed += 1
+                text = f"A copy of {target['keeper_rel']}"
+                self._record_target(job, "removed", target, text, "-")
+            elif outcome == "kept":
+                self._record_target(job, "kept", target, ROW_DETAILS[detail])
+            else:
+                failure = detail
+                self._record_target(job, "errors", target, detail, "!")
+            job.update(processed=done, progress=int(done / len(targets) * 100))
+        if removed:
+            self.invalidate_gallery_cache()
+        self._log_moved_records(job, totals)
+        line = f"Removed {_plural(removed, 'duplicate file')}"
+        if removed < len(targets):
+            line += f", {len(targets) - removed:,} not removed"
+        job.log_line(line)
+        if failure is not None:
+            line = f"Stopped after an error · {line}"
+        job.update(progress=100, status_line=f"{line} · {backup_note(backup)}")
+        if failure is not None:
+            job.publish({"type": "error", "code": "delete-failed", "message": line})
+            job.finish("failed")
+
+    @staticmethod
+    def _log_moved_records(job, totals):
+        links = totals["moved"] + totals["merged"]
+        if links:
+            job.log_line(f"Moved {_plural(links, 'database link')} to the kept copies")
+        if totals["favorites"]:
+            job.log_line(
+                f"Moved {_plural(totals['favorites'], 'favorite')} to the kept copies"
+            )
+        if totals["tags"]:
+            job.log_line(
+                f"Added {_plural(totals['tags'], 'image tag')} to the kept copies"
+            )
+        if totals["review"]:
+            job.log_line(
+                f"Settled {_plural(totals['review'], 'Needs review item')} "
+                "of removed copies"
+            )
+
+    @staticmethod
+    def _record_target(job, group, target, detail, mark="="):
+        row = {
+            "path": target["rel"],
+            "root": target["root_label"],
+            "root_index": target["root_index"],
+            "detail": detail,
+        }
+        job.record(
+            group, row, f"{mark} {target['root_label']}/{target['rel']} · {detail}"
+        )
+
+    def _remove_one_duplicate(self, db, target, keepers, spellings):
+        """``(outcome, detail, counts)`` for one reviewed removal (blocking).
+
+        The kept copy (once per group; cached in ``keepers``) and the file
+        are checked again, hashes included, and the file must not be its kept
+        copy. Then the file's records move to the kept copy in one short
+        transaction, and only then is the file unlinked: a crash or a failed
+        unlink leaves its records on the identical kept copy, never on a
+        deleted file. A failed move leaves the file and its records alone.
+        """
+        hasher = self._calculate_file_hash
+        group_id = target["group_id"]
+        if group_id not in keepers:
+            keepers[group_id] = _kept_copy_state(target, hasher)
+        if keepers[group_id] is None:
+            return "kept", KEEPER, None
+        problem = file_problem(
+            target["abs"],
+            target["root"],
+            target["hash"],
+            target["size"],
+            hasher,
+            keeper=target["keeper_abs"],
+            keeper_root=target["keeper_root"],
+        )
+        if problem:
+            return "kept", problem, None
+        try:
+            # Held open until the unlink: on Windows, deleting the kept copy
+            # itself through another path then fails instead of removing it.
+            hold = open(target["keeper_abs"], "rb")
+        except OSError:
+            return "kept", KEEPER, None
+        with hold:
+            return self._move_then_unlink(
+                db, target, keepers[group_id], spellings, hold
+            )
+
+    def _move_then_unlink(self, db, target, kept_stat, spellings, hold):
+        try:
+            counts = db.move_copy_records(copy_move(target, kept_stat, spellings))
+        except Exception:
+            self.logger.exception(f"Could not move the records of {target['rel']}")
+            return "error", RECORDS_FAILED, None
+        if not still_kept(target, hold):
+            # The kept copy went away or changed while the records moved:
+            # keep this file and give its records back to it.
+            return "kept", KEEPER_GONE, self._move_back(db, target, spellings)
+        try:
+            _unlink(target["abs"])
+        except FileNotFoundError:
+            return "removed", None, counts
+        except PermissionError:
+            self.logger.warning(
+                f"Duplicate file is locked: {target['rel']}; "
+                "its records now name the kept copy"
+            )
+            return "error", LOCKED_FILE, counts
+        except OSError:
+            self.logger.warning(
+                f"Could not delete duplicate file {target['rel']}; "
+                "its records now name the kept copy",
+                exc_info=True,
+            )
+            return "error", DELETE_FAILED, counts
+        self.logger.info(f"Deleted duplicate file: {target['rel']}")
+        _remove_thumbnail(Path(target["root"]), Path(target["rel"]), self.logger)
+        return "removed", None, counts
+
+    def _move_back(self, db, target, spellings):
+        """Give the kept copy's records to the file that stays (blocking)."""
+        swapped = {
+            **target,
+            "abs": target["keeper_abs"],
+            "root": target["keeper_root"],
+            "rel": target["keeper_rel"],
+            "locator": target["keeper_locator"],
+            "keeper_abs": target["abs"],
+            "keeper_root": target["root"],
+            "keeper_rel": target["rel"],
+            "keeper_locator": target["locator"],
+        }
+        try:
+            return db.move_copy_records(
+                copy_move(swapped, os.stat(target["abs"]), spellings)
+            )
+        except Exception:
+            self.logger.exception(f"Could not give the records back to {target['rel']}")
+            return None
+
+
+def _bound_problem(record, group, keeper=None):
+    """``file_problem`` without reading the file: size, mtime and inode.
+
+    ``keeper`` is the kept copy's record, never offered as a copy of itself.
+    """
+    return file_problem(
+        record["abs"],
+        record["root"],
+        group["hash"],
+        record["size"],
+        hash_check=False,
+        mtime_ns=record.get("mtime_ns"),
+        inode=record.get("inode"),
+        keeper=keeper["abs"] if keeper else None,
+        keeper_root=keeper["root"] if keeper else None,
+    )
+
+
+def _kept_copy_state(target, hasher):
+    """The kept copy's ``os.stat`` when it is still the reviewed bytes, else None."""
+    problem = file_problem(
+        target["keeper_abs"],
+        target["keeper_root"],
+        target["hash"],
+        target["keeper_size"],
+        hasher,
+    )
+    if problem:
+        return None
+    try:
+        return os.stat(target["keeper_abs"])
+    except OSError:
+        return None

py/api/duplicate_review.py

@@ -0,0 +1,451 @@
+"""Reviewing duplicate image files: the checks and the plan (#249 S6, T17).
+
+Pure helpers of ``py/api/duplicate_files.py``: the keep-list parsing, the
+per-file check ``file_problem`` (containment decided as text before any
+filesystem access, then a regular file of the found size and hash) and the
+public ``duplicate_files`` plan.
+"""
+
+import hashlib
+import json
+import os
+import stat as stat_module
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .admin import DELETABLE_MEDIA_EXTENSIONS
+from .maintenance import DUPLICATE_FILES
+
+# Keep entries one review takes; with paths of a few hundred characters the
+# list stays inside the preview body cap (DUPLICATE_PREVIEW_BODY_MAX, 1 MiB).
+MAX_KEEP = 2000
+MAX_DETAILS = 50
+MAX_JOB_ID = 64
+HASH_CHUNK = 1024 * 1024
+
+# What ``file_problem`` finds, and how a plan counts it as protected.
+OUTSIDE_SOURCE = "outside"
+LINK = "link"
+CHANGED_CONTENT = "changed"
+GONE = "gone"
+UNREADABLE = "unreadable"
+KEEPER = "keeper"
+SAME = "same"
+MAYBE_SAME = "maybe-same"
+NO_FILE_ID = "no-file-id"
+# Two mounts of one share may round mtimes differently (SMB keeps 100 ns,
+# FAT 2 s): within this, equal sizes on another device may be one file.
+MOUNT_MTIME_SLACK_NS = 2_000_000_000
+PROTECTED_REASONS = {
+    MAYBE_SAME: (
+        "file may be the same file reached through another mount or share",
+        "files may be the same file reached through another mount or share",
+    ),
+    NO_FILE_ID: (
+        "file: can't confirm this is a separate file on this drive",
+        "files: can't confirm these are separate files on this drive",
+    ),
+    SAME: (
+        "file is the same file as its kept copy",
+        "files are the same file as their kept copy",
+    ),
+    OUTSIDE_SOURCE: (
+        "file is not inside a configured source",
+        "files are not inside a configured source",
+    ),
+    LINK: ("file is a link, not a regular file", "files are links, not regular files"),
+    CHANGED_CONTENT: (
+        "file changed since the search",
+        "files changed since the search",
+    ),
+    GONE: ("file no longer exists", "files no longer exist"),
+    UNREADABLE: ("file could not be read", "files could not be read"),
+    KEEPER: (
+        "file kept: its kept copy changed or is gone",
+        "files kept: their kept copy changed or is gone",
+    ),
+}
+# Job outcome rows (never an OS error text).
+CHANGED = "The file changed since the review; it was kept."
+KEEPER_CHANGED = "The kept copy changed or is gone; this file was kept."
+SAME_FILE = "This is the same file as its kept copy; it was kept."
+MAYBE_SAME_FILE = (
+    "May be the same file reached through another mount or share; it was kept."
+)
+NO_FILE_ID_ROW = "Can't confirm this is a separate file on this drive; it was kept."
+KEEPER_GONE = "keeper-gone"
+KEEPER_WENT = (
+    "The kept copy changed or went away during the removal; this file was kept "
+    "and its links stay with it."
+)
+ROW_DETAILS = {
+    KEEPER_GONE: None,  # filled below
+    MAYBE_SAME: MAYBE_SAME_FILE,
+    NO_FILE_ID: NO_FILE_ID_ROW,
+    SAME: SAME_FILE,
+    OUTSIDE_SOURCE: "The file is no longer inside its source; it was kept.",
+    LINK: "The file is now a link, not a regular file; it was kept.",
+    CHANGED_CONTENT: CHANGED,
+    GONE: "The file was already gone.",
+    UNREADABLE: "The file could not be read; it was kept.",
+    KEEPER: KEEPER_CHANGED,
+}
+# An unlink fails only after the file's records moved to its kept copy.
+LOCKED_FILE = (
+    "The file is open in another program or read-only; it was not deleted, "
+    "and its links now name the kept copy."
+)
+DELETE_FAILED = "The file could not be deleted; its links now name the kept copy."
+NOT_ATTEMPTED = "Not attempted: the job stopped after an error."
+KEPT_COPY = "Kept copy"
+SOURCES_CHANGED = (
+    "The sources changed since the review; nothing was deleted. Review again."
+)
+RECORDS_FAILED = (
+    "The database could not be updated, so the file was not deleted. "
+    "Its links and tags are unchanged."
+)
+FIND_FAILED = "The duplicate search failed."
+FIND_ERROR_EVENT = "An internal error occurred. Check server logs for details."
+FIND_CANCELLED = "Duplicate scan cancelled"
+
+
+class SourcesChanged(Exception):
+    """A source a review or removal names is no longer listed at its index."""
+
+
+ROW_DETAILS[KEEPER_GONE] = KEEPER_WENT
+
+
+def still_kept(target, hold):
+    """Right before an unlink: the held kept copy is still the file at its
+    path, and the file is still not the kept copy itself (``keeper_problem``).
+    """
+    try:
+        if not os.path.samestat(os.fstat(hold.fileno()), os.stat(target["keeper_abs"])):
+            return False
+        info = os.lstat(target["abs"])
+        problem = keeper_problem(
+            target["abs"],
+            target["root"],
+            info,
+            target["keeper_abs"],
+            target["keeper_root"],
+        )
+        return problem is None
+    except OSError:
+        return False
+
+
+def _plural(count, one, many=None):
+    return f"{count:,} {one if count == 1 else (many or one + 's')}"
+
+
+def human_bytes(size):
+    """``10 B``, ``1.5 KB``, ``2.0 MB``…"""
+    if size < 1024:
+        return f"{size:,} B"
+    for unit in ("KB", "MB", "GB", "TB"):
+        size /= 1024
+        if size < 1024 or unit == "TB":
+            return f"{size:,.1f} {unit}"
+    return f"{size:,.1f} TB"  # pragma: no cover - unreachable
+
+
+def _hash_file(path):
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        for chunk in iter(lambda: handle.read(HASH_CHUNK), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def file_problem(
+    path,
+    root,
+    digest,
+    size,
+    hasher=None,
+    *,
+    hash_check=True,
+    mtime_ns=None,
+    inode=None,
+    keeper=None,
+    keeper_root=None,
+):
+    """Why ``path`` may not be treated as a copy in ``root``, or None (blocking).
+
+    Containment is decided as text first, with no filesystem access: the
+    normalized path must lie below the normalized root, outside
+    ``thumbnails``, with a media extension. Only then is the file looked at:
+    a regular file, not a link, whose resolved path is still inside the
+    resolved root and that is not ``keeper`` itself (``keeper_problem``: a
+    hardlink, one file reached through two spellings or two mounts, or a
+    volume that cannot tell files apart), of ``size`` bytes.
+    ``mtime_ns`` and ``inode`` (``[st_dev, st_ino]``), when given, bind it to
+    what the search saw; ``hash_check`` compares its content hash with
+    ``digest`` (the removal job, right before an unlink). Every handle is
+    closed when this returns.
+    """
+    # py.config imports ComfyUI's server module: only when it is in use.
+    from ..config import _canonical_path, _lexical_path, _lexically_inside
+
+    lexical = _lexical_path(str(path))
+    base = _lexical_path(str(root))
+    if lexical == base or not _lexically_inside(lexical, [base]):
+        return OUTSIDE_SOURCE
+    parts = Path(os.path.relpath(lexical, base)).parts
+    if "thumbnails" in parts or ".." in parts:
+        return OUTSIDE_SOURCE
+    if os.path.splitext(lexical)[1].lower() not in DELETABLE_MEDIA_EXTENSIONS:
+        return OUTSIDE_SOURCE
+    try:
+        info = os.lstat(path)
+    except FileNotFoundError:
+        return GONE
+    except OSError:
+        return UNREADABLE
+    if stat_module.S_ISLNK(info.st_mode):
+        return LINK
+    if not stat_module.S_ISREG(info.st_mode):
+        return LINK
+    try:
+        if not _lexically_inside(_canonical_path(path), [_canonical_path(root)]):
+            return OUTSIDE_SOURCE  # a linked folder on the way
+        if keeper is not None:
+            same = keeper_problem(path, root, info, keeper, keeper_root)
+            if same:
+                return same
+        if info.st_size != size:
+            return CHANGED_CONTENT
+        if mtime_ns is not None and info.st_mtime_ns != mtime_ns:
+            return CHANGED_CONTENT
+        if inode is not None and [info.st_dev, info.st_ino] != list(inode):
+            return CHANGED_CONTENT
+        if hash_check and (hasher or _hash_file)(path) != digest:
+            return CHANGED_CONTENT
+    except FileNotFoundError:
+        return GONE
+    except OSError:
+        return UNREADABLE
+    return None
+
+
+def keeper_problem(path, root, info, keeper, keeper_root=None):
+    """Why ``path`` (its ``lstat`` is ``info``) may be ``keeper`` itself, or None.
+
+    - ``NO_FILE_ID``: a volume reports no file id (``st_ino`` 0), so the two
+      cannot be told apart;
+    - ``SAME``: ``os.path.samestat`` (a hardlink, or one file reached through
+      two spellings of one mount);
+    - ``MAYBE_SAME``: another device, the same size, mtimes within
+      ``MOUNT_MTIME_SLACK_NS``, and the same ``st_ino`` (NFS and SMB report
+      the server's file id) or the same path within their sources, or one
+      ending with the other on a folder name (one share mounted twice, a
+      FUSE pool over a listed disk, sources listed at different depths).
+      Protect, never guess: a true copy on another disk at the same relative
+      path is kept too.
+
+    Raises OSError when the kept copy cannot be read (the caller's GONE or
+    UNREADABLE).
+    """
+    kept = os.stat(keeper)
+    if not info.st_ino or not kept.st_ino:
+        return NO_FILE_ID
+    if os.path.samestat(info, kept):
+        return SAME
+    if info.st_dev == kept.st_dev or info.st_size != kept.st_size:
+        return None
+    if abs(info.st_mtime_ns - kept.st_mtime_ns) > MOUNT_MTIME_SLACK_NS:
+        return None
+    if info.st_ino == kept.st_ino:
+        return MAYBE_SAME
+    if keeper_root is not None and _same_tail(
+        _relative_key(path, root), _relative_key(keeper, keeper_root)
+    ):
+        return MAYBE_SAME
+    return None
+
+
+def _same_tail(one, other):
+    """Whether one relative path is the other, or ends with it on a folder name.
+
+    Two mounts of one tree may be listed at different depths (``2024/x.png``
+    in one source, ``x.png`` in the other); ``ax.png`` never matches ``x.png``.
+    """
+    if one is None or other is None:
+        return False
+    return one == other or one.endswith("/" + other) or other.endswith("/" + one)
+
+
+def _relative_key(path, root):
+    try:
+        relative = os.path.relpath(str(path), str(root))
+    except ValueError:  # another drive (Windows)
+        return None
+    return os.path.normcase(relative).replace("\\", "/")
+
+
+@dataclass
+class HeldFind:
+    """One find: where it looked and, once it finished, what it found."""
+
+    origin: str  # "workspace" or "gallery"
+    job_id: str = ""
+    roots: list = field(default_factory=list)  # [(source index or None, root)]
+    legacy_dir: str = None
+    groups: list = None  # [{group_id, hash, size, files:[record]}]
+
+    def covers(self, legacy_dir):
+        """Whether its events answer the legacy gallery for ``legacy_dir``."""
+        if self.origin == "gallery":
+            return True
+        if not legacy_dir:
+            return False
+        wanted = _identity(legacy_dir)
+        return any(_identity(root) == wanted for _index, root in self.roots)
+
+
+def _identity(path):
+    return os.path.normcase(os.path.realpath(str(path)))
+
+
+def _group_order(group):
+    return (-(len(group["files"]) - 1) * group["size"], group["hash"])
+
+
+def _keep_entry(entry):
+    """``((group_id, root_index, path), None)`` or ``(None, message)``."""
+    if not isinstance(entry, dict) or set(entry) != {"group_id", "root_index", "path"}:
+        return None, "Each keep entry is {group_id, root_index, path}"
+    group_id, index, path = entry["group_id"], entry["root_index"], entry["path"]
+    if not isinstance(group_id, str) or not 0 < len(group_id) <= 128:
+        return None, "group_id must be a group's id"
+    if index is not None and (
+        isinstance(index, bool) or not isinstance(index, int) or index < 0
+    ):
+        return None, "root_index must be a source index"
+    if not isinstance(path, str) or not 0 < len(path) <= 4096:
+        return None, "path must be a file's path in its group"
+    return (group_id, index, path), None
+
+
+def _parse_options(options):
+    """``(job_id, keep, None)`` for duplicate_files options, else a message."""
+    if not isinstance(options, dict) or set(options) != {"job_id", "keep"}:
+        return None, None, "duplicate_files takes options {job_id, keep}"
+    job_id, keep = options["job_id"], options["keep"]
+    if not isinstance(job_id, str) or not 0 < len(job_id) <= MAX_JOB_ID:
+        return None, None, "job_id must be a duplicate search's job id"
+    if not isinstance(keep, list) or not 0 < len(keep) <= MAX_KEEP:
+        return None, None, f"keep must list 1 to {MAX_KEEP:,} files to keep"
+    parsed = []
+    for entry in keep:
+        key, message = _keep_entry(entry)
+        if message:
+            return None, None, message
+        parsed.append(key)
+    return job_id, parsed, None
+
+
+def _select(held, keep):
+    """``({group_id: (group, [keeper records])}, None)`` or ``(None, message)``."""
+    groups = {group["group_id"]: group for group in held.groups}
+    selection = {}
+    for group_id, index, path in keep:
+        group = groups.get(group_id)
+        if group is None:
+            return None, "A kept file names a group this search did not find"
+        match = [
+            record
+            for record in group["files"]
+            if record["root_index"] == index and record["rel"] == path
+        ]
+        if not match:
+            return None, "A kept file is not in its group"
+        _group, keepers = selection.setdefault(group_id, (group, []))
+        if match[0] not in keepers:
+            keepers.append(match[0])
+    return selection, None
+
+
+SOURCES_CHANGED_REVIEW = (
+    "The sources changed since the search. Search for duplicates again."
+)
+
+
+def _fingerprint(targets):
+    digest = hashlib.sha256()
+    for target in sorted(targets, key=lambda t: _identity(t["abs"])):
+        part = [
+            os.path.normcase(target["abs"]),
+            target["hash"],
+            target["size"],
+            os.path.normcase(target["keeper_abs"]),
+        ]
+        digest.update(json.dumps(part).encode("utf-8") + b"\n")
+    return "sha256:" + digest.hexdigest()
+
+
+def _record_parts(records, target):
+    """What moves with one removal: its links, tags and Needs review items."""
+    found = records.get(target["abs"], {})
+    links, tags, review = (found.get(key, 0) for key in ("links", "tags", "review"))
+    parts = [
+        (
+            (
+                f"{_plural(links, 'database link')} "
+                f"{'moves' if links == 1 else 'move'} to the kept copy"
+            )
+            if links
+            else "no database links"
+        )
+    ]
+    if tags:
+        parts.append("its image tags join the kept copy's")
+    if review:
+        item = "Needs review item is" if review == 1 else "Needs review items are"
+        parts.append(f"{review:,} {item} settled")
+    return parts
+
+
+def _public_plan(targets, protected, records):
+    count = len(targets)
+    groups = len({t["group_id"] for t in targets})
+    size = sum(t["size"] for t in targets)
+    reasons = [
+        f"{n:,} {PROTECTED_REASONS[code][0 if n == 1 else 1]}"
+        for code, n in sorted(protected.items())
+    ]
+    details = [
+        {
+            "label": target["rel"],
+            "detail": f"{target['root_label']} · a copy of {target['keeper_rel']}"
+            + "".join(f" · {part}" for part in _record_parts(records, target)),
+        }
+        for target in targets[:MAX_DETAILS]
+    ]
+    label = f"{_plural(count, 'duplicate file')} in {_plural(groups, 'group')}"
+    media = (
+        f"Deletes {_plural(count, 'file')} ({human_bytes(size)}) from disk; the "
+        "kept copies stay. The safety backup covers the database, not these files."
+    )
+    tagged = sum(1 for t in targets if records.get(t["abs"], {}).get("tags"))
+    review = sum(records.get(t["abs"], {}).get("review", 0) for t in targets)
+    if tagged:
+        media += (
+            f" The image tags of {_plural(tagged, 'removed copy', 'removed copies')}"
+            " join their kept copy's."
+        )
+    if review:
+        media += (
+            f" {_plural(review, 'pending Needs review item')} of the removed "
+            f"{'copy is' if review == 1 else 'copies are'} settled."
+        )
+    return {
+        "operation": DUPLICATE_FILES,
+        "scope": {"count": count, "label": label},
+        "protected": {"count": sum(protected.values()), "reasons": reasons},
+        "media": {"deletes_files": True, "label": media},
+        "details": details,
+    }

py/api/duplicate_spellings.py

@@ -0,0 +1,133 @@
+"""Every path a duplicate copy is recorded under (#249 System S6, Task 17).
+
+The search walks each source's real path, but a record names a file the way
+it was seen when it was written: under the folder the image monitor watches,
+the configured spelling, ComfyUI's output folder, a symlink to it, or a
+parent of a source listed later. ``Spellings`` finds them by containment:
+for each known folder spelling ``S`` (resolving to the folder ``R``) and a
+file ``P`` inside ``R``, the file is also recorded as ``S + relpath(P, R)``.
+
+Folders are compared by ``os.stat`` identity (``st_dev``, ``st_ino``), not
+by text, so a case variant on a case-insensitive filesystem (macOS, Windows)
+or a symlinked spelling matches. A volume that reports no file id falls
+back to ``normcase(realpath)``. Favorites are keyed by a listed root and the
+path below it, so ``favorites`` lists every listed root that holds a file.
+Blocking: each lookup stats the file's folders once (cached).
+"""
+
+import os
+from pathlib import Path
+
+from .images import _favorite_relative_key, _favorite_root_key
+
+
+def _identity(path):
+    try:
+        info = os.stat(path)
+    except OSError:
+        return None
+    if info.st_ino:
+        return ("inode", info.st_dev, info.st_ino)
+    return ("path", os.path.normcase(os.path.realpath(str(path))))
+
+
+class Spellings:
+    """Folder spellings and listed roots, matched to files by containment."""
+
+    def __init__(self, folders, listed_roots):
+        self._cache = {}
+        self._folders = []
+        for spelled in dict.fromkeys(str(f) for f in folders if f):
+            identity = self._identity(spelled)
+            if identity is not None:
+                self._folders.append((spelled, identity))
+        self._listed = []
+        for root in dict.fromkeys(str(r) for r in listed_roots if r):
+            identity = self._identity(root)
+            if identity is not None:
+                self._listed.append((root, identity))
+
+    def _identity(self, path):
+        if path not in self._cache:
+            self._cache[path] = _identity(path)
+        return self._cache[path]
+
+    def _ancestors(self, path):
+        """``{identity: folder}`` of every folder above ``path``, nearest first."""
+        found = {}
+        folder = os.path.dirname(os.path.abspath(str(path)))
+        while True:
+            identity = self._identity(folder)
+            if identity is not None:
+                found.setdefault(identity, folder)
+            parent = os.path.dirname(folder)
+            if parent == folder:
+                return found
+            folder = parent
+
+    def of(self, path):
+        """``{folder spelling: path spelled under it}``; ``""`` is ``path`` itself."""
+        path = os.path.abspath(str(path))
+        spelled = {"": path}
+        ancestors = self._ancestors(path)
+        for folder, identity in self._folders:
+            inside = ancestors.get(identity)
+            if inside is not None:
+                spelled.setdefault(
+                    folder, os.path.join(folder, os.path.relpath(path, inside))
+                )
+        return spelled
+
+    def favorites(self, path):
+        """``{listed root: path below it (POSIX)}`` for each listed root holding it."""
+        path = os.path.abspath(str(path))
+        ancestors = self._ancestors(path)
+        held = {}
+        for root, identity in self._listed:
+            inside = ancestors.get(identity)
+            if inside is not None:
+                held[root] = Path(os.path.relpath(path, inside)).as_posix()
+        return held
+
+
+def copy_move(target, kept_stat, spellings):
+    """What ``move_copy_records`` moves for one removal.
+
+    A record found under a folder spelling moves to the kept copy under
+    the same spelling when that folder holds it too, else to its real
+    path. Its favorite moves under every listed root holding the file.
+    """
+    removed = spellings.of(target["abs"])
+    kept = spellings.of(target["keeper_abs"])
+    targets = {
+        spelled: kept.get(folder, target["keeper_abs"])
+        for folder, spelled in removed.items()
+    }
+    kept_favorites = spellings.favorites(target["keeper_abs"])
+    favorites = []
+    for root, relative in spellings.favorites(target["abs"]).items():
+        kept_root, kept_rel = (
+            (root, kept_favorites[root])
+            if root in kept_favorites
+            else (target["keeper_root"], target["keeper_rel"])
+        )
+        favorites.append(
+            (
+                _favorite_root_key(root),
+                _favorite_relative_key(relative),
+                _favorite_root_key(kept_root),
+                _favorite_relative_key(kept_rel),
+            )
+        )
+    return {
+        "removed": list(removed.values()),
+        "kept": list(kept.values()),
+        "targets": targets,
+        "kept_path": target["keeper_abs"],
+        "favorites": favorites,
+        "removed_locator": target["locator"],
+        "kept_locator": target["keeper_locator"],
+        "sha256": target["hash"],
+        "kept_size": kept_stat.st_size,
+        "kept_mtime_ns": kept_stat.st_mtime_ns,
+    }

py/api/history.py

@@ -20,6 +20,7 @@ from .history_current import (
     _OpenedCurrentMedia,
     _current_media_response,
     _prepare_current_media,
+    accepts_jxl,
     _reauthorize_current_target,
     candidate_locator,
     resolve_current_candidate,
@@ -142,6 +143,18 @@ def _query(request: web.Request) -> None:
         raise ValueError("Duplicate history query parameter")
 
 
+def _jxl_flag(request: web.Request) -> bool:
+    """The cover's ``jxl`` flag (#317): ``1`` when the workspace decoded a
+    JPEG XL image (a browser may not list ``image/jxl`` in Accept), ``0`` or
+    absent otherwise; anything else is a bad request."""
+    value = request.query.get("jxl")
+    if value is None:
+        return False
+    if value not in ("0", "1"):
+        raise ValueError("Invalid jxl flag")
+    return value == "1"
+
+
 def _page_limit(request: web.Request) -> int:
     limit = _decimal(request.query.get("limit", "40"), minimum=1)
     if limit > 100:
@@ -734,7 +747,10 @@ class HistoryRoutesMixin:
                         raise HistoryReadError(422, "response-limit") from None
                 else:
                     prepared = _prepare_current_media(
-                        resolved, scope, thumbnail=kind == "thumbnail"
+                        resolved,
+                        scope,
+                        thumbnail=kind == "thumbnail",
+                        **media_options,
                     )
                 _check_current(scope, self, fence, epoch, generation)
                 return prepared
@@ -761,25 +777,45 @@ class HistoryRoutesMixin:
                     _check_current(scope, self, fence, epoch, generation)
                 raise
 
-        pending = asyncio.create_task(self._run_in_executor(project))
-        try:
-            prepared = await asyncio.shield(pending)
-        except asyncio.CancelledError:
-            pending.add_done_callback(_close_prepared_result)
-            raise
-        except (
-            HistoryReadError,
-            HistoryEpochChanged,
-            sqlite3.Error,
-            OSError,
-            ValueError,
-        ):
-            raise
-        except Exception as error:
-            self.logger.warning(
-                "Current history media unavailable (%s)", type(error).__name__
-            )
-            raise _current_unavailable("temporary_unavailable") from None
+        async def execute():
+            pending = asyncio.create_task(self._run_in_executor(project))
+            try:
+                return await asyncio.shield(pending)
+            except asyncio.CancelledError:
+                pending.add_done_callback(_close_prepared_result)
+                raise
+            except (
+                HistoryReadError,
+                HistoryEpochChanged,
+                sqlite3.Error,
+                OSError,
+                ValueError,
+            ):
+                raise
+            except Exception as error:
+                self.logger.warning(
+                    "Current history media unavailable (%s)", type(error).__name__
+                )
+                raise _current_unavailable("temporary_unavailable") from None
+
+        # A missing preview (#249) is noted on the first read, made through
+        # the serve route's admission and single flight, then read again. A
+        # video whose preview cannot be made is the placeholder frame.
+        needed = []
+        media_options = {}
+        if kind == "thumbnail":
+            media_options = {
+                "ensure_preview": lambda *preview: needed.append(preview),
+                "placeholder": self._video_placeholder_bytes(),
+                "accepts_jxl": _jxl_flag(request) or accepts_jxl(request),
+            }
+        prepared = await execute()
+        if needed:
+            if not isinstance(prepared, bytes):
+                prepared.close()
+            await self._admit_preview(*needed[0])
+            media_options["ensure_preview"] = None
+            prepared = await execute()
         if isinstance(prepared, bytes):
             return _success_response(prepared)
         return await _current_media_response(request, prepared)

py/api/history_current.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 import errno
 import hashlib
 import hmac
+import io
 import json
 import mimetypes
 import os
@@ -14,7 +15,9 @@ from typing import BinaryIO
 
 from aiohttp import web
 
+from . import thumbnail_settings
 from .images import _canonical, _public_path, SERVABLE_EXTENSIONS, VIDEO_EXTENSIONS
+from .images import existing_media_thumbnail, media_thumbnail_rel
 
 try:
     from ...utils.execution_outputs import (
@@ -238,14 +241,19 @@ def resolve_current_candidate(
 
 
 def _open_current_target(
-    target: Path, namespace: Path, scope: CurrentOutputScope
+    target: Path, namespace: Path, scope: CurrentOutputScope, preview: bool = False
 ) -> BinaryIO:
-    """Open only the canonical target and verify authority against the actual handle."""
+    """Open only the canonical target and verify authority against the actual handle.
+
+    A *preview* (a file under ``thumbnails/``) may also be JPEG XL (#317)."""
     if _canonical(target) != target:
         raise CurrentLocationUnavailable("not_authorized", stale=True)
     if not _authorized(target, namespace, scope):
         raise CurrentLocationUnavailable("not_authorized")
-    if target.suffix.lower() not in SERVABLE_EXTENSIONS:
+    suffix = target.suffix.lower()
+    if suffix not in SERVABLE_EXTENSIONS and not (
+        preview and suffix in thumbnail_settings.THUMBNAIL_EXTENSIONS
+    ):
         raise CurrentLocationUnavailable("unsupported_media")
     flags = (
         os.O_RDONLY
@@ -309,34 +317,107 @@ class _OpenedCurrentMedia:
         self.handle.close()
 
 
-def _prepare_current_media(
-    resolved: ResolvedCurrentCandidate, scope: CurrentOutputScope, *, thumbnail: bool
-) -> _OpenedCurrentMedia:
+def _preview_writable(root: Path, preview: Path) -> bool:
+    """A preview may be written: ``thumbnails`` and every link segment of the
+    preview's folder resolve inside *root* (the serve route's rule, #249)."""
+    folder = root / "thumbnails"
+    return _canonical(folder).is_relative_to(_canonical(root)) and _canonical(
+        preview
+    ).is_relative_to(_canonical(folder))
+
+
+def _is_jxl(path) -> bool:
+    return Path(path).suffix.lower() == ".jxl"
+
+
+def _preview_without_jxl(root: Path, relative: Path) -> Path | None:
+    """The first existing preview *relative* owns that is not JPEG XL."""
+    return next(
+        (
+            path
+            for path in thumbnail_settings.owned_thumbnails(root, relative)
+            if not _is_jxl(path)
+        ),
+        None,
+    )
+
+
+def accepts_jxl(request) -> bool:
+    """Whether the request's ``Accept`` lists ``image/jxl``."""
+    accept = request.headers.get("Accept", "")
+    return any(
+        part.split(";", 1)[0].strip().lower() == "image/jxl"
+        for part in accept.split(",")
+    )
+
+
+def _placeholder_media(placeholder: bytes) -> "_OpenedCurrentMedia":
+    return _OpenedCurrentMedia(io.BytesIO(placeholder), len(placeholder), "image/jpeg")
+
+
+def _cover_target(resolved, ensure_preview, placeholder, accepts_jxl):
+    """What the cover opens: a preview path, the placeholder media, or None
+    for the original (see ``_prepare_current_media``)."""
     target = resolved.canonical_target
+    relative = target.relative_to(resolved.gallery_root)
+    is_video = target.suffix.lower() in VIDEO_EXTENSIONS
+    # #317: any preview the file owns (the current format first); a missing
+    # one is made under the current format's name.
+    preview = existing_media_thumbnail(resolved.gallery_root, relative)
+    if preview is not None and not accepts_jxl and _is_jxl(preview):
+        preview = _preview_without_jxl(resolved.gallery_root, relative)
+        if preview is None:
+            if is_video and placeholder is not None:
+                return _placeholder_media(placeholder)
+            return None
+        return _canonical(preview)
+    if preview is not None:
+        return _canonical(preview)
+    preview = resolved.gallery_root / media_thumbnail_rel(relative)
+    if ensure_preview is not None and _preview_writable(resolved.gallery_root, preview):
+        ensure_preview(target, preview, is_video)
+    if is_video and placeholder is not None:
+        return _placeholder_media(placeholder)
+    return None
+
+
+def _prepare_current_media(
+    resolved: ResolvedCurrentCandidate,
+    scope: CurrentOutputScope,
+    *,
+    thumbnail: bool,
+    ensure_preview=None,
+    placeholder: bytes | None = None,
+    accepts_jxl: bool = True,
+) -> _OpenedCurrentMedia:
+    """Open the current file, or its preview for ``thumbnail``.
+
+    A missing preview that may be written is handed to
+    ``ensure_preview(src, dst, is_video)`` (the route makes it and reads
+    again, #249). Without one an image's original is opened and a video is
+    the ``placeholder`` JPEG, never the video inside an ``<img>``.
+
+    The cover's URL names no format, so a JPEG XL preview goes only to a
+    browser whose ``Accept`` lists ``image/jxl`` (*accepts_jxl*, review M3).
+    Another one gets the file's preview in another format when there is one,
+    else the original image or a video's placeholder: never a broken image.
+    """
+    target = resolved.canonical_target
+    is_preview = False
     if thumbnail:
-        relative = target.relative_to(resolved.gallery_root)
-        extension = (
-            ".jpg"
-            if target.suffix.lower() in VIDEO_EXTENSIONS
-            else target.suffix.lower()
-        )
-        preview = (
-            resolved.gallery_root
-            / "thumbnails"
-            / f"{relative.with_suffix('').as_posix()}_thumb{extension}"
-        )
-        try:
-            preview.stat()
-        except FileNotFoundError:
-            pass
-        else:
-            target = _canonical(preview)
-    handle = _open_current_target(target, resolved.namespace, scope)
+        chosen = _cover_target(resolved, ensure_preview, placeholder, accepts_jxl)
+        if isinstance(chosen, _OpenedCurrentMedia):
+            return chosen
+        if chosen is not None:
+            target, is_preview = chosen, True
+    handle = _open_current_target(target, resolved.namespace, scope, is_preview)
     try:
         return _OpenedCurrentMedia(
             handle,
             os.fstat(handle.fileno()).st_size,
-            mimetypes.guess_type(target.name)[0] or "application/octet-stream",
+            thumbnail_settings.content_type(target)
+            or mimetypes.guess_type(target.name)[0]
+            or "application/octet-stream",
         )
     except BaseException:
         handle.close()

py/api/job_routes.py

@@ -1,7 +1,8 @@
 """Session job routes (Activity): list, inspect, follow and cancel jobs.
 
 The registry itself is ``py/api/jobs.py``. The scan job's runner is in
-``py/api/admin.py``, the image tagging job's in ``py/api/image_tag_jobs.py``.
+``py/api/admin.py``, the image tagging job's in ``py/api/image_tag_jobs.py``
+and the thumbnail job's in ``py/api/thumbnail_jobs.py``.
 Every response leaves out absolute server paths: job rows already carry
 root-relative paths and public root labels.
 """
@@ -18,29 +19,74 @@ def _not_found():
     return web.json_response({"success": False, "error": "Job not found"}, status=404)
 
 
-def _bad_request(message):
-    return web.json_response({"success": False, "error": message}, status=400)
+MAX_SCAN_ROOTS = 64
+_SCOPE_ERROR = 'The scan scope must be "new" or "all"'
+_ROOTS_ERROR = (
+    f"roots must be a non-empty list of up to {MAX_SCAN_ROOTS} source indexes, "
+    "with paths naming the public path of each"
+)
+SOURCES_CHANGED_ERROR = "The sources changed since they were loaded. Reload them."
 
 
-async def _scan_scope(request):
-    """The requested scan scope ("new" or "all"), or None when the body is invalid.
+def _bad_request(message, code=None):
+    body = {"success": False, "error": message}
+    if code is not None:
+        body["code"] = code
+    return web.json_response(body, status=400)
 
-    An empty body (also a chunked one with no bytes), or one without
-    ``scope``, asks for the default.
+
+def _scan_roots(body):
+    """``(roots, error)``: ``{index: public path}`` of the selected sources, or None.
+
+    Absent ``roots`` means every source. When present it is a non-empty list
+    of at most MAX_SCAN_ROOTS non-negative ints (never bools or floats), and
+    ``paths`` the same-length list of the public path the caller read for
+    each (GET /settings), so a stale index never scans another folder.
     """
+    if "roots" not in body:
+        return None, None
+    raw = body["roots"]
+    paths = body.get("paths")
+    if not isinstance(raw, list) or not raw or len(raw) > MAX_SCAN_ROOTS:
+        return None, _ROOTS_ERROR
+    if not isinstance(paths, list) or len(paths) != len(raw):
+        return None, _ROOTS_ERROR
+    selected = {}
+    for value, path in zip(raw, paths):
+        if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+            return None, _ROOTS_ERROR
+        if not isinstance(path, str) or selected.get(value, path) != path:
+            return None, _ROOTS_ERROR
+        selected[value] = path
+    return dict(sorted(selected.items())), None
+
+
+async def _scan_request(request):
+    """``({files, roots}, None)`` for a scan start, or ``(None, message)``.
+
+    ``files`` is the scope ("new" or "all"); ``roots`` the selected source
+    indexes or None for every source. An empty body (also a chunked one with
+    no bytes), or one without ``scope``, asks for the default scope.
+    """
+    default = {"files": DEFAULT_SCAN_SCOPE, "roots": None}
     if not request.can_read_body:
-        return DEFAULT_SCAN_SCOPE
+        return default, None
     text = await request.text()
     if not text.strip():  # e.g. a chunked POST that sent no bytes
-        return DEFAULT_SCAN_SCOPE
+        return default, None
     try:
         body = json.loads(text)
     except ValueError:
-        return None
+        return None, _SCOPE_ERROR
     if not isinstance(body, dict):
-        return None
-    scope = body.get("scope", DEFAULT_SCAN_SCOPE)
-    return scope if scope in SCAN_SCOPES else None
+        return None, _SCOPE_ERROR
+    files = body.get("scope", DEFAULT_SCAN_SCOPE)
+    if files not in SCAN_SCOPES:
+        return None, _SCOPE_ERROR
+    roots, error = _scan_roots(body)
+    if error:
+        return None, error
+    return {"files": files, "roots": roots}, None
 
 
 def busy_response(busy: JobBusy):
@@ -64,6 +110,13 @@ def _summary_event(job):
 class JobRoutesMixin:
     """Mixin providing the /prompt_manager/jobs endpoints."""
 
+    def _roots_still_listed(self, selected, output_dirs):
+        """Whether each ``{index: public path}`` still names that source."""
+        return all(
+            index < len(output_dirs) and self._public_path(output_dirs[index]) == path
+            for index, path in selected.items()
+        )
+
     def _register_job_routes(self, routes):
         @routes.get("/prompt_manager/jobs")
         async def list_jobs_route(request):
@@ -77,6 +130,10 @@ class JobRoutesMixin:
         async def start_image_tag_job_route(request):
             return await self.start_image_tag_job(request)
 
+        @routes.post("/prompt_manager/jobs/thumbnails")
+        async def start_thumbnail_job_route(request):
+            return await self.start_thumbnail_job(request)
+
         @routes.get("/prompt_manager/jobs/{job_id}")
         async def job_detail_route(request):
             return await self.job_detail(request)
@@ -132,13 +189,37 @@ class JobRoutesMixin:
         """Start the metadata scan as a job (202), or 409 naming the busy job.
 
         The body's ``scope`` is "new" (the default: new and unresolved files)
-        or "all"; anything else is a 400.
+        or "all". ``roots``, when given, selects sources by their index in
+        the effective sources (``_get_all_output_dirs``), and ``paths`` names
+        the public path read for each. An index past them, or one whose
+        source now has another public path (the list changed since it was
+        read), is a 409 ``sources-changed`` and starts nothing. The job walks
+        the sources resolved here, so a later source change cannot move it.
         """
-        files = await _scan_scope(request)
-        if files is None:
-            return _bad_request('The scan scope must be "new" or "all"')
+        scan, error = await _scan_request(request)
+        if error:
+            return _bad_request(error)
+        output_dirs = None
+        roots = None
+        if scan["roots"] is not None:
+            output_dirs = await self._run_in_executor(self._get_all_output_dirs)
+            listed = await self._run_in_executor(
+                self._roots_still_listed, scan["roots"], output_dirs
+            )
+            if not listed:
+                return web.json_response(
+                    {
+                        "success": False,
+                        "code": "sources-changed",
+                        "error": SOURCES_CHANGED_ERROR,
+                    },
+                    status=409,
+                )
+            roots = list(scan["roots"])
         try:
-            job = self._start_scan_job(files)
+            job = self._start_scan_job(
+                scan["files"], roots=roots, output_dirs=output_dirs
+            )
         except JobBusy as busy:
             return busy_response(busy)
         return web.json_response({"success": True, "job": job.summary()}, status=202)

py/api/jobs.py

@@ -19,11 +19,24 @@ ones. One job of a kind runs at a time, and each job has an admission class
 - ``guarded`` must not overlap record changes but may overlap other guarded
   work (thumbnail generation and clearing, later backup). It is refused while
   a ``records`` job runs.
-- ``read`` only reads; it is refused only by a running job of its own kind.
+- ``read`` only reads; it is refused only by a running job of its own kind
+  or an ``exclusive`` one.
+- ``exclusive`` runs alone (Optimize's VACUUM, which rewrites the whole
+  database under the write lock): it is refused while any job runs, and every
+  job is refused while it runs.
 
 A short legacy-page operation takes a ``hold``: a running, non-cancellable
 job that lasts as long as the request, so the Activity page lists it and a
 workspace job is refused while it runs (and the other way round).
+
+Short request-scoped work that reads or writes the library beside any
+ordinary job (a Needs review decision, a maintenance or restore preview)
+takes a ``lease`` instead: it is not listed (so quick requests never push
+real jobs out of the finished history, and two of them never refuse each
+other), but it is refused while an ``exclusive`` job runs, and an
+``exclusive`` job that replaces the database (a restore) awaits
+``drain_leases`` before it switches the file, so no lease's connection is
+open across the switch (#249 S8).
 """
 
 import asyncio
@@ -44,6 +57,9 @@ MAX_OUTCOME_ROWS = 200  # rows listed per outcome group; counters stay exact
 MAX_LOG_LINES = 2000
 LOG_CAP_LINE = "[Log capped at 2,000 lines]"
 MAX_FINISHED_JOBS = 20  # finished jobs this session keeps
+# The longest an exclusive job waits for running leases to end (a ceiling a
+# hung request reaches, not a pacing timer: leases end with their request).
+LEASE_DRAIN_SECONDS = 60
 
 # The metadata scan's outcome groups, in counter-tile order of the spec's
 # mapping, and the per-file scan status each group collects. Files without
@@ -72,12 +88,17 @@ SCAN_GROUPS = {
 IMAGE_TAG_JOB_KIND = "image-tags"
 IMAGE_TAG_GROUP_NAMES = ("tagged", "unchanged", "skipped", "errors")
 
-ADMISSIONS = ("read", "guarded", "records")
+# Thumbnail generation (#249 System S5): previews written, already fresh, failed.
+THUMBNAIL_GROUP_NAMES = ("generated", "skipped", "errors")
+
+ADMISSIONS = ("read", "guarded", "records", "exclusive")
 # What each admission class is refused beside (besides its own kind).
+# ``exclusive`` (Optimize's VACUUM) runs alone: beside no job of any class.
 _REFUSED_BESIDE = {
-    "read": frozenset(),
-    "guarded": frozenset({"records"}),
-    "records": frozenset({"records", "guarded"}),
+    "read": frozenset({"exclusive"}),
+    "guarded": frozenset({"records", "exclusive"}),
+    "records": frozenset({"records", "guarded", "exclusive"}),
+    "exclusive": frozenset(ADMISSIONS),
 }
 
 # Kinds of the legacy-page operations that hold the registry (D80; titles in
@@ -88,6 +109,11 @@ DUPLICATE_CLEANUP_JOB_KIND = "duplicate_cleanup"
 THUMBNAILS_JOB_KIND = "thumbnails"
 LORA_IMPORT_JOB_KIND = "lora_import"
 AUTOTAG_BATCH_JOB_KIND = "autotag"
+# Duplicate image files (#249 System S6, py/api/duplicate_files.py): the
+# find is a cancellable ``read`` job; the reviewed removal is ``records``.
+DUPLICATES_JOB_KIND = "duplicates"
+DUPLICATE_GROUP_NAMES = ("groups_found",)
+DUPLICATE_CLEANUP_GROUP_NAMES = ("removed", "kept", "errors")
 # The System health check (py/api/system.py): a read-only ``read`` job with
 # no file outcomes, so it may run beside a scan.
 HEALTH_JOB_KIND = "health"
@@ -247,6 +273,32 @@ class Job:
             )
         self.log_line(log_line)
 
+    def record_counted(self, group, count, rows=()):
+        """Count ``count`` outcomes in ``group`` at once, listing ``rows``.
+
+        For outcomes that need no log line each (a thumbnail job's already
+        fresh previews): the counter is exact, ``rows`` (``record``'s row
+        shape) are listed up to MAX_OUTCOME_ROWS, and nothing is logged.
+        """
+        if group not in self.counters:
+            raise ValueError(f"Unknown outcome group {group!r} for {self.kind}")
+        self.counters[group] += max(0, int(count))
+        listed = self.outcomes[group]
+        for row in rows:
+            if len(listed) >= MAX_OUTCOME_ROWS:
+                break
+            index = row.get("root_index")
+            if isinstance(index, bool) or not isinstance(index, int) or index < 0:
+                index = None
+            listed.append(
+                {
+                    "path": _relative_path(row.get("path")),
+                    "root": str(row.get("root") or ""),
+                    "root_index": index,
+                    "detail": str(row.get("detail") or ""),
+                }
+            )
+
     def finish(self, state="finished"):
         """End the job in ``state`` and release every subscriber.
 
@@ -263,18 +315,24 @@ class Job:
         for queue in list(self._subscribers):
             queue.put_nowait(None)
 
-    async def events(self):
+    async def events(self, lead=None):
         """Yield the latest event, then each later one, until the job finishes.
 
+        ``lead``, when given, is yielded first, after the subscription is in
+        place, so nothing published while the consumer sends it is missed.
         Consume it under ``contextlib.aclosing`` so a consumer that stops early
         (a closed socket) drops its queue at once instead of at garbage collection.
         """
         queue = asyncio.Queue()
         self._subscribers.add(queue)
+        # As of the subscription: a later event or the end reaches the queue.
+        snapshot, ended = self.last_event, self.finished
         try:
-            if self.last_event is not None:
-                yield self.last_event
-            if self.finished:
+            if lead is not None:
+                yield lead
+            if snapshot is not None:
+                yield snapshot
+            if ended:
                 return
             while True:
                 payload = await queue.get()
@@ -357,6 +415,74 @@ class JobRegistry:
     def __init__(self, logger_=None):
         self._logger = logger_ or logger
         self._jobs = {}
+        self._leases = {}  # title -> running count
+        self._drain_waiters = []
+
+    # ── leases ────────────────────────────────────────────────────────
+
+    def lease(self, title):
+        """An async context manager for short request-scoped library work.
+
+        Entering raises JobBusy, naming the job, while an ``exclusive`` job
+        runs; otherwise the lease is counted until the block exits. Leases
+        are never listed and never refuse one another or any job.
+        """
+        return _Lease(self, title)
+
+    def lease_blocker(self):
+        """The running ``exclusive`` job a new lease is refused for, or None."""
+        for job in self.running():
+            if job.admission == "exclusive":
+                return job
+        return None
+
+    @property
+    def leases(self):
+        """Running leases by title (a copy)."""
+        return dict(self._leases)
+
+    def _take_lease(self, title):
+        blocker = self.lease_blocker()
+        if blocker is not None:
+            raise JobBusy(blocker)
+        self._leases[title] = self._leases.get(title, 0) + 1
+
+    def _release_lease(self, title):
+        count = self._leases.get(title, 0) - 1
+        if count > 0:
+            self._leases[title] = count
+        else:
+            self._leases.pop(title, None)
+        if not self._leases:
+            waiters, self._drain_waiters = self._drain_waiters, []
+            for waiter in waiters:
+                if not waiter.done():
+                    waiter.set_result(True)
+
+    async def drain_leases(self, timeout=None):
+        """Wait until no lease runs; False when ``timeout`` ended the wait.
+
+        For an ``exclusive`` job about to switch the database: once it runs
+        no new lease is admitted, so the count only goes down.
+        """
+        if not self._leases:
+            return True
+        waiter = asyncio.get_running_loop().create_future()
+        self._drain_waiters.append(waiter)
+        try:
+            await asyncio.wait_for(
+                asyncio.shield(waiter),
+                LEASE_DRAIN_SECONDS if timeout is None else timeout,
+            )
+            return True
+        except asyncio.TimeoutError:
+            self._logger.warning(
+                "Still running after the wait: " + ", ".join(sorted(self._leases))
+            )
+            return False
+        finally:
+            if waiter in self._drain_waiters:
+                self._drain_waiters.remove(waiter)
 
     def start(
         self,
@@ -425,20 +551,24 @@ class JobRegistry:
         self._jobs[job.id] = job
         return job
 
-    def blocker(self, kind, *, admission=None, record_changing=None):
+    def blocker(self, kind, *, admission=None, record_changing=None, compatible=()):
         """The running job a new ``kind`` job would be refused for, or None.
 
         The same kind refuses first; then the oldest running job whose class
-        the new job's admission class may not run beside.
+        the new job's admission class may not run beside. Running jobs of a
+        kind in ``compatible`` never refuse it: the caller knows that work
+        cannot conflict with its own (the monitor's Needs review recording
+        beside thumbnail work, which writes previews and no records).
         """
         same_kind = self.active(kind)
         if same_kind is not None:
             return same_kind
         refused = _REFUSED_BESIDE[resolve_admission(admission, record_changing)]
-        running = [job for job in self._jobs.values() if job.running]
+        # A snapshot: the monitor's worker thread asks too (Needs review).
+        running = [job for job in tuple(self._jobs.values()) if job.running]
         running.sort(key=lambda job: job._started_seq)
         for job in running:
-            if job.admission in refused:
+            if job.admission in refused and job.kind not in compatible:
                 return job
         return None
 
@@ -465,9 +595,15 @@ class JobRegistry:
     def get(self, job_id):
         return self._jobs.get(job_id)
 
+    def running(self):
+        """The running jobs, oldest first (a snapshot, safe off the event loop)."""
+        jobs = [job for job in tuple(self._jobs.values()) if job.running]
+        jobs.sort(key=lambda job: job._started_seq)
+        return jobs
+
     def active(self, kind):
-        """The running job of ``kind``, or None."""
-        for job in self._jobs.values():
+        """The running job of ``kind``, or None (safe off the event loop)."""
+        for job in tuple(self._jobs.values()):
             if job.kind == kind and job.running:
                 return job
         return None
@@ -509,3 +645,23 @@ class _Hold:
         if self._job.running:
             self._job.finish("finished" if exc_type is None else "failed")
         return False
+
+
+class _Lease:
+    """The async context manager ``JobRegistry.lease`` returns."""
+
+    def __init__(self, registry, title):
+        self._registry = registry
+        self._title = title
+        self._held = False
+
+    async def __aenter__(self):
+        self._registry._take_lease(self._title)
+        self._held = True
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        if self._held:
+            self._held = False
+            self._registry._release_lease(self._title)
+        return False

py/api/library_location.py

@@ -0,0 +1,420 @@
+"""Library location routes (#249 S6b): where the library lives, Move, Keep.
+
+- ``GET /prompt_manager/system/library`` → ``{success, location}``: the
+  database's path (relative to ComfyUI, as the statistics show it), why it is
+  there (``source``: ``default``, ``environment``, ``config`` or
+  ``node_folder``), whether it can move and where to (``target``), the
+  "Keep it here" choice (``keep``), whether to offer the move (``offer``:
+  movable and not kept), a ``problem`` code and the database's size. The
+  System Overview carries the same object as ``location``.
+- ``POST /prompt_manager/system/library/move`` → 202 ``{job}``: the
+  ``library_move`` job, ``exclusive`` (it runs alone and every other job,
+  legacy-page operations included, is refused while it runs), not
+  cancellable. It copies, verifies and switches the live library
+  (``database/library_move.py``) and ends with one truthful line; a failure
+  leaves the library in the node folder, unchanged. Refused before any job
+  starts: 400 ``not-movable``/``same-folder``/``target-invalid``, 409
+  ``target-has-library``/``target-conflict``/``busy``, 507
+  ``insufficient-space``.
+- ``POST /prompt_manager/system/library/keep {keep: bool}`` persists
+  ``library.keep_in_node_folder`` through the config store and answers the
+  new location.
+
+Errors are ``{success:false, code, error}`` and never name a path.
+"""
+
+import asyncio
+import functools
+import os
+
+from aiohttp import web
+
+from .job_routes import busy_response
+from .jobs import JobBusy
+
+try:
+    from ...database import library_move as lm
+    from ...database.operations import resolve_library_location
+    from ...utils import library_location as ll
+except ImportError:
+    from database import library_move as lm
+    from database.operations import resolve_library_location
+    from utils import library_location as ll
+
+LIBRARY_MOVE_JOB_KIND = "library_move"
+LIBRARY_MOVE_TITLE = "Move library"
+LIBRARY_MOVE_GROUPS = ("files", "errors")
+KEEP_BODY_MAX = 1024
+
+_REFUSAL_STATUS = {
+    "not-movable": 400,
+    "same-folder": 400,
+    "target-invalid": 400,
+    "target-has-library": 409,
+    "target-conflict": 409,
+    "insufficient-space": 507,
+}
+STILL_THERE = "The library is still in the node folder, unchanged."
+NOT_MOVED = "The library was not moved."
+OLD_LEFT = {
+    "old-in-use": (
+        "The old database is still open elsewhere, so it was left in the node "
+        "folder; it is no longer used."
+    ),
+    "old-locked": (
+        "The old files could not be renamed, so they were left in the node "
+        "folder; they are no longer used."
+    ),
+}
+
+
+def _failure(message, status, code):
+    return web.json_response(
+        {"success": False, "code": code, "error": message}, status=status
+    )
+
+
+def _plural(count, one, many=None):
+    return f"{count:,} {one if count == 1 else (many or one + 's')}"
+
+
+def _same_file(first, second):
+    try:
+        return os.path.samefile(first, second)
+    except OSError:
+        return os.path.normcase(os.path.realpath(first)) == os.path.normcase(
+            os.path.realpath(second)
+        )
+
+
+CUSTOM_NODES = "custom_nodes"
+
+
+def _inside(path, folder):
+    """``path`` relative to ``folder`` by text (normalised spellings), or None."""
+    child, parent = os.path.normcase(path), os.path.normcase(folder)
+    if child == parent:
+        return ""
+    prefix = parent.rstrip(os.sep) + os.sep
+    return path[len(prefix) :] if child.startswith(prefix) else None
+
+
+def _comfyui_custom_nodes():
+    """ComfyUI's custom_nodes folders as it lists them (unresolved), or []."""
+    try:
+        from ..config import _import_folder_paths
+
+        getter = getattr(_import_folder_paths(), "get_folder_paths", None)
+        folders = getter(CUSTOM_NODES) if getter else []
+        return [folder for folder in folders or [] if isinstance(folder, str)]
+    except Exception:
+        return []
+
+
+def node_folder_public_path(path, extension_root, custom_nodes):
+    """``custom_nodes/<node folder>/...`` for a path in the node folder, or None.
+
+    The node folder is matched at its own unresolved place in a custom_nodes
+    folder (one of ``custom_nodes``, or the parent of ``extension_root`` when
+    that is named custom_nodes), so a node folder that is a symlink to a
+    checkout outside ComfyUI still reads relative to ComfyUI. ``path`` may be
+    spelled through the link or resolved. Never absolute, never ``..``:
+    anything else is None and the caller uses ``_public_path``.
+    """
+    if not path or not extension_root:
+        return None
+    try:
+        root = os.path.normpath(os.path.abspath(extension_root))
+        name = os.path.basename(root)
+        folders = [os.path.normpath(os.path.abspath(f)) for f in custom_nodes]
+        parent = os.path.dirname(root)
+        if os.path.normcase(os.path.basename(parent)) == CUSTOM_NODES:
+            folders.append(parent)
+        spellings = [os.path.normpath(os.path.abspath(path))]
+        spellings.append(os.path.realpath(spellings[0]))
+    except (OSError, ValueError, TypeError):
+        return None
+    for folder in folders:
+        node = os.path.join(folder, name)
+        for spelling, node_spelling in zip(spellings, (node, os.path.realpath(node))):
+            rest = _inside(spelling, node_spelling)
+            if rest is None:
+                continue
+            parts = [os.path.basename(folder), name] + (
+                rest.split(os.sep) if rest else []
+            )
+            if all(part and part not in (".", "..") for part in parts):
+                return "/".join(parts)
+    return None
+
+
+class LibraryLocationRoutesMixin:
+    """Mixin for the /prompt_manager/system/library endpoints."""
+
+    # Replaced in tests with a resolver over a temp tree.
+    _library_resolver = staticmethod(resolve_library_location)
+
+    def _register_library_location_routes(self, routes):
+        @routes.get("/prompt_manager/system/library")
+        async def library_location_route(request):
+            return await self.get_library_location(request)
+
+        @routes.post("/prompt_manager/system/library/move")
+        async def library_move_route(request):
+            return await self.start_library_move(request)
+
+        @routes.post("/prompt_manager/system/library/keep")
+        async def library_keep_route(request):
+            return await self.keep_library(request)
+
+    # ── location ──────────────────────────────────────────────────────
+
+    def _library_public_path(self, path):
+        """The library's path for display: through the node folder's place in
+        custom_nodes when it is there (a symlinked node folder included), else
+        ``_public_path``. Only the library location uses this; sources and
+        jobs keep ``_public_path``, which their requests round-trip."""
+        shown = node_folder_public_path(
+            path, self._extension_root, _comfyui_custom_nodes()
+        )
+        return shown or self._public_path(path)
+
+    def _live_location(self):
+        """The resolved location, unless the live database is another file.
+
+        A database the API was handed (tests, the browser fixture server) or
+        one the resolver no longer names is reported as configured and is
+        never moved.
+        """
+        location = self._library_resolver()
+        live = self.db.model.db_path
+        if _same_file(location.db_path, live):
+            return location
+        return ll.LibraryLocation(
+            ll.SOURCE_CONFIG,
+            live,
+            location.config_path,
+            os.path.dirname(live),
+            config_explicit=location.config_explicit,
+        )
+
+    def _location_payload(self, location):
+        """The public view of ``location`` (blocking: stats the database)."""
+        from ..config import PromptManagerConfig
+
+        keep = bool(PromptManagerConfig.KEEP_LIBRARY_IN_NODE_FOLDER)
+        size = 0
+        try:
+            size = os.path.getsize(location.db_path)
+        except OSError:
+            pass
+        return {
+            "path": self._library_public_path(location.db_path),
+            # Where Move library would put it, and whether config.json goes too.
+            "target_source": location.target_source if location.movable else None,
+            "config_moves": location.movable and not location.config_explicit,
+            "source": location.source,
+            "movable": location.movable,
+            "keep": keep,
+            "offer": location.movable and not keep,
+            "target": (
+                self._library_public_path(location.target_dir)
+                if location.movable
+                else None
+            ),
+            "problem": location.problem or self._node_folder_risk(location),
+            "size_bytes": size,
+        }
+
+    # The node folder (tests point it at a temp tree).
+    _extension_root = ll.EXTENSION_ROOT
+
+    def _node_folder_risk(self, location):
+        """``inside-node-folder`` for a library that stays in the node folder.
+
+        A configured database path, or a config.json the resolver still reads
+        from the node folder, is deleted with the node by a reinstall, and
+        it is never offered a move.
+        """
+        if location.source == ll.SOURCE_NODE_FOLDER:
+            return None
+        paths = [location.db_path] + (
+            [] if location.config_explicit else [location.config_path]
+        )
+        root = self._extension_root
+        for path in paths:
+            parent = os.path.dirname(os.path.abspath(path))
+            if ll.same_folder(parent, root) or os.path.normcase(
+                os.path.realpath(parent)
+            ).startswith(os.path.normcase(os.path.realpath(root)) + os.sep):
+                return "inside-node-folder"
+        return None
+
+    def _library_payload(self):
+        return self._location_payload(self._live_location())
+
+    async def get_library_location(self, request):
+        try:
+            payload = await self._run_in_executor(self._library_payload)
+        except Exception:
+            self.logger.exception("Library location could not be read")
+            return _failure(
+                "The library location could not be read.", 500, "location-failed"
+            )
+        return web.json_response(
+            {"success": True, "location": payload},
+            headers={"Cache-Control": "no-store"},
+        )
+
+    # ── move ──────────────────────────────────────────────────────────
+
+    def _plan_library_move(self):
+        """The checked plan (blocking); raises MoveFailed."""
+        plan = lm.plan_move(self._live_location())
+        if lm.space_problem(plan) is not None:
+            raise lm.MoveFailed("insufficient-space")
+        return plan
+
+    async def start_library_move(self, request):
+        blocker = self._jobs.blocker(LIBRARY_MOVE_JOB_KIND, admission="exclusive")
+        if blocker is not None:
+            return busy_response(JobBusy(blocker))
+        try:
+            await self._run_in_executor(self._plan_library_move)
+        except lm.MoveFailed as refused:
+            status = _REFUSAL_STATUS.get(refused.code, 400)
+            return _failure(refused.message, status, refused.code)
+        except Exception:
+            self.logger.exception("Move library could not be planned")
+            return _failure(NOT_MOVED, 500, "move-failed")
+        try:
+            job = self._jobs.start(
+                LIBRARY_MOVE_JOB_KIND,
+                LIBRARY_MOVE_TITLE,
+                admission="exclusive",
+                cancellable=False,
+                scope={},
+                groups=LIBRARY_MOVE_GROUPS,
+                runner=self._run_library_move,
+            )
+        except JobBusy as busy:
+            return busy_response(busy)
+        return web.json_response({"success": True, "job": job.summary()}, status=202)
+
+    def _after_library_switch(self):
+        """Forget what described the old file (best effort, after the switch).
+
+        Plans, the health report and the history read fence named the old
+        file; the fence is closed before it is dropped.
+        """
+        self._database_replaced()
+        fence, self._history_read_fence = self._history_read_fence, None
+        if fence is not None:
+            fence.close()
+
+    def finish_interrupted_library_move(self):
+        """Startup: rename old files a crash left after a move (blocking)."""
+        try:
+            location = self._library_resolver()
+            if _same_file(location.db_path, self.db.model.db_path):
+                return lm.finish_interrupted_move(location)
+        except Exception:
+            self.logger.exception("Could not finish an interrupted library move")
+        return []
+
+    async def _run_library_move(self, job):
+        from ..config_store import _COMMIT_LOCK
+
+        loop = asyncio.get_running_loop()
+
+        def progress(line):
+            def show():
+                job.log_line(line)
+                job.update(status_line=line)
+
+            loop.call_soon_threadsafe(show)
+
+        job.update(status_line="Checking the new folder")
+        try:
+            plan = await self._run_in_executor(self._plan_library_move)
+            target = self._library_public_path(plan.target_dir)
+            job.log_line(f"Moving the library to {target}")
+            result = await self._run_in_executor(
+                functools.partial(
+                    lm.move_library,
+                    plan,
+                    after_switch=self._after_library_switch,
+                    config_lock=_COMMIT_LOCK,
+                    progress=progress,
+                )
+            )
+        except lm.MoveFailed as failed:
+            self.logger.error(f"Move library failed: {failed.code}")
+            return self._fail_library_move(
+                job, failed.code, f"{failed.message} {STILL_THERE}"
+            )
+        except Exception:
+            self.logger.exception("Move library failed")
+            return self._fail_library_move(job, None, f"{NOT_MOVED} {STILL_THERE}")
+        await asyncio.sleep(0)  # the progress lines come first
+        job.record_counted("files", len(result.files))
+        line = (
+            f"Moved the library to {target}: "
+            f"{_plural(result.counts.get('prompts', 0), 'prompt')} and "
+            f"{_plural(result.counts.get('generated_images', 0), 'image')} verified"
+        )
+        if result.retire_problem:
+            line += ". " + OLD_LEFT.get(result.retire_problem, OLD_LEFT["old-locked"])
+        elif result.renamed:
+            line += (
+                f". The old files were renamed {', '.join(result.renamed)}; "
+                "nothing was deleted"
+            )
+        line += ". Logs move at the next restart."
+        job.log_line(line)
+        job.update(progress=100, status_line=line)
+
+    @staticmethod
+    def _fail_library_move(job, code, message):
+        from .maintenance import _fail_job
+
+        _fail_job(job, code, message)
+
+    # ── keep it here ─────────────────────────────────────────────────
+
+    async def keep_library(self, request):
+        from ..config import PromptManagerConfig
+        from ..config_store import get_config_store
+
+        try:
+            if (request.content_length or 0) > KEEP_BODY_MAX:
+                raise ValueError("too large")
+            data = await request.json()
+        except Exception:
+            data = None
+        if not isinstance(data, dict) or not isinstance(data.get("keep"), bool):
+            return _failure("keep must be true or false.", 400, "invalid-request")
+        keep = data["keep"]
+
+        def mutate(config):
+            library = config.get("library")
+            library = dict(library) if isinstance(library, dict) else {}
+            library["keep_in_node_folder"] = keep
+            config["library"] = library
+            return config
+
+        def publish(_config):
+            PromptManagerConfig.KEEP_LIBRARY_IN_NODE_FOLDER = keep
+
+        try:
+            await self._run_in_executor(
+                functools.partial(
+                    get_config_store().commit,
+                    mutate,
+                    expected_revision=None,
+                    publish=publish,
+                )
+            )
+        except Exception as exc:
+            return self._config_commit_failure(exc)
+        return await self.get_library_location(request)

py/api/lora_import_routes.py

@@ -0,0 +1,483 @@
+"""The staged LoRA reference import as a reviewed Activity job (#221, S10).
+
+``POST /prompt_manager/lora/import/preview`` (body ``{}``) reviews an import:
+it lists the LoraManager metadata files and parses them, and counts the
+current imports, those a saved pair uses and the example images an import
+would download. It writes nothing and requests nothing. It answers a
+``Plan`` (the maintenance plan's shape, ``py/api/maintenance.py``) plus
+``{lora_files, with_metadata, current_imports, blocked_by_pairs,
+planned_downloads, network:{planned_downloads, api_key}}``. A plan that saved
+pairs block carries no token (nothing can be applied).
+
+``POST /prompt_manager/lora/import/apply {token}`` starts the job (202
+``{job}``): kind ``lora_import``, titled "LoRA reference import", admission
+``records``, cancellable while it downloads only. Refused before it starts:
+``plan-changed`` (409: the metadata files changed since the review),
+``plan-expired``, ``plan-used``, ``storage-changed``, ``busy``,
+``insufficient-space`` (as maintenance). The job stages the records
+(downloads into the cache first, each counted in ``downloaded`` or
+``download_errors``), takes the safety backup the policy promises, then
+replaces the collection in one transaction bound to the reviewed imports. Any
+failure leaves the previous imports exactly as they were, and the job says so.
+
+The legacy ``POST /lora/scan`` runs the same stages (``stage_lora_import``
+and ``replace_lora_imports``) under its SSE event shape.
+"""
+
+import asyncio
+import os
+import sqlite3
+
+from aiohttp import web
+
+from .. import lora_import, lora_utils
+from .job_routes import busy_response
+from .jobs import LORA_IMPORT_JOB_KIND, JobBusy
+from .maintenance import (
+    MAX_TOKEN_LENGTH,
+    _failure,
+    _fail_job,
+    _invalid,
+    _iso,
+    disk_plan,
+    short_space_message,
+)
+from .maintenance_plans import ScopeTooLarge
+
+try:
+    from ...database.category_import import EmptyReplacement
+    from ...database.maintenance import PlanChanged
+    from ...database.pairs import PairDependencyError
+except ImportError:  # pragma: no cover - flat test imports
+    from database.category_import import EmptyReplacement
+    from database.maintenance import PlanChanged
+    from database.pairs import PairDependencyError
+
+LORA_OPERATION = "lora_import"
+# The review reads the library: a request lease, so it is refused while a
+# restore runs and a restore waits for it before switching the file (S8).
+LORA_PREVIEW_LEASE = "LoRA import review"
+CATEGORY = lora_import.LORA_CATEGORY
+SOURCE_CHANGED = (
+    "The LoRA metadata files changed since the review; nothing was changed. "
+    "Review the import again."
+)
+IMPORTS_CHANGED = (
+    "The imported LoRA prompts changed since the review; the previous imports "
+    "were kept. Review the import again."
+)
+BLOCKED = (
+    "Saved pairs use some imported LoRA prompts, so the collection cannot be "
+    "replaced; the previous imports were kept."
+)
+INTEGRATION_CHANGED = (
+    "The LoraManager integration changed since the review; nothing was changed. "
+    "Review the import again."
+)
+EMPTY = "No LoRA could be prepared for import; the previous imports were kept."
+FAILED = "The import failed; the previous LoRA imports were kept."
+CACHE_NOTE = "Images already downloaded stay in the image cache."
+CANCELLED = "Cancelled before anything was written; the previous imports were kept."
+DISABLED = "LoraManager integration is not enabled"
+NO_PATH = "LoraManager path not configured"
+
+
+def _noun(count, word, plural=None):
+    return word if count == 1 else (plural or word + "s")
+
+
+def _count(count, word, plural=None):
+    return f"{count:,} {_noun(count, word, plural)}"
+
+
+def _import_line(result, skipped):
+    parts = [f"Imported {_count(result['imported'], 'LoRA')}"]
+    if result["linked"] or result["duplicates"]:
+        linked = result["linked"] + result["duplicates"]
+        parts.append(f"{linked:,} linked to an existing prompt")
+    if skipped:
+        parts.append(f"{skipped:,} skipped")
+    return " · ".join(parts)
+
+
+def _all_downloads_failed(errors):
+    """The warning when every planned download failed (#337)."""
+    if errors == 1:
+        return "Warning: the example image could not be downloaded"
+    return f"Warning: none of the {errors:,} example images could be downloaded"
+
+
+def _with_downloads(line, downloaded, errors):
+    """``line`` with the failed downloads: counted when some failed, led by
+    a warning when every planned download failed (#337). The job still
+    finishes: the import itself succeeded and the downloads are best effort."""
+    if not errors:
+        return line
+    if not downloaded:
+        return f"{_all_downloads_failed(errors)} · {line}"
+    failed = f"{_count(errors, 'example image')} could not be downloaded"
+    return f"{line} · {failed}"
+
+
+class LoraImportRoutesMixin:
+    """Mixin providing the reviewed LoRA import (preview, apply, job)."""
+
+    def _register_lora_import_routes(self, routes):
+        @routes.post("/prompt_manager/lora/import/preview")
+        async def lora_import_preview_route(request):
+            return await self.preview_lora_import(request)
+
+        @routes.post("/prompt_manager/lora/import/apply")
+        async def lora_import_apply_route(request):
+            return await self.apply_lora_import(request)
+
+    # ── shared stages ─────────────────────────────────────────────────
+
+    async def _lora_source(self):
+        """``(path, None)``: the configured, allowed LoraManager path, or
+        ``(None, (code, message))`` when the import cannot run."""
+        from ..config import IntegrationConfig
+
+        if not IntegrationConfig.LORA_MANAGER_ENABLED:
+            return None, ("lora-disabled", DISABLED)
+        lm_path = IntegrationConfig.LORA_MANAGER_PATH
+        if not lm_path:
+            return None, ("lora-path", NO_PATH)
+        allowed = await self._run_in_executor(
+            lora_utils.resolve_lora_manager_path, lm_path
+        )
+        if allowed is None:
+            from .lora_integration import _LORA_PATH_ERROR
+
+            return None, ("lora-path", _LORA_PATH_ERROR)
+        return allowed, None
+
+    async def stage_lora_import(self, files, *, on_record=None, cancelled=None):
+        """Stage ``files`` off the loop: records, skips and download counts."""
+        from ..config import IntegrationConfig
+
+        cache_dir = await self._run_in_executor(lora_utils.get_lora_image_cache_dir)
+        await self._run_in_executor(lora_utils.sweep_stale_downloads, cache_dir)
+        loop = asyncio.get_running_loop()
+
+        def report(index, record, staged):
+            if on_record is not None:
+                loop.call_soon_threadsafe(on_record, index, record, staged)
+
+        return await self._run_in_executor(
+            lambda: lora_import.stage(
+                files,
+                cache_dir,
+                IntegrationConfig.CIVITAI_API_KEY,
+                on_record=report,
+                cancelled=cancelled or (lambda: False),
+                logger=self.logger,
+            )
+        )
+
+    async def lora_files_unchanged(self, lm_path, expected):
+        """Whether the metadata files under ``lm_path`` still fingerprint as
+        ``expected`` (listed again, so an added file counts too)."""
+
+        def current():
+            return lora_import.fingerprint(lora_import.discover(lm_path))
+
+        try:
+            return await self._run_in_executor(current) == expected
+        except OSError:
+            return False
+
+    async def replace_lora_imports(self, db, staged, *, expected_ids, allow_empty):
+        """Swap the collection for ``staged.records`` in one transaction."""
+        return await self._run_in_executor(
+            lambda: db.replace_category_prompts(
+                CATEGORY,
+                staged.records,
+                expected_ids=expected_ids,
+                allow_empty=allow_empty,
+            )
+        )
+
+    # ── preview ───────────────────────────────────────────────────────
+
+    async def preview_lora_import(self, request):
+        try:
+            async with self._jobs.lease(LORA_PREVIEW_LEASE):
+                return await self._preview_lora_import(request)
+        except JobBusy as busy:
+            return busy_response(busy)
+
+    async def _preview_lora_import(self, request):
+        data, error = await self._read_maintenance_body(request, ())
+        if error is not None:
+            return error
+        lm_path, refused = await self._lora_source()
+        if refused is not None:
+            return _failure(refused[1], 400, refused[0])
+        db = self.db
+        identity = self._database_identity(db)
+        try:
+            cache_dir = await self._run_in_executor(
+                lambda: lora_utils.get_lora_image_cache_dir(create=False)
+            )
+            found = await self._run_in_executor(lora_import.preview, lm_path, cache_dir)
+            state = await self._run_in_executor(db.category_import_state, CATEGORY)
+        except Exception:
+            self.logger.exception("LoRA import preview failed")
+            return _failure("The LoRA import could not be reviewed.", 500)
+        if identity != self._database_identity(self.db):
+            return _failure(
+                "The database was replaced while it was reviewed. Review again.",
+                409,
+                "storage-changed",
+            )
+        return await self._lora_plan_response(db, identity, lm_path, found, state)
+
+    async def _lora_plan_response(self, db, identity, lm_path, found, state):
+        from ..config import IntegrationConfig
+
+        current = len(state["ids"])
+        blocked = state["paired"]
+        policy = self._safety_backup_policy()
+        try:
+            disk, _short, size = await self._run_in_executor(
+                disk_plan, db.model.db_path, backup=policy != "off", vacuum=False
+            )
+        except (OSError, sqlite3.Error):
+            self.logger.exception("Could not measure the disk space for a plan")
+            return _failure("The LoRA import could not be reviewed.", 500)
+        token = None
+        expires_at = None
+        if not blocked:
+            payload = {
+                "path": lm_path,
+                "fingerprint": found["fingerprint"],
+                "expected_ids": state["ids"],
+                "empty": found["with_metadata"] == 0,
+                "backup": policy,
+            }
+            try:
+                token = self._maintenance_plans.issue(
+                    LORA_OPERATION, found["fingerprint"], payload, identity
+                )
+            except ScopeTooLarge:
+                return _failure(
+                    "This import is too large to review at once.", 413, "too-large"
+                )
+            expires_at = _iso(self._maintenance_plans.peek(token).expires_at)
+        name = os.path.basename(db.model.db_path)
+        downloads = found["planned_downloads"]
+        reasons = (
+            [f"{_count(blocked, 'imported prompt')} used by saved pairs"]
+            if blocked
+            else []
+        )
+        return web.json_response(
+            {
+                "success": True,
+                "operation": LORA_OPERATION,
+                "token": token,
+                "expires_at": expires_at,
+                "lora_files": found["lora_files"],
+                "with_metadata": found["with_metadata"],
+                "current_imports": current,
+                "blocked_by_pairs": blocked,
+                "planned_downloads": downloads,
+                "scope": {
+                    "count": found["with_metadata"],
+                    "label": (
+                        f"Replace {_count(current, 'imported prompt')} with "
+                        f"{_count(found['with_metadata'], 'LoRA')}"
+                    ),
+                },
+                "protected": {"count": blocked, "reasons": reasons},
+                "backup": {
+                    "policy": policy,
+                    "destination_label": f"{name}.backup_<date and time>",
+                    "expected_bytes": size if policy != "off" else None,
+                },
+                "media": {
+                    "deletes_files": False,
+                    "label": "No files are removed; image links are replaced",
+                },
+                "network": {
+                    "planned_downloads": downloads,
+                    "api_key": bool(IntegrationConfig.CIVITAI_API_KEY),
+                },
+                "details": [{"label": n, "detail": ""} for n in found["names"]],
+                "disk": disk,
+            },
+            headers={"Cache-Control": "no-store"},
+        )
+
+    # ── apply ─────────────────────────────────────────────────────────
+
+    async def apply_lora_import(self, request):
+        data, error = await self._read_maintenance_body(request, ("token",))
+        if error is not None:
+            return error
+        token = data.get("token")
+        if not isinstance(token, str) or not 0 < len(token) <= MAX_TOKEN_LENGTH:
+            return _invalid("token must be the plan's token")
+        plan, refused = self._peek_plan(token)
+        if refused is not None:
+            return refused
+        if plan.operation != LORA_OPERATION:
+            return _failure(
+                "This review expired. Review the plan again.", 410, "plan-expired"
+            )
+        store = self._maintenance_plans
+        db = self.db
+        if plan.db_identity != self._database_identity(db):
+            store.discard(token)
+            return _failure(
+                "The database was replaced since the review. Review again.",
+                409,
+                "storage-changed",
+            )
+        lm_path = plan.payload["path"]
+        # M5: the integration must still be on and at the reviewed install.
+        current, _refused = await self._lora_source()
+        if current != lm_path:
+            store.discard(token)
+            return _failure(INTEGRATION_CHANGED, 409, "plan-changed")
+        try:
+            files = await self._run_in_executor(lora_import.discover, lm_path)
+            now = await self._run_in_executor(lora_import.fingerprint, files)
+            backup = self._backup_promised(plan)
+            _disk, short, _size = await self._run_in_executor(
+                disk_plan, db.model.db_path, backup=backup, vacuum=False
+            )
+        except Exception:
+            self.logger.exception("LoRA import could not start")
+            return _failure(
+                "The import could not start. Nothing was changed.", 500, "apply-failed"
+            )
+        if now != plan.fingerprint:
+            store.discard(token)
+            return _failure(SOURCE_CHANGED, 409, "plan-changed")
+        if short is not None:
+            return _failure(short_space_message(short), 507, "insufficient-space")
+        plan, refused = self._peek_plan(token)
+        if refused is not None:
+            return refused
+        try:
+            job = self._jobs.start(
+                LORA_IMPORT_JOB_KIND,
+                lora_import.JOB_TITLE,
+                admission="records",
+                cancellable=True,
+                scope={"operation": LORA_OPERATION, "lora_files": len(files)},
+                groups=lora_import.GROUPS,
+                runner=lambda job: self._run_lora_import(job, db, plan, files, backup),
+            )
+        except JobBusy as busy:
+            return busy_response(busy)
+        store.consume(token, LORA_OPERATION, job_id=job.id)
+        return web.json_response({"success": True, "job": job.summary()}, status=202)
+
+    # ── the job ───────────────────────────────────────────────────────
+
+    async def _run_lora_import(self, job, db, plan, files, backup_on):
+        total = len(files)
+        job.update(total=total, status_line="Preparing LoRA records")
+        job.log_line(f"Found {_count(total, 'LoRA metadata file')}")
+
+        def on_record(index, record, staged):
+            job.update(
+                processed=index + 1,
+                progress=int(90 * (index + 1) / max(total, 1)),
+                status_line=f"Prepared {index + 1:,} of {total:,}",
+            )
+            job.publish({"type": "progress", "progress": job.progress})
+
+        try:
+            staged = await self.stage_lora_import(
+                files, on_record=on_record, cancelled=lambda: job.cancelled
+            )
+        except lora_import.ImportCancelled:
+            job.log_line(f"{CANCELLED} {CACHE_NOTE}")
+            job.update(status_line=CANCELLED)
+            job.finish("cancelled")
+            return
+        except Exception:
+            self.logger.exception("LoRA import staging failed")
+            return _fail_job(job, "import-failed", f"{FAILED} {CACHE_NOTE}")
+        self._count_downloads(job, staged)
+        # M4: what staging skipped stays on the job whatever happens next.
+        job.record_counted(
+            "skipped",
+            len(staged.skipped),
+            [{"path": "", "detail": name} for name in staged.skipped],
+        )
+        # Past this point nothing stops halfway: the replace is one transaction.
+        # Published, so a view that offered Cancel during the downloads drops it.
+        job.cancellable = False
+        job.publish({"type": "progress", "progress": job.progress})
+        if job.cancelled:
+            job.log_line(f"{CANCELLED} {CACHE_NOTE}")
+            job.update(status_line=CANCELLED)
+            job.finish("cancelled")
+            return
+        ok, _backup = await self._safety_backup_step(job, db, backup_on)
+        if not ok:
+            return
+        # I1: the files are listed and fingerprinted again right before the
+        # replace, so a file changed, removed or added while the downloads ran
+        # (LoraManager refreshing its CivitAI info) aborts with nothing deleted.
+        if not await self.lora_files_unchanged(plan.payload["path"], plan.fingerprint):
+            return _fail_job(job, "plan-changed", f"{SOURCE_CHANGED} {CACHE_NOTE}")
+        job.update(status_line="Replacing the LoRA collection", progress=95)
+        await self._replace_in_job(job, db, plan, staged)
+
+    def _count_downloads(self, job, staged):
+        downloaded = staged.stats.get("downloaded", 0)
+        errors = staged.stats.get("download_errors", 0)
+        job.record_counted("downloaded", downloaded)
+        rows = []
+        if errors and not downloaded:
+            warning = _all_downloads_failed(errors)
+            rows = [{"path": "", "detail": f"{warning}; the log has the details"}]
+            job.log_line(warning)
+        job.record_counted("download_errors", errors, rows)
+        if downloaded or errors:
+            job.log_line(
+                f"Downloaded {_count(downloaded, 'example image')}"
+                + (f"; {errors:,} could not be downloaded" if errors else "")
+            )
+
+    async def _replace_in_job(self, job, db, plan, staged):
+        try:
+            result = await self.replace_lora_imports(
+                db,
+                staged,
+                expected_ids=plan.payload["expected_ids"],
+                allow_empty=plan.payload["empty"],
+            )
+        except PlanChanged:
+            return _fail_job(job, "plan-changed", f"{IMPORTS_CHANGED} {CACHE_NOTE}")
+        except PairDependencyError:
+            return _fail_job(job, "blocked-by-pairs", f"{BLOCKED} {CACHE_NOTE}")
+        except EmptyReplacement:
+            return _fail_job(job, "nothing-to-import", f"{EMPTY} {CACHE_NOTE}")
+        except Exception:
+            self.logger.exception("LoRA import failed")
+            return _fail_job(job, "import-failed", f"{FAILED} {CACHE_NOTE}")
+        rows = {"imported": [], "linked": []}
+        for row in result["rows"]:
+            group = "imported" if row["outcome"] == "imported" else "linked"
+            rows[group].append({"path": "", "detail": row["name"]})
+        job.record_counted("imported", result["imported"], rows["imported"])
+        job.record_counted(
+            "linked", result["linked"] + result["duplicates"], rows["linked"]
+        )
+        line = _import_line(result, len(staged.skipped))
+        if result["removed"]:
+            job.log_line(f"Replaced {_count(result['removed'], 'previous import')}")
+        job.log_line(line)
+        line = _with_downloads(
+            line,
+            staged.stats.get("downloaded", 0),
+            staged.stats.get("download_errors", 0),
+        )
+        job.update(progress=100, processed=job.total, status_line=line)

py/api/lora_integration.py

@@ -1,7 +1,9 @@
 """LoraManager integration API routes for PromptManager."""
 
+import asyncio
+import contextlib
 import json
-from pathlib import Path
+import threading
 
 from aiohttp import web
 
@@ -37,6 +39,21 @@ def _lora_settings_mutation(values):
     return mutate
 
 
+# The admin page's own words for the refusals it can meet (it has no review).
+_FILES_CHANGED = (
+    "The LoRA metadata files changed during the scan; the previous imports "
+    "were kept. Run the scan again."
+)
+_IMPORTS_CHANGED = (
+    "The imported LoRA prompts changed during the scan; the previous imports "
+    "were kept. Run the scan again."
+)
+
+
+class LoraFilesChanged(Exception):
+    """A metadata file changed, appeared or went while the legacy scan staged."""
+
+
 def _lora_error_frame(message):
     """An import stream's error event, as the admin page's modal reads it.
 
@@ -46,6 +63,23 @@ def _lora_error_frame(message):
     return {"type": "error", "status": message, "progress": 0, "message": message}
 
 
+def _closed(request):
+    """A check (safe off the loop) for whether ``request``'s client left."""
+
+    def closed():
+        transport = request.transport
+        return transport is None or transport.is_closing()
+
+    return closed
+
+
+def _stopped(error) -> bool:
+    """Whether a legacy scan ended because its page closed the connection."""
+    from .. import lora_import
+
+    return isinstance(error, (ConnectionError, lora_import.ImportCancelled))
+
+
 class LoraIntegrationMixin:
     """Mixin providing LoraManager detection, scanning, and trigger word endpoints."""
 
@@ -108,7 +142,11 @@ class LoraIntegrationMixin:
         """Get current LoraManager integration status."""
         try:
             from ..config import IntegrationConfig
-            from ..lora_utils import detect_lora_manager, get_trigger_cache
+            from ..lora_utils import (
+                detect_lora_manager,
+                get_trigger_cache,
+                resolve_lora_manager_path,
+            )
 
             config = IntegrationConfig.get_config()["lora_manager"]
             cache = get_trigger_cache()
@@ -117,6 +155,12 @@ class LoraIntegrationMixin:
             detected_path = await self._run_in_executor(
                 detect_lora_manager, config.get("path", "")
             )
+            # A detected install reached through a link outside custom_nodes is
+            # found but cannot be enabled (S10 review N5): say which.
+            usable = bool(detected_path) and (
+                await self._run_in_executor(resolve_lora_manager_path, detected_path)
+                is not None
+            )
 
             return web.json_response(
                 {
@@ -126,6 +170,7 @@ class LoraIntegrationMixin:
                     "trigger_words_enabled": config["trigger_words_enabled"],
                     "has_civitai_api_key": bool(config.get("civitai_api_key")),
                     "detected": detected_path is not None,
+                    "detected_usable": usable,
                     "detected_path": (
                         self._public_path(detected_path) if detected_path else ""
                     ),
@@ -168,6 +213,9 @@ class LoraIntegrationMixin:
     async def lora_enable(self, request):
         """Enable or disable LoraManager integration and save it to config.json.
 
+        ``expected_revision`` (optional, GET /settings' ``revision``) refuses
+        a save over a config.json changed meanwhile (``settings-changed``).
+
         The values are committed through the config store first (#220) and
         published at runtime only once config.json holds them; a save that
         cannot be written reports ``persisted: false`` and changes nothing.
@@ -180,6 +228,11 @@ class LoraIntegrationMixin:
             for flag in _LORA_FLAGS:
                 if flag in data and not isinstance(data[flag], bool):
                     return self._bad_lora_request(f"{flag} must be true or false")
+            # The System Save row sends the revision it read (#220); the
+            # legacy page sends none and merges into what is on disk.
+            expected_revision = data.get("expected_revision")
+            if expected_revision is not None and not isinstance(expected_revision, str):
+                return self._bad_lora_request("expected_revision must be a string")
             enabled = data.get("enabled", False)
             path = data.get("path", "")
             trigger_words = data.get("trigger_words_enabled", False)
@@ -226,7 +279,7 @@ class LoraIntegrationMixin:
                 _saved, revision = await self._run_in_executor(
                     get_config_store().commit,
                     _lora_settings_mutation(values),
-                    expected_revision=None,
+                    expected_revision=expected_revision,
                     publish=publish,
                 )
             except (ConfigUnreadable, RevisionConflict, OSError) as exc:
@@ -308,43 +361,69 @@ class LoraIntegrationMixin:
             ) as job:
                 await response.prepare(request)
                 try:
-                    await self._lora_scan_stream(allowed, send_progress)
+                    await self._lora_scan_stream(
+                        allowed, send_progress, disconnected=_closed(request)
+                    )
+                except asyncio.CancelledError:
+                    # The server cancelled the handler when the page left.
+                    job.finish("cancelled")
+                    raise
                 except Exception as e:
-                    self.logger.exception("LoRA scan failed")
-                    job.finish("failed")
-                    await send_progress(_lora_error_frame(self._public_error(e)))
-
-                await response.write_eof()
+                    # A page that left stopped the scan; nothing failed (R2).
+                    job.finish("cancelled" if _stopped(e) else "failed")
+                    await self._send_scan_failure(e, send_progress)
+                with contextlib.suppress(ConnectionError, RuntimeError):
+                    await response.write_eof()
             return response
 
         except Exception as e:
             self.logger.error(f"LoRA scan failed: {e}")
             return self._error_response(e)
 
-    async def _lora_scan_stream(self, lm_path, send_progress):
-        """Import every LoRA under ``lm_path``, reporting through ``send_progress``."""
-        from ..config import IntegrationConfig
-        from ..lora_utils import (
-            download_civitai_images,
-            find_lora_directories,
-            get_example_prompt_from_metadata,
-            get_lora_image_cache_dir,
-            get_preview_images_from_metadata,
-            get_trigger_words_from_metadata,
-            get_model_name_from_metadata,
-            read_lora_metadata,
+    async def _send_scan_failure(self, error, send_progress):
+        """The error frame for a failed legacy scan; quiet when the page left.
+
+        Expected refusals (files or imports changed, saved pairs, nothing to
+        import) are warnings in the admin page's own words; anything else is
+        logged with its traceback.
+        """
+        from .lora_import_routes import (
+            EmptyReplacement,
+            PairDependencyError,
+            PlanChanged,
         )
 
-        await send_progress(
-            {
-                "type": "progress",
-                "status": "Clearing previous lora-manager imports...",
-                "progress": 0,
-            }
-        )
+        if _stopped(error):
+            self.logger.info("LoRA scan stopped: the page closed its connection")
+            return
+        if isinstance(error, PlanChanged):
+            message = _IMPORTS_CHANGED
+        elif isinstance(error, LoraFilesChanged):
+            message = str(error)
+        else:
+            message = self._public_error(error)
+        if isinstance(
+            error,
+            (PlanChanged, LoraFilesChanged, EmptyReplacement, PairDependencyError),
+        ):
+            self.logger.warning(f"LoRA scan refused: {message}")
+        else:
+            self.logger.exception("LoRA scan failed")
+        with contextlib.suppress(ConnectionError, RuntimeError):
+            await send_progress(_lora_error_frame(message))
 
-        # Clear previous imports so reimport is always clean
-        await self._run_in_executor(self.db.delete_prompts_by_category, "lora-manager")
+    async def _lora_scan_stream(
+        self, lm_path, send_progress, disconnected=lambda: False
+    ):
+        """Import every LoRA under ``lm_path``, reporting through ``send_progress``.
+
+        The staged path of the System import (#221, ``lora_import_routes``):
+        discover, stage every record (downloads into the cache first), then
+        replace the collection in one transaction. A failure at any stage
+        raises with the previous imports untouched; an empty replacement of a
+        non-empty collection is refused (it needs the reviewed import).
+        """
+        from .. import lora_import
 
         await send_progress(
             {
@@ -353,19 +432,8 @@ class LoraIntegrationMixin:
                 "progress": 2,
             }
         )
-
-        lora_dirs = await self._run_in_executor(find_lora_directories, lm_path)
-
-        # Collect all metadata files
-        meta_files = []
-        for d in lora_dirs:
-            dir_path = Path(d)
-            meta_files.extend(dir_path.rglob("*.metadata.json"))
-
-        total = len(meta_files)
-        imported = 0
-        skipped = 0
-
+        files = await self._run_in_executor(lora_import.discover, lm_path)
+        total = len(files)
         await send_progress(
             {
                 "type": "progress",
@@ -375,116 +443,105 @@ class LoraIntegrationMixin:
             }
         )
 
-        cache_dir = get_lora_image_cache_dir()
+        reviewed = await self._run_in_executor(lora_import.fingerprint, files)
+        events = asyncio.Queue()
+        state = await self._run_in_executor(
+            self.db.category_import_state, lora_import.LORA_CATEGORY
+        )
+        # Records whose prompt already exists outside the collection are
+        # linked, not imported (the running counts; the end ones are exact).
+        known = set()
 
-        for i, meta_file in enumerate(meta_files):
-            metadata = await self._run_in_executor(read_lora_metadata, meta_file)
-            if not metadata:
-                skipped += 1
-                continue
+        def on_record(index, record, _staged):
+            events.put_nowait((index, record))
 
-            model_name = get_model_name_from_metadata(metadata)
-            trigger_words = get_trigger_words_from_metadata(metadata)
-
-            # Collect all images: local previews + downloaded civitai examples
-            preview_paths = await self._run_in_executor(
-                get_preview_images_from_metadata, metadata, meta_file
-            )
-            civitai_paths = await self._run_in_executor(
-                download_civitai_images,
-                metadata,
-                meta_file,
-                cache_dir,
-                IntegrationConfig.CIVITAI_API_KEY,
-            )
-
-            # Merge, local first, dedup
-            seen = set(preview_paths)
-            all_images = list(preview_paths)
-            for cp in civitai_paths:
-                if cp not in seen:
-                    all_images.append(cp)
-                    seen.add(cp)
-
-            # Build prompt text: prefer example prompt, then model name
-            example_prompt = get_example_prompt_from_metadata(metadata)
-            prompt_text = example_prompt or model_name
-
-            # Build tags
-            tags = ["lora-manager", f"lora:{model_name}"]
-            tags.extend(trigger_words)
-
-            # Save to database via existing mechanism
-            try:
-                import hashlib
-
-                prompt_hash = hashlib.sha256(
-                    prompt_text.strip().lower().encode("utf-8")
-                ).hexdigest()
+        counts = {"imported": 0}
 
+        async def report(index, record):
+            if record is not None and record["hash"] not in known:
+                known.add(record["hash"])
                 existing = await self._run_in_executor(
-                    self.db.get_prompt_by_hash, prompt_hash
+                    self.db.existing_prompt_hashes,
+                    [record["hash"]],
+                    lora_import.LORA_CATEGORY,
                 )
-
-                if existing:
-                    # Link all images
-                    for pp in all_images:
-                        await self._run_in_executor(
-                            self.db.link_image_to_prompt,
-                            existing["id"],
-                            pp,
-                        )
-                    skipped += 1
-                else:
-                    prompt_id = await self._run_in_executor(
-                        self.db.save_prompt,
-                        prompt_text,
-                        "lora-manager",  # category
-                        tags,
-                        None,  # rating
-                        None,  # notes
-                        prompt_hash,
-                    )
-
-                    if prompt_id:
-                        for pp in all_images:
-                            await self._run_in_executor(
-                                self.db.link_image_to_prompt,
-                                prompt_id,
-                                pp,
-                            )
-                        imported += 1
-                    else:
-                        skipped += 1
-
-            except Exception as e:
-                self.logger.warning(f"Failed to import LoRA {model_name}: {e}")
-                skipped += 1
-
-            # Progress update for every LoRA
-            progress = int(5 + (90 * (i + 1) / max(total, 1)))
-            img_count = len(all_images)
-            status = f"{model_name}"
-            if img_count:
-                status += f" ({img_count} images)"
+                if not existing:
+                    counts["imported"] += 1
+            status = record["name"] if record else files[index].name
+            if record and record["images"]:
+                status += f" ({len(record['images'])} images)"
             await send_progress(
                 {
                     "type": "progress",
                     "status": status,
-                    "progress": progress,
-                    "processed": i + 1,
-                    "imported": imported,
-                    "skipped": skipped,
+                    "progress": int(5 + (90 * (index + 1) / max(total, 1))),
+                    "processed": index + 1,
+                    "imported": counts["imported"],
+                    "skipped": index + 1 - counts["imported"],
                 }
             )
 
+        # Each record's event is queued (through the loop) before staging
+        # ends, so reporting until staging is done and then draining the
+        # queue reports every record in order. I2: when the page goes away
+        # (its connection closes, or a report cannot be sent) staging stops
+        # before its next LoRA, and this returns only once it has stopped, so
+        # the caller's records hold covers every download.
+        stop = threading.Event()
+        staging = asyncio.ensure_future(
+            self.stage_lora_import(
+                files,
+                on_record=on_record,
+                cancelled=lambda: stop.is_set() or disconnected(),
+            )
+        )
+        try:
+            while not staging.done():
+                getter = asyncio.ensure_future(events.get())
+                await asyncio.wait(
+                    {getter, staging}, return_when=asyncio.FIRST_COMPLETED
+                )
+                if getter.done():
+                    await report(*getter.result())
+                else:
+                    getter.cancel()
+            while not events.empty():
+                await report(*events.get_nowait())
+        finally:
+            stop.set()
+            # Staging must have stopped before the records hold is released,
+            # even when the handler is cancelled again while it waits (R3).
+            interrupted = False
+            while not staging.done():
+                try:
+                    await asyncio.shield(staging)
+                except asyncio.CancelledError:
+                    interrupted = True
+                except Exception:
+                    pass
+            if interrupted:
+                raise asyncio.CancelledError
+        staged = await staging
+        if not await self.lora_files_unchanged(lm_path, reviewed):
+            raise LoraFilesChanged(_FILES_CHANGED)
+
+        await send_progress(
+            {
+                "type": "progress",
+                "status": "Replacing previous lora-manager imports...",
+                "progress": 96,
+            }
+        )
+        result = await self.replace_lora_imports(
+            self.db, staged, expected_ids=state["ids"], allow_empty=False
+        )
         await send_progress(
             {
                 "type": "complete",
                 "progress": 100,
                 "total": total,
-                "imported": imported,
-                "skipped": skipped,
+                "imported": result["imported"],
+                "skipped": total - result["imported"],
             }
         )
 

py/api/maintenance.py

@@ -0,0 +1,692 @@
+"""Maintenance routes: reviewed, read-only plans (#249 System S6).
+
+``POST /prompt_manager/maintenance/preview {operation, options:{}}`` reviews
+one operation (``duplicate_prompts``, ``optimize``, ``unused_components`` or
+``missing_links``; ``database/maintenance.py``) off the event loop and
+answers a ``Plan``: ``{success, token, operation, expires_at, scope:{count,
+label}, protected:{count, reasons}, backup:{policy, destination_label},
+media:{deletes_files, label}, details:[≤50 {label, detail}]}``. The preview
+writes nothing. The plan's fingerprint, its targets and the sources it judged
+stay in the server's ``PlanStore`` under the token, bound to the database the
+preview read (a restore that replaces it invalidates the plan).
+
+The operation enum is strict, ``options`` must be an empty object and the
+body is capped at ``PREVIEW_BODY_MAX`` bytes. Errors are ``{success:false,
+code, error}`` with ``invalid-request`` (400), ``too-large`` (413: the body,
+or a plan over the store's budget), ``storage-changed`` (409: the database
+was replaced while the preview read it) or a null code (500); none carries a
+server path or exception text.
+
+``POST /prompt_manager/maintenance/apply {token}`` applies a reviewed plan as
+an Activity job (202 ``{job}``): kind ``maintenance``, titled after the
+operation, admission ``records`` (refused while a scan, restore, LoRA import
+or other record-changing job runs, and refusing them meanwhile), not
+cancellable, with outcome groups ``changed``, ``protected`` and ``errors``.
+The token is consumed when the job starts (on the same loop turn, before its
+runner runs); a refused start keeps it. The runner:
+
+1. takes a safety backup when the plan was reviewed with the policy on or the
+   policy (``maintenance.safety_backup``, default on) is on now: SQLite's
+   backup API into a temp file beside the database, ``verify_database_file``,
+   fsync, ``0o600`` on POSIX, then ``os.replace`` onto a unique
+   ``<db>.backup_<YYYYmmdd_HHMMSS_ffffff>[_n]`` name. Any failure removes
+   what it wrote and ends the job ``backup-failed`` with nothing changed;
+2. applies the plan, which first rechecks the reviewed fingerprint inside
+   ``BEGIN IMMEDIATE`` (``plan-changed`` writes nothing);
+3. counts the changed and protected records, and prunes old safety backups.
+
+The job log names the backup by its file name only, and the job says "No
+safety backup" when none was taken. Apply errors: ``invalid-request`` (400),
+``apply-failed`` (500: nothing started), ``plan-expired`` (410: unknown,
+expired or forgotten after a restart),
+``plan-used`` (409, with the job that applied it), ``storage-changed`` (409:
+a restore replaced the database since the review) and ``busy`` (409).
+"""
+
+import datetime
+import json
+import os
+import shutil
+import sqlite3
+
+from aiohttp import web
+
+from .admin import _prune_safety_backups, _scan_location, _scan_roots
+from .job_routes import busy_response
+from .jobs import MAINTENANCE_JOB_KIND, JobBusy
+from .maintenance_plans import PlanExpired, PlanUsed, ScopeTooLarge
+
+try:
+    from ...database import safety_backup as _backups
+    from ...database.safety_backup import (  # noqa: F401 - re-exported
+        SAFETY_TEMP_PREFIX,
+        SafetyBackupFailed,
+        sweep_safety_temps,
+    )
+    from ...database.workflow_storage import PRE_MIGRATION_LABEL, pre_migration_backups
+    from ...database.health import readonly_uri
+    from ...database.maintenance import MAINTENANCE_OPERATIONS, PlanChanged
+except ImportError:
+    from database import safety_backup as _backups
+    from database.safety_backup import (  # noqa: F401 - re-exported
+        SAFETY_TEMP_PREFIX,
+        SafetyBackupFailed,
+        sweep_safety_temps,
+    )
+    from database.workflow_storage import PRE_MIGRATION_LABEL, pre_migration_backups
+    from database.health import readonly_uri
+    from database.maintenance import MAINTENANCE_OPERATIONS, PlanChanged
+
+PREVIEW_BODY_MAX = 4096
+MAINTENANCE_PREVIEW_LEASE = "Maintenance preview"
+# Duplicate-file previews carry the reviewed keepers (py/api/duplicate_files.py).
+DUPLICATE_PREVIEW_BODY_MAX = 1024 * 1024
+DUPLICATE_FILES = "duplicate_files"
+WORKFLOW_STORAGE = "workflow_storage"  # applied by py/api/workflow_storage.py
+PREVIEW_OPERATIONS = MAINTENANCE_OPERATIONS + (DUPLICATE_FILES,)
+# Room left over beyond what a step writes, so a disk is never filled to 0.
+DISK_MARGIN_BYTES = 16 * 2**20
+# The concept's Maintenance row titles, which name each operation's job.
+MAINTENANCE_TITLES = {
+    "duplicate_prompts": "Duplicate prompt text",
+    "optimize": "Optimize database",
+    "unused_components": "Unused prompt components",
+    "missing_links": "Missing-file links",
+    "workflow_storage": "Store each workflow once",
+}
+_OPERATION_ERROR = "operation must be one of: " + ", ".join(PREVIEW_OPERATIONS)
+MAINTENANCE_GROUPS = ("changed", "protected", "errors")
+MAX_TOKEN_LENGTH = 128
+BACKUP_FAILED = (
+    "The safety backup could not be taken and verified; nothing was changed."
+)
+PLAN_CHANGED = (
+    "The library changed since the review; nothing was changed. "
+    "Review the plan again."
+)
+APPLY_FAILED = "Maintenance failed; nothing was changed."
+NOTHING_TO_DO = "Every image record already stores its workflow once; nothing to do."
+NO_BACKUP = "No safety backup"
+
+
+def backup_failed_message(error):
+    """The job line for a failed backup, naming a damaged workflow document."""
+    reason = getattr(error, "reason", None) or ""
+    if reason.startswith("Workflow document "):
+        return f"{BACKUP_FAILED} {reason}"
+    return BACKUP_FAILED
+
+
+def _free_bytes(path):
+    return shutil.disk_usage(path).free
+
+
+def _device(path):
+    try:
+        return os.stat(path).st_dev
+    except OSError:
+        return path
+
+
+def sqlite_temp_dir(environ=None, *, windows=None, usable=None):
+    """The folder SQLite builds its temporary files in (VACUUM's copy).
+
+    Mirrors SQLite's own search, which differs from ``tempfile``'s. On Unix
+    (``unixTempFileDir``): ``SQLITE_TMPDIR``, ``TMPDIR``, then ``/var/tmp``,
+    ``/usr/tmp`` and ``/tmp``, the first that is a writable directory, else
+    the current directory. On Windows (``GetTempPathW``): ``TMP``, ``TEMP``,
+    then ``USERPROFILE``, else the current directory.
+    """
+    environ = os.environ if environ is None else environ
+    if windows is None:
+        windows = os.name == "nt"
+    if windows:
+        for name in ("TMP", "TEMP", "USERPROFILE"):
+            if environ.get(name):
+                return environ[name]
+        return os.path.abspath(".")
+    if usable is None:
+
+        def usable(path):
+            return os.path.isdir(path) and os.access(path, os.W_OK | os.X_OK)
+
+    candidates = [environ.get("SQLITE_TMPDIR"), environ.get("TMPDIR")]
+    candidates += ["/var/tmp", "/usr/tmp", "/tmp"]
+    for candidate in candidates:
+        if candidate and usable(candidate):
+            return candidate
+    return os.path.abspath(".")
+
+
+def database_bytes(db_path):
+    """The size a safety backup of the database will be (blocking).
+
+    SQLite's backup API copies every page, committed WAL content included, so
+    the copy is ``page_count * page_size`` read on one read-only snapshot.
+    """
+    conn = sqlite3.connect(readonly_uri(db_path), uri=True)
+    try:
+        page_size = conn.execute("PRAGMA page_size").fetchone()[0]
+        return page_size * conn.execute("PRAGMA page_count").fetchone()[0]
+    finally:
+        conn.close()
+
+
+def _megabytes(size):
+    return f"{size / 2**20:,.1f} MB"
+
+
+def disk_plan(db_path, *, backup, vacuum, vacuum_bytes=None):
+    """Whether the disk has room for an apply's writes (blocking).
+
+    ``backup``: the safety backup, one database-sized file beside the
+    database. ``vacuum``: VACUUM writes the rebuilt database through the WAL
+    beside it and builds it in a temporary copy in SQLite's temporary folder
+    (``sqlite_temp_dir``; SQLite's documentation: up to twice the database
+    in free space). Needs
+    on one device add up. ``vacuum_bytes``, when given, is what VACUUM
+    copies (the live pages, for Reclaim space) instead of the whole file.
+    Returns ``(public, short)``: ``public`` is
+    ``{free_bytes, required_bytes, sufficient}`` for the database folder,
+    ``short`` None or ``(place, what, required, free)`` of the first place
+    that is short, and ``size`` the database's size (0 when nothing is
+    written).
+    """
+    db_path = os.path.abspath(db_path)
+    folder = os.path.dirname(db_path)
+    size = database_bytes(db_path) if backup or vacuum else 0
+    needs = []  # (place, folder, bytes, what)
+    if backup:
+        needs.append(("database folder", folder, size, "the safety backup"))
+    if vacuum:
+        copy = size if vacuum_bytes is None else vacuum_bytes
+        what = "Optimize" if vacuum_bytes is None else "Reclaim space"
+        needs.append(("database folder", folder, copy, what))
+        needs.append(("temporary folder", sqlite_temp_dir(), copy, what))
+    devices = {}
+    for place, path, needed, what in needs:
+        entry = devices.setdefault(_device(path), {"place": place, "path": path})
+        entry["bytes"] = entry.get("bytes", 0) + needed
+        entry.setdefault("what", [])
+        if what not in entry["what"]:
+            entry["what"].append(what)
+    short = None
+    public = {"free_bytes": _free_bytes(folder), "required_bytes": 0}
+    for device, entry in devices.items():
+        required = entry["bytes"] + DISK_MARGIN_BYTES
+        free = (
+            public["free_bytes"]
+            if entry["path"] == folder
+            else _free_bytes(entry["path"])
+        )
+        if device == _device(folder):
+            public["required_bytes"] = required
+        if free < required and short is None:
+            short = (entry["place"], " and ".join(entry["what"]), required, free)
+    public["sufficient"] = short is None
+    return public, short, size
+
+
+# A restore upload's hard ceiling; below it, free disk space decides.
+RESTORE_MAX_BYTES = 64 * 2**30
+
+
+def size_label(size):
+    """``1.6 GB`` or ``120.0 MB``: a backup's size for a message."""
+    if size >= 2**30:
+        return f"{size / 2**30:,.1f} GB"
+    return _megabytes(size)
+
+
+def restore_room(db_path):
+    """The largest restore upload the disk has room for (blocking).
+
+    Everything a restore writes is in the library's folder (#318): the
+    upload, its staged copy (``database/restore_stage.py``) and the WAL
+    growth while the stage is copied over the live database (3x the upload),
+    plus the safety backup of the current database (1x its size), with
+    ``DISK_MARGIN_BYTES`` to spare.
+    """
+    db_path = os.path.abspath(db_path)
+    folder = os.path.dirname(db_path)
+    current = database_bytes(db_path) if os.path.exists(db_path) else 0
+    room = (_free_bytes(folder) - current - DISK_MARGIN_BYTES) // 3
+    return max(0, room)
+
+
+def restore_space_message(size, room, *, known):
+    """The truthful refusal of a restore the disks have no room for."""
+    if known:
+        return (
+            f"Not enough free disk space to restore a {size_label(size)} backup; "
+            f"there is room for about {size_label(room)}. Nothing was changed."
+        )
+    return (
+        "Not enough free disk space to restore this backup: it is larger than "
+        f"the {size_label(room)} there is room for. Nothing was changed."
+    )
+
+
+def short_space_message(short):
+    """The truthful refusal for ``disk_plan``'s ``short``."""
+    place, what, required, free = short
+    verb = "need" if " and " in what else "needs"
+    return (
+        f"Not enough free disk space: {what} {verb} about {_megabytes(required)} "
+        f"in the {place} and {_megabytes(free)} is free. Nothing was changed."
+    )
+
+
+def _changed_line(operation, count):
+    if operation == "optimize":
+        return "Optimized the database"
+    if operation == "duplicate_prompts":
+        noun = "duplicate prompt" if count == 1 else "duplicate prompts"
+        return f"Merged {count:,} {noun}"
+    if operation == "unused_components":
+        noun = "unused prompt component" if count == 1 else "unused prompt components"
+        return f"Removed {count:,} {noun}"
+    noun = "link to a missing file" if count == 1 else "links to missing files"
+    return f"Removed {count:,} {noun}"
+
+
+def take_safety_backup(model, label="backup"):
+    """Write and verify a safety backup; return its file name (blocking).
+
+    See ``database/safety_backup.py``: a backup file on disk is always a
+    verified one. Raises SafetyBackupFailed, leaving no file.
+    """
+    return os.path.basename(_backups.take_safety_backup(model, label))
+
+
+def _failure(message, status, code=None, **extra):
+    return web.json_response(
+        {"success": False, "code": code, "error": message, **extra}, status=status
+    )
+
+
+def _invalid(message):
+    return _failure(message, 400, "invalid-request")
+
+
+def _iso(timestamp):
+    return datetime.datetime.fromtimestamp(timestamp, datetime.timezone.utc).isoformat()
+
+
+class MaintenanceRoutesMixin:
+    """Mixin providing the /prompt_manager/maintenance plan endpoints."""
+
+    def _register_maintenance_routes(self, routes):
+        @routes.post("/prompt_manager/maintenance/preview")
+        async def maintenance_preview_route(request):
+            return await self.preview_maintenance(request)
+
+        @routes.post("/prompt_manager/maintenance/apply")
+        async def maintenance_apply_route(request):
+            return await self.apply_maintenance_plan(request)
+
+    def _database_identity(self, db):
+        """What binds a plan to one database: the swap generation and its file."""
+        path = os.path.normcase(os.path.realpath(db.model.db_path))
+        return (self._db_generation, path)
+
+    @staticmethod
+    def _safety_backup_policy():
+        """``on`` or ``off``: whether an apply takes a safety backup first."""
+        from ..config import PromptManagerConfig
+
+        return "on" if PromptManagerConfig.SAFETY_BACKUP else "off"
+
+    async def _read_maintenance_body(self, request, allowed, cap=None):
+        """``(data, None)`` for a capped JSON object with only ``allowed`` keys.
+
+        ``cap(data)``, when given, is the body's byte limit for what it asks
+        (read up to ``DUPLICATE_PREVIEW_BODY_MAX``); else PREVIEW_BODY_MAX.
+        """
+        limit = PREVIEW_BODY_MAX if cap is None else DUPLICATE_PREVIEW_BODY_MAX
+        data, error = await self._read_json_body(request, max_bytes=limit)
+        if error is not None:
+            if error.status == 413:
+                return None, _failure("Request body too large", 413, "too-large")
+            return None, _invalid("Request body must be a JSON object")
+        if cap is not None:
+            size = len(json.dumps(data, separators=(",", ":")).encode("utf-8"))
+            if size > cap(data):
+                return None, _failure("Request body too large", 413, "too-large")
+        unknown = sorted(set(data) - set(allowed))
+        if unknown:
+            return None, _invalid("Unknown field: " + ", ".join(unknown)[:200])
+        return data, None
+
+    async def preview_maintenance(self, request):
+        """Review one operation under a registry lease (#249 S8).
+
+        The preview's read-only connections must not be open while a restore
+        switches the database: it is refused (409 ``busy``) while an
+        ``exclusive`` job runs, and a restore waits for running previews.
+        """
+        try:
+            async with self._jobs.lease(MAINTENANCE_PREVIEW_LEASE):
+                return await self._preview_maintenance(request)
+        except JobBusy as busy:
+            return busy_response(busy)
+
+    async def _preview_maintenance(self, request):
+        data, error = await self._read_maintenance_body(
+            request,
+            ("operation", "options"),
+            cap=lambda body: (
+                DUPLICATE_PREVIEW_BODY_MAX
+                if body.get("operation") == DUPLICATE_FILES
+                else PREVIEW_BODY_MAX
+            ),
+        )
+        if error is not None:
+            return error
+        operation = data.get("operation")
+        options = data.get("options", {})
+        if not isinstance(operation, str) or operation not in PREVIEW_OPERATIONS:
+            return _invalid(_OPERATION_ERROR)
+        if operation == DUPLICATE_FILES:
+            return await self.preview_duplicate_files(options)
+        if not isinstance(options, dict) or options:
+            return _invalid(f"{operation} takes no options")
+        db = self.db
+        identity = self._database_identity(db)
+        try:
+            roots = (
+                await self._run_in_executor(self._health_roots)
+                if operation == "missing_links"
+                else []
+            )
+            draft = await self._run_in_executor(
+                db.preview_maintenance, operation, roots
+            )
+        except Exception:
+            self.logger.exception(f"Maintenance preview of {operation} failed")
+            return _failure("Failed to review maintenance", 500)
+        return await self._plan_response(
+            db,
+            identity,
+            draft.operation,
+            draft.fingerprint,
+            draft.public(),
+            {
+                "targets": draft.targets,
+                "roots": roots,
+                "protected": draft.protected["count"],
+                "rows": draft.scope["count"],
+            },
+        )
+
+    async def _plan_response(
+        self, db, identity, operation, fingerprint, public, payload
+    ):
+        """Issue the reviewed plan's token and answer the ``Plan``.
+
+        Refused with ``storage-changed`` when the database was replaced while
+        it was reviewed. The plan reports the safety backup's expected size
+        and the disk space the apply needs (``disk_plan``).
+        """
+        if identity != self._database_identity(self.db):
+            return _failure(
+                "The database was replaced while it was reviewed. Review again.",
+                409,
+                "storage-changed",
+            )
+        policy = self._safety_backup_policy()
+        destination = "backup"
+        if operation == WORKFLOW_STORAGE:
+            # Always backed up first, whatever the policy (the way back);
+            # one kept pre-migration backup ever, pooled ones after it.
+            policy = "required"
+            kept = await self._run_in_executor(pre_migration_backups, db.model.db_path)
+            destination = "backup" if kept else PRE_MIGRATION_LABEL
+        try:
+            disk, _short, size = await self._run_in_executor(
+                disk_plan,
+                db.model.db_path,
+                backup=policy != "off",
+                vacuum=operation == "optimize",
+            )
+        except (OSError, sqlite3.Error):
+            self.logger.exception("Could not measure the disk space for a plan")
+            return _failure("Failed to review maintenance", 500)
+        store = self._maintenance_plans
+        try:
+            token = store.issue(
+                operation, fingerprint, {**payload, "backup": policy}, identity
+            )
+        except ScopeTooLarge:
+            return _failure(
+                "This plan is too large to review at once.", 413, "too-large"
+            )
+        plan = store.peek(token, operation)
+        name = os.path.basename(db.model.db_path)
+        return web.json_response(
+            {
+                "success": True,
+                "token": token,
+                "expires_at": _iso(plan.expires_at),
+                **public,
+                "backup": {
+                    "policy": policy,
+                    "destination_label": f"{name}.{destination}_<date and time>",
+                    "expected_bytes": size if policy != "off" else None,
+                },
+                "disk": disk,
+            },
+            headers={"Cache-Control": "no-store"},
+        )
+
+    # ── apply ─────────────────────────────────────────────────────────
+
+    async def apply_maintenance_plan(self, request):
+        data, error = await self._read_maintenance_body(request, ("token",))
+        if error is not None:
+            return error
+        token = data.get("token")
+        if not isinstance(token, str) or not 0 < len(token) <= MAX_TOKEN_LENGTH:
+            return _invalid("token must be the plan's token")
+        plan, refused = self._peek_plan(token)
+        if refused is not None:
+            return refused
+        store = self._maintenance_plans
+        db = self.db
+        if plan.db_identity != self._database_identity(db):
+            store.discard(token)
+            return _failure(
+                "The database was replaced since the review. Review again.",
+                409,
+                "storage-changed",
+            )
+        if plan.operation == WORKFLOW_STORAGE and not plan.payload.get("rows"):
+            store.discard(token)  # no job, no backup: nothing to rewrite
+            return _failure(NOTHING_TO_DO, 409, "nothing-to-do")
+        backup = self._backup_promised(plan)
+        try:
+            _disk, short, _size = await self._run_in_executor(
+                disk_plan,
+                db.model.db_path,
+                backup=backup,
+                vacuum=plan.operation == "optimize",
+            )
+        except (OSError, sqlite3.Error):
+            self.logger.exception("Could not measure the disk space for an apply")
+            # Coded: the workspace tells the server's own refusal (nothing
+            # started) from a proxy's 5xx (the job may have started).
+            return _failure(APPLY_FAILED, 500, "apply-failed")
+        if short is not None:
+            # Refused before any job starts: nothing fails halfway for space.
+            return _failure(short_space_message(short), 507, "insufficient-space")
+        # The token may have been used, expired or dropped while the disk was
+        # measured: look again with no await before the job starts.
+        plan, refused = self._peek_plan(token)
+        if refused is not None:
+            return refused
+        try:
+            if plan.operation == DUPLICATE_FILES:
+                job = self._start_duplicate_cleanup(db, plan, backup)
+            elif plan.operation == WORKFLOW_STORAGE:
+                job = self._start_workflow_storage(db, backup)
+            else:
+                job = self._jobs.start(
+                    MAINTENANCE_JOB_KIND,
+                    MAINTENANCE_TITLES[plan.operation],
+                    # VACUUM rewrites the whole file under the write lock: it
+                    # runs alone, beside no other job of any class.
+                    admission=(
+                        "exclusive" if plan.operation == "optimize" else "records"
+                    ),
+                    cancellable=False,
+                    scope={"operation": plan.operation},
+                    groups=MAINTENANCE_GROUPS,
+                    runner=lambda job: self._run_maintenance_plan(
+                        job, db, plan, backup
+                    ),
+                )
+        except JobBusy as busy:
+            return busy_response(busy)  # the token stays usable
+        # Same loop turn as the peek and the start: the runner has not run.
+        store.consume(token, plan.operation, job_id=job.id)
+        return web.json_response({"success": True, "job": job.summary()}, status=202)
+
+    def _peek_plan(self, token):
+        """``(plan, None)`` for a usable token, else ``(None, refusal)``."""
+        try:
+            return self._maintenance_plans.peek(token), None
+        except PlanUsed as used:
+            job = self._jobs.get(used.job_id)
+            return None, _failure(
+                "This plan was already applied.",
+                409,
+                "plan-used",
+                job={"id": used.job_id, "title": job.title if job else None},
+            )
+        except PlanExpired:
+            return None, _failure(
+                "This review expired. Review the plan again.", 410, "plan-expired"
+            )
+
+    def _backup_promised(self, plan):
+        """A plan reviewed with the policy on keeps that promise; so does on now.
+
+        Decided once, when the apply starts (the disk check measured it), and
+        handed to the job.
+        """
+        if plan.operation == WORKFLOW_STORAGE:
+            return True  # never without its pre-migration backup
+        return plan.payload["backup"] == "on" or self._safety_backup_policy() == "on"
+
+    async def _safety_backup_step(self, job, db, backup_on):
+        """``(ok, name)``: take the promised safety backup, or report none.
+
+        ``name`` is the backup's file name, or None when no backup was
+        promised. A failed backup ends the job ``backup-failed`` (``ok``
+        False).
+        """
+        if not backup_on:
+            job.log_line("No safety backup (the policy is off)")
+            return True, None
+        job.update(status_line="Taking a safety backup")
+        job.log_line("Taking a safety backup of the database")
+        try:
+            backup = await self._run_in_executor(take_safety_backup, db.model)
+        except SafetyBackupFailed as error:
+            self.logger.error("Safety backup failed", exc_info=True)
+            _fail_job(job, "backup-failed", backup_failed_message(error))
+            return False, None
+        job.log_line(f"Safety backup {backup} verified")
+        return True, backup
+
+    async def _prune_backup_pool(self, job, db):
+        """Keep the one ``<db>.backup_*`` pool (restore's too) at its cap."""
+        removed = await self._run_in_executor(_prune_safety_backups, db.model.db_path)
+        if removed:
+            job.log_line(f"Removed {len(removed)} older safety backups")
+
+    async def _run_maintenance_plan(self, job, db, plan, backup_on):
+        ok, backup = await self._safety_backup_step(job, db, backup_on)
+        if not ok:
+            return
+        try:
+            await self._apply_maintenance_plan(job, db, plan, backup)
+        finally:
+            if backup:
+                await self._prune_backup_pool(job, db)
+
+    async def _apply_maintenance_plan(self, job, db, plan, backup):
+        payload = plan.payload
+        job.update(status_line=f"Applying: {job.title}")
+        try:
+            result = await self._run_in_executor(
+                db.apply_maintenance,
+                plan.operation,
+                plan.fingerprint,
+                payload["targets"],
+                payload["roots"],
+            )
+        except PlanChanged:
+            return _fail_job(job, "plan-changed", PLAN_CHANGED)
+        except Exception:
+            self.logger.exception(f"Maintenance {plan.operation} failed")
+            return _fail_job(job, None, APPLY_FAILED)
+        rows = await self._run_in_executor(
+            self._maintenance_rows, plan.operation, result["rows"]
+        )
+        job.record_counted("changed", result["changed"], rows)
+        job.record_counted("protected", payload["protected"])
+        line = _changed_line(plan.operation, result["changed"])
+        job.log_line(line)
+        job.update(progress=100, status_line=f"{line} · {backup_note(backup)}")
+
+    def _maintenance_rows(self, operation, described):
+        """Outcome rows for the changed records (root-relative paths only)."""
+        if operation == "missing_links":
+            roots = _scan_roots(self._get_all_output_dirs())
+            rows = []
+            for item in described:
+                path, label, index = _scan_location(item["image_path"], roots)
+                rows.append(
+                    {
+                        "path": path,
+                        "root": label,
+                        "root_index": index,
+                        "detail": "Link removed; the file was already missing",
+                    }
+                )
+            return rows
+        if operation == "duplicate_prompts":
+            return [
+                {
+                    "path": "",
+                    "detail": (
+                        f"Prompt {item['prompt_id']} merged into "
+                        f"prompt {item['kept_id']}"
+                    ),
+                }
+                for item in described
+            ]
+        return [
+            {"path": "", "detail": f"Removed: {item.get('text') or item['prompt_id']}"}
+            for item in described
+        ]
+
+
+def backup_note(backup):
+    """The status line's backup part: the file name, or that there is none."""
+    return f"Safety backup {backup}" if backup else NO_BACKUP
+
+
+def _fail_job(job, code, message):
+    """End ``job`` failed with ``message`` (one error row) and its code.
+
+    The code is also the job's ``scope["failure"]``, so Activity can offer
+    Review again for a plan the library overtook.
+    """
+    if code:
+        job.scope["failure"] = code
+    job.record("errors", {"path": "", "detail": message}, f"! {message}")
+    job.update(status_line=message)
+    job.publish({"type": "error", "code": code, "message": message})
+    job.finish("failed")

py/api/maintenance_plans.py

@@ -0,0 +1,138 @@
+"""The reviewed-plan store behind maintenance previews (#249 System S6).
+
+A preview issues a plan: its operation, the fingerprint of exactly what was
+reviewed, the payload an apply needs (target ids, the sources it judged) and
+the identity of the database it describes. Everything is held here, in
+server memory, under a single-use token (``secrets.token_urlsafe(32)``); the
+client only ever sees the token and the public plan. Plans expire after
+``ttl`` seconds and are gone after a restart.
+
+The store keeps at most ``max_plans`` plans and ``max_bytes`` of payload
+(measured as compact JSON). A plan larger than ``max_bytes`` is refused with
+``ScopeTooLarge``: it is never cut down to fit, since an apply must do
+exactly what was reviewed. A new plan that fits makes room by dropping the
+oldest ones, which then read as expired.
+
+A consumed token is remembered (the last ``MAX_USED``) with the job it
+started, so a second apply of it is told which job ran it.
+"""
+
+import json
+import secrets
+import time
+from collections import OrderedDict
+from dataclasses import dataclass, field
+
+
+class PlanExpired(Exception):
+    """No live plan has the token: unknown, expired, dropped or another operation's."""
+
+
+class PlanUsed(Exception):
+    """The token was already applied; ``job_id`` is the job that applied it."""
+
+    def __init__(self, job_id):
+        super().__init__("This plan was already applied")
+        self.job_id = job_id
+
+
+class ScopeTooLarge(Exception):
+    """The plan's payload exceeds the store's byte budget."""
+
+
+@dataclass
+class StoredPlan:
+    """One reviewed plan, as only the server sees it."""
+
+    operation: str
+    fingerprint: str
+    payload: dict
+    db_identity: tuple
+    expires_at: float  # wall-clock seconds since the epoch, for the response
+    deadline: float = field(repr=False)  # on the store's monotonic clock
+    size: int = field(repr=False)
+
+
+def _payload_size(payload):
+    return len(json.dumps(payload, separators=(",", ":"), default=str))
+
+
+class PlanStore:
+    """Reviewed maintenance plans under single-use tokens."""
+
+    MAX_USED = 64  # consumed tokens remembered for plan-used answers
+
+    def __init__(
+        self,
+        ttl=900,
+        max_plans=8,
+        max_bytes=16 * 2**20,
+        *,
+        clock=time.monotonic,
+        wall_clock=time.time,
+    ):
+        self.ttl = ttl
+        self.max_plans = max_plans
+        self.max_bytes = max_bytes
+        self._clock = clock
+        self._wall_clock = wall_clock
+        self._plans = OrderedDict()  # token -> StoredPlan, oldest first
+        self._used = OrderedDict()  # token -> job id, oldest first
+
+    def issue(self, operation, fingerprint, payload, db_identity) -> str:
+        """Hold a plan and return its token; ScopeTooLarge when it cannot fit."""
+        size = _payload_size(payload)
+        if size > self.max_bytes:
+            raise ScopeTooLarge(f"The plan needs {size} bytes")
+        self._drop_expired()
+        while self._plans and (
+            len(self._plans) >= self.max_plans
+            or self._held_bytes() + size > self.max_bytes
+        ):
+            self._plans.popitem(last=False)
+        token = secrets.token_urlsafe(32)
+        self._plans[token] = StoredPlan(
+            operation=operation,
+            fingerprint=fingerprint,
+            payload=payload,
+            db_identity=tuple(db_identity),
+            expires_at=self._wall_clock() + self.ttl,
+            deadline=self._clock() + self.ttl,
+            size=size,
+        )
+        return token
+
+    def peek(self, token, operation=None) -> StoredPlan:
+        """The live plan of ``token``, left in place; raises PlanUsed or PlanExpired."""
+        if not isinstance(token, str):
+            raise PlanExpired("No such plan")
+        if token in self._used:
+            raise PlanUsed(self._used[token])
+        plan = self._plans.get(token)
+        if plan is None or (operation is not None and plan.operation != operation):
+            raise PlanExpired("No such plan")
+        if self._clock() > plan.deadline:
+            del self._plans[token]
+            raise PlanExpired("The plan expired")
+        return plan
+
+    def consume(self, token, operation=None, *, job_id=None) -> StoredPlan:
+        """Take the plan of ``token`` once; later calls raise PlanUsed(job_id)."""
+        plan = self.peek(token, operation)
+        del self._plans[token]
+        self._used[token] = job_id
+        while len(self._used) > self.MAX_USED:
+            self._used.popitem(last=False)
+        return plan
+
+    def discard(self, token):
+        """Forget a plan that can no longer apply (its database was replaced)."""
+        self._plans.pop(token, None)
+
+    def _held_bytes(self):
+        return sum(plan.size for plan in self._plans.values())
+
+    def _drop_expired(self):
+        now = self._clock()
+        for token in [t for t, plan in self._plans.items() if now > plan.deadline]:
+            del self._plans[token]

py/api/restore_plans.py

@@ -0,0 +1,146 @@
+"""Reviewed restores: staged uploads held under single-use tokens (#249 S8).
+
+A restore preview stages the upload (``database/restore_stage.py``) and
+keeps it here under a ``secrets.token_urlsafe(32)`` token with the live
+library's fingerprint and the database identity it was reviewed against.
+``take`` hands the stage to the restore job exactly once; a second apply of
+the token names that job (``PlanUsed``). An expired, discarded or unknown
+token raises ``PlanExpired``; its stage folder is removed. A restart forgets
+every token (the startup sweep removes the folders).
+
+At most ``max_stages`` stages are held. Bytes are bounded by free disk space
+(the upload is refused when the disk has no room, and held stages use that
+disk), not by a fixed budget. A stage being applied belongs to its job and is
+never evicted or counted.
+
+The store is only read and changed on the event loop (it has no lock). Its
+entries own stage folders, whose removal is blocking: every method that
+drops an entry returns it (or keeps it in ``take_doomed``), and the caller
+removes the folder in the executor (``HeldRestore.staged.discard``).
+"""
+
+import secrets
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional
+
+from .maintenance_plans import PlanExpired, PlanUsed
+
+STAGE_TTL_SECONDS = 900
+MAX_STAGES = 2
+_USED_KEPT = 32  # applied tokens remembered for plan-used answers
+
+
+class TooManyStages(Exception):
+    """Every stage slot is held by a reviewed restore."""
+
+
+@dataclass
+class HeldRestore:
+    staged: Any  # database.restore_stage.StagedRestore
+    fingerprint: str
+    db_identity: Any
+    live: Dict[str, int]
+    expires_at: float
+
+
+class RestorePlanStore:
+    def __init__(
+        self,
+        clock: Optional[Callable[[], float]] = None,
+        ttl: float = STAGE_TTL_SECONDS,
+        max_stages: int = MAX_STAGES,
+    ):
+        self._ttl = ttl
+        self._max = max_stages
+        self._clock = clock or time.time
+        self._held: Dict[str, HeldRestore] = {}
+        self._used: Dict[str, str] = {}
+        self._doomed: List[HeldRestore] = []
+
+    @property
+    def ttl(self) -> float:
+        return self._ttl
+
+    def now(self) -> float:
+        return self._clock()
+
+    def __len__(self):
+        return len(self._held)
+
+    def full(self) -> bool:
+        return len(self._held) >= self._max
+
+    def issue(self, staged, fingerprint, db_identity, live) -> str:
+        """Hold ``staged`` and return its token; TooManyStages when full."""
+        if self.full():
+            raise TooManyStages()
+        token = secrets.token_urlsafe(32)
+        self._held[token] = HeldRestore(
+            staged=staged,
+            fingerprint=fingerprint,
+            db_identity=db_identity,
+            live=dict(live),
+            expires_at=self._clock() + self._ttl,
+        )
+        return token
+
+    def peek(self, token) -> HeldRestore:
+        if token in self._used:
+            raise PlanUsed(self._used[token])
+        held = self._held.get(token)
+        if held is None:
+            raise PlanExpired()
+        if held.expires_at <= self._clock():
+            self._doomed.append(self._held.pop(token))
+            raise PlanExpired()
+        return held
+
+    def take(self, token, job_id) -> HeldRestore:
+        """Hand the held stage to the job applying it (single use)."""
+        held = self.peek(token)
+        del self._held[token]
+        self._used[token] = job_id
+        while len(self._used) > _USED_KEPT:
+            self._used.pop(next(iter(self._used)))
+        return held
+
+    def give_back(self, token, held) -> bool:
+        """Hold a taken stage again under its token (its job did not apply it).
+
+        False, holding nothing, when the review expired meanwhile or its slot
+        was reused (the store is full): the caller then discards the stage.
+        """
+        if held.expires_at <= self._clock() or self.full():
+            return False
+        self._used.pop(token, None)
+        self._held[token] = held
+        return True
+
+    def entry(self, token) -> Optional[HeldRestore]:
+        """The held entry, expired or not (for the response that issued it)."""
+        return self._held.get(token)
+
+    def pop(self, token) -> Optional[HeldRestore]:
+        """Drop the token; its entry (to discard) or None when it was not held."""
+        return self._held.pop(token, None)
+
+    def pop_expired(self) -> List[HeldRestore]:
+        """Drop every expired entry; them, with any ``peek`` found expired."""
+        now = self._clock()
+        expired = [t for t, held in self._held.items() if held.expires_at <= now]
+        return [self._held.pop(token) for token in expired] + self.take_doomed()
+
+    def pop_all(self) -> List[HeldRestore]:
+        """Drop every entry (the library was replaced); them, to discard."""
+        held = list(self._held.values()) + self.take_doomed()
+        self._held.clear()
+        return held
+
+    def take_doomed(self) -> List[HeldRestore]:
+        doomed, self._doomed = self._doomed, []
+        return doomed
+
+    def next_expiry(self) -> Optional[float]:
+        """When the soonest held entry expires (clock time), or None."""
+        return min((held.expires_at for held in self._held.values()), default=None)

py/api/review.py

@@ -0,0 +1,731 @@
+"""Needs review routes (#249 E3): the pending queue, item detail, decisions.
+
+``GET /prompt_manager/review/items`` lists pending items oldest first behind
+an HMAC keyset cursor bound to the storage epoch only (a restore makes an
+old cursor stale; a decision or a new item does not, because the
+``(created_at, id)`` keyset stays ordered when items leave or are appended);
+``total`` is the exact pending count. ``GET .../items/{id}`` adds the
+candidates and the dependency fingerprint. ``POST .../items/{id}/decision``
+records one explicit decision: Apply links the chosen sampler's pair only
+when the capture is the item's bytes, the current file still hashes to them,
+the evidence they yield is unchanged and the ingester's compatible-only rules
+allow it; Leave unresolved links nothing.
+
+Targets are formatted from the recorded spelling against the current roots
+(no file access beyond the roots' real paths); a file under no current root
+is ``unavailable``. Responses carry no server path, no locator and no
+exception text.
+"""
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import os
+import re
+import urllib.parse
+
+from aiohttp import web
+
+from .annotations import _HEX64, _TOKEN, _UUID, _capture_error, _error
+from .images import media_thumbnail_url
+from .inspection_service import VIDEO_EXTENSIONS
+from .job_routes import busy_response
+from .jobs import JobBusy
+from .prompts import bad_request
+
+try:
+    from ...database.library import display_title
+    from ...database.library_commands import LibraryCommandError
+    from ...database.review_decisions import ReviewCommandError
+    from ...utils.media_capture import CaptureError
+    from ...utils.review_capture import (
+        captured_review,
+        item_profile,
+        review_evidence,
+    )
+except ImportError:
+    from database.library import display_title
+    from database.library_commands import LibraryCommandError
+    from database.review_decisions import ReviewCommandError
+    from utils.media_capture import CaptureError
+    from utils.review_capture import captured_review, item_profile, review_evidence
+
+ITEMS_URL = "/prompt_manager/review/items"
+DEFAULT_LIMIT = 40
+MAX_LIMIT = 40
+MAX_CURSOR = 4096
+MAX_BODY_BYTES = 64 * 1024
+# The serialized detail stays under this; past it the detail is ``limited``.
+MAX_DETAIL_BYTES = 8 * 1024 * 1024
+UNRESOLVED = "unresolved"
+_DECISION_FIELDS = frozenset(
+    {
+        "expected_epoch",
+        "expected_revision",
+        "capture_token",
+        "sha256",
+        "dependency_fingerprint",
+        "choice",
+    }
+)
+_CURSOR_SECRET = os.urandom(32)
+# The real path of a spelling; module-level so a test can fake a junction.
+_realpath = os.path.realpath
+_LIMIT = re.compile(r"[0-9]{1,3}")
+_NO_STORE = {"Cache-Control": "no-store"}
+
+_STATUS = {
+    "review-missing": 404,
+    "review-conflict": 409,
+    "association-conflict": 409,
+    "file-changed": 409,
+    "storage-changed": 409,
+    "source-changed": 409,
+    "capture-expired": 409,
+}
+_MESSAGES = {
+    "review-missing": "This review item no longer exists. Reload the queue.",
+    "review-conflict": (
+        "This item was decided or changed since it was opened. Reload the queue."
+    ),
+    "association-conflict": (
+        "This image is already linked to another prompt or negative, so this "
+        "sampler path cannot be attached safely. The existing links were "
+        "preserved."
+    ),
+    "dependencies-changed": (
+        "The image's saved links changed since this item was opened. Reopen it "
+        "to see the current association."
+    ),
+    "file-changed": (
+        "The file changed since it was reviewed. A metadata scan adds its new "
+        "bytes as a new item."
+    ),
+    "storage-changed": "Prompt storage was restored; reload the review queue.",
+    "source-changed": (
+        "The source changed. Refresh the image collection before reviewing this "
+        "file."
+    ),
+    "capture-expired": "The preview expired. Open the item again.",
+    "other-file": "The preview belongs to another file. Open the item again.",
+    "evidence-changed": (
+        "This file's metadata no longer gives the evidence that was reviewed. "
+        "Reload the queue."
+    ),
+}
+
+
+_DEFAULT_MESSAGE = "The decision could not be saved. Reload the queue."
+
+
+def _coded(code: str, message_key: str | None = None, **extra) -> web.Response:
+    message = _MESSAGES.get(message_key or code, _DEFAULT_MESSAGE)
+    return _error(_STATUS.get(code, 409), code, message, **extra)
+
+
+def _failed() -> web.Response:
+    return _error(500, "review-failed", "The review queue could not be read.")
+
+
+def format_review_target(spelled_path, locator, real_roots, *, pathmod=os.path):
+    """``(root_index, relative)`` of the first root that lists the file, or None.
+
+    ``spelled_path`` is the file's recorded spelling, ``locator`` its folded
+    identity and ``real_roots`` ``(index, realpath)`` pairs. The relative
+    path keeps the recorded spelling (a Windows locator is case-folded, a
+    listing target is not) and must fold back to the locator.
+    """
+    sep = pathmod.sep
+    for index, real_root in real_roots:
+        head = spelled_path[: len(real_root)]
+        if pathmod.normcase(head) != pathmod.normcase(real_root):
+            continue
+        rest = spelled_path[len(real_root) :]
+        if not real_root.endswith(sep):
+            if not rest.startswith(sep):
+                continue
+            rest = rest[1:]
+        parts = rest.split(sep)
+        if any(
+            part in ("", ".", "..") or "/" in part or "\\" in part or ":" in part
+            for part in parts
+        ):
+            continue
+        if pathmod.normcase(pathmod.join(real_root, *parts)) != locator:
+            continue
+        return index, "/".join(parts)
+    return None
+
+
+class _StaleCursor(ValueError):
+    """A well-formed cursor this process cannot verify (e.g. after a restart)."""
+
+
+def _encode_cursor(epoch: str, key: tuple) -> str:
+    payload = json.dumps(
+        {"v": 2, "e": epoch, "k": list(key)},
+        separators=(",", ":"),
+        ensure_ascii=True,
+    ).encode()
+    signature = hmac.new(_CURSOR_SECRET, payload, hashlib.sha256).digest()
+    return base64.urlsafe_b64encode(signature + payload).decode().rstrip("=")
+
+
+def _decode_cursor(token: str) -> tuple:
+    """``(epoch, (created_at, id))`` of a cursor.
+
+    ``ValueError`` when malformed; :class:`_StaleCursor` when well-formed but
+    signed by another secret (the per-process secret changes on every start,
+    so an open page's cursor is stale after a restart, not forged).
+    """
+    try:
+        if len(token) > MAX_CURSOR:
+            raise ValueError()
+        raw = base64.b64decode(
+            token + "=" * (-len(token) % 4), altchars=b"-_", validate=True
+        )
+        signature, payload = raw[:32], raw[32:]
+        if len(signature) != 32 or not payload:
+            raise ValueError()
+        expected = hmac.new(_CURSOR_SECRET, payload, hashlib.sha256).digest()
+        if not hmac.compare_digest(signature, expected):
+            raise _StaleCursor("This page of the queue is out of date")
+        data = json.loads(payload)
+        key = data["k"]
+        if (
+            data["v"] != 2
+            or not isinstance(data["e"], str)
+            or not isinstance(key, list)
+            or len(key) != 2
+            or not all(isinstance(part, str) for part in key)
+        ):
+            raise ValueError()
+        return data["e"], tuple(key)
+    except _StaleCursor:
+        raise
+    except (ValueError, KeyError, TypeError, UnicodeError, binascii.Error):
+        raise ValueError("Invalid review cursor; reload the queue") from None
+
+
+def _limit(value):
+    if value is None:
+        return DEFAULT_LIMIT
+    if _LIMIT.fullmatch(value) is None or not 1 <= int(value) <= MAX_LIMIT:
+        return None
+    return int(value)
+
+
+def _side_text(side) -> str | None:
+    if isinstance(side, dict) and isinstance(side.get("text"), str):
+        return side["text"]
+    return None
+
+
+def _workable(candidate: dict) -> bool:
+    return (
+        candidate.get("state") == "resolved"
+        and _side_text(candidate.get("positive")) is not None
+        and _side_text(candidate.get("negative")) is not None
+    )
+
+
+def _side_label(titles: dict, side, empty: str) -> str:
+    """The Library title of the side's saved prompt, else its first line."""
+    text = _side_text(side)
+    if text is None:
+        return empty
+    stored = side.get("storage_text")
+    stored = stored if isinstance(stored, str) else text
+    return display_title(titles.get(stored, ()), text) or empty
+
+
+REVIEW_DECISION_LEASE = "Needs review decision"
+
+
+class ReviewRoutesMixin:
+    """The Needs review queue over E1's schema and E2's recorded items."""
+
+    def _register_review_routes(self, routes: web.RouteTableDef) -> None:
+        routes.get(ITEMS_URL)(self.list_review_items)
+        routes.get(ITEMS_URL + "/{item_id}")(self.get_review_item)
+        routes.post(ITEMS_URL + "/{item_id}/decision")(self.decide_review_item)
+
+    # -- shared ----------------------------------------------------------------
+
+    def _review_roots(self):
+        """``(roots, real_roots)``: the current gallery roots and their realpaths.
+
+        Blocking (it lists the roots and resolves them): call it on a worker.
+        """
+        roots = list(self._get_all_output_dirs())
+        return roots, [(i, _realpath(str(root))) for i, root in enumerate(roots)]
+
+    def _review_view(self, row: dict, roots, real_roots) -> dict:
+        """The public ReviewItem of one stored row (no path, no locator)."""
+        found = format_review_target(row["spelled_path"], row["locator"], real_roots)
+        target = url = thumbnail_url = None
+        if found is not None:
+            index, relative = found
+            target = {
+                "root_index": index,
+                "root_scope": self._gallery_root_scope(roots[index], index),
+                "path": relative,
+            }
+            # The Images listing's media URL for the same file (formatting only).
+            url = (
+                "/prompt_manager/images/serve/"
+                f"{urllib.parse.quote(relative, safe='/')}?root={index}"
+                f"&root_scope={target['root_scope']}"
+            )
+            # The Images listing's thumbnail, when one exists (one stat).
+            thumbnail_url = media_thumbnail_url(
+                roots[index], relative, index, root_scope=target["root_scope"]
+            )
+        filename = os.path.basename(row["spelled_path"])
+        return {
+            "id": row["id"],
+            "state": row["state"],
+            "revision": row["revision"],
+            "created_at": row["created_at"],
+            "filename": filename,
+            "target": target,
+            "unavailable": target is None,
+            "candidate_count": row["candidate_count"],
+            "limited": row["limited"],
+            "url": url,
+            "thumbnail_url": thumbnail_url,
+            "is_video": os.path.splitext(filename)[1].lower() in VIDEO_EXTENSIONS,
+        }
+
+    @staticmethod
+    def _review_image_path(row: dict, roots, target) -> str:
+        """The path the scan and the monitor link this file under."""
+        if target is None:
+            return row["spelled_path"]
+        root = roots[target["root_index"]]
+        return os.path.join(str(root), *target["path"].split("/"))
+
+    # -- queue -----------------------------------------------------------------
+
+    async def list_review_items(self, request: web.Request) -> web.Response:
+        """GET ``?limit=1..40&cursor=``: one page of pending items."""
+        limit = _limit(request.query.get("limit"))
+        if limit is None:
+            return bad_request(f"limit must be an integer from 1 to {MAX_LIMIT}")
+        bound = None
+        cursor = request.query.get("cursor")
+        if cursor:
+            try:
+                bound = _decode_cursor(cursor)
+            except _StaleCursor:
+                return await self._stale_cursor()
+            except ValueError as exc:
+                return bad_request(str(exc))
+        try:
+            page, views = await self._run_in_executor(
+                self._review_page, limit, bound[1] if bound else None
+            )
+        except Exception:
+            self.logger.exception("Review queue read failed")
+            return _failed()
+        if bound is not None and bound[0] != page["epoch"]:
+            return _coded("storage-changed", library_epoch=page["epoch"])
+        items = page["items"]
+        next_cursor = None
+        if page["more"] and items:
+            last = items[-1]
+            next_cursor = _encode_cursor(
+                page["epoch"], (last["created_at"], last["id"])
+            )
+        return web.json_response(
+            {
+                "success": True,
+                "library_epoch": page["epoch"],
+                # F3: the queue version the change stream's ``ready`` names.
+                "review_revision": page["revision"],
+                "total": page["total"],
+                "items": views,
+                "next_cursor": next_cursor,
+            },
+            headers=_NO_STORE,
+        )
+
+    async def _stale_cursor(self) -> web.Response:
+        """409 ``review-conflict`` with the current total: reload the queue."""
+        try:
+            page = await self._run_in_executor(self.db.review_queue_page, limit=1)
+        except Exception:
+            self.logger.exception("Review queue read failed")
+            return _failed()
+        return _coded(
+            "review-conflict", total=page["total"], library_epoch=page["epoch"]
+        )
+
+    def _review_page(self, limit: int, after):
+        """Worker thread: one queue page and the public views of its items."""
+        page = self.db.review_queue_page(limit=limit, after=after)
+        roots, real_roots = self._review_roots()
+        return page, [
+            self._review_view(row, roots, real_roots) for row in page["items"]
+        ]
+
+    # -- detail ----------------------------------------------------------------
+
+    async def get_review_item(self, request: web.Request) -> web.Response:
+        """GET one item with its candidates and dependency fingerprint."""
+        try:
+            read = await self._run_in_executor(
+                self._review_detail, request.match_info["item_id"]
+            )
+        except Exception:
+            self.logger.exception("Review item read failed")
+            return _failed()
+        if read is None:
+            return _coded("review-missing")
+        item, view, fingerprint, candidates = read
+        detail = {
+            "success": True,
+            "library_epoch": item["epoch"],
+            **view,
+            "candidates": candidates,
+            "dependency_fingerprint": fingerprint,
+            "sha256": item["sha256"],
+            "total": item["total"],
+        }
+        if len(json.dumps(detail).encode("utf-8")) > MAX_DETAIL_BYTES:
+            detail = {**detail, "candidates": [], "limited": True}
+        return web.json_response(detail, headers=_NO_STORE)
+
+    def _review_detail(self, item_id: str):
+        """Worker thread: ``(item, view, fingerprint, candidates)`` or None."""
+        item = self.db.review_item(item_id)
+        if item is None:
+            return None
+        roots, real_roots = self._review_roots()
+        view = self._review_view(item, roots, real_roots)
+        image_path = self._review_image_path(item, roots, view["target"])
+        aliases, _known = physical_spellings(self.db, image_path, item["locator"])
+        fingerprint = self.db.review_dependency_fingerprint(image_path, aliases)
+        return item, view, fingerprint, self._review_candidates(item)
+
+    def _review_candidates(self, item: dict) -> list:
+        """The detail's candidates: role texts, a label and selectability."""
+        if item["limited"]:
+            return []
+        candidates = [
+            c for c in item["evidence"].get("candidates", []) if isinstance(c, dict)
+        ]
+        texts = set()
+        for candidate in candidates:
+            for role in ("positive", "negative"):
+                side = candidate.get(role)
+                if isinstance(side, dict):
+                    for key in ("text", "storage_text"):
+                        if isinstance(side.get(key), str):
+                            texts.add(side[key])
+        titles = self.db.stored_prompt_titles(texts)
+        rows = []
+        for candidate in candidates:
+            positive = _side_text(candidate.get("positive"))
+            negative = _side_text(candidate.get("negative"))
+            label = (
+                _side_label(titles, candidate.get("positive"), "No positive")
+                + " / "
+                + _side_label(titles, candidate.get("negative"), "No negative")
+            )
+            rows.append(
+                {
+                    "hash": candidate.get("hash"),
+                    "sampler_id": candidate.get("sampler_id"),
+                    "state": "resolved" if _workable(candidate) else "unresolved",
+                    "reason": candidate.get("reason") or "",
+                    "label": label,
+                    "positive": {"text": positive} if positive is not None else None,
+                    "negative": {"text": negative} if negative is not None else None,
+                }
+            )
+        return rows
+
+    # -- decision --------------------------------------------------------------
+
+    async def decide_review_item(self, request: web.Request) -> web.Response:
+        """POST one explicit decision on one pending item.
+
+        The decision runs under a registry lease (#249 S8): it is refused
+        (409 ``busy``) while a restore or another ``exclusive`` job runs, and
+        a restore waits for decisions already running before it switches the
+        database. Decisions never refuse one another or a scan.
+        """
+        try:
+            async with self._jobs.lease(REVIEW_DECISION_LEASE):
+                return await self._decide_review_item(request)
+        except JobBusy as busy:
+            return busy_response(busy)
+
+    async def _decide_review_item(self, request: web.Request) -> web.Response:
+        data, error = await self._read_json_body(request, max_bytes=MAX_BODY_BYTES)
+        if error is not None:
+            return error
+        guards, error = _decision_guards(data)
+        if error is not None:
+            return error
+        try:
+            item = await self._run_in_executor(
+                self.db.review_item, request.match_info["item_id"]
+            )
+        except Exception:
+            self.logger.exception("Review item read failed")
+            return _failed()
+        if item is None:
+            return _coded("review-missing")
+        choice = guards["choice"]
+        candidate = None
+        if choice != UNRESOLVED:
+            candidate = next(
+                (
+                    c
+                    for c in item["evidence"].get("candidates", [])
+                    if isinstance(c, dict) and c.get("hash") == choice
+                ),
+                None,
+            )
+            if candidate is None or item["limited"]:
+                return bad_request("choice is not one of this item's candidates")
+            if not _workable(candidate):
+                return bad_request("This sampler path cannot be applied")
+            if guards["capture_token"] is None:
+                return bad_request("Apply needs a capture of the file")
+        verified = None
+        if guards["capture_token"] is not None:
+            verified, error = await self._verified_review_capture(
+                item, guards, need_metadata=candidate is not None
+            )
+            if error is not None:
+                return error
+        elif guards["sha256"] != item["sha256"]:
+            return bad_request("sha256 does not match the item")
+        return await self._record_decision(item, guards, candidate, verified)
+
+    async def _verified_review_capture(self, item, guards, *, need_metadata):
+        """``((capture, facts, image_path, metadata), None)`` or ``(None, error)``.
+
+        The capture must be the item's file and bytes, under the expected
+        epoch and a current root; the current file must re-hash to the same
+        bytes; for Apply, the capture's metadata must still yield exactly the
+        reviewed evidence.
+        """
+        store = self._captures
+        capture = store.get(guards["capture_token"]) if store is not None else None
+        if capture is None:
+            return None, _coded("capture-expired")
+        if capture.locator != item["locator"]:
+            return None, _coded("capture-expired", "other-file")
+        if guards["sha256"] != capture.sha256:
+            return None, bad_request("sha256 does not match the preview")
+        if capture.sha256 != item["sha256"]:
+            return None, _coded("file-changed")
+        if guards["expected_epoch"] != capture.epoch:
+            current = await self._run_in_executor(self.db.get_execution_epoch)
+            return None, _coded("storage-changed", library_epoch=current)
+        try:
+            root, error = await self._run_in_executor(
+                self._scoped_root, capture.root_index, capture.scope
+            )
+            if error is not None:
+                return None, error
+            read = await self._run_in_executor(
+                _verify_and_read, store, capture, item, root, need_metadata
+            )
+        except CaptureError as exc:
+            return None, _capture_error(exc)
+        if read is None:
+            return None, _coded("source-changed")
+        relative, facts, captured = read
+        if facts.locator != item["locator"]:
+            return None, _coded("capture-expired", "other-file")
+        if facts.sha256 != item["sha256"]:
+            return None, _coded("file-changed")
+        metadata = None
+        if need_metadata:
+            if captured is None or not _candidate_still_offered(
+                captured[1], guards["choice"]
+            ):
+                return None, _coded("review-conflict", "evidence-changed")
+            metadata = captured[0]
+        image_path = os.path.join(str(root), *relative.split("/"))
+        return (capture, facts, image_path, metadata), None
+
+    def _decide_sync(self, item, guards, candidate, verified):
+        """Worker thread: resolve the file's spellings, decide, build the view.
+
+        Returns ``(result, view)``; a refusal raises with ``exc.view`` set.
+        """
+        _capture, facts, image_path, metadata = verified or (None, None, None, None)
+        aliases, known = (), None
+        if candidate is not None:
+            aliases, known = physical_spellings(self.db, image_path, item["locator"])
+        try:
+            result = self.db.decide_review_item(
+                item_id=item["id"],
+                expected_epoch=guards["expected_epoch"],
+                expected_revision=guards["expected_revision"],
+                # The bytes the re-hash proved, or the body's for Leave unresolved.
+                sha256=facts.sha256 if facts is not None else guards["sha256"],
+                outcome="selected" if candidate is not None else UNRESOLVED,
+                candidate=candidate,
+                image_path=image_path,
+                metadata=metadata,
+                expected_fingerprint=guards["dependency_fingerprint"],
+                aliases=aliases,
+                known_rows=known,
+            )
+        except ReviewCommandError as exc:
+            if exc.item is not None:
+                roots, real_roots = self._review_roots()
+                exc.view = self._review_view(exc.item, roots, real_roots)
+            raise
+        roots, real_roots = self._review_roots()
+        return result, self._review_view(result["item"], roots, real_roots)
+
+    async def _record_decision(self, item, guards, candidate, verified):
+        capture = verified[0] if verified else None
+        try:
+            result, view = await self._run_in_executor(
+                self._decide_sync, item, guards, candidate, verified
+            )
+        except ReviewCommandError as exc:
+            return self._decision_refused(exc)
+        except LibraryCommandError as exc:
+            return _coded(exc.code, library_epoch=exc.epoch)
+        except Exception:
+            self.logger.exception("Review decision failed")
+            return _error(500, "decision-failed", "The decision could not be saved.")
+        if capture is not None:
+            # The decision used the capture; the page returns to Images.
+            self._captures.release(capture.token)
+        body = {
+            "success": True,
+            "library_epoch": guards["expected_epoch"],
+            "item": view,
+            "total": result["total"],
+        }
+        if result["pair"] is not None:
+            body["pair"] = result["pair"]
+        return web.json_response(body, headers=_NO_STORE)
+
+    def _decision_refused(self, exc: ReviewCommandError) -> web.Response:
+        extra = {"library_epoch": exc.epoch}
+        if exc.total is not None:
+            extra["total"] = exc.total
+        if exc.view is not None:
+            extra["item"] = exc.view
+        message = None
+        if exc.fingerprint is not None:
+            extra["dependency_fingerprint"] = exc.fingerprint
+        if exc.code == "association-conflict" and exc.changed:
+            message = "dependencies-changed"
+        return _coded(exc.code, message, **extra)
+
+
+def _decision_guards(data: dict):
+    """The validated decision fields, or ``(None, error)``."""
+    if set(data) != _DECISION_FIELDS:
+        return None, bad_request(
+            "Request must contain exactly " + ", ".join(sorted(_DECISION_FIELDS))
+        )
+    epoch, revision = data["expected_epoch"], data["expected_revision"]
+    if not isinstance(epoch, str) or _UUID.fullmatch(epoch) is None:
+        return None, bad_request("expected_epoch must be a canonical UUID")
+    if type(revision) is not int or revision < 0:
+        return None, bad_request("expected_revision must be a non-negative integer")
+    token = data["capture_token"]
+    if token is not None and (
+        not isinstance(token, str) or _TOKEN.fullmatch(token) is None
+    ):
+        return None, bad_request("Invalid capture token")
+    for name in ("sha256", "dependency_fingerprint"):
+        value = data[name]
+        if not isinstance(value, str) or _HEX64.fullmatch(value) is None:
+            return None, bad_request(
+                f"{name} must be 64 lowercase hexadecimal characters"
+            )
+    choice = data["choice"]
+    if not isinstance(choice, str) or (
+        choice != UNRESOLVED and _HEX64.fullmatch(choice) is None
+    ):
+        return None, bad_request("choice must be a candidate hash or unresolved")
+    return {**data}, None
+
+
+def _verify_and_read(store, capture, item, root, need_metadata: bool):
+    """Worker thread: ``(relative, facts, captured)``, or None off the root.
+
+    Formats the item's target under the capture's root (resolving the root's
+    real path), re-hashes the current file, then reads the capture and
+    resolves it with the profile the item's evidence was recorded with.
+    """
+    found = format_review_target(
+        item["spelled_path"],
+        item["locator"],
+        [(capture.root_index, _realpath(str(root)))],
+    )
+    if found is None:
+        return None
+    relative = found[1]
+    facts = store.verify(root, relative)
+    captured = None
+    if need_metadata:
+        captured = captured_review(store, capture, item_profile(item["evidence"]))
+    return relative, facts, captured
+
+
+def _same_file(spelled: str, image_path: str, locator: str) -> bool:
+    """True when ``spelled`` reaches the physical file at ``locator``."""
+    try:
+        if os.path.normcase(_realpath(spelled)) == locator:
+            return True
+        return os.path.samefile(spelled, image_path)
+    except (OSError, ValueError):
+        return False
+
+
+def physical_spellings(db, image_path: str, locator: str):
+    """``(aliases, known_rows)`` for the legacy rows of one physical file.
+
+    The roots are real paths, while the monitor links a file under the
+    directory it watches, so a symlinked or junctioned root, a ``subst`` or a
+    mapped drive spells the same file otherwise. Every row whose spelling
+    ends with the file's name (the link summaries' fallback lookup) is a
+    candidate; ``aliases`` are the candidates that resolve to ``locator``
+    (``normcase(realpath)``, as the capture forms it) or are the same file,
+    and ``known_rows`` every candidate id, so a decision can refuse a
+    same-name row it did not classify. Blocking: call it on a worker.
+    """
+    rows = db.review_same_name_rows(os.path.basename(image_path))
+    aliases = tuple(
+        spelled
+        for _row_id, spelled in rows
+        if isinstance(spelled, str)
+        and spelled != image_path
+        and _same_file(spelled, image_path, locator)
+    )
+    return tuple(dict.fromkeys(aliases)), frozenset(row_id for row_id, _ in rows)
+
+
+def _candidate_still_offered(resolution: dict, choice: str) -> bool:
+    """True when the captured bytes still offer the chosen candidate.
+
+    Only what the decision depends on is re-checked: the bytes are still
+    ``ambiguous`` and the chosen candidate (its hash covers its sampler,
+    sides and provenance) is still among their candidates. A resolver change
+    that rewords the top-level reason or reorders candidates leaves a
+    pending item applicable.
+    """
+    if not isinstance(resolution, dict) or resolution.get("state") != "ambiguous":
+        return False
+    evidence, _count, limited = review_evidence(resolution)
+    if limited:
+        return False
+    return any(c.get("hash") == choice for c in evidence.get("candidates", ()))

py/api/review_events.py

@@ -0,0 +1,171 @@
+"""Needs review change stream (#249 PR F2).
+
+``GET /prompt_manager/review/events`` is a server-sent event stream for an
+open Needs review page: ``event: ready`` when it opens, then
+``event: change`` after each committed queue change (an item the scan or the
+monitor recorded, a decision from any tab, a spelling refresh) and after a
+restore. The first notice is sent at once; notices in the next
+``COALESCE_SECONDS`` collapse into one trailing ``change`` (M9: a busy scan
+records file after file, and each event costs every open page a re-read).
+The page re-reads its queue on each ``change``; nothing polls. ``change``
+carries no data (``{}``). ``ready`` carries the queue's version
+``{library_epoch, review_revision}``, read after the stream subscribed, the
+same pair a list read answers: a page whose first read already answered that
+version skips the re-read (F3, one read per visit), and any later change is a
+``change`` event. Nothing else about the queue is pushed.
+
+A ``: keepalive`` comment every ``HEARTBEAT_SECONDS`` lets the server notice
+a closed tab (its write fails) and drop the subscription; clients ignore
+comments. Shutdown (``close_review_events``, an ``on_shutdown`` hook) ends
+every stream, and a stream asked for afterwards is a 503.
+"""
+
+import asyncio
+import json
+
+from aiohttp import web
+
+try:
+    from ...database.execution_history import subscribe_history_restore
+    from ...database.review_changes import subscribe_review_changes
+except ImportError:
+    from database.execution_history import subscribe_history_restore
+    from database.review_changes import subscribe_review_changes
+
+EVENTS_URL = "/prompt_manager/review/events"
+HEARTBEAT_SECONDS = 25
+# After a ``change``, the next one waits this long, collapsing the notices in between.
+COALESCE_SECONDS = 0.4
+_CHANGE = b"event: change\ndata: {}\n\n"
+_KEEPALIVE = b": keepalive\n\n"
+
+
+def _ready(version: dict) -> bytes:
+    data = json.dumps(version, separators=(",", ":"), sort_keys=True)
+    return f"event: ready\ndata: {data}\n\n".encode("utf-8")
+
+
+class _Stream:
+    """One open stream: a change flag set from any thread, and a close flag."""
+
+    def __init__(self, loop: asyncio.AbstractEventLoop) -> None:
+        self._loop = loop
+        self.changed = asyncio.Event()
+        self.closed = asyncio.Event()
+        self.ready = False
+
+    def wake(self) -> None:
+        """Thread-safe: mark a change (the loop may already be gone)."""
+        try:
+            self._loop.call_soon_threadsafe(self.changed.set)
+        except RuntimeError:  # the loop closed
+            pass
+
+    async def next(self, timeout: float) -> str:
+        """``change``, ``closed`` or ``idle`` (nothing within ``timeout``)."""
+        waits = {
+            asyncio.ensure_future(self.changed.wait()): "change",
+            asyncio.ensure_future(self.closed.wait()): "closed",
+        }
+        try:
+            done, _ = await asyncio.wait(
+                waits, timeout=timeout, return_when=asyncio.FIRST_COMPLETED
+            )
+        finally:
+            for waiter in waits:
+                waiter.cancel()
+        if self.closed.is_set():
+            return "closed"
+        if done:
+            self.changed.clear()
+            return "change"
+        return "idle"
+
+    async def closed_within(self, timeout: float) -> bool:
+        """Wait up to ``timeout``; true when the stream closed meanwhile."""
+        try:
+            await asyncio.wait_for(self.closed.wait(), timeout)
+        except asyncio.TimeoutError:
+            return False
+        return True
+
+
+class ReviewEventsMixin:
+    """The Needs review change stream."""
+
+    def _register_review_event_routes(self, routes: web.RouteTableDef) -> None:
+        routes.get(EVENTS_URL)(self.review_events)
+
+    def _review_streams(self) -> set:
+        streams = getattr(self, "_open_review_streams", None)
+        if streams is None:
+            streams = self._open_review_streams = set()
+        return streams
+
+    def review_stream_count(self) -> int:
+        """How many change streams have sent ``ready`` and are open (tests and
+        diagnostics): a queue change after this count moved is a ``change``
+        event on them, never part of the version ``ready`` named."""
+        return sum(1 for stream in self._review_streams() if stream.ready)
+
+    async def close_review_events(self, app) -> None:
+        """End every open stream; later requests get 503 (shutdown hook)."""
+        self._review_events_closed = True
+        for stream in list(self._review_streams()):
+            stream.closed.set()
+
+    async def _queue_version(self) -> dict:
+        """The queue version for ``ready``, read after subscribing (so a change
+        after this read is an event); ``{}`` when it cannot be read, and the
+        page then re-reads."""
+        try:
+            return await self._run_in_executor(self.db.review_queue_version)
+        except Exception:
+            self.logger.warning("Needs review version read failed", exc_info=True)
+            return {}
+
+    async def review_events(self, request: web.Request) -> web.StreamResponse:
+        if getattr(self, "_review_events_closed", False):
+            return web.json_response(
+                {"success": False, "error": "The server is shutting down."},
+                status=503,
+            )
+        stream = _Stream(asyncio.get_running_loop())
+        db_path = self.db.model.db_path
+        unsubscribers = (
+            subscribe_review_changes(db_path, stream.wake),
+            subscribe_history_restore(db_path, stream.wake),
+        )
+        streams = self._review_streams()
+        streams.add(stream)
+        response = web.StreamResponse(
+            status=200,
+            headers={
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-store",
+                "X-Accel-Buffering": "no",
+            },
+        )
+        try:
+            version = await self._queue_version()
+            await response.prepare(request)
+            await response.write(_ready(version))
+            stream.ready = True
+            while True:
+                outcome = await stream.next(HEARTBEAT_SECONDS)
+                if outcome == "closed":
+                    break
+                if outcome == "idle":
+                    await response.write(_KEEPALIVE)
+                    continue
+                await response.write(_CHANGE)
+                if await stream.closed_within(COALESCE_SECONDS):
+                    break
+            await response.write_eof()
+        except (ConnectionError, RuntimeError) as exc:  # the tab went away
+            self.logger.debug(f"Needs review stream closed ({exc})")
+        finally:
+            streams.discard(stream)
+            for unsubscribe in unsubscribers:
+                unsubscribe()
+        return response

py/api/review_recording.py

@@ -0,0 +1,399 @@
+"""Needs review recording for the output scan and the live monitor (#249).
+
+The rule (maintainer test of #284/#288): a file is queued only when its
+final outcome is ambiguous and unlinked. The strict resolver must find it
+``ambiguous``, the scan's legacy fallback (the browser parser,
+``_graph_prompt_text``) must not link it, and no saved row may link it
+already. A file the fallback links, an exact pair the ingester stored and an
+already linked file are never queued. Neither is an ambiguous file with
+nothing to choose: fewer than two of its candidates carry a prompt
+(``utils.review_capture.reviewable``); the scan reports it unresolved ("could
+not be traced") unless the inspection profile finds a choice in it.
+
+Only scans add items (maintainer ruling, 2026-10-23). The monitor's pass
+records nothing: it only removes the pending items of an output it linked.
+
+The queue heals itself: a pending item whose file is now linked (by the
+fallback, a later resolution or the monitor) is removed by the next scan
+that lists the file or by the monitor's next pass over it. The next scan
+also removes a pending item without a choice whose file is still ambiguous
+without one (``settle_untraced_review_items``), and an older version's
+item of bytes now untraced (``settle_stale_review_items``). Only an undecided item goes
+(``pending``, revision 0, no decision row); a decision is never deleted or
+changed (``settle_linked_review_items``).
+
+The scan records through ``_record_scanned_review`` (best effort: a failure
+is logged and counted), which goes through
+``utils.review_capture.record_ambiguous_file`` on the API's capture store;
+the monitor calls ``record_review_file`` from its worker thread after its
+own link. Nothing here links a file.
+
+Recording changes records, so it follows the registry's ``records``
+admission (#289). The scan records under its own ``records`` job. The
+monitor's pass lasts one file and is not a job: it is refused while a
+``records`` or ``guarded`` job runs (``deferred``), and the next scan reads
+the file again. Thumbnail work (the job and the gallery's generate and clear
+holds, kind ``thumbnails``) is ``guarded`` but only writes and removes preview
+files under ``thumbnails/`` and never touches the database, so it does not
+defer the recording (#249 S5 M7): a long rebuild no longer holds Needs review
+back for its whole run.
+"""
+
+import hashlib
+import os
+from pathlib import Path
+
+from .admin import SCAN_LOG_PREFIXES, _plural, _scan_location, _scan_roots
+from .jobs import THUMBNAILS_JOB_KIND
+
+# The kind the monitor's recording checks admission under (never registered).
+REVIEW_RECORDING_KIND = "review_recording"
+# Guarded kinds that change no records, so the recording may run beside them.
+PREVIEW_ONLY_KINDS = (THUMBNAILS_JOB_KIND,)
+# record_ambiguous_file outcomes that leave the file in the pending queue.
+QUEUED_OUTCOMES = ("recorded", "limited", "duplicate")
+NEW_OUTCOMES = ("recorded", "limited")
+
+try:
+    from ...utils import review_capture
+    from ...utils.review_capture import record_ambiguous_file
+except ImportError:
+    from utils import review_capture
+    from utils.review_capture import record_ambiguous_file
+
+# Untraced files remembered per process so a rescan of an unchanged file does
+# not run the inspection profile again (oldest forgotten first). A plain dict
+# of 16-byte digests (the locator, and its size, mtime_ns and item version):
+# measured at 8.6 MiB with 65,536 entries (tracemalloc, CPython 3.14).
+MAX_UNTRACED_MEMORY = 65_536
+
+
+def _digest(text: str) -> bytes:
+    data = text.encode("utf-8", "surrogatepass")
+    return hashlib.blake2b(data, digest_size=16).digest()
+
+
+def _memory_key(locator: str) -> bytes:
+    """A 16-byte digest of ``locator`` (the untraced memory's key)."""
+    return _digest(locator)
+
+
+# The scan log's reason for items that leave the queue with nothing to choose.
+NOTHING_TO_CHOOSE = "nothing to choose"
+
+
+class ReviewRecordingMixin:
+    """Record the scan's and the monitor's ambiguous files for Needs review."""
+
+    def _record_scanned_review(self, media_file, roots, review=None, scanned=None):
+        """Record one ambiguous, unlinked scanned file (logged and counted).
+
+        ``scanned`` is the scan's ``(metadata, inspection_resolution)``.
+        """
+        try:
+            outcome = self._record_review_sync(
+                media_file, roots, review, inspection=True, scanned=scanned
+            )
+        except Exception:
+            self.logger.warning(
+                f"{media_file.name} could not be added to Needs review",
+                exc_info=True,
+            )
+            if review is not None:
+                review["errors"] += 1
+            return
+        if review is None:
+            return
+        if outcome in NEW_OUTCOMES:
+            review["added"] += 1
+        if outcome in QUEUED_OUTCOMES:
+            review["queued"] += 1
+
+    def _record_review_sync(
+        self, media_file, roots, review=None, inspection=False, scanned=None
+    ):
+        """``record_ambiguous_file`` for a file under one of ``roots`` (blocking).
+
+        ``inspection`` (the scan only) lets a file without a choice under the
+        default profile be recorded from the inspection profile's choices.
+        An ``untraced`` file (its captured bytes offer nothing to choose) also
+        loses its pending items that offer nothing either.
+        """
+        located = self._review_location(media_file, roots)
+        if located is None:
+            return "skipped"
+        root, index, relative, _spelled = located
+        outcome = record_ambiguous_file(
+            self.db,
+            self._capture_store(),
+            Path(root),
+            index,
+            relative,
+            inspection=inspection,
+            scanned=scanned,
+        )
+        if outcome == "untraced":
+            self._settle_untraced_reviews([media_file], roots, review)
+        return outcome
+
+    def _untraced_scan_outcome(self, media_file, roots, canonical, review=None):
+        """The scan status of an unlinked file the default profile left
+        ambiguous without a choice (blocking).
+
+        ``ambiguous`` when the inspection profile offers a choice: the file is
+        recorded for review from that profile (never linked), or ``unchanged``
+        when a saved row links it already. Otherwise ``unresolved``, and its
+        pending items without a choice leave the queue. The profile runs at
+        most once per file state: not for bytes already queued (or decided)
+        at the file's current size and ``mtime_ns`` under the version that
+        its records depend on, and not again for a state it already found
+        untraced in this process.
+        """
+        try:
+            choice = self._inspection_choice(media_file, roots, canonical)
+        except Exception:
+            # One bad file never stops the scan: it stays "could not be traced".
+            self.logger.warning(
+                f"{media_file.name} could not be inspected for Needs review",
+                exc_info=True,
+            )
+            if review is not None:
+                review["errors"] += 1
+            return "unresolved"
+        if choice is None:
+            self._settle_untraced_reviews([media_file], roots, review)
+            self._settle_stale_reviews(media_file, roots, canonical, review)
+            return "unresolved"
+        if self._review_file_linked(media_file, roots):
+            return "unchanged"
+        self._record_scanned_review(media_file, roots, review, scanned=choice)
+        return "ambiguous"
+
+    def _inspection_choice(self, media_file, roots, canonical):
+        """``(canonical, resolution_or_None)`` when the file offers a choice.
+
+        The resolution is None when the file's current state is already in
+        the queue (so the profile did not run). None when it offers none.
+        """
+        if canonical is None:
+            return None
+        version = review_capture.inspection_review_version(canonical)
+        located = self._review_location(media_file, roots)
+        if version is None or located is None:
+            return None
+        locator = os.path.normcase(located[3])
+        try:
+            facts = os.lstat(located[3])
+        except OSError:
+            facts = None
+        state = None
+        if facts is not None:
+            state = _digest(f"{facts.st_size}:{facts.st_mtime_ns}:{version}")
+            if self.db.review_decided_at(
+                locator, facts.st_size, facts.st_mtime_ns
+            ) or self.db.review_fingerprint_queued(
+                locator, facts.st_size, facts.st_mtime_ns, version
+            ):
+                return canonical, None
+        memory = self._untraced_memory()
+        key = _memory_key(locator)
+        if state is not None and memory.get(key) == state:
+            return None
+        resolution = review_capture.inspection_choice(canonical)
+        if resolution is not None:
+            memory.pop(key, None)
+            return canonical, resolution
+        if state is not None:
+            memory.pop(key, None)  # re-inserted last: the newest state
+            memory[key] = state
+            while len(memory) > MAX_UNTRACED_MEMORY:
+                del memory[next(iter(memory))]
+        return None
+
+    def _settle_stale_reviews(self, media_file, roots, canonical, review=None):
+        """Remove the pending, undecided items of an untraced file's current
+        bytes recorded under another version (best effort, counted in
+        ``review["untraced"]``).
+
+        The current resolver and table offer nothing to choose in these
+        bytes, so an item of an older version would only refuse Apply.
+        """
+        located = self._review_location(media_file, roots)
+        if located is None or canonical is None:
+            return 0
+        # An unusable semantics table says nothing about the current
+        # versions; never let it retire items a working table recorded.
+        if review_capture.inspection_review_version(canonical) is None:
+            return 0
+        try:
+            facts = os.lstat(located[3])
+            removed = self.db.settle_stale_review_items(
+                os.path.normcase(located[3]),
+                facts.st_size,
+                facts.st_mtime_ns,
+                review_capture.item_versions(canonical),
+            )
+        except Exception:
+            self.logger.warning(
+                f"Stale Needs review items of {media_file.name} could not be "
+                "removed",
+                exc_info=True,
+            )
+            if review is not None:
+                review["errors"] += 1
+            return 0
+        if review is not None:
+            review["untraced"] += removed
+        return removed
+
+    def _untraced_memory(self):
+        memory = getattr(self, "_untraced_inspections", None)
+        if memory is None:
+            memory = self._untraced_inspections = {}
+        return memory
+
+    @staticmethod
+    def _review_location(media_file, roots, real_roots=None):
+        """``(root, root_index, relative, spelled)`` of a listed file, or None.
+
+        ``spelled`` is the capture's spelling of the file (the real root joined
+        with the relative path); ``os.path.normcase`` of it is the locator
+        review items are stored under. ``real_roots`` caches each root's
+        ``realpath`` across a batch.
+        """
+        relative, _label, index = _scan_location(media_file, roots)
+        root = next((r for r, _l, i in roots if i == index), None)
+        if index is None or root is None:
+            return None
+        if real_roots is None:
+            real_roots = {}
+        real = real_roots.get(index)
+        if real is None:
+            real = real_roots[index] = os.path.realpath(os.fspath(root))
+        spelled = os.path.join(real, *relative.split("/"))
+        return root, index, relative, spelled
+
+    def _review_file_linked(self, media_file, roots):
+        """True when a saved row links the scanned file (any spelling)."""
+        located = self._review_location(media_file, roots)
+        spellings = (str(media_file),) + ((located[3],) if located else ())
+        return self.db.review_file_linked(spellings)
+
+    def _settle_scanned_reviews(self, media_files, roots, review=None):
+        """Remove the pending items of ``media_files`` that are now linked.
+
+        Blocking; best effort like recording (a failure is logged and
+        counted in ``review["errors"]``). Returns how many items left.
+        """
+        real_roots = {}
+        files = []
+        for media_file in media_files:
+            located = self._review_location(media_file, roots, real_roots)
+            if located is not None:
+                spelled = located[3]
+                files.append((os.path.normcase(spelled), (str(media_file), spelled)))
+        try:
+            settled = self.db.settle_linked_review_items(files) if files else 0
+        except Exception:
+            self.logger.warning(
+                "Needs review items of linked files could not be removed",
+                exc_info=True,
+            )
+            if review is not None:
+                review["errors"] += 1
+            return 0
+        if review is not None:
+            review["settled"] += settled
+        return settled
+
+    def _settle_untraced_reviews(self, media_files, roots, review=None):
+        """Remove the pending items without a choice of untraced ``media_files``.
+
+        ``media_files`` are files found ambiguous with fewer than two
+        candidates that carry a prompt. Blocking; best effort like the linked
+        settle (a failure is logged and counted in ``review["errors"]``).
+        Returns how many items left.
+        """
+        locators = []
+        for media_file in media_files:
+            located = self._review_location(media_file, roots)
+            if located is not None:
+                locators.append(os.path.normcase(located[3]))
+        try:
+            removed = self.db.settle_untraced_review_items(locators) if locators else 0
+        except Exception:
+            self.logger.warning(
+                "Needs review items without a choice could not be removed",
+                exc_info=True,
+            )
+            if review is not None:
+                review["errors"] += 1
+            return 0
+        if review is not None:
+            review["untraced"] += removed
+        return removed
+
+    def record_review_file(self, image_path):
+        """Apply the Needs review rule to one monitor output (its worker thread).
+
+        Only scans add items (maintainer ruling, 2026-10-23): the monitor
+        only clears the items of outputs it links. Maps ``image_path`` to the
+        gallery root that lists it; a file under no current root is
+        ``skipped``. A linked file's pending items are removed and the answer
+        is ``linked``. Any other file is ``skipped``: nothing is captured or
+        recorded, and the next scan reads it. While a job runs that a
+        ``records`` job may not run beside, other than thumbnail work
+        (``PREVIEW_ONLY_KINDS``), nothing is written and the answer is
+        ``deferred``. Errors propagate: the monitor logs them and keeps its
+        link.
+        """
+        busy = self._jobs.blocker(
+            REVIEW_RECORDING_KIND, admission="records", compatible=PREVIEW_ONLY_KINDS
+        )
+        if busy is not None:
+            self.logger.info(
+                f"Needs review was not updated for "
+                f"{os.path.basename(str(image_path))} while {busy.title} runs; "
+                "the next scan reads it again"
+            )
+            return "deferred"
+        full = os.path.abspath(str(image_path))
+        located = Path(os.path.realpath(os.path.dirname(full))) / os.path.basename(full)
+        roots = _scan_roots(self._get_all_output_dirs())
+        if self._review_location(located, roots) is None:
+            return "skipped"
+        if self._review_file_linked(located, roots):
+            self._settle_scanned_reviews([located], roots)
+            return "linked"
+        return "skipped"
+
+    @staticmethod
+    def _log_review_items(job, review):
+        """The scan log's Needs review summary lines (none when nothing moved)."""
+        prefix = SCAN_LOG_PREFIXES["review"]
+        if review["added"]:
+            job.log_line(
+                f"{prefix} {_plural(review['added'], 'image')} added to Needs review"
+            )
+        already = review["queued"] - review["added"]
+        if already:
+            job.log_line(
+                f"{prefix} {_plural(already, 'image')} already in Needs review"
+            )
+        if review["settled"]:
+            job.log_line(
+                f"{SCAN_LOG_PREFIXES['known']} "
+                f"{_plural(review['settled'], 'image')} left Needs review · now linked"
+            )
+        if review["untraced"]:
+            job.log_line(
+                f"{SCAN_LOG_PREFIXES['known']} "
+                f"{_plural(review['untraced'], 'image')} left Needs review · "
+                f"{NOTHING_TO_CHOOSE}"
+            )
+        if review["errors"]:
+            job.log_line(
+                f"{SCAN_LOG_PREFIXES['errors']} "
+                f"{_plural(review['errors'], 'image')} could not be added to "
+                "Needs review"
+            )

py/api/settings_routes.py

@@ -4,8 +4,16 @@ A save validates the payload, commits it to config.json through the config
 store and publishes it at runtime inside that commit; a save that cannot be
 written changes nothing at runtime and says so. ``_config_commit_failure``
 is shared with the LoRA integration's save.
+
+GET also reports the image sources and the monitor (``sources.py``). A save
+that changes the sources runs as a ``source_change`` registry hold, so it is
+refused while a record-changing job (a scan) runs. ``monitoring_enabled``
+takes effect at the next restart. ``POST /prompt_manager/settings/validate-source``
+checks one path and writes nothing.
 """
 
+import contextlib
+import functools
 import os
 
 from aiohttp import web
@@ -15,7 +23,12 @@ from ..config_store import (
     RevisionConflict,
     get_config_store,
 )
+from . import sources
+from . import thumbnail_encode
+from . import thumbnail_settings
 from .admin import _current_image_monitor
+from .job_routes import busy_response
+from .jobs import THUMBNAILS_JOB_KIND, JobBusy
 
 try:
     from ...utils.validators import validate_result_timeout, validate_worker_threads
@@ -23,13 +36,81 @@ except ImportError:
     from utils.validators import validate_result_timeout, validate_worker_threads
 
 
-# Settings owned by POST /settings: config attribute -> (section, key).
+# Settings owned by POST /settings: config attribute -> its keys in config.json.
 _SETTINGS_FILE_KEYS = {
     "RESULT_TIMEOUT": ("web_ui", "result_timeout"),
     "WEBUI_DISPLAY_MODE": ("web_ui", "webui_display_mode"),
     "INFINITE_SCROLL": ("web_ui", "infinite_scroll"),
     "WORKER_THREADS": ("performance", "worker_threads"),
+    "MONITORING_ENABLED": ("gallery", "monitoring", "enabled"),
+    "SAFETY_BACKUP": ("maintenance", "safety_backup"),
+    "THUMBNAIL_FORMAT": ("thumbnails", "format"),
+    "THUMBNAIL_QUALITY": ("thumbnails", "quality"),
+    "THUMBNAIL_EDGE": ("thumbnails", "edge"),
 }
+# The thumbnail settings a running Convert outdated job fixes (#317).
+_THUMBNAIL_SETTINGS = ("THUMBNAIL_FORMAT", "THUMBNAIL_QUALITY", "THUMBNAIL_EDGE")
+# Attributes that live on GalleryConfig; the others on PromptManagerConfig.
+_GALLERY_SETTINGS = frozenset({"MONITORING_ENABLED"})
+SOURCE_CHANGE_JOB_KIND = "source_change"
+SOURCE_CHANGE_JOB_TITLE = "Source change"
+
+
+def _source_identity(path):
+    """The case-folded spelling two roots are the same directory by (Windows)."""
+    return os.path.normcase(path)
+
+
+def _stat_identity(path):
+    """``(st_dev, st_ino)`` of an existing directory, or None.
+
+    Catches case variants on a case-insensitive filesystem whose spelling
+    normcase keeps (macOS).
+    """
+    try:
+        stat = os.stat(path)
+    except (OSError, ValueError):
+        return None
+    return (stat.st_dev, stat.st_ino) if stat.st_ino else None
+
+
+# Refusals that a reconnected drive or folder can lift.
+_RECONNECTABLE = frozenset({"not-found", "not-directory"})
+
+
+def _root_key(root):
+    """The directory a configured root names (resolved), else its spelling."""
+    from ..config import GalleryConfig
+
+    try:
+        return GalleryConfig.resolve_gallery_root(root)
+    except (OSError, TypeError, ValueError, AttributeError):
+        return root
+
+
+def _request_error(message):
+    return {"code": "invalid-request", "error": message}
+
+
+def _invalid_source(index, entry, code, reason):
+    """The 400 body for the source at ``index`` that cannot be used.
+
+    Names it by its public spelling (computed as text: a refused path is
+    never resolved), so the page can mark that row and say why.
+    """
+    source = sources.public_spelling(entry)
+    advice = (
+        "Remove it or reconnect it, then save."
+        if code in _RECONNECTABLE
+        else "Remove it, then save."
+    )
+    return {
+        "code": "invalid-source",
+        "source": source,
+        "index": index,
+        "reason": reason,
+        "error": f"{source} can't be used: {reason}. {advice}",
+    }
 
 
 def _section(config, name):
@@ -47,10 +128,8 @@ def _settings_mutation(updates, new_roots):
 
     def mutate(config):
         for name, value in updates.items():
-            section, key = _SETTINGS_FILE_KEYS[name]
-            merged = _section(config, section)
-            merged[key] = value
-            config[section] = merged
+            *sections, key = _SETTINGS_FILE_KEYS[name]
+            _set_nested(config, sections, key, value)
         if new_roots is not None:
             gallery = _section(config, "gallery")
             monitoring = _section(gallery, "monitoring")
@@ -62,6 +141,16 @@ def _settings_mutation(updates, new_roots):
     return mutate
 
 
+def _set_nested(config, sections, key, value):
+    """``config[s1][s2]...[key] = value``, each section a fresh dict."""
+    if not sections:
+        config[key] = value
+        return
+    merged = _section(config, sections[0])
+    _set_nested(merged, sections[1:], key, value)
+    config[sections[0]] = merged
+
+
 async def _read_json(request):
     """Parse a JSON object body through the package's capped reader."""
     from . import _read_json_body
@@ -81,6 +170,10 @@ class SettingsRoutesMixin:
         async def save_settings_route(request):
             return await self.save_settings(request)
 
+        @routes.post("/prompt_manager/settings/validate-source")
+        async def validate_source_route(request):
+            return await self.validate_source(request)
+
     async def get_settings(self, request):
         """Get current settings."""
         try:
@@ -90,15 +183,26 @@ class SettingsRoutesMixin:
                 self._public_path(d) for d in GalleryConfig.MONITORING_DIRECTORIES
             ]
             revision = await self._run_in_executor(self._config_revision)
+            source_status, monitor = await self._run_in_executor(self._source_status)
+            # #317: which thumbnail formats can be written (a cached probe).
+            encoders = await self._run_in_executor(thumbnail_encode.encoder_status)
             return web.json_response(
                 {
                     "success": True,
                     **revision,
+                    "sources": source_status,
+                    "monitor": monitor,
+                    "thumbnail_encoders": encoders,
                     "settings": {
+                        "monitoring_enabled": GalleryConfig.MONITORING_ENABLED,
                         "result_timeout": PromptManagerConfig.RESULT_TIMEOUT,
                         "webui_display_mode": PromptManagerConfig.WEBUI_DISPLAY_MODE,
                         "infinite_scroll": PromptManagerConfig.INFINITE_SCROLL,
                         "worker_threads": PromptManagerConfig.WORKER_THREADS,
+                        "safety_backup": PromptManagerConfig.SAFETY_BACKUP,
+                        "thumbnail_format": PromptManagerConfig.THUMBNAIL_FORMAT,
+                        "thumbnail_quality": PromptManagerConfig.THUMBNAIL_QUALITY,
+                        "thumbnail_edge": PromptManagerConfig.THUMBNAIL_EDGE,
                         "cpu_count": PromptManagerConfig.max_worker_threads(),
                         "gallery_root_paths": root_paths,
                         "gallery_root_path": root_paths[0] if root_paths else "",
@@ -115,6 +219,61 @@ class SettingsRoutesMixin:
                 status=500,
             )
 
+    def _source_status(self):
+        """``(sources, monitor)`` of GET /settings (blocking)."""
+        from ..config import GalleryConfig
+
+        output_dirs, auto_detected = self._output_dirs_with_origin()
+        return sources.describe_sources(
+            configured=list(GalleryConfig.MONITORING_DIRECTORIES),
+            output_dirs=output_dirs,
+            auto_detected=auto_detected,
+            monitor=_current_image_monitor(),
+            enabled=GalleryConfig.MONITORING_ENABLED,
+        )
+
+    async def validate_source(self, request):
+        """Check one source path ``{path}``; writes nothing.
+
+        200 ``{success, valid, label, path, code, reason}``: a valid source
+        answers its label and public path, an invalid one its code and reason
+        only. A body without a string ``path`` is a 400 ``invalid-request``.
+        """
+        data, error_response = await _read_json(request)
+        if error_response is not None:
+            too_large = error_response.status == 413
+            return web.json_response(
+                {
+                    "success": False,
+                    "code": "too-large" if too_large else "invalid-request",
+                    "error": (
+                        "Request body too large"
+                        if too_large
+                        else "Request body must be a JSON object"
+                    ),
+                },
+                status=error_response.status,
+            )
+        path = data.get("path")
+        if not isinstance(path, str):
+            return web.json_response(
+                {
+                    "success": False,
+                    "code": "invalid-request",
+                    "error": "path must be a string",
+                },
+                status=400,
+            )
+        try:
+            result = await self._run_in_executor(sources.validate_source, path)
+        except Exception:
+            self.logger.exception("Source validation failed")
+            return web.json_response(
+                {"success": False, "code": None, "error": "Failed to check the source"},
+                status=500,
+            )
+        return web.json_response({"success": True, **result})
+
     def _monitored_directories(self):
         """Directories the running image monitor watches, else the configured roots."""
         from ..config import GalleryConfig
@@ -150,10 +309,36 @@ class SettingsRoutesMixin:
                 return web.json_response(
                     {"success": False, "error": str(ve)}, status=400
                 )
+            if updates.get("THUMBNAIL_FORMAT") == "jxl":
+                # #317: JPEG XL only with an encoder (a cached probe).
+                encoder = await self._run_in_executor(
+                    functools.partial(
+                        thumbnail_encode.detect_jxl_encoder, recheck_missing=True
+                    )
+                )
+                if encoder is None:
+                    return web.json_response(
+                        {
+                            "success": False,
+                            "code": "jxl-unavailable",
+                            "error": thumbnail_encode.JXL_UNAVAILABLE,
+                        },
+                        status=400,
+                    )
 
-            new_roots, error = self._parse_gallery_roots(data)
+            refused = self._thumbnail_change_refused(updates)
+            if refused is not None:
+                return refused
+
+            # Off the loop: an accepted root is resolved (filesystem access).
+            new_roots, error = await self._run_in_executor(
+                self._parse_gallery_roots, data
+            )
             if error:
-                return web.json_response({"success": False, "error": error}, status=400)
+                return web.json_response({"success": False, **error}, status=400)
+            roots_change = new_roots is not None and await self._run_in_executor(
+                self._roots_change, new_roots
+            )
 
             published = {}
 
@@ -162,15 +347,30 @@ class SettingsRoutesMixin:
                 # they were written, so the runtime ends on the last one.
                 published.update(self._publish_settings(updates, new_roots))
 
-            try:
-                _saved, revision = await self._run_in_executor(
-                    get_config_store().commit,
-                    _settings_mutation(updates, new_roots),
-                    expected_revision=expected_revision,
-                    publish=publish,
-                )
-            except (ConfigUnreadable, RevisionConflict, OSError) as exc:
-                return self._config_commit_failure(exc)
+            async with contextlib.AsyncExitStack() as stack:
+                hold = None
+                if roots_change:
+                    try:
+                        hold = await stack.enter_async_context(
+                            self._jobs.hold(
+                                SOURCE_CHANGE_JOB_KIND,
+                                SOURCE_CHANGE_JOB_TITLE,
+                                admission="records",
+                            )
+                        )
+                    except JobBusy as busy:
+                        return busy_response(busy)
+                try:
+                    _saved, revision = await self._run_in_executor(
+                        get_config_store().commit,
+                        _settings_mutation(updates, new_roots),
+                        expected_revision=expected_revision,
+                        publish=publish,
+                    )
+                except (ConfigUnreadable, RevisionConflict, OSError) as exc:
+                    if hold is not None:
+                        hold.finish("failed")
+                    return self._config_commit_failure(exc)
 
             return web.json_response(
                 {
@@ -189,6 +389,33 @@ class SettingsRoutesMixin:
                 status=500,
             )
 
+    def _thumbnail_change_refused(self, updates):
+        """409 ``busy`` for a thumbnail format, quality or size change while
+        Convert outdated runs (review I4): the job converts to the settings
+        it started with, and a change under it would make it remove previews
+        in the newly chosen format. Unchanged values pass."""
+        from ..config import PromptManagerConfig
+
+        changed = any(
+            key in updates and updates[key] != getattr(PromptManagerConfig, key)
+            for key in _THUMBNAIL_SETTINGS
+        )
+        job = self._jobs.active(THUMBNAILS_JOB_KIND) if changed else None
+        if job is None or job.scope.get("mode") != "convert":
+            return None
+        return web.json_response(
+            {
+                "success": False,
+                "code": "busy",
+                "error": (
+                    f"{job.title} is running. Change the thumbnail settings "
+                    "when it finishes, or cancel it first."
+                ),
+                "running": {"id": job.id, "title": job.title},
+            },
+            status=409,
+        )
+
     def _publish_settings(self, updates, new_roots):
         """Install committed settings at runtime (inside the config commit).
 
@@ -196,10 +423,11 @@ class SettingsRoutesMixin:
         as ``runtime_applied: false`` with the fields that need a restart;
         nothing is retried or rolled back. Never raises.
         """
-        from ..config import PromptManagerConfig
+        from ..config import GalleryConfig, PromptManagerConfig
 
         for name, value in updates.items():
-            setattr(PromptManagerConfig, name, value)
+            owner = GalleryConfig if name in _GALLERY_SETTINGS else PromptManagerConfig
+            setattr(owner, name, value)
         restart_fields = []
         runtime_applied = True
         if new_roots is not None:
@@ -212,11 +440,40 @@ class SettingsRoutesMixin:
                 )
                 runtime_applied = False
                 restart_fields.append("gallery_root_paths")
+        if "MONITORING_ENABLED" in updates:
+            # The monitor starts with the server: a restart applies the setting
+            # unless the observer already matches it.
+            if updates["MONITORING_ENABLED"] != self._observer_alive():
+                restart_fields.append("monitoring_enabled")
         return {
             "runtime_applied": runtime_applied,
             "restart_required_fields": restart_fields,
         }
 
+    @staticmethod
+    def _roots_change(new_roots):
+        """Whether a save changes the sources (blocking: it resolves them).
+
+        Compared as directories, not spellings: the legacy page resends the
+        roots resolved, while config.json may hold them as hand-written
+        (relative, another case), and an unchanged resend is no change.
+        """
+        from ..config import GalleryConfig
+
+        if new_roots is None:
+            return False
+        return [_root_key(root) for root in new_roots] != [
+            _root_key(root) for root in GalleryConfig.MONITORING_DIRECTORIES
+        ]
+
+    @staticmethod
+    def _observer_alive():
+        """Whether the image monitor's observer is running now. Never raises."""
+        try:
+            return sources.monitor_state(_current_image_monitor())[1]
+        except Exception:
+            return False
+
     def _config_commit_failure(self, exc):
         """The response for a config commit that wrote nothing."""
         not_saved = {"success": False, "persisted": False, "runtime_applied": False}
@@ -283,10 +540,30 @@ class SettingsRoutesMixin:
             if not isinstance(data["infinite_scroll"], bool):
                 raise ValueError("infinite_scroll must be true or false")
             updates["INFINITE_SCROLL"] = data["infinite_scroll"]
+        if "monitoring_enabled" in data:
+            if not isinstance(data["monitoring_enabled"], bool):
+                raise ValueError("monitoring_enabled must be true or false")
+            updates["MONITORING_ENABLED"] = data["monitoring_enabled"]
+        if "safety_backup" in data:
+            if not isinstance(data["safety_backup"], bool):
+                raise ValueError("safety_backup must be true or false")
+            updates["SAFETY_BACKUP"] = data["safety_backup"]
         if "worker_threads" in data:
             updates["WORKER_THREADS"] = validate_worker_threads(
                 data["worker_threads"], PromptManagerConfig.max_worker_threads()
             )
+        if "thumbnail_format" in data:
+            updates["THUMBNAIL_FORMAT"] = thumbnail_settings.validate_format(
+                data["thumbnail_format"]
+            )
+        if "thumbnail_quality" in data:
+            updates["THUMBNAIL_QUALITY"] = thumbnail_settings.validate_quality(
+                data["thumbnail_quality"]
+            )
+        if "thumbnail_edge" in data:
+            updates["THUMBNAIL_EDGE"] = thumbnail_settings.validate_edge(
+                data["thumbnail_edge"]
+            )
         return updates
 
     def _parse_gallery_roots(self, data):
@@ -295,15 +572,21 @@ class SettingsRoutesMixin:
         Accepts ``gallery_root_paths`` (list, preferred) or the legacy single
         ``gallery_root_path`` string. Blank entries are dropped.
 
+        Each entry passes the same checks as validate-source
+        (``sources.source_problem``): the form, then containment as text,
+        before anything is resolved. Blocking (an accepted root is resolved).
+
         Returns:
             (roots, error): ``roots`` is the validated list, or ``None`` when
-            the payload carries no gallery root key; ``error`` is a message
-            when validation failed (and ``roots`` is then ``None``).
+            the payload carries no gallery root key; ``error`` is the coded
+            body of the 400 when validation failed (``roots`` is then None).
+            An unusable source is ``invalid-source`` naming its public path
+            and its position in the list.
         """
         if "gallery_root_paths" in data:
             raw = data["gallery_root_paths"]
             if not isinstance(raw, list):
-                return None, "gallery_root_paths must be a list"
+                return None, _request_error("gallery_root_paths must be a list")
         elif "gallery_root_path" in data:
             raw = [data["gallery_root_path"]]
         else:
@@ -312,27 +595,38 @@ class SettingsRoutesMixin:
         from ..config import GalleryConfig
 
         roots = []
-        for entry in raw:
+        seen = set()
+        for index, entry in enumerate(raw):
             if not isinstance(entry, str):
-                return None, "Gallery root paths must be strings"
+                return None, _request_error("Gallery root paths must be strings")
             entry = entry.strip()
             if not entry:
                 continue
-            ok, reason = GalleryConfig.validate_gallery_root(entry)
-            if not ok:
-                return (
-                    None,
-                    f"Invalid gallery root '{os.path.basename(entry)}': {reason}",
-                )
-            roots.append(GalleryConfig.resolve_gallery_root(entry))
+            code, reason = sources.source_problem(entry)
+            if code is not None:
+                return None, _invalid_source(index, entry, code, reason)
+            root = GalleryConfig.resolve_gallery_root(entry)
+            keys = {("path", _source_identity(root)), ("file", _stat_identity(root))}
+            keys.discard(("file", None))
+            if keys & seen:
+                continue  # another spelling of a root already listed
+            seen |= keys
+            roots.append(root)
         return roots, None
 
     def _apply_gallery_roots(self, roots):
-        """Install validated gallery roots; returns True when they changed."""
+        """Install validated gallery roots; returns True when they changed.
+
+        Another spelling of the same directories installs the resolved
+        spelling and is no change (nothing to restart for).
+        """
         from ..config import GalleryConfig
 
         if roots == list(GalleryConfig.MONITORING_DIRECTORIES):
             return False
+        if not self._roots_change(roots):
+            GalleryConfig.MONITORING_DIRECTORIES = roots
+            return False
         GalleryConfig.MONITORING_DIRECTORIES = roots
         self._cached_output_dir = None
         self.reset_gallery_roots_cache()

py/api/sources.py

@@ -0,0 +1,304 @@
+"""Image sources as System › Sources & scans shows them (#249 S4).
+
+- ``source_form_error`` is the lexical check a submitted source path passes
+  before any filesystem access: no control characters, no ``..`` part, and
+  only the native path forms (on Windows a drive or a UNC share, never the
+  ``\\\\?\\`` and ``\\\\.\\`` namespaces, a drive-relative path, an alternate
+  data stream, a device name or a part Windows would silently trim; on POSIX
+  no Windows drive or backslash form).
+- ``source_problem`` is the one refusal every caller answers (validate-source
+  and the settings save): the form check, then
+  ``GalleryConfig.gallery_root_problem``, which decides containment as text
+  before it touches the filesystem.
+- ``describe_sources`` (blocking: it resolves paths) reports the configured
+  sources with their validity, the effective sources with their listing
+  index and watch state, and the image monitor's state. Every path in it is
+  a public path (``_public_path``), never an absolute one; ``in_comfyui``
+  says whether an effective source's public path is relative to the ComfyUI
+  base (``in_comfyui_base``), so the page can read it as ``ComfyUI/<path>``.
+
+A source's watch state is ``watching`` when the monitor's observer is alive,
+scheduled that directory and monitoring is on; ``stopping`` when it still
+watches it but monitoring was switched off (it stops at the next restart);
+``manual`` when monitoring is off or this process has no monitor; else
+``restart_pending`` (a source added since the monitor started, monitoring
+switched on, or an observer that stopped).
+"""
+
+import logging
+import ntpath
+import os
+import re
+
+logger = logging.getLogger("prompt_manager.api")
+
+MAX_SOURCE_PATH = 4096  # characters
+FORM_REASONS = {
+    "empty": "Gallery root must be a non-empty path",
+    "invalid-form": "Gallery root is not a folder path this server can use",
+    "traversal": "Gallery root must not contain '..'",
+}
+_DRIVE = re.compile(r"[A-Za-z]:")
+_POSIX_FOREIGN = re.compile(r"^[A-Za-z]:")
+# Reserved device names: Windows opens the device for any folder of that name.
+_DEVICE_NAME = re.compile(r"^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³])(\..*)?$", re.I)
+# folder_paths getters and the label of the directory each one reports.
+_COMFYUI_LABELS = (
+    ("get_output_directory", "ComfyUI output"),
+    ("get_input_directory", "ComfyUI input"),
+    ("get_temp_directory", "ComfyUI temp"),
+    ("get_user_directory", "ComfyUI user"),
+)
+WATCH_STATES = ("watching", "stopping", "manual", "restart_pending")
+
+
+def source_form_error(text, *, windows=None):
+    """The form code that refuses ``text`` as a source path, or None.
+
+    ``windows`` selects the path rules (default: this OS). No filesystem
+    access happens here.
+    """
+    if windows is None:
+        windows = os.name == "nt"
+    if not isinstance(text, str) or len(text) > MAX_SOURCE_PATH:
+        return "invalid-form"
+    if any(ord(char) < 32 or ord(char) == 127 for char in text):
+        return "invalid-form"
+    text = text.strip()
+    if not text:
+        return "empty"
+    return _windows_form_error(text) if windows else _posix_form_error(text)
+
+
+def _posix_form_error(text):
+    if "\\" in text or _POSIX_FOREIGN.match(text):
+        return "invalid-form"  # a Windows path names nothing on this server
+    return "traversal" if ".." in text.split("/") else None
+
+
+def _windows_form_error(text):
+    portable = text.replace("/", "\\")
+    if portable.startswith(("\\\\?\\", "\\\\.\\")):
+        return "invalid-form"  # verbatim and device namespaces
+    if portable.startswith("\\\\"):
+        drive, rest = ntpath.splitdrive(portable)
+        share = drive[2:].split("\\")
+        if len(share) != 2 or any(part in ("", ".", "..") for part in share):
+            return "invalid-form"
+    else:
+        drive, rest = ntpath.splitdrive(portable)
+        if drive and (not _DRIVE.fullmatch(drive) or not rest.startswith("\\")):
+            return "invalid-form"  # "C:folder" is relative to that drive's cwd
+    if ":" in rest:
+        return "invalid-form"  # an alternate data stream
+    parts = rest.split("\\")
+    if ".." in parts:
+        return "traversal"
+    for part in parts:
+        if part in ("", "."):
+            continue
+        if part[-1] in ". " or _DEVICE_NAME.match(part):
+            return "invalid-form"
+    return None
+
+
+def source_problem(text):
+    """``(code, reason)`` that refuses ``text`` as a source, else ``(None, "")``.
+
+    The form check runs first and touches nothing; then containment is
+    decided as text before any filesystem access (see
+    ``GalleryConfig.gallery_root_problem``). Every caller answers alike.
+    """
+    from ..config import GalleryConfig
+
+    code = source_form_error(text)
+    if code is not None:
+        return code, FORM_REASONS[code]
+    return GalleryConfig.gallery_root_problem(text)
+
+
+def public_spelling(text):
+    """How a refused source is named in a response, computed as text only.
+
+    Relative to the path anchor it lies under (its public path), else its
+    last part: the caller sent the path, so naming it reveals nothing, and a
+    refused path is never resolved to name it.
+    """
+    from ..config import GalleryConfig, _lexical_path, _lexically_inside
+
+    text = str(text).strip()
+    try:
+        lexical = os.path.normpath(text)
+        key = _lexical_path(text)  # the same length as ``lexical``
+        if not os.path.isabs(text):
+            return lexical.replace("\\", "/")
+        for anchor in GalleryConfig.path_anchors():
+            if _lexically_inside(key, [anchor]):
+                rest = lexical[len(anchor.rstrip(os.sep)) :].lstrip(os.sep)
+                return rest.replace(os.sep, "/") or "."
+        return os.path.basename(lexical) or lexical
+    except (TypeError, ValueError):
+        return ""
+
+
+def identity(path):
+    """The comparison key of a directory: resolved and case-folded (Windows)."""
+    return os.path.normcase(os.path.realpath(str(path)))
+
+
+def _comfyui_labels():
+    """``{identity: label}`` of the directories ComfyUI reports."""
+    try:
+        import folder_paths
+    except ImportError:
+        return {}
+    labels = {}
+    for getter_name, label in _COMFYUI_LABELS:
+        getter = getattr(folder_paths, getter_name, None)
+        if getter is None:
+            continue
+        try:
+            directory = getter()
+        except Exception:
+            continue
+        if isinstance(directory, str) and directory:
+            labels.setdefault(identity(directory), label)
+    return labels
+
+
+def source_label(path, labels=None):
+    """ "ComfyUI output" for ComfyUI's own directories, else the folder name."""
+    if labels is None:
+        labels = _comfyui_labels()
+    label = labels.get(identity(path))
+    if label:
+        return label
+    return os.path.basename(os.path.normpath(str(path))) or str(path)
+
+
+def _configured(entry, labels, public_path):
+    from ..config import GalleryConfig
+
+    code, reason = GalleryConfig.gallery_root_problem(entry)
+    try:
+        resolved = GalleryConfig.resolve_gallery_root(entry)
+    except (OSError, TypeError, ValueError):
+        resolved = str(entry)
+    return {
+        "label": source_label(resolved, labels),
+        "path": public_path(resolved),
+        "valid": code is None,
+        "code": code,
+        "reason": reason or None,
+    }
+
+
+def monitor_state(monitor):
+    """``(present, observer_alive, scheduled directories)`` of the image monitor."""
+    if monitor is None:
+        return False, False, []
+    status = monitor.get_status()
+    scheduled = [str(d) for d in status.get("monitored_directories") or []]
+    return True, bool(status.get("observer_alive")), scheduled
+
+
+def watch_state(path, *, present, alive, scheduled_keys, enabled):
+    """One of ``WATCH_STATES`` (see the module docstring)."""
+    if alive and identity(path) in scheduled_keys:
+        return "watching" if enabled else "stopping"
+    if not present or not enabled:
+        return "manual"
+    return "restart_pending"
+
+
+def in_comfyui_base(path):
+    """Whether ``_public_path(path)`` is relative to the ComfyUI base directory.
+
+    The base is the first anchor ``_public_path`` tries, so this agrees with
+    it: the same canonical (realpath + normcase) spelling on both sides.
+    """
+    from pathlib import Path
+
+    from ..config import _comfyui_base_directory
+
+    base = _comfyui_base_directory()
+    if not path or not base:
+        return False
+    try:
+        canonical = Path(os.path.normcase(os.path.realpath(str(path))))
+        anchor = Path(os.path.normcase(os.path.realpath(base)))
+    except (OSError, ValueError):
+        return False
+    return canonical.is_relative_to(anchor)
+
+
+def describe_sources(*, configured, output_dirs, auto_detected, monitor, enabled):
+    """``(sources, monitor)`` for GET /settings (blocking; public paths only).
+
+    ``configured`` is the configured roots, ``output_dirs`` and
+    ``auto_detected`` what ``_output_dirs_with_origin`` returned, ``monitor``
+    the running ImageMonitor or None, ``enabled`` the monitoring setting.
+    """
+    from . import _public_path
+
+    labels = _comfyui_labels()
+    present, alive, scheduled = monitor_state(monitor)
+    scheduled_keys = {identity(path) for path in scheduled}
+    effective = [
+        {
+            "label": source_label(path, labels),
+            "path": _public_path(path),
+            "root_index": index,
+            "watch": watch_state(
+                path,
+                present=present,
+                alive=alive,
+                scheduled_keys=scheduled_keys,
+                enabled=enabled,
+            ),
+            "in_comfyui": in_comfyui_base(path),
+        }
+        for index, path in enumerate(output_dirs)
+    ]
+    return (
+        {
+            "configured": [
+                _configured(entry, labels, _public_path) for entry in configured
+            ],
+            "effective": effective,
+            "auto_detected": bool(auto_detected),
+        },
+        {
+            "present": present,
+            "observer_alive": alive,
+            "scheduled": [_public_path(path) for path in scheduled],
+        },
+    )
+
+
+def validate_source(text):
+    """``{valid, label, path, code, reason}`` for one submitted path (blocking).
+
+    Writes nothing. An invalid path answers its code and reason with no
+    label or path, so a response never echoes what was typed.
+    """
+    from ..config import GalleryConfig
+    from . import _public_path
+
+    code, reason = source_problem(text)
+    if code is not None:
+        return {
+            "valid": False,
+            "label": None,
+            "path": None,
+            "code": code,
+            "reason": reason,
+        }
+    resolved = GalleryConfig.resolve_gallery_root(text)
+    return {
+        "valid": True,
+        "label": source_label(resolved),
+        "path": _public_path(resolved),
+        "code": None,
+        "reason": None,
+    }

py/api/system.py

@@ -9,9 +9,10 @@
   kept.
 - ``GET /prompt_manager/system/overview`` is the System › Overview aggregate.
   Every value is real or null: there is no backup status until backups report
-  one, no health result until a check ran, and no Needs-review count until
-  the review queue exists. The missing-thumbnail count is not part of it:
-  the page reads ``/images/thumbnails/status``, which walks every source.
+  one and no health result until a check ran; ``needs_review.pending`` is the
+  Needs review queue's pending total. The missing-thumbnail count is not part
+  of it: the page reads ``/images/thumbnails/status``, which walks every
+  source.
 - ``GET /prompt_manager/system/statistics`` lists runs and ratings per
   category, with the legacy ``/stats`` totals and the Overview's count of
   rated images (images whose linked prompt is rated).
@@ -40,6 +41,19 @@ _HEALTH_STATUS_LINES = {
 _StoredReport = namedtuple("_StoredReport", "generation report")
 
 
+async def _gather_settled(*reads):
+    """Await every read, then raise the first failure.
+
+    Unlike a plain gather, a failure never answers while the other executor
+    reads still run against the database.
+    """
+    results = await asyncio.gather(*reads, return_exceptions=True)
+    for result in results:
+        if isinstance(result, BaseException):
+            raise result
+    return results
+
+
 def _failure(message, status=500, code=None):
     return web.json_response(
         {"success": False, "code": code, "error": message}, status=status
@@ -154,9 +168,10 @@ class SystemRoutesMixin:
         from ..config import GalleryConfig
 
         try:
-            (output_dirs, auto_detected), counts = await asyncio.gather(
+            (output_dirs, auto_detected), counts, location = await _gather_settled(
                 self._run_in_executor(self._output_dirs_with_origin),
                 self._run_in_executor(self.db.library_counts),
+                self._run_in_executor(self._library_payload),
             )
         except Exception:
             self.logger.exception("System overview failed")
@@ -174,12 +189,14 @@ class SystemRoutesMixin:
                 },
                 "health": health_summary(self._current_health_report()),
                 "backup": None,  # no verified backup status exists yet (S8)
-                "needs_review": {"pending": None},  # no review queue yet (Q6)
+                "needs_review": {"pending": counts["review_pending"]},
                 "sources": {
                     "configured": len(GalleryConfig.MONITORING_DIRECTORIES),
                     "effective": len(output_dirs),
                     "auto_detected": auto_detected,
                 },
+                # Where the library lives and why (py/api/library_location.py).
+                "location": location,
             },
             headers={"Cache-Control": "no-store"},
         )
@@ -188,7 +205,7 @@ class SystemRoutesMixin:
 
     async def get_system_statistics(self, request):
         try:
-            by_category, totals, counts = await asyncio.gather(
+            by_category, totals, counts = await _gather_settled(
                 self._run_in_executor(self.db.usage_by_category),
                 self._run_in_executor(self.db.get_statistics),
                 self._run_in_executor(self.db.library_counts),

py/api/thumbnail_auto.py

@@ -0,0 +1,865 @@
+"""Automatic thumbnails (#249): previews are a cache the server keeps itself.
+
+The approved mock has no repeated global thumbnail prompt
+(``docs/concepts/workspace/README.md``), so the workspace never asks. Every
+listing gives an image or video a thumbnail URL (``media_thumbnail``), and the
+previews behind those URLs are made here, in three ways:
+
+- **On first view.** ``GET /prompt_manager/images/serve/thumbnails/<rel>_thumb
+  <ext>`` for a preview that does not exist yet is admitted on the event loop
+  (``_PreviewGate``): at most ``ON_DEMAND_LIMIT`` previews are written at once,
+  on this API's own small pool (never the default executor), one flight runs
+  per file, and the requests waiting are capped (``MAX_WAITING``); past the
+  cap a request gets its fallback at once. Inside the admission the preview is
+  mapped back to its media file under the same root (the request text is
+  checked first: no traversal, drive, UNC or empty segment; then a regular
+  file inside the root, never through a link), made and served. When it
+  cannot be made an image's original is served and a video's placeholder
+  frame, both ``Cache-Control: no-store``: a video is never sent to an
+  ``<img>``. A file that cannot be decoded is remembered for this session
+  (keyed by its path, size and mtime) and counted for the System Overview
+  (``failed`` in ``/images/thumbnails/status``); I/O errors and a preview
+  another program holds open (Windows) are not remembered. The recorded
+  history's thumbnail route goes through the same admission and flight key.
+- **On capture.** The image monitor hands every new output it settles to
+  ``queue_capture_thumbnail``, which queues its preview for one background
+  worker thread (``AutoThumbnailer``). Each wake takes at most Worker threads
+  (``WORKER_THREADS``) files and writes them on that many threads; enqueuing
+  is O(1), so the monitor and ComfyUI's queue never wait. A file already
+  queued is not queued again, the queue is bounded (``MAX_QUEUED``) and a
+  preview left out is made on its first view instead.
+- **After a scan.** A scan that added files checks the missing previews; from
+  ``SCAN_THUMBNAIL_JOB_THRESHOLD`` up it starts the thumbnail Activity job
+  (missing only, visible and cancellable) instead of writing them silently,
+  and fewer go through the worker.
+
+Every preview is written by ``_generate_one`` with the server's thumbnail
+settings (format, quality, size limit; ``thumbnail_settings``, #317), into a
+temp sibling verified and renamed over the old one, so a reader never sees a
+partial file. A request for an older preview name (``_thumb.png``) is answered
+with the preview in the current format.
+
+Holds: automatic previews only write files under ``thumbnails/`` and never
+touch the database, like the thumbnail job, so they run beside a scan, image
+tagging and the Needs review recording (S5 M7). They are not written while a
+job runs that replaces the database or removes media and previews: a restore,
+a duplicate removal, a sources change, the gallery's thumbnail clear or an
+``exclusive`` job (``_auto_thumbnail_blocker``). The holds are checked when a
+write starts (after its slot) and again just before its rename.
+
+Shutdown: ``close_auto_thumbnails`` stops the worker at a file boundary,
+kills a running ffmpeg, waits a bounded time (and logs when the wait ran
+out) and shuts the view pool down; after the app's cleanup
+(``final=True``) nothing starts a worker again. Importing this module again
+(a package reload) stops the workers the previous import left.
+"""
+
+import asyncio
+import collections
+import functools
+import io
+import os
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+from aiohttp import web
+
+from . import thumbnail_settings
+from .images import (
+    MEDIA_EXTENSIONS,
+    THUMBNAIL_CLEAR_TITLE,
+    VIDEO_EXTENSIONS,
+    _has_traversal,
+    _is_within,
+    _thumbnail_is_fresh,
+    _video_placeholder_image,
+    _worker_threads,
+    media_thumbnail_rel,
+)
+from .jobs import (
+    DUPLICATE_CLEANUP_JOB_KIND,
+    RESTORE_JOB_KIND,
+    THUMBNAILS_JOB_KIND,
+    JobBusy,
+)
+from .settings_routes import SOURCE_CHANGE_JOB_KIND
+from .thumbnail_encode import shutdown_encoders, writer_settings
+from .thumbnail_jobs import ThumbnailOptions
+
+try:
+    from ...utils.parallel import map_parallel
+except ImportError:  # tests import the package top-level
+    from utils.parallel import map_parallel
+
+# The placeholder frame a video without a preview is answered with (JPEG
+# bytes, never written to disk); written previews follow the settings.
+PLACEHOLDER_SIZE = (thumbnail_settings.DEFAULT_EDGE, thumbnail_settings.DEFAULT_EDGE)
+PLACEHOLDER_QUALITY = 85
+# Source extensions in the order a shared preview name looks for them (R2).
+_SOURCE_ORDER = thumbnail_settings.IMAGE_SOURCE_ORDER + tuple(sorted(VIDEO_EXTENSIONS))
+# Previews views may write at once (the size of the view pool).
+ON_DEMAND_LIMIT = 3
+# View requests that may wait on the gate; one more gets its fallback at once.
+MAX_WAITING = 64
+# How long a pool thread waits for the capture worker's flight of the same file.
+FLIGHT_WAIT_SECONDS = 20
+# How long close() waits for the worker's batch in hand (ffmpeg's own limit).
+CLOSE_WAIT_SECONDS = 30
+# Files the capture worker holds; more are made on their first view.
+MAX_QUEUED = 10_000
+# Undecodable files remembered per session (oldest forgotten first).
+MAX_FAILURES_REMEMBERED = 4096
+# Missing previews after a scan from which the visible thumbnail job starts:
+# a fresh install or a newly added source. Fewer go through the worker.
+SCAN_THUMBNAIL_JOB_THRESHOLD = 200
+# Jobs beside which no automatic preview is written (see the module docstring).
+AUTO_REFUSED_KINDS = frozenset(
+    {RESTORE_JOB_KIND, DUPLICATE_CLEANUP_JOB_KIND, SOURCE_CHANGE_JOB_KIND}
+)
+WORKER_NAME = "PromptManagerThumbnailWorker"
+POOL_PREFIX = "pm-preview"
+# Identifies this import's workers: a reload stops the ones it did not start.
+_MODULE_TOKEN = object()
+
+READY, FAILED, BUSY, DEFERRED = "ready", "failed", "busy", "deferred"
+# What the gate answers a request past MAX_WAITING.
+OVER = object()
+
+
+def _fingerprint(src):
+    """``(path, size, mtime_ns)`` of *src*, or None when it cannot be read."""
+    try:
+        stat = os.stat(src)
+    except OSError:
+        return None
+    return (os.path.normcase(str(src)), stat.st_size, stat.st_mtime_ns)
+
+
+def flight_key(root, rel_parts):
+    """The single-flight key of ``root/rel_parts``: its folder resolved, case
+    folded. The serve route, the history route and the worker share it."""
+    path = Path(root).joinpath(*rel_parts)
+    return os.path.normcase(os.path.join(os.path.realpath(path.parent), path.name))
+
+
+def _dst_key(dst):
+    return flight_key(Path(dst).parent, (Path(dst).name,))
+
+
+@functools.lru_cache(maxsize=1)
+def video_placeholder_jpeg():
+    """The placeholder frame as JPEG bytes (a video whose preview is missing)."""
+    buffer = io.BytesIO()
+    _video_placeholder_image(PLACEHOLDER_SIZE).save(
+        buffer, "JPEG", quality=PLACEHOLDER_QUALITY, optimize=True
+    )
+    return buffer.getvalue()
+
+
+def _is_preview_request(filepath):
+    """Text check only: ``thumbnails/<...>/<name>_thumb<lower-case ext>``.
+
+    Refuses, as text and before any path is joined, what a joined path could
+    take as an anchor: a backslash, a drive or stream colon, and empty, ``.``
+    or ``..`` segments (so a leading ``/`` and ``//server/share`` too).
+    """
+    if "\\" in filepath or ":" in filepath:
+        return False
+    parts = filepath.split("/")
+    if len(parts) < 2 or parts[0] != "thumbnails":
+        return False
+    if any(part in ("", ".", "..") for part in parts) or "thumbnails" in parts[1:-1]:
+        return False
+    stem, extension = os.path.splitext(parts[-1])
+    return (
+        stem.endswith("_thumb")
+        and len(stem) > len("_thumb")
+        and extension == extension.lower()
+        and extension in thumbnail_settings.THUMBNAIL_EXTENSIONS
+    )
+
+
+def _regular_file(path):
+    """True for a regular file that is not a link (one lstat)."""
+    try:
+        return not path.is_symlink() and path.is_file()
+    except OSError:
+        return False
+
+
+def _candidates(parts):
+    """``(folder parts, base, source extensions)`` of a checked preview
+    request: every media extension that owns the requested preview name
+    (``thumbnail_settings.owns``), images first (ruling R2)."""
+    stem, extension = os.path.splitext(parts[-1])
+    wanted = [
+        source
+        for source in _SOURCE_ORDER
+        if source in MEDIA_EXTENSIONS and thumbnail_settings.owns(extension, source)
+    ]
+    return parts[1:-1], stem[: -len("_thumb")], wanted
+
+
+def _current_preview(root, parts):
+    """The preview *parts* names, in the format written now (#317): a request
+    for an older name (``_thumb.png`` before a conversion) is answered with
+    the current file."""
+    _folder, base, _wanted = _candidates(parts)
+    name = base + thumbnail_settings.THUMB_SUFFIX + writer_settings().extension
+    return Path(root).joinpath(*parts[:-1], name)
+
+
+def _quick_source(root, parts):
+    """``(src, is_video)`` by exact name only (no folder listing), or None."""
+    root = Path(root)
+    folder_parts, base, wanted = _candidates(parts)
+    folder = root.joinpath(*folder_parts)
+    for extension in wanted:
+        for name in (base + extension, base + extension.upper()):
+            path = folder / name
+            if _regular_file(path) and _is_within(path, root):
+                return path, extension in VIDEO_EXTENSIONS
+    return None
+
+
+def _thumbnail_source(root, parts):
+    """``(src, dst, is_video)`` for the preview *parts* under *root*, or None.
+
+    *parts* passed ``_is_preview_request``. The source has the preview's name
+    without ``_thumb`` and an extension that owns the requested one (any case:
+    exact names first, then one listing of the folder; ruling R4). It must be
+    a regular file inside *root*. ``dst`` is the preview in the format written
+    now (#317), whatever extension was requested; it is None when the
+    preview's folder resolves outside ``root/thumbnails`` (a link): nothing is
+    written there.
+    """
+    root = Path(root)
+    folder_parts, base, wanted = _candidates(parts)
+    quick = _quick_source(root, parts)
+    if quick is not None:
+        found = quick[0]
+    else:
+        found = _scan_folder(root.joinpath(*folder_parts), base, set(wanted))
+        if found is None or not _is_within(found, root):
+            return None
+    rel = Path(*folder_parts, found.name)
+    dst = root / media_thumbnail_rel(rel)
+    if dst != _current_preview(root, parts):
+        return None
+    if not _is_within(root / "thumbnails", root) or not _is_within(
+        dst, root / "thumbnails"
+    ):
+        dst = None
+    return found, dst, found.suffix.lower() in VIDEO_EXTENSIONS
+
+
+def _scan_folder(folder, base, extensions):
+    """A mixed-case extension (``.Png``): one listing of *folder*, or None."""
+    try:
+        with os.scandir(folder) as entries:
+            for entry in entries:
+                stem, extension = os.path.splitext(entry.name)
+                if stem == base and extension.lower() in extensions:
+                    path = Path(entry.path)
+                    if _regular_file(path):
+                        return path
+    except OSError:
+        return None
+    return None
+
+
+def _stop_stale_workers():
+    """Stop capture workers a previous import of this module started."""
+    for thread in threading.enumerate():
+        token = getattr(thread, "pm_preview_token", None)
+        close = getattr(thread, "pm_preview_close", None)
+        if token is not None and token is not _MODULE_TOKEN and close is not None:
+            close()
+
+
+class AutoThumbnailer:
+    """Single-flight preview writes and the capture worker (thread-safe).
+
+    ``generate(src, dst, is_video, *, stop, guard, track)`` writes one
+    preview and returns ``_generate_one``'s result dict; ``may_write()``
+    says whether automatic previews may be written now. Views call
+    ``ensure`` on the view pool, the monitor calls ``enqueue`` from its
+    thread.
+    """
+
+    def __init__(
+        self,
+        generate,
+        may_write,
+        logger,
+        *,
+        workers=_worker_threads,
+        max_queued=MAX_QUEUED,
+        start_worker=True,
+    ):
+        self._generate = generate
+        self._may_write = may_write
+        self._logger = logger
+        self._workers = workers
+        self._max_queued = max_queued
+        self._start_worker = start_worker
+        self._changed = threading.Condition()
+        self._inflight = {}
+        self._failures = collections.OrderedDict()
+        self._queue = collections.deque()
+        self._queued = set()
+        self._processes = []
+        self._worker = None
+        # True from a worker's start until it leaves (under the lock), so an
+        # idle worker can exit and the next enqueue starts a fresh one.
+        self._worker_running = False
+        self._closed = False
+        self._busy = False
+        self._batch = 0
+
+    @property
+    def failure_count(self):
+        with self._changed:
+            return len(self._failures)
+
+    @property
+    def closed(self):
+        return self._closed
+
+    def _allowed(self):
+        return not self._closed and self._may_write()
+
+    def _track(self, process):
+        """Keep an ffmpeg process so close() can kill it."""
+        with self._changed:
+            self._processes = [p for p in self._processes if p.poll() is None]
+            self._processes.append(process)
+            closed = self._closed
+        if closed:
+            process.kill()
+
+    # ── one preview ───────────────────────────────────────────────────
+
+    def ensure(self, src, dst, is_video):
+        """Make *dst* for *src* unless it is fresh; returns the outcome.
+
+        ``ready`` (the preview is there), ``failed`` (the file cannot be
+        decoded, remembered), ``busy`` (an I/O error, the file is gone, or
+        another flight did not finish) or ``deferred`` (a hold refuses
+        automatic writes, checked when the write starts and before its
+        rename). Blocking: call it off the event loop.
+        """
+        if _thumbnail_is_fresh(src, dst):
+            return READY
+        fingerprint = _fingerprint(src)
+        if fingerprint is None:
+            return BUSY
+        key = _dst_key(dst)
+        with self._changed:
+            if fingerprint in self._failures:
+                return FAILED
+            flight = self._inflight.get(key)
+            if flight is None:
+                self._inflight[key] = done = threading.Event()
+        if flight is not None:
+            flight.wait(FLIGHT_WAIT_SECONDS)
+            if _thumbnail_is_fresh(src, dst):
+                return READY
+            with self._changed:
+                return FAILED if fingerprint in self._failures else BUSY
+        try:
+            return self._lead(src, dst, is_video, fingerprint)
+        finally:
+            with self._changed:
+                self._inflight.pop(key, None)
+                self._changed.notify_all()
+            done.set()
+
+    def _lead(self, src, dst, is_video, fingerprint):
+        if not self._allowed():
+            return DEFERRED
+        if _thumbnail_is_fresh(src, dst):
+            return READY
+        result = self._generate(
+            src,
+            dst,
+            is_video,
+            stop=lambda: self._closed,
+            guard=self._allowed,
+            track=self._track,
+        )
+        if result.get("action") in ("generated", "skipped"):
+            return READY
+        if result.get("held"):
+            return DEFERRED
+        if not result.get("decode"):
+            return BUSY  # an I/O error says nothing about the file
+        error = result.get("error") or "failed"
+        with self._changed:
+            self._failures[fingerprint] = error
+            while len(self._failures) > MAX_FAILURES_REMEMBERED:
+                self._failures.popitem(last=False)
+        self._logger.info(
+            f"No preview for {os.path.basename(str(src))} ({error}); "
+            "the original is shown"
+        )
+        return FAILED
+
+    # ── the capture worker ────────────────────────────────────────────
+
+    def enqueue(self, src, dst, is_video):
+        """Queue *dst*'s preview for the worker; False when already queued,
+        full or closed. Never blocks on a write."""
+        key = _dst_key(dst)
+        with self._changed:
+            if self._closed or key in self._queued:
+                return False
+            if len(self._queue) >= self._max_queued:
+                return False
+            self._queued.add(key)
+            self._queue.append((key, Path(src), Path(dst), bool(is_video)))
+            self._busy = True
+            if self._start_worker and not self._worker_running:
+                self._start_worker_locked()
+            self._changed.notify_all()
+        return True
+
+    def _start_worker_locked(self):
+        """Start the worker (lock held). A start that fails leaves the file
+        queued and the next enqueue tries again."""
+        worker = threading.Thread(target=self._run, name=WORKER_NAME, daemon=True)
+        worker.pm_preview_token = _MODULE_TOKEN
+        worker.pm_preview_close = self.close
+        self._worker_running = True
+        try:
+            worker.start()
+        except RuntimeError:
+            self._worker_running = False
+            self._busy = False
+            self._logger.warning(
+                "The automatic preview worker could not start; the next output "
+                "tries again",
+                exc_info=True,
+            )
+            return
+        self._worker = worker
+
+    def _run(self):
+        try:
+            self._drain()
+        except Exception:
+            self._logger.warning("The automatic preview worker stopped", exc_info=True)
+        finally:
+            # Whatever ended the loop, the next enqueue starts a fresh worker.
+            with self._changed:
+                self._worker_running = False
+                self._busy = False
+                self._batch = 0
+                self._changed.notify_all()
+
+    def _drain(self):
+        while True:
+            with self._changed:
+                if self._closed or not self._queue:
+                    # Idle or closed: leave, so no thread outlives its work.
+                    self._busy = False
+                    self._worker_running = False
+                    self._changed.notify_all()
+                    return
+                take = min(len(self._queue), max(1, int(self._workers() or 1)))
+                batch = [self._queue.popleft() for _ in range(take)]
+                self._batch = len(batch)
+                self._changed.notify_all()
+            try:
+                map_parallel(self._write_queued, batch, len(batch))
+            finally:
+                with self._changed:
+                    self._batch = 0
+                    for key, *_rest in batch:
+                        self._queued.discard(key)
+
+    def _write_queued(self, item):
+        _key, src, dst, is_video = item
+        try:
+            self.ensure(src, dst, is_video)
+        except Exception:  # one file never stops the worker
+            self._logger.warning(
+                f"Automatic preview failed for {src.name}", exc_info=True
+            )
+
+    def close(self):
+        """Stop the worker at its next file boundary (queued files are
+        dropped), kill a running ffmpeg and wait up to CLOSE_WAIT_SECONDS;
+        a worker still running after that is logged."""
+        with self._changed:
+            self._closed = True
+            self._queue.clear()
+            self._queued.clear()
+            processes, self._processes = self._processes, []
+            self._changed.notify_all()
+            worker = self._worker
+        for process in processes:
+            try:
+                process.kill()
+            except OSError:
+                pass
+        if worker is None or worker is threading.current_thread():
+            return
+        worker.join(CLOSE_WAIT_SECONDS)
+        if worker.is_alive():
+            self._logger.warning(
+                "The automatic preview worker is still running after "
+                f"{CLOSE_WAIT_SECONDS} s; it stops at its next file"
+            )
+
+    # ── waits (tests and shutdown; never timers) ──────────────────────
+
+    def _wait_for(self, predicate, timeout):
+        with self._changed:
+            return self._changed.wait_for(predicate, timeout)
+
+    def wait_idle(self, timeout=None):
+        """True once the worker has nothing queued or in hand."""
+        return self._wait_for(lambda: not self._busy, timeout)
+
+    def wait_batch(self, size, timeout=None):
+        """True once the worker holds a batch of *size* files."""
+        return self._wait_for(lambda: self._batch == size, timeout)
+
+
+class _PreviewGate:
+    """Admission of view requests on the event loop (#249 I2).
+
+    Waiters are coroutines: at most ``limit`` previews are written at once
+    on the view pool, one flight runs per key, and past ``MAX_WAITING``
+    waiting requests ``run`` answers ``OVER`` at once.
+    """
+
+    def __init__(self, limit, logger):
+        self.loop = asyncio.get_running_loop()
+        self._slots = asyncio.Semaphore(limit)
+        self._flights = {}
+        self._tasks = set()
+        self._logger = logger
+        self._tick = asyncio.Event()
+        self.waiting = 0
+
+    def _changed(self):
+        tick, self._tick = self._tick, asyncio.Event()
+        tick.set()
+
+    async def settled(self, predicate):
+        """Return once ``predicate()`` holds (re-checked at each change)."""
+        while not predicate():
+            await self._tick.wait()
+
+    async def run(self, key, work, pool):
+        """``work()``'s answer for *key* (shared by every request of the
+        flight), None when it raised, or OVER past the cap."""
+        if self.waiting >= MAX_WAITING:
+            return OVER
+        flight = self._flights.get(key)
+        if flight is None:
+            flight = self.loop.create_future()
+            self._flights[key] = flight
+            task = self.loop.create_task(self._lead(key, flight, work, pool))
+            self._tasks.add(task)
+            task.add_done_callback(self._tasks.discard)
+        self.waiting += 1
+        self._changed()
+        try:
+            return await asyncio.shield(flight)
+        finally:
+            self.waiting -= 1
+            self._changed()
+
+    async def _lead(self, key, flight, work, pool):
+        result = None
+        try:
+            async with self._slots:
+                result = await self.loop.run_in_executor(pool, work)
+        except Exception:
+            self._logger.warning("Automatic preview failed", exc_info=True)
+        finally:
+            self._flights.pop(key, None)
+            if not flight.done():
+                flight.set_result(result)
+
+
+class AutoThumbnailMixin:
+    """Automatic previews on the API: views, the monitor's queue, scans."""
+
+    _auto_thumbnailer = None
+    _auto_thumbnails_shut = False
+    _preview_gate_obj = None
+    _preview_pool_obj = None
+    _auto_thumbnailer_lock = threading.Lock()
+
+    def _auto_thumbnails(self):
+        """This API's AutoThumbnailer, created on first use (no worker after
+        the app's cleanup)."""
+        with AutoThumbnailMixin._auto_thumbnailer_lock:
+            if self._auto_thumbnailer is None:
+                self._auto_thumbnailer = AutoThumbnailer(
+                    self._write_auto_thumbnail,
+                    lambda: self._auto_thumbnail_blocker() is None,
+                    self.logger,
+                    start_worker=not self._auto_thumbnails_shut,
+                )
+            return self._auto_thumbnailer
+
+    def close_auto_thumbnails(self, final=False):
+        """Stop the capture worker and the view pool, and forget them.
+
+        Bounded (see AutoThumbnailer.close). ``final`` (the app's cleanup)
+        also keeps a late monitor event from starting a worker again; a
+        test reset passes False and the next use starts fresh ones.
+        """
+        with AutoThumbnailMixin._auto_thumbnailer_lock:
+            if final:
+                self._auto_thumbnails_shut = True
+            thumbnailer, self._auto_thumbnailer = self._auto_thumbnailer, None
+            pool, self._preview_pool_obj = self._preview_pool_obj, None
+            self._preview_gate_obj = None
+        if thumbnailer is not None:
+            thumbnailer.close()
+        if pool is not None:
+            pool.shutdown(wait=False, cancel_futures=True)
+        if final:
+            shutdown_encoders()  # kill JPEG XL / ffmpeg encoders still running
+
+    def _auto_thumbnail_failures(self):
+        thumbnailer = self._auto_thumbnailer
+        return 0 if thumbnailer is None else thumbnailer.failure_count
+
+    def _write_auto_thumbnail(self, src, dst, is_video, *, stop, guard, track):
+        return self._generate_one(
+            src,
+            dst,
+            writer_settings(),
+            is_video,
+            stop=stop,
+            guard=guard,
+            track=track,
+        )
+
+    def _auto_thumbnail_blocker(self):
+        """The running job automatic previews wait for, or None (any thread)."""
+        for job in self._jobs.running():
+            if job.admission == "exclusive" or job.kind in AUTO_REFUSED_KINDS:
+                return job
+            if job.kind == THUMBNAILS_JOB_KIND and job.title == THUMBNAIL_CLEAR_TITLE:
+                return job
+        return None
+
+    # ── the view admission ────────────────────────────────────────────
+
+    def _preview_gate(self):
+        """The gate of the running loop (a new loop gets a new one)."""
+        gate = self._preview_gate_obj
+        if gate is None or gate.loop is not asyncio.get_running_loop():
+            gate = self._preview_gate_obj = _PreviewGate(ON_DEMAND_LIMIT, self.logger)
+        return gate
+
+    def _preview_pool(self):
+        with AutoThumbnailMixin._auto_thumbnailer_lock:
+            if self._preview_pool_obj is None:
+                self._preview_pool_obj = ThreadPoolExecutor(
+                    ON_DEMAND_LIMIT, thread_name_prefix=POOL_PREFIX
+                )
+            return self._preview_pool_obj
+
+    def _preview_pool_threads(self):
+        pool = self._preview_pool_obj
+        return [] if pool is None else list(getattr(pool, "_threads", ()))
+
+    def _video_placeholder_bytes(self):
+        return video_placeholder_jpeg()
+
+    async def _admit_preview(self, src, dst, is_video):
+        """Make one preview through the view admission (the history route).
+
+        Shares the serve route's flight key; every flight answers the
+        ``ensure`` outcome (or None, or OVER), whichever route started it.
+        """
+        return await self._preview_gate().run(
+            flight_key(Path(dst).parent, (Path(dst).name,)),
+            functools.partial(self._ensure_view, src, dst, is_video),
+            self._preview_pool(),
+        )
+
+    def _ensure_view(self, src, dst, is_video):
+        """``ensure``, reporting a preview removed under us as busy."""
+        outcome = self._auto_thumbnails().ensure(src, dst, is_video)
+        if outcome == READY and not Path(dst).is_file():
+            return BUSY  # removed under us: the fallback this once
+        return outcome
+
+    # ── on first view ─────────────────────────────────────────────────
+
+    def _preview_on_demand(self, root, parts):
+        """The ``ensure`` outcome for the preview *parts* under *root*
+        (``deferred`` when its folder is linked out of the root), or None
+        when no media file previews as *parts*."""
+        located = _thumbnail_source(root, parts)
+        if located is None:
+            return None
+        src, dst, is_video = located
+        if dst is None:
+            return DEFERRED
+        return self._ensure_view(src, dst, is_video)
+
+    def _preview_response(self, outcome, src, dst, is_video):
+        if outcome == READY and dst is not None:
+            return self._file_response(dst)
+        if is_video:
+            return web.Response(
+                body=video_placeholder_jpeg(),
+                content_type="image/jpeg",
+                headers={"Cache-Control": "no-store"},
+            )
+        response = web.FileResponse(src)
+        response.headers["Cache-Control"] = "no-store"
+        return response
+
+    async def _serve_missing_thumbnail(self, output_dirs, filepath):
+        """The made preview, or its fallback; None when *filepath* names no
+        preview of a media file in *output_dirs*.
+
+        The flight answers only the outcome (a history flight may be the one
+        joined); the file it previews is derived here: the preview path is
+        the request's own, and a fallback looks its source up again on the
+        view pool (bounded by it, never the default executor).
+        """
+        if _has_traversal(filepath) or not _is_preview_request(filepath):
+            return None
+        parts = tuple(filepath.split("/"))
+        gate = self._preview_gate()
+        pool = self._preview_pool()
+        for root in output_dirs:
+            root = Path(root)
+            outcome = await gate.run(
+                flight_key(root, parts),
+                functools.partial(self._preview_on_demand, root, parts),
+                pool,
+            )
+            if outcome is None:
+                continue
+            if outcome is OVER:
+                # Past the cap: exact names only, no listing, no write.
+                quick = _quick_source(root, parts)
+                if quick is None:
+                    continue
+                return self._preview_response(BUSY, quick[0], None, quick[1])
+            dst = _current_preview(root, parts)
+            if outcome == READY:
+                return self._file_response(dst)
+            located = await gate.loop.run_in_executor(
+                pool, _thumbnail_source, root, parts
+            )
+            if located is None:
+                continue
+            src, _dst, is_video = located
+            return self._preview_response(outcome, src, None, is_video)
+        return None
+
+    # ── on capture ────────────────────────────────────────────────────
+
+    def queue_capture_thumbnail(self, image_path):
+        """Queue the preview of a new output (the monitor's thread).
+
+        Returns ``queued``, ``fresh`` (its preview is current) or ``skipped``
+        (not a media file under a current root, a link, a preview itself,
+        already queued, or after the app's cleanup). Never writes on the
+        caller's thread.
+        """
+        if self._auto_thumbnails_shut:
+            return "skipped"
+        located = self._capture_target(image_path)
+        if located is None:
+            return "skipped"
+        src, dst, is_video = located
+        if _thumbnail_is_fresh(src, dst):
+            return "fresh"
+        if self._auto_thumbnails().enqueue(src, dst, is_video):
+            return "queued"
+        return "skipped"
+
+    def _capture_target(self, image_path):
+        path = Path(os.path.abspath(str(image_path)))
+        if path.suffix.lower() not in MEDIA_EXTENSIONS or not _regular_file(path):
+            return None
+        folded = os.path.normcase(str(path))
+        for root in self._get_all_output_dirs():
+            root = Path(os.path.abspath(str(root)))
+            base = os.path.normcase(str(root)).rstrip("\\/") + os.sep
+            if not folded.startswith(base) or not _is_within(path, root):
+                continue
+            rel = Path(os.path.relpath(path, root))
+            if "thumbnails" in rel.parts[:-1]:
+                return None
+            dst = root / media_thumbnail_rel(rel)
+            if not _is_within(root / "thumbnails", root) or not _is_within(
+                dst, root / "thumbnails"
+            ):
+                return None
+            return path, dst, path.suffix.lower() in VIDEO_EXTENSIONS
+        return None
+
+    # ── after a scan ──────────────────────────────────────────────────
+
+    async def _thumbnails_after_scan(self, job, output_dirs=None):
+        """Hand a finished scan's missing previews on; returns what it did.
+
+        None (the scan added nothing), ``job`` (the thumbnail job started for
+        ``SCAN_THUMBNAIL_JOB_THRESHOLD`` or more missing previews), ``busy``
+        (a job refused it; the previews are made on view), ``queued`` (fewer,
+        through the worker) or ``none`` (nothing missing). It counts the
+        sources the scan walked (``output_dirs``, narrowed to the job's
+        ``roots``; every source when None). The server log says which.
+        """
+        if job.counters.get("added", 0) <= 0:
+            return None
+        if output_dirs is None:
+            output_dirs = await self._run_in_executor(self._get_all_output_dirs)
+        roots = job.scope.get("roots")
+        if roots:
+            output_dirs = [output_dirs[i] for i in roots if 0 <= i < len(output_dirs)]
+        plan = await self._run_in_executor(self._plan_gallery_thumbnails, output_dirs)
+        missing = len(plan["targets"]) + plan["remaining"]
+        if missing >= SCAN_THUMBNAIL_JOB_THRESHOLD:
+            options = ThumbnailOptions("missing", writer_settings())
+            try:
+                self._start_thumbnail_job(options)
+            except JobBusy as busy:
+                self.logger.info(
+                    f"{missing:,} previews missing after the scan; the thumbnail "
+                    f"job did not start while {busy.running.title} runs"
+                )
+                return "busy"
+            self.logger.info(
+                f"{missing:,} previews missing after the scan; thumbnail job started"
+            )
+            return "job"
+        if not missing:
+            return "none"
+        thumbnailer = self._auto_thumbnails()
+        for src, dst, is_video in plan["targets"]:
+            thumbnailer.enqueue(src, dst, is_video)
+        self.logger.info(f"{missing:,} previews missing after the scan; queued")
+        return "queued"
+
+    async def _hand_off_scan_thumbnails(self, job, output_dirs=None):
+        """``_thumbnails_after_scan`` for the scan runner: never raises."""
+        try:
+            return await self._thumbnails_after_scan(job, output_dirs)
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            self.logger.warning("Previews after the scan failed", exc_info=True)
+            return None
+
+
+# A package reload re-runs this module: stop the workers the old one left.
+_stop_stale_workers()

py/api/thumbnail_convert.py

@@ -0,0 +1,405 @@
+"""Convert outdated thumbnails (#317): an explicit, cancellable Activity job.
+
+``POST /prompt_manager/jobs/thumbnails {mode: "convert"}`` (and
+``GET /prompt_manager/images/thumbnails/plan?mode=convert`` for its count)
+starts "Convert outdated thumbnails": the thumbnail job's kind, ``guarded``
+admission (never beside a record-changing job such as a scan, a restore or
+a duplicate removal; one thumbnail job at a time), its worker threads and
+its outcome groups. Nothing converts on its own: changing the format in
+Appearance only makes previews "outdated".
+
+A preview is outdated when the file owns one in another format than the one
+written now (``writer_settings``: a legacy ``_thumb.png``, or a format
+switched away from). For each such file, at a file boundary (Cancel keeps
+what was converted):
+
+1. the new preview is written from the SOURCE media in the configured
+   format (``_generate_one``: atomic, verified to decode; a video whose frame
+   cannot be decoded fails rather than getting the placeholder), unless a
+   current preview at least as new as the source is already there and
+   decodes;
+2. only then are that file's old-format previews removed: regular files (no
+   links) in its ``thumbnails/`` folder, owned by that source
+   (``thumbnail_settings.owns``), with the source still present. One already
+   gone counts as removed.
+
+Files sharing a stem in one folder (``x.png`` and ``x.mp4``) share one
+preview (ruling R2), so they are converted once, as a group: the preview is
+made from the first source in ``thumbnail_settings.source_rank`` order
+(``.png``, ``.jpg``, ``.jpeg``, ``.webp``, ``.gif``, then videos), the old
+previews of every source in the group are removed, and each removed or
+written file's bytes count once.
+
+A failure keeps the old preview. Previews whose source is gone (orphans) are
+never planned, so never touched. The format the job converts to is fixed
+when it starts; Appearance refuses a thumbnail settings change while it runs
+(409), and should the format still change underneath, the job stops at the
+next file without removing anything in another format. The final status line
+reads "N converted · F failed · <bytes before> → <bytes after>".
+"""
+
+import asyncio
+import functools
+import os
+import time
+from pathlib import Path
+
+from . import thumbnail_settings
+from .thumbnail_encode import ThumbnailVerifyError, verify_thumbnail, writer_settings
+from .admin import _plural, _scan_location, _scan_roots, _scan_status_line
+from .images import _thumbnail_is_fresh, _worker_threads, _thumbnail_batch_size
+from .prompts import safe_error_message
+
+try:
+    from ...utils.parallel import map_parallel
+except ImportError:  # tests import the package top-level
+    from utils.parallel import map_parallel
+
+CONVERT_JOB_TITLE = "Convert outdated thumbnails"
+NOTHING_OUTDATED = "No outdated previews to convert"
+CANCELLED_BEFORE_CONVERTING = "Cancelled before any preview was converted"
+SOURCE_GONE = "The file is gone; its old preview was kept"
+OLD_NOT_REMOVED = "Converted; the old preview could not be removed"
+FORMAT_CHANGED = (
+    "Stopped: the thumbnail format changed while converting · "
+    "{converted} converted. Run Convert outdated again."
+)
+_UNITS = ("B", "KB", "MB", "GB", "TB")
+
+
+def readable_bytes(count):
+    """``1.5 KB``-style size (whole bytes below 1 KB)."""
+    size = float(count)
+    for unit in _UNITS:
+        if size < 1024 or unit == _UNITS[-1]:
+            return f"{int(size)} B" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size:.1f} {_UNITS[-1]}"  # pragma: no cover - loop always returns
+
+
+def _old_previews(src, dst, settings):
+    """``[(path, size)]``: *src*'s previews beside *dst* in another format."""
+    stem = dst.name[: -len(dst.suffix)] if dst.suffix else dst.name
+    old = []
+    for path in thumbnail_settings.owned_in_folder(
+        dst.parent, stem, src.suffix, settings.extension
+    ):
+        if path.suffix == settings.extension:
+            continue
+        try:
+            old.append((path, path.stat().st_size))
+        except OSError:
+            continue
+    return old
+
+
+def _group_targets(targets):
+    """``[[(src, dst, is_video)]]``: targets sharing a preview name (one
+    folder, one stem) in one group, its first source first (R2)."""
+    groups = {}
+    for target in targets:
+        dst = Path(target[1])
+        key = os.path.normcase(str(dst.with_suffix("")))
+        groups.setdefault(key, []).append(target)
+    ordered = []
+    for group in groups.values():
+        group.sort(
+            key=lambda t: (thumbnail_settings.source_rank(Path(t[0]).suffix), str(t[0]))
+        )
+        ordered.append(group)
+    return ordered
+
+
+def _same_file(a, b):
+    """Whether *a* and *b* name one file (re-review N1: on a case-insensitive
+    disk ``x_thumb.JPG`` is the ``x_thumb.jpg`` just written). Without inode
+    numbers (st_ino 0 on some SMB/FAT mounts) the resolved, normcased paths
+    are compared."""
+    try:
+        first, second = os.stat(a), os.stat(b)
+    except OSError:
+        return False
+    if first.st_ino and second.st_ino:
+        return (first.st_dev, first.st_ino) == (second.st_dev, second.st_ino)
+    return os.path.normcase(os.path.realpath(a)) == os.path.normcase(
+        os.path.realpath(b)
+    )
+
+
+def _format_changed(settings):
+    """Whether previews are written in another format than *settings* now."""
+    return writer_settings().extension != settings.extension
+
+
+def _finished_line(totals, remaining):
+    line = (
+        f"{totals['converted']:,} converted · {totals['failed']:,} failed · "
+        f"{readable_bytes(totals['before'])} → {readable_bytes(totals['after'])}"
+    )
+    if remaining:
+        line += f" · {remaining:,} more on the next run"
+    return line
+
+
+class ThumbnailConvertMixin:
+    """The Convert outdated job (started through ``_start_thumbnail_job``)."""
+
+    async def _run_convert_job(self, job, options):
+        try:
+            state = await self._convert_job_body(job, options)
+        except Exception:
+            self.logger.exception("Thumbnail conversion failed")
+            job.update(status_line="Thumbnail conversion stopped on an internal error.")
+            job.log_line("Conversion failed · internal error")
+            state = "failed"
+        job.finish(state)
+
+    async def _convert_job_body(self, job, options):
+        output_dirs = await self._run_in_executor(self._get_all_output_dirs)
+        if not output_dirs:
+            message = "ComfyUI output directory not found"
+            job.update(status_line=message)
+            job.log_line(f"Conversion failed · {message}")
+            return "failed"
+        folders = _plural(len(output_dirs), "output folder")
+        job.scope["output_folders"] = len(output_dirs)
+        job.update(status_line=f"Looking for outdated previews in {folders}")
+        job.log_line(
+            f"Conversion started · {folders} · to {options.settings.describe()}"
+        )
+        plan = await self._plan_conversion(job, options, output_dirs)
+        if job.cancelled:
+            return self._end_conversion(job, 0, CANCELLED_BEFORE_CONVERTING)
+        if not plan["targets"]:
+            job.update(progress=100, status_line=NOTHING_OUTDATED)
+            job.log_line(f"Conversion finished · {NOTHING_OUTDATED.lower()}")
+            return "finished"
+        totals, left = await self._convert_in_batches(job, options, plan, output_dirs)
+        self.invalidate_gallery_cache()
+        if totals["stopped"]:
+            job.update(status_line=FORMAT_CHANGED.format(converted=totals["converted"]))
+            job.log_line(
+                "Conversion stopped · the thumbnail format changed · "
+                f"{_plural(totals['converted'], 'preview')} converted"
+            )
+            return "cancelled"
+        if job.cancelled:
+            return self._end_conversion(
+                job,
+                totals["converted"],
+                f"Cancelled · {_plural(totals['converted'], 'preview')} converted",
+            )
+        line = _finished_line(totals, left)
+        job.update(progress=100, status_line=line)
+        job.log_line(f"Conversion finished · {line}")
+        self.logger.info(f"Thumbnail conversion: {line}")
+        return "finished"
+
+    @staticmethod
+    def _end_conversion(job, converted, status_line):
+        job.update(status_line=status_line)
+        job.log_line(
+            f"Conversion cancelled · {_plural(converted, 'preview')} converted"
+        )
+        return "cancelled"
+
+    async def _plan_conversion(self, job, options, output_dirs, exclude=None):
+        """One batch's plan (at most MAX_THUMBNAIL_FILES targets), off-loop."""
+        return await self._run_in_executor(
+            self._plan_gallery_thumbnails,
+            output_dirs,
+            "convert",
+            stop=lambda: job.cancelled,
+            settings=options.settings,
+            exclude=exclude,
+        )
+
+    async def _convert_in_batches(self, job, options, plan, output_dirs):
+        """Convert ``plan``, then plan again after each batch until nothing
+        is left, the job is cancelled or stopped, or a batch converted
+        nothing (files that fail are never planned again). Returns
+        ``(totals across batches, files left)``."""
+        totals = {"converted": 0, "failed": 0, "before": 0, "after": 0}
+        totals["stopped"] = False
+        run = {
+            "index": 0,
+            "batches": 0,
+            "total": len(plan["targets"]) + plan["remaining"],
+        }
+        run["start"] = time.monotonic()
+        job.update(
+            total=run["total"], status_line=_scan_status_line(0, run["total"], 0, 0)
+        )
+        attempted = set()
+        while True:
+            before = totals["converted"]
+            await self._convert_targets(
+                job, options, plan["targets"], output_dirs, totals, run
+            )
+            attempted.update(src for src, _dst, _video in plan["targets"])
+            stop = job.cancelled or totals["stopped"]
+            if stop or not plan["remaining"] or totals["converted"] == before:
+                return totals, plan["remaining"]
+            plan = await self._plan_conversion(
+                job, options, output_dirs, exclude=attempted
+            )
+            if job.cancelled:
+                return totals, 0
+            run["total"] = run["index"] + len(plan["targets"]) + plan["remaining"]
+            job.update(total=run["total"])
+            if not plan["targets"]:
+                return totals, plan["remaining"]
+
+    async def _convert_targets(self, job, options, targets, output_dirs, totals, run):
+        """Convert one batch's *targets* in worker batches of preview groups,
+        recording each file against the job's overall ``run`` counters."""
+        roots = _scan_roots(output_dirs)
+        groups = _group_targets(targets)
+        batch_size = _thumbnail_batch_size(_worker_threads())
+        for batch_start in range(0, len(groups), batch_size):
+            if job.cancelled or totals["stopped"]:
+                break
+            batch = groups[batch_start : batch_start + batch_size]
+            results = await self._run_in_executor(
+                self._convert_batch, batch, options.settings, lambda: job.cancelled
+            )
+            for group, group_results in zip(batch, results):
+                for (src, _dst, _video), result in zip(group, group_results):
+                    if result["action"] == "stopped":
+                        totals["stopped"] = True
+                    if result["action"] in ("cancelled", "stopped"):
+                        continue
+                    run["index"] += 1
+                    index, total = run["index"], max(run["total"], run["index"])
+                    self._record_conversion(job, src, result, roots, totals)
+                    job.update(processed=index, progress=index * 100 // total)
+            run["batches"] += 1
+            job.update(
+                status_line=_scan_status_line(
+                    run["index"],
+                    run["total"],
+                    run["batches"],
+                    time.monotonic() - run["start"],
+                )
+            )
+            await asyncio.sleep(0)  # let other requests run between batches
+
+    @staticmethod
+    def _record_conversion(job, src, result, roots, totals):
+        path, label, index = _scan_location(src, roots)
+        where = f"{label}/{path}" if label else path
+        row = {"path": path, "root": label, "root_index": index}
+        if result["action"] == "converted":
+            totals["converted"] += 1
+            totals["before"] += result["before"]
+            totals["after"] += result["after"]
+            detail = result["detail"]
+            job.record("generated", {**row, "detail": detail}, f"+ {where} · {detail}")
+            return
+        totals["failed"] += 1
+        detail = result.get("error") or "failed"
+        job.record("errors", {**row, "detail": detail}, f"! {where} · {detail}")
+
+    def _convert_batch(self, groups, settings, stop):
+        """Convert preview ``groups`` on the configured worker threads
+        (blocking); one result list per group."""
+        convert = functools.partial(self._convert_group, settings=settings, stop=stop)
+        return map_parallel(convert, groups, _worker_threads())
+
+    def _convert_group(self, group, settings, stop):
+        """Convert the preview a group of same-stem files shares, once.
+
+        The first source writes it; the others are recorded with the same
+        outcome and no bytes of their own."""
+        src, dst, is_video = group[0]
+        siblings = [Path(target[0]) for target in group[1:]]
+        result = self._convert_one(
+            src, dst, is_video, settings, stop=stop, siblings=siblings
+        )
+        if result["action"] != "converted":
+            return [result] * len(group)
+        shared = {**result, "before": 0, "after": 0}
+        shared["detail"] = f"{result['detail']} (shares {Path(src).name}'s preview)"
+        return [result] + [shared] * len(siblings)
+
+    def _convert_one(self, src, dst, is_video, settings, stop=None, siblings=()):
+        """Convert one file's preview (blocking; never raises).
+
+        ``converted`` with the bytes removed and written, ``error`` (the old
+        preview kept), ``cancelled`` (a file boundary) or ``stopped`` (the
+        format changed underneath, review I4). *siblings* share the preview
+        (R2): their old previews go too.
+        """
+        if stop is not None and stop():
+            return {"action": "cancelled"}
+        if _format_changed(settings):
+            return {"action": "stopped"}
+        dst = Path(dst)
+        try:
+            old = self._old_group_previews([Path(src), *siblings], dst, settings)
+            if not self._current_preview_usable(src, dst, settings):
+                made = self._generate_one(
+                    src, dst, settings, is_video, rebuild=True, placeholder=False
+                )
+                if made["action"] != "generated":
+                    return {"action": "error", "error": made.get("error")}
+                dst = Path(made["path"])
+            if dst.suffix != settings.extension or not dst.is_file():
+                return {"action": "error", "error": "The new preview was not written"}
+            if not os.path.isfile(src):
+                return {"action": "error", "error": SOURCE_GONE}
+            if _format_changed(settings):
+                return {"action": "stopped"}
+            old = [(path, size) for path, size in old if not _same_file(path, dst)]
+            removed, kept = self._remove_old_previews(old)
+            if kept:
+                return {"action": "error", "error": OLD_NOT_REMOVED}
+            label = thumbnail_settings.FORMAT_LABELS[settings.format]
+            return {
+                "action": "converted",
+                "before": removed,
+                "after": dst.stat().st_size,
+                "detail": f"Converted to {label}",
+            }
+        except Exception as exc:
+            self.logger.warning(f"Conversion failed for {src.name}", exc_info=True)
+            return {"action": "error", "error": safe_error_message(exc)}
+
+    @staticmethod
+    def _old_group_previews(sources, dst, settings):
+        """``[(path, size)]`` of every source's old previews, each path once."""
+        seen, old = set(), []
+        for source in sources:
+            for path, size in _old_previews(source, dst, settings):
+                key = os.path.normcase(str(path))
+                if key not in seen:
+                    seen.add(key)
+                    old.append((path, size))
+        return old
+
+    @staticmethod
+    def _current_preview_usable(src, dst, settings):
+        """A current preview at least as new as *src* that decodes (M4)."""
+        if not _thumbnail_is_fresh(src, dst):
+            return False
+        try:
+            verify_thumbnail(dst, settings.format)
+        except ThumbnailVerifyError:
+            return False
+        return True
+
+    def _remove_old_previews(self, old):
+        """``(bytes removed, [kept paths])``; a file already gone counts as
+        removed, with no bytes (another run or a sibling removed it)."""
+        removed, kept = 0, []
+        for path, size in old:
+            try:
+                os.remove(path)
+            except FileNotFoundError:
+                continue
+            except OSError as exc:
+                self.logger.warning(f"Could not remove old preview {path}: {exc}")
+                kept.append(path)
+                continue
+            removed += size
+        return removed, kept

py/api/thumbnail_encode.py

@@ -0,0 +1,524 @@
+"""Thumbnail encoders (#317): every preview file is written here.
+
+``write_thumbnail(frame, dst, settings)`` encodes a prepared frame
+(``thumbnail_frame``: the first frame, RGB, fitted inside the edge) in the
+configured format into a hidden temp sibling, closes it, verifies that it
+decodes, and renames it over ``dst`` (``os.replace``), so a reader never sees
+a partial file and a failure keeps the old preview. ``guard()`` is asked just
+before the rename (automatic previews' holds, #249).
+
+Formats: WebP (Pillow, ``method=4``) and JPEG (Pillow, ``optimize``) always
+work. JPEG XL needs no new dependency; the first encoder found is used:
+
+1. Pillow, natively or through the ``pillow_jxl`` plugin (imported when
+   installed: ``pip install pillow-jxl-plugin``), given the quality itself;
+2. ffmpeg built with ``libjxl`` (``-distance``), fed a PNG on stdin;
+3. ``cjxl`` from libjxl (``-d``), fed a temp PNG that is closed first.
+
+Quality maps to a JPEG XL distance with libjxl's own
+``JxlEncoderDistanceFromQuality``: ``0.1 + (100 - q) * 0.09`` from 30 up
+(q80 → d1.9, q85 → d1.45, q90 → d1.0), the quadratic below 30, and q100 →
+d0.1 (a preview is never lossless). Pillow's plugin applies the same mapping
+inside libjxl. Detection is cached (``detect_jxl_encoder(refresh=True)``
+probes again); "none found" is probed again on the settings read
+(``encoder_status``) and after MISSING_ENCODER_TTL, so one slow probe never
+turns JPEG XL off until a restart. An encoder that fails because its binary
+or module is gone makes that write detect again: another encoder found is
+used for that file, none at all writes it as WebP (logged once) and
+refreshes what Appearance reads. Any other failure (one bad file) raises
+without a probe.
+
+Encoder processes (and ffmpeg's video frames, images.py) go through
+``run_encoder``: tracked, bounded by a timeout, and killed by
+``shutdown_encoders()`` at the app's cleanup, after which none starts.
+"""
+
+import importlib
+import io
+import os
+import re
+import shutil
+import subprocess  # nosec B404 - fixed argv lists, never a shell
+import threading
+import time
+from dataclasses import replace
+from pathlib import Path
+
+from PIL import Image
+
+from . import thumbnail_settings
+
+try:
+    from ...utils.logging_config import get_logger
+except ImportError:  # tests import the package top-level
+    from utils.logging_config import get_logger
+
+logger = get_logger("prompt_manager.thumbnails")
+
+PILLOW_JXL_FORMAT = "JXL"
+JXL_UNAVAILABLE = (
+    "No JPEG XL encoder found. Install pillow-jxl-plugin "
+    "(pip install pillow-jxl-plugin), ffmpeg built with libjxl, or cjxl from "
+    "libjxl, then restart ComfyUI."
+)
+# Seconds an encoder process may run (ffmpeg's video frame shares it).
+ENCODE_TIMEOUT = 30
+PROBE_TIMEOUT = 10
+JXL_EFFORT = 7
+WEBP_METHOD = 4
+JXL_SIGNATURES = (b"\xff\x0a", b"\x00\x00\x00\x0cJXL \r\n\x87\n")
+_NO_WINDOW = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+
+
+class PreviewWriteHeld(Exception):
+    """A preview write stopped before its rename: ``guard()`` said no (#249)."""
+
+
+# The result error of a write held before its rename (never remembered).
+PREVIEW_HELD = "Preview writes are held while another job runs"
+
+
+class ThumbnailVerifyError(RuntimeError):
+    """The encoded preview did not decode; it was never renamed in."""
+
+
+class EncoderFailed(RuntimeError):
+    """An encoder process failed or wrote nothing."""
+
+
+class EncoderClosed(RuntimeError):
+    """The app is shutting down: no encoder process runs any more."""
+
+
+# ── temp files ───────────────────────────────────────────────────────
+
+
+def temp_sibling(dst, tag="part"):
+    """Hidden temp path next to *dst* that keeps its extension."""
+    dst = Path(dst)
+    token = f"{os.getpid()}-{threading.get_ident()}"
+    return dst.with_name(f".{dst.stem}.{tag}-{token}{dst.suffix}")
+
+
+def replace_unless_held(tmp, dst, guard=None):
+    """Rename *tmp* over *dst*, unless ``guard()`` is false (PreviewWriteHeld)."""
+    if guard is not None and not guard():
+        raise PreviewWriteHeld(PREVIEW_HELD)
+    os.replace(tmp, dst)
+
+
+# ``temp_sibling``'s names: ``.<stem>.<tag>-<pid>-<thread id><ext>``.
+_TEMP_NAME = re.compile(r"^\..+\.(?:part|src)-(\d+)-\d+\.[A-Za-z0-9]+$")
+# A temp at least this old (seconds) outlived its write: no encode runs longer.
+STRAY_TEMP_AGE = 4 * ENCODE_TIMEOUT
+# When this process started (this module's import): a temp carrying its PID
+# that is older was left by an earlier run with the same PID (containers).
+PROCESS_STARTED = time.time()
+
+
+def sweep_stray_temps(folder, min_age=None):
+    """Remove the temp files a crashed write left under *folder* (a preview
+    folder, walked without following links); returns ``(count, bytes)``.
+
+    Only ``temp_sibling`` names are touched, never a link. With *min_age*
+    (seconds, the startup sweep) a temp younger than that, or one this
+    process wrote since it started (it may still be writing it), is left;
+    ``min_age=0`` (the clear, which holds every preview write) removes them
+    all.
+    """
+    min_age = STRAY_TEMP_AGE if min_age is None else min_age
+    now = time.time()
+    own = str(os.getpid())
+    count = size = 0
+    for root, _dirs, files in os.walk(folder):
+        for name in files:
+            match = _TEMP_NAME.match(name)
+            if match is None:
+                continue
+            path = Path(root) / name
+            try:
+                stat = path.lstat()
+                if path.is_symlink() or not path.is_file():
+                    continue
+                if min_age and (
+                    now - stat.st_mtime < min_age
+                    or (match.group(1) == own and stat.st_mtime >= PROCESS_STARTED)
+                ):
+                    continue
+                path.unlink()
+            except OSError as exc:
+                logger.debug(f"Could not remove stray temp {name}: {exc}")
+                continue
+            count += 1
+            size += stat.st_size
+    return count, size
+
+
+def _unlink_quietly(path):
+    try:
+        Path(path).unlink()
+    except FileNotFoundError:
+        pass
+    except OSError as exc:
+        logger.debug(f"Could not remove temp file {Path(path).name}: {exc}")
+
+
+# ── encoder processes ────────────────────────────────────────────────
+
+_process_lock = threading.Lock()
+_processes = set()
+_closed = False
+
+
+def run_encoder(cmd, *, input=None, timeout=ENCODE_TIMEOUT, track=None):
+    """Run *cmd* (a fixed argv) with *input* on stdin; returns a
+    CompletedProcess with bytes output.
+
+    The process is tracked so ``shutdown_encoders`` can kill it; past
+    *timeout* it is killed and TimeoutExpired raised. After the shutdown
+    nothing starts (EncoderClosed). ``track(process)`` sees it too.
+    """
+    with _process_lock:
+        if _closed:
+            raise EncoderClosed("Encoders are shut down")
+    process = subprocess.Popen(  # nosec B603 - fixed argv, no shell
+        cmd,
+        stdin=subprocess.PIPE if input is not None else subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        creationflags=_NO_WINDOW,
+    )
+    with _process_lock:
+        _processes.add(process)
+        closed = _closed
+    try:
+        if closed:
+            process.kill()
+        if track is not None:
+            track(process)
+        try:
+            out, err = process.communicate(input=input, timeout=timeout)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.communicate()
+            raise
+    finally:
+        with _process_lock:
+            _processes.discard(process)
+            closed = _closed
+    if closed:
+        raise EncoderClosed("Encoder stopped by the shutdown")
+    return subprocess.CompletedProcess(cmd, process.returncode, out, err)
+
+
+def shutdown_encoders():
+    """Kill every running encoder process; none starts afterwards."""
+    global _closed
+    with _process_lock:
+        _closed = True
+        running = list(_processes)
+    for process in running:
+        try:
+            process.kill()
+        except OSError:
+            pass
+
+
+def reset_encoders():
+    """Allow encoders again and forget the detection (tests, a reload)."""
+    global _closed, _detected, _fallback_logged
+    with _process_lock:
+        _closed = False
+    with _detect_lock:
+        _detected = _UNSET
+        _fallback_logged = False
+
+
+# ── JPEG XL detection ────────────────────────────────────────────────
+
+_UNSET = object()
+_detect_lock = threading.Lock()
+_detected = _UNSET
+_detected_at = 0.0
+# Seconds after which "no JPEG XL encoder" is probed again.
+MISSING_ENCODER_TTL = 60
+_fallback_logged = False
+
+
+def _pillow_jxl_format():
+    """Pillow's JPEG XL format id when it can save one, else None."""
+    try:
+        native = Image.registered_extensions().get(".jxl")
+    except Exception:
+        native = None
+    if native and native in Image.SAVE:
+        return native
+    return PILLOW_JXL_FORMAT if PILLOW_JXL_FORMAT in Image.SAVE else None
+
+
+def _pillow_can_save_jxl():
+    if _pillow_jxl_format():
+        return True
+    try:
+        importlib.import_module("pillow_jxl")
+    except Exception:
+        return False
+    return _pillow_jxl_format() is not None
+
+
+def _pillow_decodes_jxl():
+    try:
+        native = Image.registered_extensions().get(".jxl")
+    except Exception:
+        native = None
+    return bool(native and native in Image.OPEN) or PILLOW_JXL_FORMAT in Image.OPEN
+
+
+def _ffmpeg_has_libjxl():
+    """Whether the ffmpeg on PATH lists the ``libjxl`` encoder."""
+    if not shutil.which("ffmpeg"):
+        return False
+    try:
+        done = run_encoder(
+            ["ffmpeg", "-hide_banner", "-encoders"], timeout=PROBE_TIMEOUT
+        )
+    except (OSError, subprocess.SubprocessError, EncoderClosed):
+        return False
+    listing = done.stdout
+    if isinstance(listing, bytes):
+        listing = listing.decode("utf-8", "replace")
+    return any(
+        len(line.split()) > 1 and line.split()[1] == "libjxl"
+        for line in listing.splitlines()
+    )
+
+
+def _detect():
+    if _pillow_can_save_jxl():
+        return "pillow"
+    if _ffmpeg_has_libjxl():
+        return "ffmpeg"
+    if shutil.which("cjxl"):
+        return "cjxl"
+    return None
+
+
+def detect_jxl_encoder(refresh=False, recheck_missing=False):
+    """``pillow``, ``ffmpeg``, ``cjxl`` or None (cached; blocking on a probe).
+
+    A cached None is probed again with *recheck_missing* or once it is older
+    than MISSING_ENCODER_TTL."""
+    global _detected, _detected_at
+    with _detect_lock:
+        now = time.monotonic()
+        stale_missing = _detected is None and (
+            recheck_missing or now - _detected_at >= MISSING_ENCODER_TTL
+        )
+        if refresh or _detected is _UNSET or stale_missing:
+            _detected = _detect()
+            _detected_at = now
+        return _detected
+
+
+def _encoder_gone(encoder):
+    """Whether *encoder*'s binary or module is no longer there."""
+    if encoder == "pillow":
+        return not _pillow_can_save_jxl()
+    return shutil.which(encoder) is None
+
+
+def encoder_status():
+    """Which formats can be written now (``GET /prompt_manager/settings``;
+    a "none found" is probed again here)."""
+    encoder = detect_jxl_encoder(recheck_missing=True)
+    return {
+        "webp": {"available": True},
+        "jpeg": {"available": True},
+        "jxl": {
+            "available": encoder is not None,
+            "encoder": encoder,
+            "reason": None if encoder is not None else JXL_UNAVAILABLE,
+        },
+    }
+
+
+def jxl_distance(quality):
+    """libjxl's distance for a 1–100 quality (q100 gives 0.1, never lossless)."""
+    if quality >= 100:
+        return 0.1
+    if quality >= 30:
+        return 0.1 + (100 - quality) * 0.09
+    return 53.0 / 3000.0 * quality * quality - 23.0 / 20.0 * quality + 25.0
+
+
+# ── frames and writers ───────────────────────────────────────────────
+
+
+def thumbnail_frame(img, edge):
+    """The first frame of *img* as RGB, fitted inside ``edge`` x ``edge``."""
+    try:
+        img.seek(0)
+    except (EOFError, AttributeError, ValueError):
+        pass
+    try:
+        img.draft("RGB", (edge, edge))  # JPEG: decode at a reduced scale
+    except (AttributeError, ValueError, OSError):
+        pass
+    frame = img.convert("RGB") if img.mode != "RGB" else img.copy()
+    frame.thumbnail((edge, edge), Image.Resampling.LANCZOS)
+    return frame
+
+
+def _png_bytes(img):
+    buffer = io.BytesIO()
+    img.save(buffer, "PNG", compress_level=1)
+    return buffer.getvalue()
+
+
+def _write_webp(img, tmp, settings, track):
+    img.save(tmp, "WEBP", quality=settings.quality, method=WEBP_METHOD)
+
+
+def _write_jpeg(img, tmp, settings, track):
+    img.save(tmp, "JPEG", quality=settings.quality, optimize=True)
+
+
+def _check(done, tmp, name):
+    if done.returncode != 0 or not Path(tmp).is_file():
+        detail = (done.stderr or b"")[-300:]
+        if isinstance(detail, bytes):
+            detail = detail.decode("utf-8", "replace")
+        raise EncoderFailed(f"{name} could not encode the preview: {detail.strip()}")
+
+
+class _EncoderGone(RuntimeError):
+    """No JPEG XL encoder is left: this file is written as WebP."""
+
+
+def _write_jxl(img, tmp, settings, track):
+    """Encode with the detected encoder. One that failed because it is gone
+    makes the write detect again once (another one is used, none raises
+    _EncoderGone); any other failure raises without a probe."""
+    encoder = detect_jxl_encoder()
+    try:
+        _encode_jxl(encoder, img, tmp, settings, track)
+        return
+    except (OSError, EncoderFailed) as exc:
+        if encoder is not None and not _encoder_gone(encoder):
+            raise
+        again = detect_jxl_encoder(refresh=True)
+        if again is None:
+            raise _EncoderGone(str(exc)) from exc
+        if again == encoder:
+            raise
+        logger.info(f"JPEG XL encoder {encoder} failed; using {again}")
+    _unlink_quietly(tmp)
+    _encode_jxl(again, img, tmp, settings, track)
+
+
+def _encode_jxl(encoder, img, tmp, settings, track):
+    distance = f"{jxl_distance(settings.quality):.2f}"
+    if encoder == "pillow":
+        img.save(
+            tmp,
+            _pillow_jxl_format() or PILLOW_JXL_FORMAT,
+            quality=min(settings.quality, 99),
+            effort=JXL_EFFORT,
+            num_threads=1,
+        )
+        return
+    if encoder == "ffmpeg":
+        cmd = [
+            "ffmpeg", "-v", "error", "-f", "png_pipe", "-i", "-",
+            "-frames:v", "1", "-c:v", "libjxl", "-distance", distance,
+            "-effort", str(JXL_EFFORT), "-f", "image2", "-update", "1",
+            "-y", str(tmp),
+        ]  # fmt: skip
+        _check(run_encoder(cmd, input=_png_bytes(img), track=track), tmp, "ffmpeg")
+        return
+    if encoder == "cjxl":
+        source = temp_sibling(Path(tmp).with_suffix(".png"), "src")
+        try:
+            with open(source, "wb") as handle:
+                handle.write(_png_bytes(img))
+            cmd = ["cjxl", str(source), str(tmp), "-d", distance, "-e", str(JXL_EFFORT)]
+            _check(run_encoder(cmd, track=track), tmp, "cjxl")
+        finally:
+            _unlink_quietly(source)
+        return
+    raise EncoderFailed(JXL_UNAVAILABLE)
+
+
+_WRITERS = {"webp": _write_webp, "jpeg": _write_jpeg, "jxl": _write_jxl}
+
+
+def verify_thumbnail(path, fmt):
+    """Raise ThumbnailVerifyError unless *path* decodes as a preview.
+
+    A JPEG XL file Pillow cannot read (no plugin) is checked by signature.
+    """
+    try:
+        if fmt == "jxl" and not _pillow_decodes_jxl():
+            with open(path, "rb") as handle:
+                head = handle.read(12)
+            if not head.startswith(JXL_SIGNATURES):
+                raise ThumbnailVerifyError("The JPEG XL preview has no signature")
+            return
+        with Image.open(path) as written:
+            written.load()
+    except ThumbnailVerifyError:
+        raise
+    except Exception as exc:
+        raise ThumbnailVerifyError(f"The new preview does not decode: {exc}") from exc
+
+
+def _jxl_fallback():
+    """Log once that JPEG XL previews are being written as WebP."""
+    global _fallback_logged
+    with _detect_lock:
+        first, _fallback_logged = not _fallback_logged, True
+    if first:
+        logger.warning(
+            "JPEG XL is the thumbnail format but no JPEG XL encoder is available "
+            "any more; previews are written as WebP until one is installed"
+        )
+
+
+def writer_settings(settings=None):
+    """The settings a preview is written with now: the configured ones, but
+    WebP while JPEG XL has no encoder (logged once). Its extension names the
+    file, so "outdated" means a preview this server would not write now."""
+    settings = settings or thumbnail_settings.current()
+    if settings.format == "jxl" and detect_jxl_encoder() is None:
+        _jxl_fallback()
+        return replace(settings, format="webp")
+    return settings
+
+
+def write_thumbnail(frame, dst, settings, *, guard=None, track=None):
+    """Encode *frame* into *dst* in ``settings``' format; returns the path
+    written (``.webp`` when JPEG XL fell back). Atomic and verified; raises
+    PreviewWriteHeld, ThumbnailVerifyError, EncoderFailed, EncoderClosed or
+    the OSError of the write."""
+    dst = Path(dst)
+    fmt = settings.format
+    if fmt == "jxl" and detect_jxl_encoder() is None:
+        _jxl_fallback()
+        fmt, dst = "webp", dst.with_suffix(".webp")
+    try:
+        return _write_verified(frame, dst, fmt, settings, guard, track)
+    except _EncoderGone:
+        _jxl_fallback()
+        dst = dst.with_suffix(".webp")
+        return _write_verified(frame, dst, "webp", settings, guard, track)
+
+
+def _write_verified(frame, dst, fmt, settings, guard, track):
+    tmp = temp_sibling(dst)
+    try:
+        _WRITERS[fmt](frame, tmp, settings, track)
+        verify_thumbnail(tmp, fmt)
+        replace_unless_held(tmp, dst, guard)
+    finally:
+        _unlink_quietly(tmp)
+    return dst

py/api/thumbnail_jobs.py

@@ -0,0 +1,519 @@
+"""Thumbnail generation as an Activity job (#249 System S5, Task 12; #317).
+
+- ``GET /prompt_manager/images/thumbnails/plan?mode=`` counts what a run
+  would do over every gallery root and writes nothing: ``{success, targets,
+  fresh, outdated, remaining, roots, mode, format, quality, size}``.
+- ``POST /prompt_manager/jobs/thumbnails {mode}`` starts the ``thumbnails``
+  job (202 ``{job}``). Its admission class is ``guarded``: it never runs
+  beside a record-changing job, and one thumbnail job runs at a time. It
+  stops at a file boundary when cancelled, keeping the previews it wrote.
+  Its outcome groups are ``generated``, ``skipped`` (already fresh) and
+  ``errors``.
+
+``mode`` is ``missing`` (previews that are absent or older than their file),
+``rebuild`` (every preview again, fresh ones too) or ``convert`` (Convert
+outdated: previews in another format, see ``thumbnail_convert.py``). Format, quality and
+size limit are the server's thumbnail settings (``thumbnail_settings``,
+#317), read once when the job starts and shown in its scope; a ``size`` or
+``quality`` an older client sends is ignored. Every preview is written next
+to the old one, verified and renamed over it, so nothing is cleared first and
+a failure keeps the old preview; originals are only read.
+
+The legacy gallery stream ``POST /images/generate-thumbnails/progress``
+starts this job (missing previews, the server's settings; its ``quality``
+preset is ignored, #317 R3) or attaches to the running one. Its first frame,
+``job {id, started}``, names that job and whether this stream started it (the
+gallery cancels by that id, and only a job it started); then come the job's
+legacy ``status``/``start``/``progress``/``file_error``/``complete`` frames. A
+client that goes away no longer stops the work: the job outlives the request,
+as a scan does.
+"""
+
+import asyncio
+import functools
+import json
+import time
+from dataclasses import dataclass
+
+from aiohttp import web
+
+from .admin import _plural, _scan_location, _scan_roots, _scan_status_line
+from .images import (
+    _BodyTooLarge,
+    _new_thumbnail_stats,
+    _read_json_body,
+    _record_thumbnail_result,
+    _thumbnail_batch_size,
+    _thumbnail_complete_payload,
+    _thumbnail_progress_payload,
+    _worker_threads,
+)
+from .job_routes import busy_response
+from .jobs import THUMBNAIL_GROUP_NAMES, THUMBNAILS_JOB_KIND, JobBusy
+from .thumbnail_convert import CONVERT_JOB_TITLE
+from .thumbnail_encode import writer_settings
+from .thumbnail_settings import ThumbnailSettings
+
+THUMBNAIL_JOB_TITLE = "Thumbnail generation"
+THUMBNAIL_MODES = ("missing", "rebuild", "convert")
+_OPTIONS_ERROR = 'mode must be "missing", "rebuild" or "convert"'
+CANCELLED_ERROR = "Thumbnail generation was cancelled"
+CANCELLED_BEFORE_WRITING = "Cancelled before any preview was written"
+NOTHING_TO_PREVIEW = "No images or videos to preview"
+_MODE_LOG = {"missing": "missing previews", "rebuild": "every preview"}
+# Outcome rows: what happened to each file's preview.
+_DETAILS = {
+    "generated": "Preview written",
+    "skipped": "Preview already up to date",
+}
+_LOG_PREFIXES = {"generated": "+", "errors": "!"}
+
+
+@dataclass(frozen=True)
+class ThumbnailOptions:
+    """One run's choices: the mode and the thumbnail settings it writes with."""
+
+    mode: str
+    settings: ThumbnailSettings
+
+    @property
+    def rebuild(self):
+        return self.mode == "rebuild"
+
+    def scope(self):
+        return {
+            "mode": self.mode,
+            "format": self.settings.format,
+            "quality": self.settings.quality,
+            "size": self.settings.edge,
+        }
+
+
+def thumbnail_options(raw, *, from_query=False):
+    """``(ThumbnailOptions, None)`` from a body or query, or ``(None, message)``.
+
+    An absent mode is ``missing``; the settings are the server's now.
+    """
+    if not isinstance(raw, dict) and not hasattr(raw, "get"):
+        return None, _OPTIONS_ERROR
+    mode = raw.get("mode", "missing")
+    if mode not in THUMBNAIL_MODES:
+        return None, _OPTIONS_ERROR
+    return ThumbnailOptions(mode, writer_settings()), None
+
+
+def _invalid(message):
+    return web.json_response(
+        {"success": False, "code": "invalid-request", "error": message}, status=400
+    )
+
+
+def _frame(event, data):
+    """A legacy stream frame as the job publishes it."""
+    return {"event": event, "data": data}
+
+
+def _finished_line(plan, stats):
+    """A finished job's status line: what it wrote, or that it had nothing to do."""
+    if not plan["targets"]:
+        if plan["skipped"]:
+            return f"No previews to generate · {plan['skipped']:,} already up to date"
+        return NOTHING_TO_PREVIEW
+    parts = [f"{_plural(stats['generated'], 'preview')} written"]
+    if stats["errors"]:
+        parts.append(_plural(len(stats["errors"]), "error"))
+    if plan["remaining"]:
+        parts.append(f"{plan['remaining']:,} more on the next run")
+    return " · ".join(parts)
+
+
+class ThumbnailJobsMixin:
+    """The thumbnail plan, the thumbnail job and the legacy stream on it."""
+
+    async def get_thumbnail_plan(self, request):
+        """What a thumbnail run would do (read-only; capped like a run)."""
+        options, error = thumbnail_options(request.query, from_query=True)
+        if error:
+            return _invalid(error)
+        try:
+            output_dirs = await self._run_in_executor(self._get_all_output_dirs)
+            plan = await self._run_in_executor(
+                self._plan_gallery_thumbnails,
+                output_dirs,
+                options.mode,
+                settings=options.settings,
+            )
+        except Exception:
+            self.logger.exception("Thumbnail plan failed")
+            return web.json_response(
+                {
+                    "success": False,
+                    "code": None,
+                    "error": "The thumbnail plan could not be read",
+                },
+                status=500,
+            )
+        return web.json_response(
+            {
+                "success": True,
+                "targets": len(plan["targets"]),
+                "fresh": plan["fresh"],
+                "outdated": plan["outdated"],
+                "remaining": plan["remaining"],
+                "roots": [self._public_path(root) for root in output_dirs],
+                **options.scope(),
+            },
+            headers={"Cache-Control": "no-store"},
+        )
+
+    async def start_thumbnail_job(self, request):
+        """Start the thumbnail job (202), or 409 naming the job in the way."""
+        body = {}
+        if request.can_read_body:
+            try:
+                body = await _read_json_body(request)
+            except _BodyTooLarge:
+                return web.json_response(
+                    {"success": False, "code": "too-large", "error": "Body too large"},
+                    status=413,
+                )
+            except (ValueError, UnicodeDecodeError):
+                return _invalid(_OPTIONS_ERROR)
+        options, error = thumbnail_options(body)
+        if error:
+            return _invalid(error)
+        try:
+            job = self._start_thumbnail_job(options)
+        except JobBusy as busy:
+            return busy_response(busy)
+        return web.json_response({"success": True, "job": job.summary()}, status=202)
+
+    def _start_thumbnail_job(self, options):
+        """Register the thumbnail job synchronously; raises JobBusy.
+
+        ``convert`` runs Convert outdated (``thumbnail_convert.py``) under the
+        same kind, admission, cancel and groups.
+        """
+        convert = options.mode == "convert"
+        runner = self._run_convert_job if convert else self._run_thumbnail_job
+        return self._jobs.start(
+            THUMBNAILS_JOB_KIND,
+            CONVERT_JOB_TITLE if convert else THUMBNAIL_JOB_TITLE,
+            admission="guarded",
+            cancellable=True,
+            scope=options.scope(),
+            runner=functools.partial(runner, options=options),
+            groups=THUMBNAIL_GROUP_NAMES,
+        )
+
+    # ── the job ───────────────────────────────────────────────────────
+
+    async def _run_thumbnail_job(self, job, options):
+        try:
+            state = await self._thumbnail_job_body(job, options)
+        except Exception:
+            self.logger.exception("Thumbnail generation failed")
+            job.update(status_line="Thumbnail generation stopped on an internal error.")
+            job.log_line("Thumbnails failed · internal error")
+            job.publish(
+                _frame(
+                    "error",
+                    {
+                        "error": "An internal error occurred",
+                        "message": "Thumbnail generation failed. Check server logs.",
+                    },
+                )
+            )
+            state = "failed"
+        job.finish(state)
+
+    async def _thumbnail_job_body(self, job, options):
+        """Plan, then generate in worker batches; returns the final state.
+
+        Every exit sets the job's final status line (I3): what was written,
+        that there was nothing to do, or what a cancel kept.
+        """
+        output_dirs = await self._run_in_executor(self._get_all_output_dirs)
+        if not output_dirs:
+            message = "ComfyUI output directory not found"
+            job.update(status_line=message)
+            job.log_line(f"Thumbnails failed · {message}")
+            job.publish(_frame("error", {"error": message}))
+            return "failed"
+        folders = _plural(len(output_dirs), "output folder")
+        job.scope["output_folders"] = len(output_dirs)
+        job.update(status_line=f"Looking for media files in {folders}")
+        job.log_line(
+            f"Thumbnails started · {folders} · {_MODE_LOG[options.mode]} · "
+            f"{options.settings.describe()}"
+        )
+        job.publish(
+            _frame(
+                "status",
+                {"phase": "scanning", "message": "Scanning for images and videos..."},
+            )
+        )
+        plan = await self._plan_thumbnail_batch(job, options, output_dirs)
+        if job.cancelled:  # M2: stopped during the walk, before any start frame
+            return self._end_cancelled(job, 0, CANCELLED_BEFORE_WRITING)
+        roots = _scan_roots(output_dirs)
+        self._record_fresh(job, plan, roots)
+        stats, start, left, attempted = await self._generate_in_batches(
+            job, options, plan, roots, output_dirs
+        )
+        self.invalidate_gallery_cache()
+        generated = _plural(stats["generated"], "preview")
+        if job.cancelled:
+            return self._end_cancelled(
+                job, stats["generated"], f"Cancelled · {generated} written"
+            )
+        overall = {"targets": attempted, "skipped": plan["skipped"], "remaining": left}
+        payload = _thumbnail_complete_payload(
+            len(attempted) + plan["skipped"] + left,
+            stats,
+            start,
+            remaining=left,
+            processed=len(attempted),
+        )
+        job.update(progress=100, status_line=_finished_line(overall, stats))
+        if left:
+            job.log_line(f"{left:,} more previews are left for the next run")
+        errors = _plural(len(stats["errors"]), "error")
+        job.log_line(f"Thumbnails finished · {generated} written · {errors}")
+        self.logger.info(payload["message"])
+        job.publish(_frame("complete", payload))
+        return "finished"
+
+    async def _plan_thumbnail_batch(self, job, options, output_dirs, exclude=None):
+        """One batch's plan (at most MAX_THUMBNAIL_FILES targets), off-loop."""
+        return await self._run_in_executor(
+            self._plan_gallery_thumbnails,
+            output_dirs,
+            options.mode,
+            stop=lambda: job.cancelled,
+            settings=options.settings,
+            exclude=exclude,
+        )
+
+    async def _generate_in_batches(self, job, options, plan, roots, output_dirs):
+        """Work through ``plan``, then plan again after each batch until
+        nothing is left, the job is cancelled, or a batch made no progress
+        (every file failed: they are not planned again, and the rest waits
+        for the next run). Files worked on are never planned twice. Returns
+        ``(stats, start, files left, files worked on)``; progress counts
+        against the overall total."""
+        run = {
+            "index": 0,
+            "batches": 0,
+            "total": len(plan["targets"]) + plan["remaining"],
+        }
+        stats = _new_thumbnail_stats()
+        stats["skipped"] = plan["skipped"]
+        start = time.monotonic()
+        self._publish_thumbnail_start(job, plan, run["total"])
+        attempted = set()
+        while True:
+            before = stats["generated"] + stats["skipped"]
+            await self._generate_thumbnail_targets(
+                job, options, plan, roots, stats, run, start
+            )
+            attempted.update(src for src, _dst, _video in plan["targets"])
+            progressed = stats["generated"] + stats["skipped"] > before
+            if job.cancelled or not plan["remaining"] or not progressed:
+                return stats, start, plan["remaining"], attempted
+            plan = await self._plan_thumbnail_batch(
+                job, options, output_dirs, exclude=attempted
+            )
+            if job.cancelled:
+                return stats, start, 0, attempted
+            run["total"] = run["index"] + len(plan["targets"]) + plan["remaining"]
+            job.update(total=run["total"])
+            if not plan["targets"]:
+                return stats, start, plan["remaining"], attempted
+
+    @staticmethod
+    def _end_cancelled(job, generated, status_line):
+        """Close a cancelled job: its status line, log line and error frame."""
+        job.update(status_line=status_line)
+        job.log_line(f"Thumbnails cancelled · {_plural(generated, 'preview')} written")
+        job.publish(
+            _frame("error", {"error": CANCELLED_ERROR, "message": CANCELLED_ERROR})
+        )
+        return "cancelled"
+
+    def _record_fresh(self, job, plan, roots):
+        """List the already fresh previews under Skipped (no log line each)."""
+        rows = []
+        for src in plan["fresh_files"]:
+            path, label, index = _scan_location(src, roots)
+            rows.append(
+                {
+                    "path": path,
+                    "root": label,
+                    "root_index": index,
+                    "detail": _DETAILS["skipped"],
+                }
+            )
+        job.record_counted("skipped", plan["skipped"], rows)
+        if plan["skipped"]:
+            job.log_line(f"= {plan['skipped']:,} previews already up to date")
+
+    @staticmethod
+    def _publish_thumbnail_start(job, plan, total):
+        """The legacy stream's start frame, with the job's overall total."""
+        targets = plan["targets"]
+        video_count = sum(1 for _, _, is_video in targets if is_video)
+        message = (
+            f"Found {total - video_count} images and {video_count} videos to process"
+        )
+        if plan["skipped"]:
+            message += f" ({plan['skipped']} already have thumbnails)"
+        job.update(total=total)
+        if total:  # never "Processing file 0 of 0" (I3)
+            job.update(status_line=_scan_status_line(0, total, 0, 0))
+        job.publish(
+            _frame(
+                "start",
+                {
+                    "total_images": total,
+                    "skipped": plan["skipped"],
+                    "remaining": 0,
+                    "phase": "processing",
+                    "image_count": total - video_count,
+                    "video_count": video_count,
+                    "message": message,
+                },
+            )
+        )
+
+    async def _generate_thumbnail_targets(
+        self, job, options, plan, roots, stats, run, start
+    ):
+        """Generate one batch (``plan``'s targets) in worker batches,
+        publishing each file against the job's overall ``run`` counters."""
+        targets = plan["targets"]
+        batch_size = _thumbnail_batch_size(_worker_threads())
+        generate = {
+            "rebuild": options.rebuild,
+            "stop": lambda: job.cancelled,
+        }
+        for batch_start in range(0, len(targets), batch_size):
+            if job.cancelled:
+                break
+            batch = targets[batch_start : batch_start + batch_size]
+            results = await self._run_in_executor(
+                self._generate_batch, batch, options.settings, **generate
+            )
+            for (src, _dst, _video), result in zip(batch, results):
+                if result["action"] == "cancelled":
+                    continue
+                run["index"] += 1
+                index, total = run["index"], max(run["total"], run["index"])
+                _record_thumbnail_result(stats, result)
+                self._record_thumbnail_outcome(job, src, result, roots)
+                job.update(processed=index, progress=index * 100 // total)
+                if result["action"] == "error":
+                    job.publish(
+                        _frame(
+                            "file_error",
+                            {"file": result["file"], "error": result["error"]},
+                        )
+                    )
+                job.publish(
+                    _frame(
+                        "progress",
+                        _thumbnail_progress_payload(index, total, stats, result, start),
+                    )
+                )
+            run["batches"] += 1
+            job.update(
+                status_line=_scan_status_line(
+                    run["index"], run["total"], run["batches"], time.monotonic() - start
+                )
+            )
+            await asyncio.sleep(0)  # let other requests run between batches
+
+    @staticmethod
+    def _record_thumbnail_outcome(job, src, result, roots):
+        path, label, index = _scan_location(src, roots)
+        where = f"{label}/{path}" if label else path
+        if result["action"] == "error":
+            group, detail = "errors", result.get("error") or "failed"
+        elif result["action"] == "skipped":
+            group, detail = "skipped", _DETAILS["skipped"]
+        else:
+            group, detail = "generated", _DETAILS["generated"]
+        row = {"path": path, "root": label, "root_index": index, "detail": detail}
+        if group == "skipped":
+            job.record_counted(group, 1, [row])
+            return
+        job.record(group, row, f"{_LOG_PREFIXES[group]} {where} · {detail}")
+
+    # ── the legacy gallery stream ─────────────────────────────────────
+
+    async def generate_thumbnails_with_progress(self, request):
+        """The gallery's thumbnail stream (POST, server-sent events).
+
+        Starts the thumbnail job (missing previews with the server's
+        thumbnail settings; the gallery's ``quality`` preset is ignored, R3),
+        or attaches to the running thumbnail job, and streams its frames. A
+        legacy hold (the blocking generate or clear) or a record-changing
+        job refuses it with the stream's error frame. The job goes on when
+        the client goes away.
+        """
+        response = web.StreamResponse(
+            status=200,
+            headers={
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+            },
+        )
+        await response.prepare(request)
+        # M3: read the registry after the last await, so a job that started
+        # while the headers went out is attached to, not refused.
+        job, started, busy = self._legacy_stream_job()
+        if busy is not None:
+            message = f"{busy.title} already running"
+            await self._emit_sse(
+                response, "error", {"error": message, "message": message}
+            )
+            return response
+        # No await between the start and the subscription: the lead frame is
+        # sent after it, so the stream misses none of the runner's frames.
+        events = job.events(lead=_frame("job", {"id": job.id, "started": started}))
+        try:
+            async for payload in events:
+                frame = (
+                    f"event: {payload['event']}\ndata: {json.dumps(payload['data'])}"
+                )
+                await response.write(f"{frame}\n\n".encode("utf-8"))
+        except Exception as exc:  # a write failed: the client went away
+            self.logger.info(
+                f"Thumbnail progress client disconnected ({exc}); "
+                "the thumbnails continue in the background"
+            )
+        finally:
+            # Also when aiohttp cancels the handler on disconnect: the job is
+            # its own task and goes on.
+            await events.aclose()
+        return response
+
+    def _legacy_stream_job(self):
+        """``(job, started, busy)`` for the legacy stream, synchronously.
+
+        Attaches to the running cancellable thumbnail job, or starts one for
+        the missing previews with the server's settings, or names the job in
+        the way.
+        """
+        running = self._jobs.active(THUMBNAILS_JOB_KIND)
+        if running is not None and running.scope.get("mode") == "convert":
+            return None, False, running  # no legacy frames to follow (#317)
+        if running is not None and running.cancellable:
+            return running, False, None
+        busy = self._jobs.blocker(THUMBNAILS_JOB_KIND, admission="guarded")
+        if busy is not None:
+            return None, False, busy
+        # blocker() said free and nothing awaited since, so the start is admitted.
+        options = ThumbnailOptions("missing", writer_settings())
+        return self._start_thumbnail_job(options), True, None

py/api/thumbnail_settings.py

@@ -0,0 +1,228 @@
+"""Thumbnail settings and names (#317): the one place every preview writer reads.
+
+Settings (System › Appearance, ``POST /prompt_manager/settings``, config.json
+``thumbnails``): ``thumbnail_format`` (``webp`` default, ``jxl``, ``jpeg``),
+``thumbnail_quality`` (1–100, default 80) and ``thumbnail_edge`` (the longest
+edge, 128–2048 px, default 512). ``current()`` is the snapshot a writer takes
+once per preview; automatic previews, the Activity job, the history route and
+the legacy gallery routes all go through it.
+
+Names: a media file ``<rel>/<stem>.<ext>`` previews as
+``thumbnails/<rel>/<stem>_thumb<extension of the format>`` (``.webp``,
+``.jxl``, ``.jpg``), images and videos alike. Two files with one stem in one
+folder share that name (ruling R2). Older releases kept the source's own
+extension (``.png``, ``.jpeg``, ``.gif``, ``.webp``, ``.jpg``; ``.jpg`` for a
+video): those are read, served and converted, never written. A preview with a
+format extension (``.webp``, ``.jxl``, ``.jpg``) belongs to every same-stem
+source; a legacy-only one (``.png``, ``.jpeg``, ``.gif``) only to a source
+with that extension (``owns``, ruling R4). Lookups take the first existing
+preview the source owns, preferring the configured format.
+"""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+FORMATS = ("webp", "jxl", "jpeg")
+FORMAT_EXTENSIONS = {"webp": ".webp", "jxl": ".jxl", "jpeg": ".jpg"}
+FORMAT_LABELS = {"webp": "WebP", "jxl": "JPEG XL", "jpeg": "JPEG"}
+DEFAULT_FORMAT = "webp"
+DEFAULT_QUALITY = 80
+DEFAULT_EDGE = 512
+MIN_QUALITY, MAX_QUALITY = 1, 100
+MIN_EDGE, MAX_EDGE = 128, 2048
+
+# Extensions a format writes, then the ones only older releases wrote.
+WRITTEN_EXTENSIONS = (".webp", ".jxl", ".jpg")
+LEGACY_EXTENSIONS = (".png", ".jpeg", ".gif")
+THUMBNAIL_EXTENSIONS = WRITTEN_EXTENSIONS + LEGACY_EXTENSIONS
+CONTENT_TYPES = {
+    ".webp": "image/webp",
+    ".jxl": "image/jxl",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+}
+THUMB_SUFFIX = "_thumb"
+
+
+@dataclass(frozen=True)
+class ThumbnailSettings:
+    """One preview's settings: the format, the quality and the longest edge."""
+
+    format: str
+    quality: int
+    edge: int
+
+    @property
+    def extension(self):
+        return FORMAT_EXTENSIONS[self.format]
+
+    @property
+    def size(self):
+        return (self.edge, self.edge)
+
+    def describe(self):
+        """``WebP · quality 80 · 512 px`` (log lines and the job's scope)."""
+        return f"{FORMAT_LABELS[self.format]} · quality {self.quality} · {self.edge} px"
+
+
+def current():
+    """The configured settings now (read once per preview or per run)."""
+    from ..config import PromptManagerConfig
+
+    fmt = PromptManagerConfig.THUMBNAIL_FORMAT
+    return ThumbnailSettings(
+        fmt if fmt in FORMATS else DEFAULT_FORMAT,
+        int(PromptManagerConfig.THUMBNAIL_QUALITY),
+        int(PromptManagerConfig.THUMBNAIL_EDGE),
+    )
+
+
+def _whole(value, low, high, message):
+    if type(value) is not int or not low <= value <= high:
+        raise ValueError(message)
+    return value
+
+
+def validate_format(value):
+    if not isinstance(value, str) or value not in FORMATS:
+        raise ValueError('thumbnail_format must be "webp", "jxl" or "jpeg"')
+    return value
+
+
+def validate_quality(value):
+    return _whole(
+        value,
+        MIN_QUALITY,
+        MAX_QUALITY,
+        f"thumbnail_quality must be a whole number from {MIN_QUALITY} to {MAX_QUALITY}",
+    )
+
+
+def validate_edge(value):
+    return _whole(
+        value,
+        MIN_EDGE,
+        MAX_EDGE,
+        "thumbnail_edge must be a whole number of pixels "
+        f"from {MIN_EDGE} to {MAX_EDGE}",
+    )
+
+
+# ── names ────────────────────────────────────────────────────────────
+
+
+def thumbnail_stem_rel(rel_path):
+    """``thumbnails/<rel without extension>_thumb`` (POSIX)."""
+    return f"thumbnails/{Path(rel_path).with_suffix('').as_posix()}{THUMB_SUFFIX}"
+
+
+def thumbnail_rel(rel_path, extension=None):
+    """The preview of *rel_path* in *extension* (the configured one when None)."""
+    return thumbnail_stem_rel(rel_path) + (extension or current().extension)
+
+
+# Ruling R2: files sharing a stem share one preview, made from the first
+# source in this order: these images, then videos (by extension name).
+IMAGE_SOURCE_ORDER = (".png", ".jpg", ".jpeg", ".webp", ".gif")
+
+
+def source_rank(source_extension):
+    """Sort key of a source extension in R2's order (images first)."""
+    extension = source_extension.lower()
+    if extension in IMAGE_SOURCE_ORDER:
+        return (0, IMAGE_SOURCE_ORDER.index(extension), extension)
+    return (1, 0, extension)
+
+
+def owns(thumb_extension, source_extension):
+    """Whether a ``_thumb<thumb_extension>`` preview can belong to a source
+    with *source_extension* (ruling R4)."""
+    thumb_extension = thumb_extension.lower()
+    if thumb_extension in WRITTEN_EXTENSIONS:
+        return True
+    if thumb_extension in LEGACY_EXTENSIONS:
+        return thumb_extension == source_extension.lower()
+    return False
+
+
+def _legacy_extension(source_extension):
+    from .inspection_service import VIDEO_EXTENSIONS
+
+    source_extension = source_extension.lower()
+    return ".jpg" if source_extension in VIDEO_EXTENSIONS else source_extension
+
+
+def candidate_extensions(source_extension, preferred=None):
+    """The preview extensions a source owns, in lookup order: the configured
+    one, the name an older release gave it, then the other written ones."""
+    preferred = preferred or current().extension
+    ordered = [preferred, _legacy_extension(source_extension), *WRITTEN_EXTENSIONS]
+    seen = []
+    for extension in ordered:
+        if extension not in seen and owns(extension, source_extension):
+            seen.append(extension)
+    return tuple(seen)
+
+
+def owned_extensions(source_extension, preferred=None):
+    """``candidate_extensions`` plus the other spellings an older release
+    may have given a legacy preview (review M1): the source's own
+    (``X_thumb.JPG`` for ``X.JPG``) and the upper-case legacy one."""
+    extensions = list(candidate_extensions(source_extension, preferred))
+    legacy = _legacy_extension(source_extension)
+    for spelling in (source_extension, legacy.upper()):
+        if spelling not in extensions and owns(spelling, source_extension):
+            extensions.append(spelling)
+    return tuple(extensions)
+
+
+def _is_preview_file(path):
+    try:
+        return not path.is_symlink() and path.is_file()
+    except OSError:
+        return False
+
+
+def owned_in_folder(folder, stem, source_extension, preferred=None):
+    """Yield the existing previews ``<folder>/<stem><ext>`` a source with
+    *source_extension* owns, in lookup order (regular files, no links; one
+    file found under two spellings on a case-insensitive disk once)."""
+    seen = set()
+    for extension in owned_extensions(source_extension, preferred):
+        path = Path(folder) / (stem + extension)
+        if not _is_preview_file(path):
+            continue
+        try:
+            stat = path.stat()
+            identity = (stat.st_dev, stat.st_ino) if stat.st_ino else str(path)
+        except OSError:
+            continue
+        if identity in seen:
+            continue  # the same file under another case (Windows, macOS)
+        seen.add(identity)
+        yield path
+
+
+def _owned(root, rel_path, preferred):
+    rel_path = Path(rel_path)
+    stem = Path(root) / thumbnail_stem_rel(rel_path)
+    return owned_in_folder(stem.parent, stem.name, rel_path.suffix, preferred)
+
+
+def owned_thumbnails(root, rel_path, preferred=None):
+    """Every existing preview of *rel_path* under *root*, in lookup order."""
+    return list(_owned(root, rel_path, preferred))
+
+
+def existing_thumbnail(root, rel_path, preferred=None):
+    """The preview a listing shows for *rel_path*: the first owned one that
+    exists (the configured format first), or None."""
+    return next(_owned(root, rel_path, preferred), None)
+
+
+def content_type(path):
+    """The Content-Type of a preview file by its extension, or None."""
+    return CONTENT_TYPES.get(os.path.splitext(str(path))[1].lower())

py/api/workflow_storage.py

@@ -0,0 +1,277 @@
+"""Store each workflow once: the migration and Reclaim space jobs (#249 S6).
+
+Reviewed like every maintenance operation (``POST /prompt_manager/
+maintenance/preview {operation:"workflow_storage"}``, a ``Plan`` with the
+records to rewrite, the backup and the disk check) and applied with its token
+(``POST /prompt_manager/maintenance/apply``). The apply starts:
+
+1. **Store each workflow once**: kind ``maintenance``, admission ``records``,
+   cancellable, groups ``changed``/``protected``/``errors``. It always takes
+   a verified pre-migration backup, whatever the safety backup policy, named
+   ``<db>.pre-workflow-storage_<stamp>`` outside the pruned ``<db>.backup_*``
+   pool and kept until the user removes it (``backup-failed`` ends the job
+   with nothing rewritten). It then rewrites old-form rows batch by batch
+   (``database/workflow_storage.py``): one transaction per batch of at most
+   ``BATCH_SECONDS``, then ``BATCH_PAUSE`` with the write lock free, progress
+   after each, Cancel honoured between batches. A row that cannot be
+   rewritten stays inline and is listed in ``errors``; any other failure
+   rolls its batch back whole and fails the job. Every record still reads as
+   before, and the next apply continues from the first old-form row.
+2. **Reclaim space**, once every record was looked at: kind ``maintenance``,
+   admission ``exclusive`` (it runs alone; VACUUM holds the write lock), not
+   cancellable. It checks the disk for VACUUM's copies of the live pages
+   (``disk_plan``), then sweeps, runs VACUUM and truncates the WAL. When
+   another job holds the registry, it does not start and the finished
+   migration says so and names Optimize database.
+
+Only the database changes: no image or video file is opened.
+"""
+
+import asyncio
+import sqlite3
+
+from .jobs import MAINTENANCE_JOB_KIND, JobBusy
+from .maintenance import (
+    MAINTENANCE_GROUPS,
+    PRE_MIGRATION_LABEL,
+    SafetyBackupFailed,
+    backup_failed_message,
+    _fail_job,
+    _megabytes,
+    disk_plan,
+    short_space_message,
+    take_safety_backup,
+)
+
+try:
+    from ...database import workflow_storage
+    from ...database.health import readonly_uri
+except ImportError:
+    from database import workflow_storage
+    from database.health import readonly_uri
+
+OPERATION = workflow_storage.OPERATION
+TITLE = "Store each workflow once"
+RECLAIM_TITLE = "Reclaim space"
+REWRITE_FAILED = (
+    "Storing workflows once stopped on an error. The batch in progress was "
+    "rolled back; every record reads as before. Run it again to continue."
+)
+RECLAIM_FAILED = "Reclaim space failed; the database is unchanged."
+ROW_KEPT = "could not be rewritten; it keeps its inline text and reads as before"
+
+
+NOTHING_LEFT = "Every image record already stores its workflow once"
+
+
+def _plural(count, one, many=None):
+    return f"{count:,} {one if count == 1 else (many or one + 's')}"
+
+
+def live_bytes(db_path):
+    """The pages VACUUM copies: page_count minus the free list (blocking)."""
+    conn = sqlite3.connect(readonly_uri(db_path), uri=True)
+    try:
+        page_size = conn.execute("PRAGMA page_size").fetchone()[0]
+        pages = conn.execute("PRAGMA page_count").fetchone()[0]
+        free = conn.execute("PRAGMA freelist_count").fetchone()[0]
+        return page_size * (pages - free)
+    finally:
+        conn.close()
+
+
+class WorkflowStorageRoutesMixin:
+    """Mixin for the maintenance routes: the workflow storage jobs."""
+
+    def _start_workflow_storage(self, db, backup):
+        """Start the migration job (raises JobBusy); the token is the caller's."""
+        return self._jobs.start(
+            MAINTENANCE_JOB_KIND,
+            TITLE,
+            admission="records",
+            cancellable=True,
+            scope={"operation": OPERATION},
+            groups=MAINTENANCE_GROUPS,
+            runner=lambda job: self._run_workflow_storage(job, db, backup),
+        )
+
+    async def _run_workflow_storage(self, job, db, _backup_on):
+        # Always backed up first, whatever the policy: the way back. The first
+        # apply keeps a pre-migration backup; later ones (after a Cancel, a
+        # rerun) take a pooled safety backup, so only one copy is never pruned.
+        counts = await self._run_in_executor(db.workflow_storage_status)
+        if not counts["rows"]:
+            job.log_line(NOTHING_LEFT)
+            job.update(progress=100, status_line=NOTHING_LEFT)
+            return
+        kept = await self._run_in_executor(
+            workflow_storage.pre_migration_backups, db.model.db_path
+        )
+        label = "backup" if kept else PRE_MIGRATION_LABEL
+        backup = await self._backup_before_rewrite(job, db, label, kept)
+        if backup is None:
+            return
+        try:
+            done = await self._rewrite_workflows(job, db, backup)
+        finally:
+            if kept:
+                await self._prune_backup_pool(job, db)
+        if done:
+            job.finish("finished")
+            self._start_reclaim_space(job, db)
+
+    async def _backup_before_rewrite(self, job, db, label, kept):
+        """The verified backup's status note, or None (the job failed).
+
+        ``label`` ``pre-workflow-storage``: kept until the user removes it.
+        ``backup``: a pooled safety backup, while the earliest kept
+        pre-migration backup (``kept[0]``) stays. A failure ends the job
+        ``backup-failed``, nothing changed.
+        """
+        noun = "safety backup" if kept else "pre-migration backup"
+        job.update(status_line=f"Taking the {noun}")
+        job.log_line(f"Taking the {noun} of the database")
+        try:
+            name = await self._run_in_executor(take_safety_backup, db.model, label)
+        except SafetyBackupFailed as error:
+            self.logger.error("Backup before the rewrite failed", exc_info=True)
+            _fail_job(job, "backup-failed", backup_failed_message(error))
+            return None
+        if kept:
+            job.log_line(
+                f"Safety backup {name} verified; the pre-migration backup "
+                f"{kept[0]} is kept"
+            )
+            return f"Safety backup {name}"
+        job.log_line(
+            f"Pre-migration backup {name} verified; it is kept until you remove it"
+        )
+        return f"Pre-migration backup {name}"
+
+    async def _rewrite_workflows(self, job, db, backup):
+        """Rewrite every old-form row; True when every row was looked at."""
+        counts = await self._run_in_executor(db.workflow_storage_status)
+        job.update(total=counts["rows"], processed=0)
+        job.update(status_line="Rewriting image records")
+        job.log_line(f"{_plural(counts['rows'], 'image record')} to rewrite")
+        rows = protected = errors = 0
+        last_id = 0
+        while True:
+            if job.cancelled:
+                return self._stopped(job, rows, backup)
+            try:
+                batch = await self._run_in_executor(
+                    db.migrate_workflow_batch,
+                    last_id,
+                    workflow_storage.BATCH_ROWS,
+                    workflow_storage.BATCH_BYTES,
+                )
+            except Exception:
+                self.logger.exception("Storing workflows once failed")
+                _fail_job(job, None, REWRITE_FAILED)
+                return False
+            if batch["done"]:
+                break
+            last_id = batch["last_id"]
+            rows += batch["rows"]
+            protected += batch["protected"]
+            errors += len(batch["errors"])
+            job.record_counted("changed", batch["rows"])
+            job.record_counted("protected", batch["protected"])
+            for image_id in batch["errors"]:
+                job.record(
+                    "errors",
+                    {"path": "", "detail": f"Image record {image_id}: {ROW_KEPT}"},
+                    f"! Image record {image_id}: {ROW_KEPT}",
+                )
+            total = max(job.total, rows)
+            job.update(
+                processed=rows,
+                total=total,
+                progress=100 * rows // total if total else 100,
+                status_line=f"Rewrote {_plural(rows, 'image record')}",
+            )
+            job.publish({"type": "progress", "processed": rows, "total": total})
+            # Leave the write lock free between batches (monitor, run counts).
+            await asyncio.sleep(workflow_storage.BATCH_PAUSE)
+        removed = await self._run_in_executor(db.sweep_workflow_documents)
+        line = f"Rewrote {_plural(rows, 'image record')}"
+        if protected:
+            line += f"; {_plural(protected, 'stored value')} not text, kept as is"
+        if errors:
+            kept = "keeps its" if errors == 1 else "keep their"
+            line += (
+                f"; {_plural(errors, 'image record')} could not be rewritten and "
+                f"{kept} inline text"
+            )
+        job.log_line(line)
+        if removed:
+            job.log_line(f"Removed {_plural(removed, 'unused workflow document')}")
+        job.update(progress=100, status_line=f"{line} · {backup}")
+        return True
+
+    def _stopped(self, job, rows, backup):
+        line = (
+            f"Stopped after {_plural(rows, 'image record')}; "
+            "run it again to continue"
+        )
+        job.log_line(line)
+        job.update(status_line=f"{line} · {backup}")
+        job.finish("cancelled")
+        return False
+
+    def _start_reclaim_space(self, finished, db):
+        """Start Reclaim space after the migration ``finished``, or say why not."""
+        try:
+            self._jobs.start(
+                MAINTENANCE_JOB_KIND,
+                RECLAIM_TITLE,
+                admission="exclusive",
+                cancellable=False,
+                scope={"operation": OPERATION},
+                groups=MAINTENANCE_GROUPS,
+                runner=lambda job: self._run_reclaim_space(job, db),
+            )
+        except JobBusy as busy:
+            line = (
+                f"Reclaim space did not start: {busy.running.title} is running. "
+                "Run Optimize database to give the space back."
+            )
+            finished.log_line(line)
+            finished.update(status_line=f"{finished.status_line} · {line}")
+            return
+        finished.log_line("Reclaim space started")
+
+    async def _run_reclaim_space(self, job, db):
+        job.update(status_line="Checking free disk space")
+        try:
+            live = await self._run_in_executor(live_bytes, db.model.db_path)
+            _disk, short, _size = await self._run_in_executor(
+                disk_plan,
+                db.model.db_path,
+                backup=False,
+                vacuum=True,
+                vacuum_bytes=live,
+            )
+        except (OSError, sqlite3.Error):
+            self.logger.exception("Could not measure the disk space for Reclaim space")
+            return _fail_job(job, None, RECLAIM_FAILED)
+        if short is not None:
+            return _fail_job(job, "insufficient-space", short_space_message(short))
+        job.update(status_line="Reclaiming space (the database is locked)")
+        job.log_line("Rebuilding the database file (VACUUM)")
+        try:
+            result = await self._run_in_executor(db.reclaim_space)
+        except Exception:
+            self.logger.exception("Reclaim space failed")
+            return _fail_job(job, None, RECLAIM_FAILED)
+        saved = max(0, result["before_bytes"] - result["after_bytes"])
+        line = (
+            f"Reclaimed {_megabytes(saved)} · the database is now "
+            f"{_megabytes(result['after_bytes'])}"
+        )
+        if result["checkpoint_busy"]:
+            line += " (the rest after the next restart)"
+        job.record_counted("changed", 1)
+        job.log_line(line)
+        job.update(progress=100, status_line=line)

py/config.py

@@ -31,18 +31,19 @@ routes = server_instance.routes
 extension_uri = None  # Will be set in __init__.py
 
 import os  # noqa: E402
-from pathlib import Path  # noqa: E402
 from typing import Any, Dict, List, Optional, Tuple  # noqa: E402
 
 # Import logging system
 try:
     from ..utils.logging_config import get_logger
+    from ..utils import library_location
 except ImportError:
     import sys
 
     current_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
     sys.path.insert(0, current_dir)
     from utils.logging_config import get_logger
+    from utils import library_location
 
 # Initialize logger for config operations
 config_logger = get_logger("prompt_manager.config")
@@ -51,6 +52,14 @@ config_logger = get_logger("prompt_manager.config")
 # may be used as gallery roots in addition to ComfyUI's own directories.
 EXTRA_GALLERY_ROOTS_ENV = "PROMPT_MANAGER_EXTRA_GALLERY_ROOTS"
 
+# The one answer for every path outside the allowed folders. The filesystem
+# root and the home directory answer it too, so no caller learns the server's
+# layout (home path, user name) from a refusal (#249 S4).
+OUTSIDE_ALLOWED_REASON = (
+    "Gallery root must be inside a ComfyUI directory (output, input, temp, user) "
+    f"or one listed in {EXTRA_GALLERY_ROOTS_ENV}"
+)
+
 # Environment variable overriding where config.json is read from and saved to.
 CONFIG_PATH_ENV = "PROMPT_MANAGER_CONFIG_PATH"
 
@@ -89,6 +98,29 @@ def write_private_json(path: str, data: Any) -> None:
         os.chmod(path, 0o600)
 
 
+def _lexical_path(path: str) -> str:
+    """``path`` normalised for comparison without touching the filesystem.
+
+    normpath collapses ``.`` and ``..`` as text and normcase folds case on
+    Windows; neither opens, stats nor resolves anything (no SMB request for a
+    UNC path). A symlink is only seen by :func:`_canonical_path` later.
+    """
+    return os.path.normcase(os.path.normpath(path))
+
+
+def _lexically_inside(path: str, parents: List[str]) -> bool:
+    """Whether the normalised ``path`` is one of ``parents`` or below one.
+
+    Pure text on normalised spellings (:func:`_lexical_path` or
+    :func:`_canonical_path`): no filesystem access.
+    """
+    sep = os.path.sep
+    return any(
+        path == parent or path.startswith(parent.rstrip(sep) + sep)
+        for parent in parents
+    )
+
+
 def _is_filesystem_root(path: str) -> bool:
     """True for '/' on POSIX and drive roots such as 'C:\\' on Windows."""
     return os.path.dirname(path) == path
@@ -170,7 +202,6 @@ class GalleryConfig:
         AUTO_CLEANUP_MISSING_FILES (bool): Automatically remove missing file records
         MAX_IMAGE_AGE_DAYS (int): Maximum age in days before cleaning up images
         IMAGES_PER_PAGE (int): Number of images to display per page in web UI
-        THUMBNAIL_SIZE (int): Size in pixels for generated thumbnails
         ENABLE_SEARCH (bool): Enable search functionality in web interface
         ENABLE_METADATA_VIEW (bool): Enable metadata viewing for images
         MAX_CONCURRENT_PROCESSING (int): Maximum concurrent image processing tasks
@@ -195,7 +226,6 @@ class GalleryConfig:
 
     # Web interface settings
     IMAGES_PER_PAGE = 20
-    THUMBNAIL_SIZE = 256
     ENABLE_SEARCH = True
     ENABLE_METADATA_VIEW = True
 
@@ -235,7 +265,6 @@ class GalleryConfig:
             },
             "web_interface": {
                 "images_per_page": cls.IMAGES_PER_PAGE,
-                "thumbnail_size": cls.THUMBNAIL_SIZE,
                 "enable_search": cls.ENABLE_SEARCH,
                 "enable_metadata_view": cls.ENABLE_METADATA_VIEW,
             },
@@ -268,7 +297,12 @@ class GalleryConfig:
         """
         monitoring = new_config.get("monitoring", {})
         if "enabled" in monitoring:
-            cls.MONITORING_ENABLED = monitoring["enabled"]
+            if isinstance(monitoring["enabled"], bool):
+                cls.MONITORING_ENABLED = monitoring["enabled"]
+            else:  # a hand-edited "false" would otherwise switch it on
+                config_logger.warning(
+                    "Ignoring gallery monitoring enabled: expected true or false"
+                )
         if "directories" in monitoring:
             directories = cls._validated_directories(monitoring["directories"])
             if directories is not None:
@@ -293,8 +327,6 @@ class GalleryConfig:
         web_interface = new_config.get("web_interface", {})
         if "images_per_page" in web_interface:
             cls.IMAGES_PER_PAGE = web_interface["images_per_page"]
-        if "thumbnail_size" in web_interface:
-            cls.THUMBNAIL_SIZE = web_interface["thumbnail_size"]
         if "enable_search" in web_interface:
             cls.ENABLE_SEARCH = web_interface["enable_search"]
         if "enable_metadata_view" in web_interface:
@@ -337,31 +369,56 @@ class GalleryConfig:
         Filesystem roots are never allowed as parents, even when listed in
         the environment, because that would re-open the whole disk.
         """
-        parents = []
+        return [canonical for canonical, _spelling in cls._allowed_parent_pairs()]
+
+    @classmethod
+    def _allowed_parent_pairs(cls) -> List[Tuple[str, str]]:
+        """``(canonical, lexical spelling)`` of each allowed parent.
+
+        Only trusted directories (ComfyUI's own and the environment's) are
+        resolved here; the spelling is how ComfyUI or the environment wrote
+        the directory, so a submitted path can be compared without resolving it.
+        """
+        pairs = []
+        seen = set()
         for candidate in _comfyui_directories() + _extra_gallery_roots():
             try:
                 canonical = _canonical_path(candidate)
+                spelling = _lexical_path(os.path.abspath(candidate))
             except (OSError, ValueError):
                 continue
             if _is_filesystem_root(canonical) or not os.path.isdir(canonical):
                 continue
-            if canonical not in parents:
-                parents.append(canonical)
-        return parents
+            if canonical not in seen:
+                seen.add(canonical)
+                pairs.append((canonical, spelling))
+        return pairs
 
     @classmethod
     def path_anchors(cls) -> List[str]:
         """Canonical directories that relative gallery paths are resolved against.
 
         The ComfyUI base directory comes first, followed by the parent of each
-        directory listed in PROMPT_MANAGER_EXTRA_GALLERY_ROOTS, so an extra
-        root is addressed by its own name (``gallery/sub``) rather than by an
-        absolute path. The same anchors drive the public (relative) form of
-        paths in API responses.
+        ComfyUI directory outside it (``--output-directory D:\\Renders``) and of
+        each directory listed in PROMPT_MANAGER_EXTRA_GALLERY_ROOTS, so such a
+        directory is addressed by its own name (``Renders/sub``) rather than by
+        an absolute path, and two folders of one name stay apart. The same
+        anchors drive the public (relative) form of paths in API responses.
         """
         anchors = []
         base = _comfyui_base_directory()
         candidates = [base] if base else []
+        try:
+            base_key = _canonical_path(base) if base else None
+        except (OSError, ValueError):
+            base_key = None
+        for directory in _comfyui_directories():
+            try:
+                canonical = _canonical_path(directory)
+            except (OSError, ValueError):
+                continue
+            if base_key is None or not _lexically_inside(canonical, [base_key]):
+                candidates.append(os.path.dirname(canonical))
         candidates.extend(os.path.dirname(root) for root in _extra_gallery_roots())
         for candidate in candidates:
             try:
@@ -399,33 +456,69 @@ class GalleryConfig:
             (True, "") when the directory lies inside one of
             :meth:`allowed_gallery_parents`; otherwise (False, reason).
         """
+        code, reason = cls.gallery_root_problem(path)
+        return code is None, reason
+
+    @classmethod
+    def gallery_root_problem(cls, path: Any) -> Tuple[Optional[str], str]:
+        """``(code, reason)`` why ``path`` may not be a gallery root, else (None, "").
+
+        Codes: ``empty``, ``unresolvable``, ``outside-allowed``, ``not-found``
+        and ``not-directory``. No reason names the path.
+
+        Containment is decided twice. First lexically, with no filesystem
+        access at all: a path (UNC, ``\\\\?\\``, a device, anything) whose
+        normalised spelling lies outside every allowed parent answers
+        ``outside-allowed`` before it is resolved, so the server never opens
+        or stats it (no SMB connection, no existence or timing oracle). Only
+        then is it resolved and checked again, which catches a symlink out.
+        The filesystem root and the home directory answer ``outside-allowed``
+        too: one answer for every caller (validate-source, the settings save,
+        config.json), and the detail goes to the log only.
+        """
         if not isinstance(path, str) or not path.strip():
-            return False, "Gallery root must be a non-empty path"
+            return "empty", "Gallery root must be a non-empty path"
+
+        pairs = cls._allowed_parent_pairs()
+        spellings = [spelling for pair in pairs for spelling in pair]
+        try:
+            lexical = cls._lexical_candidates(path)
+        except (TypeError, ValueError):
+            return "unresolvable", "Gallery root could not be resolved"
+        if not any(_lexically_inside(candidate, spellings) for candidate in lexical):
+            return "outside-allowed", OUTSIDE_ALLOWED_REASON
 
         try:
             canonical = cls.resolve_gallery_root(path)
         except (OSError, ValueError):
-            return False, "Gallery root could not be resolved"
+            return "unresolvable", "Gallery root could not be resolved"
 
         if _is_filesystem_root(canonical):
-            return False, "Gallery root cannot be a filesystem root"
+            config_logger.info("Gallery root refused: a filesystem root")
+            return "outside-allowed", OUTSIDE_ALLOWED_REASON
         if canonical == _canonical_path(os.path.expanduser("~")):
-            return False, "Gallery root cannot be the home directory"
+            config_logger.info("Gallery root refused: the home directory")
+            return "outside-allowed", OUTSIDE_ALLOWED_REASON
+        if not _lexically_inside(canonical, [canonical for canonical, _ in pairs]):
+            return "outside-allowed", OUTSIDE_ALLOWED_REASON
         if not os.path.exists(canonical):
-            return False, "Gallery root does not exist"
+            return "not-found", "Gallery root does not exist"
         if not os.path.isdir(canonical):
-            return False, "Gallery root is not a directory"
+            return "not-directory", "Gallery root is not a directory"
+        return None, ""
 
-        candidate = Path(canonical)
-        for parent in cls.allowed_gallery_parents():
-            if candidate.is_relative_to(Path(parent)):
-                return True, ""
+    @classmethod
+    def _lexical_candidates(cls, path: str) -> List[str]:
+        """Every spelling ``path`` may resolve to, normalised as text (no IO).
 
-        return (
-            False,
-            "Gallery root must be inside a ComfyUI directory "
-            f"(output, input, temp, user) or one listed in {EXTRA_GALLERY_ROOTS_ENV}",
-        )
+        An absolute path is itself; a relative one is joined to each
+        :meth:`path_anchors` entry, as :meth:`resolve_gallery_root` tries them.
+        """
+        path = path.strip()
+        if os.path.isabs(path):
+            return [_lexical_path(path)]
+        anchors = cls.path_anchors()
+        return [_lexical_path(os.path.join(anchor, path)) for anchor in anchors]
 
 
 class IntegrationConfig:
@@ -563,6 +656,23 @@ class PromptManagerConfig:
     DEFAULT_WORKER_THREADS = max(1, (os.cpu_count() or 1) // 2)
     WORKER_THREADS = DEFAULT_WORKER_THREADS
 
+    # Maintenance: a reviewed apply takes a verified safety backup of the
+    # database first (System › Backup & export › Recovery policy, #249 S6).
+    SAFETY_BACKUP = True
+
+    # "Keep it here" (#249 S6b): the user chose to keep a node-folder library
+    # where it is, so the workspace stops offering to move it.
+    KEEP_LIBRARY_IN_NODE_FOLDER = False
+
+    # Thumbnails (#317): every preview writer reads these through
+    # py/api/thumbnail_settings.py (System › Appearance). The legacy
+    # ``gallery.web_interface.thumbnail_size`` was never read and is ignored.
+    THUMBNAIL_FORMATS = ("webp", "jxl", "jpeg")
+    THUMBNAIL_FORMAT = "webp"
+    THUMBNAIL_QUALITY = 80
+    THUMBNAIL_EDGE = 512
+    THUMBNAIL_EDGE_RANGE = (128, 2048)
+
     @classmethod
     def max_worker_threads(cls) -> int:
         """Largest accepted worker-thread count: the detected core count."""
@@ -617,6 +727,13 @@ class PromptManagerConfig:
                 "auto_backup_interval": cls.AUTO_BACKUP_INTERVAL,
                 "worker_threads": cls.WORKER_THREADS,
             },
+            "maintenance": {"safety_backup": cls.SAFETY_BACKUP},
+            "library": {"keep_in_node_folder": cls.KEEP_LIBRARY_IN_NODE_FOLDER},
+            "thumbnails": {
+                "format": cls.THUMBNAIL_FORMAT,
+                "quality": cls.THUMBNAIL_QUALITY,
+                "edge": cls.THUMBNAIL_EDGE,
+            },
             "gallery": GalleryConfig.get_config(),
             "integrations": IntegrationConfig.get_config(),
             "autotag": AutotagConfig.get_config(),
@@ -626,14 +743,12 @@ class PromptManagerConfig:
     def get_config_path(cls) -> str:
         """Path of the persisted config.json.
 
-        Honours ``PROMPT_MANAGER_CONFIG_PATH`` when set; otherwise the file
-        lives at the repository root next to ``pyproject.toml``.
+        Honours ``PROMPT_MANAGER_CONFIG_PATH`` when set; otherwise it lives in
+        the library's data folder (``utils.library_location``): the node
+        folder for a library that was not moved, else ComfyUI's
+        ``user/__promptmanager``.
         """
-        override = os.environ.get(CONFIG_PATH_ENV, "").strip()
-        if override:
-            return override
-        repo_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-        return os.path.join(repo_root, "config.json")
+        return library_location.config_location()[0]
 
     @classmethod
     def load_from_file(cls, config_path: Optional[str] = None):
@@ -752,6 +867,20 @@ class PromptManagerConfig:
                 performance["worker_threads"], cls.WORKER_THREADS
             )
 
+        maintenance = new_config.get("maintenance", {})
+        if isinstance(maintenance, dict) and isinstance(
+            maintenance.get("safety_backup"), bool
+        ):
+            cls.SAFETY_BACKUP = maintenance["safety_backup"]
+
+        library = new_config.get("library", {})
+        if isinstance(library, dict) and isinstance(
+            library.get("keep_in_node_folder"), bool
+        ):
+            cls.KEEP_LIBRARY_IN_NODE_FOLDER = library["keep_in_node_folder"]
+
+        cls._update_thumbnails(new_config.get("thumbnails"))
+
         # Update gallery config
         if "gallery" in new_config:
             GalleryConfig.update_config(new_config["gallery"])
@@ -763,6 +892,22 @@ class PromptManagerConfig:
         if "autotag" in new_config:
             AutotagConfig.update_config(new_config["autotag"])
 
+    @classmethod
+    def _update_thumbnails(cls, section: Any) -> None:
+        """Apply a ``thumbnails`` section; a hand-edited bad value is ignored."""
+        if not isinstance(section, dict):
+            return
+        fmt = section.get("format")
+        if fmt in cls.THUMBNAIL_FORMATS:
+            cls.THUMBNAIL_FORMAT = fmt
+        quality = section.get("quality")
+        if type(quality) is int and 1 <= quality <= 100:
+            cls.THUMBNAIL_QUALITY = quality
+        edge = section.get("edge")
+        low, high = cls.THUMBNAIL_EDGE_RANGE
+        if type(edge) is int and low <= edge <= high:
+            cls.THUMBNAIL_EDGE = edge
+
 
 # Load configuration on import
 try:

py/lora_import.py

@@ -0,0 +1,173 @@
+"""The staged LoRA reference import (#221, #249 System S10).
+
+The import reads LoraManager's ``*.metadata.json`` files and turns each LoRA
+into one prompt of the ``lora-manager`` category, tagged with its name and
+trigger words and linked to its preview images. It runs in three stages, and
+only the last writes to the database:
+
+1. **discover**: list the metadata files (``discover``) and fingerprint them
+   (path, size and modification time; ``fingerprint``). ``preview`` adds the
+   counts a review shows. Nothing is written and nothing is requested.
+2. **stage**: read each file and build its record; CivitAI example images are
+   downloaded into the image cache first (best effort, counted). A cancelled
+   or failed stage leaves the database untouched; downloaded images stay in
+   the cache.
+3. **replace**: the files are listed and fingerprinted once more (a file
+   changed, removed or added while staging aborts the import), then
+   ``PromptDatabase.replace_category_prompts`` swaps the old collection for
+   the staged records in one transaction (or changes nothing).
+
+Both the System job (``POST /lora/import/apply``) and the legacy ``POST
+/lora/scan`` run these stages (``py/api/lora_integration.py``).
+"""
+
+import hashlib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Dict, List, Optional
+
+from . import lora_utils
+
+try:
+    from ..utils.hashing import generate_prompt_hash
+except ImportError:  # pragma: no cover - flat test imports
+    from utils.hashing import generate_prompt_hash
+
+LORA_CATEGORY = "lora-manager"
+JOB_TITLE = "LoRA reference import"
+# The job's outcome groups, in its counter-tile order.
+GROUPS = ("imported", "linked", "skipped", "downloaded", "download_errors", "errors")
+METADATA_SUFFIX = "*.metadata.json"
+
+
+class ImportCancelled(Exception):
+    """The import was cancelled while staging; nothing was written."""
+
+
+def discover(lora_manager_path: str) -> List[Path]:
+    """Every LoRA metadata file, sorted and without repeats.
+
+    Raises whatever listing a folder raised: a discovery that cannot see
+    every folder must not replace the collection with part of it.
+    """
+    seen = set()
+    files = []
+    for folder in lora_utils.find_lora_directories(lora_manager_path):
+        for path in Path(folder).rglob(METADATA_SUFFIX):
+            key = str(path)
+            if key not in seen:
+                seen.add(key)
+                files.append(path)
+    files.sort(key=str)
+    return files
+
+
+def fingerprint(files: List[Path]) -> str:
+    """What a review saw of ``files``: each path, size and modification time."""
+    digest = hashlib.sha256()
+    for path in files:
+        try:
+            stat = path.stat()
+            entry = f"{path}\0{stat.st_size}\0{stat.st_mtime_ns}\n"
+        except OSError:
+            entry = f"{path}\0missing\n"
+        digest.update(entry.encode("utf-8", "surrogatepass"))
+    return "sha256:" + digest.hexdigest()
+
+
+def preview(lora_manager_path: str, cache_dir: Path) -> Dict:
+    """The review's counts (blocking; reads only, requests nothing).
+
+    ``{lora_files, with_metadata, planned_downloads, fingerprint, names}``:
+    the metadata files found, those that parse, the example images an import
+    would download (not yet in the cache) and the first LoRA names.
+    """
+    files = discover(lora_manager_path)
+    with_metadata = 0
+    planned = 0
+    names = []
+    for path in files:
+        metadata = lora_utils.read_lora_metadata(path)
+        if not metadata:
+            continue
+        with_metadata += 1
+        planned += lora_utils.planned_civitai_downloads(metadata, path, cache_dir)
+        if len(names) < 50:
+            names.append(lora_utils.get_model_name_from_metadata(metadata))
+    return {
+        "lora_files": len(files),
+        "with_metadata": with_metadata,
+        "planned_downloads": planned,
+        "fingerprint": fingerprint(files),
+        "names": names,
+    }
+
+
+def build_record(metadata: Dict, path: Path, images: List[str]) -> Dict:
+    """The prompt a LoRA becomes: its example prompt (else its name), tags, images."""
+    model_name = lora_utils.get_model_name_from_metadata(metadata)
+    text = lora_utils.get_example_prompt_from_metadata(metadata) or model_name
+    tags = ["lora-manager", f"lora:{model_name}"]
+    tags.extend(lora_utils.get_trigger_words_from_metadata(metadata))
+    return {
+        "name": model_name,
+        "text": text,
+        "hash": generate_prompt_hash(text),
+        "tags": list(dict.fromkeys(tags)),
+        "images": images,
+    }
+
+
+@dataclass
+class StagedImport:
+    """The records an import will write, and what staging counted."""
+
+    total: int
+    records: List[Dict] = field(default_factory=list)
+    skipped: List[str] = field(default_factory=list)
+    stats: Dict[str, int] = field(
+        default_factory=lambda: {"downloaded": 0, "download_errors": 0}
+    )
+
+
+def stage(
+    files: List[Path],
+    cache_dir: Path,
+    api_key: str = "",
+    *,
+    on_record: Optional[Callable[[int, Dict, "StagedImport"], None]] = None,
+    cancelled: Callable[[], bool] = lambda: False,
+    logger=None,
+) -> StagedImport:
+    """Read each file and build its record, downloading its example images.
+
+    Blocking. A file that cannot be read, or whose record fails to build, is
+    skipped by its name. ``cancelled()`` is asked before each file (raises
+    ImportCancelled); ``on_record(index, record_or_None, staged)`` follows
+    each one.
+    """
+    staged = StagedImport(total=len(files))
+    for index, path in enumerate(files):
+        if cancelled():
+            raise ImportCancelled()
+        record = None
+        metadata = lora_utils.read_lora_metadata(path)
+        if not metadata:
+            staged.skipped.append(path.name)
+        else:
+            try:
+                local = lora_utils.get_preview_images_from_metadata(metadata, path)
+                remote = lora_utils.download_civitai_images(
+                    metadata, path, cache_dir, api_key, stats=staged.stats
+                )
+                images = list(dict.fromkeys([*local, *remote]))
+                record = build_record(metadata, path, images)
+                staged.records.append(record)
+            except Exception as error:  # one LoRA never stops the import
+                name = lora_utils.get_model_name_from_metadata(metadata)
+                if logger is not None:
+                    logger.warning(f"Failed to prepare LoRA {name}: {error}")
+                staged.skipped.append(name)
+        if on_record is not None:
+            on_record(index, record, staged)
+    return staged

py/lora_utils.py

@@ -8,14 +8,16 @@ return empty results rather than raising.
 """
 
 import hashlib
+import http.client
 import json
 import os
 import re
 import threading
+import urllib.error
 import urllib.request
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
-from urllib.parse import urlsplit
+from urllib.parse import urljoin, urlsplit
 
 try:
     from ..utils.logging_config import get_logger
@@ -82,23 +84,46 @@ def detect_lora_manager(custom_path: str = "") -> Optional[str]:
         if p.is_dir() and _looks_like_lora_manager(p):
             return str(p.resolve())
 
-    # 2. Auto-detect via custom_nodes (case-insensitive scan)
+    # 2. Auto-detect in every custom_nodes folder (case-insensitive scan):
+    # ComfyUI's own first, then the extra ones it registered (#144).
+    folders = []
     root = find_comfyui_root()
     if root:
-        custom_nodes = root / "custom_nodes"
-        if custom_nodes.is_dir():
-            for entry in custom_nodes.iterdir():
-                if (
-                    entry.is_dir()
-                    and "lora" in entry.name.lower()
-                    and "manager" in entry.name.lower()
-                    and _looks_like_lora_manager(entry)
-                ):
-                    return str(entry.resolve())
+        folders.append(root / "custom_nodes")
+    folders.extend(custom_nodes_directories())
+    seen = set()
+    for custom_nodes in folders:
+        key = os.path.normcase(os.path.abspath(str(custom_nodes)))
+        if key in seen:
+            continue
+        seen.add(key)
+        found = _lora_manager_in(Path(custom_nodes))
+        if found:
+            return found
 
     return None
 
 
+def _lora_manager_in(custom_nodes: Path) -> Optional[str]:
+    """The LoraManager install directly under ``custom_nodes``, or None."""
+    try:
+        entries = sorted(custom_nodes.iterdir()) if custom_nodes.is_dir() else []
+    except OSError:
+        return None
+    for entry in entries:
+        try:
+            if (
+                entry.is_dir()
+                and "lora" in entry.name.lower()
+                and "manager" in entry.name.lower()
+                and _looks_like_lora_manager(entry)
+            ):
+                return str(entry.resolve())
+        except OSError:
+            continue
+    return None
+
+
 def _looks_like_lora_manager(path: Path) -> bool:
     """Heuristic: does this directory look like a LoraManager install?"""
     # Must have __init__.py (ComfyUI extension) or README.md
@@ -396,19 +421,40 @@ def get_preview_image_from_metadata(
 
 _THUMB_MAX_SIZE = 512
 
+# CivitAI's own domains (#340: civitai.red and civitai.green serve the same
+# content as civitai.com).
+CIVITAI_DOMAINS = ("civitai.com", "civitai.red", "civitai.green")
 # Only these hosts may ever receive the CivitAI API key, and only over HTTPS.
 CIVITAI_HOSTS = frozenset(
-    {"civitai.com", "www.civitai.com", "api.civitai.com", "image.civitai.com"}
+    f"{prefix}{domain}"
+    for domain in CIVITAI_DOMAINS
+    for prefix in ("", "www.", "api.", "image.")
 )
 MAX_CIVITAI_DOWNLOAD_BYTES = 50 * 1024 * 1024
 _DOWNLOAD_CHUNK_BYTES = 64 * 1024
 
 
+# A redirect is followed (#337: image.civitai.com now answers with a redirect
+# to blobs-b2.civitai.com) only over HTTPS to one of CIVITAI_DOMAINS or a
+# subdomain of one, at most this many hops, and never with the API key.
+MAX_CIVITAI_REDIRECTS = 3
+_REDIRECT_CODES = frozenset({301, 302, 303, 307, 308})
+_USER_AGENT = "ComfyUI-PromptManager/1.0"
+
+
+class _DownloadFailed(Exception):
+    """A download failed for the short, loggable ``reason`` it carries."""
+
+    def __init__(self, reason: str):
+        super().__init__(reason)
+        self.reason = reason
+
+
 class _RefuseRedirects(urllib.request.HTTPRedirectHandler):
-    """Never follow a redirect: urllib would re-send the Bearer header to it."""
+    """Never follow a redirect inside urllib: it would re-send the Bearer
+    header. A 3xx surfaces as ``HTTPError``; ``_download_one`` decides."""
 
     def redirect_request(self, req, fp, code, msg, headers, newurl):
-        logger.warning(f"Refusing redirect from {req.full_url} to {newurl}")
         return None
 
 
@@ -425,6 +471,84 @@ def _open_url(req: urllib.request.Request, timeout: float = 10):
     return _opener.open(req, timeout=timeout)
 
 
+def _loggable(url: str) -> str:
+    """``url`` without its query, fragment or credentials (signed URLs)."""
+    try:
+        parts = urlsplit(url)
+        host = parts.hostname or ""
+    except ValueError:
+        return "<unparsable URL>"
+    return f"{parts.scheme}://{host}{parts.path}"
+
+
+def _on_civitai_domain(hostname: str) -> bool:
+    """True when ``hostname`` is one of CIVITAI_DOMAINS or a subdomain of one."""
+    return any(
+        hostname == domain or hostname.endswith(f".{domain}")
+        for domain in CIVITAI_DOMAINS
+    )
+
+
+def is_civitai_redirect_target(url: str) -> bool:
+    """True when a redirect to ``url`` may be followed: HTTPS on one of
+    CIVITAI_DOMAINS or a subdomain of one, matched on the parsed host name,
+    default port and no credentials in the URL."""
+    try:
+        parts = urlsplit(url)
+        port = parts.port
+    except ValueError:
+        return False
+    hostname = (parts.hostname or "").lower()
+    return (
+        parts.scheme == "https"
+        and _on_civitai_domain(hostname)
+        and parts.username is None
+        and parts.password is None
+        and port in (None, 443)
+    )
+
+
+def _redirect_target(url: str, error) -> Optional[str]:
+    """The URL a 3xx ``error`` for ``url`` points to, or None when absent."""
+    if error.code not in _REDIRECT_CODES:
+        return None
+    location = (error.headers.get("Location") or "").strip()
+    if not location:
+        return None
+    return urljoin(url, location)
+
+
+def _open_following_civitai_redirects(url: str, api_key: str):
+    """Open ``url``, following only allowed CivitAI redirects (keyless).
+
+    The first request carries the key; every redirected one carries the
+    User-Agent alone. Returns the open response; raises ``_DownloadFailed``
+    when a redirect is refused or the hop limit is reached. Other HTTP
+    errors propagate.
+    """
+    headers = {"User-Agent": _USER_AGENT}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    current = url
+    for hop in range(MAX_CIVITAI_REDIRECTS + 1):
+        req = urllib.request.Request(current, headers=headers)
+        try:
+            return _open_url(req, timeout=10)
+        except urllib.error.HTTPError as error:
+            with error:
+                target = _redirect_target(current, error)
+            if target is None:
+                raise
+        if hop == MAX_CIVITAI_REDIRECTS:
+            raise _DownloadFailed(f"more than {MAX_CIVITAI_REDIRECTS} redirects")
+        if not is_civitai_redirect_target(target):
+            raise _DownloadFailed(f"redirect refused to {_loggable(target)}")
+        logger.debug(f"Following redirect to {_loggable(target)}")
+        current = target
+        headers = {"User-Agent": _USER_AGENT}  # never the key across a redirect
+    raise AssertionError("unreachable")  # pragma: no cover - loop ends above
+
+
 def is_civitai_url(url: str) -> bool:
     """True when ``url`` is an HTTPS URL on an allow-listed CivitAI host."""
     try:
@@ -465,73 +589,160 @@ def _read_capped(resp, cap: int) -> Optional[bytes]:
     return b"".join(chunks)
 
 
+def _network_reason(error: BaseException) -> str:
+    """A short reason for a failed request: a timeout or a network error."""
+    cause = getattr(error, "reason", error)  # URLError wraps the socket error
+    if isinstance(cause, TimeoutError):
+        return "timed out"
+    return f"network error: {cause}"
+
+
+def _fetch_civitai_body(url: str, api_key: str) -> bytes:
+    """The body behind ``url`` (redirects as allowed, size capped), or
+    ``_DownloadFailed`` with the reason it could not be fetched."""
+    try:
+        with _open_following_civitai_redirects(url, api_key) as resp:
+            raw = _read_capped(resp, MAX_CIVITAI_DOWNLOAD_BYTES)
+    except urllib.error.HTTPError as error:
+        error.close()
+        raise _DownloadFailed(f"HTTP {error.code}") from None
+    except (urllib.error.URLError, OSError, http.client.HTTPException) as error:
+        raise _DownloadFailed(_network_reason(error)) from None
+    if raw is None:
+        cap = MAX_CIVITAI_DOWNLOAD_BYTES
+        size = f"{cap // (1024 * 1024)} MB" if cap >= 1024 * 1024 else f"{cap} byte"
+        raise _DownloadFailed(f"larger than the {size} cap")
+    return raw
+
+
+def _thumbnail(raw: bytes):
+    """``raw`` decoded and shrunk to an RGB thumbnail, or ``_DownloadFailed``."""
+    from io import BytesIO
+
+    from PIL import Image
+
+    try:
+        with Image.open(BytesIO(raw)) as img:
+            img.thumbnail((_THUMB_MAX_SIZE, _THUMB_MAX_SIZE), Image.LANCZOS)
+            return img.convert("RGB")
+    except Exception as error:  # PIL raises several types for bad data
+        raise _DownloadFailed(
+            f"image could not be decoded ({type(error).__name__})"
+        ) from None
+
+
 def _download_one(url: str, local_path: Path, api_key: str) -> Optional[str]:
     """Download a single CivitAI image, resize to thumbnail, save as JPEG.
 
     Refuses any URL that is not HTTPS on an allow-listed CivitAI host so the
-    API key is never sent elsewhere, and refuses bodies larger than
-    MAX_CIVITAI_DOWNLOAD_BYTES.
+    API key is never sent elsewhere, follows a redirect only as
+    ``_open_following_civitai_redirects`` allows (without the key), and
+    refuses bodies larger than MAX_CIVITAI_DOWNLOAD_BYTES. A failure logs
+    one warning with a short reason and the URL without query or
+    credentials (#340), and returns None.
     """
-    if not is_civitai_url(url):
-        logger.warning(f"Refusing non-CivitAI download URL: {url}")
-        return None
     try:
-        headers = {"User-Agent": "ComfyUI-PromptManager/1.0"}
-        if api_key:
-            headers["Authorization"] = f"Bearer {api_key}"
-        req = urllib.request.Request(url, headers=headers)
-        with _open_url(req, timeout=10) as resp:
-            raw = _read_capped(resp, MAX_CIVITAI_DOWNLOAD_BYTES)
-        if raw is None:
-            logger.warning(f"Refusing oversized download: {url}")
-            return None
-
-        # Resize to thumbnail to save disk space
-        from io import BytesIO
-
-        from PIL import Image
-
-        img = Image.open(BytesIO(raw))
-        img.thumbnail((_THUMB_MAX_SIZE, _THUMB_MAX_SIZE), Image.LANCZOS)
-        img = img.convert("RGB")
-        img.save(str(local_path), "JPEG", quality=85)
-
+        if not is_civitai_url(url):
+            raise _DownloadFailed("not an allowed CivitAI URL")
+        image = _thumbnail(_fetch_civitai_body(url, api_key))
+        try:
+            _save_atomically(image, local_path)
+        except OSError as error:
+            raise _DownloadFailed(
+                f"image could not be saved ({error.strerror or type(error).__name__})"
+            ) from None
+    except _DownloadFailed as failure:
+        reason = failure.reason
+    except Exception as error:  # best effort: an import never fails on one image
+        reason = f"unexpected {type(error).__name__}"
+    else:
         return str(local_path.resolve())
-    except Exception as e:
-        logger.debug(f"Failed to download {url}: {e}")
-        return None
+    logger.warning(f"CivitAI image download failed: {_loggable(url)}: {reason}")
+    return None
 
 
-def download_civitai_images(
-    metadata: Dict, metadata_path: Path, cache_dir: Path, api_key: str = ""
-) -> List[str]:
-    """Download civitai example images to a local cache directory.
+_PART_PREFIX = ".pm-"
+_PART_SUFFIX = ".part"
+# A temp download older than this was left by a killed process, not a live one
+# (each download has a 10 s timeout).
+STALE_PART_SECONDS = 3600
 
-    Uses thumbnail URLs (512px) instead of full-size originals, and
-    downloads in parallel (up to 8 concurrent) for speed.
 
-    Args:
-        api_key: CivitAI API key for authenticated downloads (NSFW content).
+def _save_atomically(image, local_path: Path) -> None:
+    """Write ``image`` as JPEG so ``local_path`` only ever names a whole file.
 
-    Returns:
-        List of absolute paths to downloaded image files.
+    The image goes to a ``.pm-*.part`` file in the same folder, which is
+    closed before ``os.replace`` puts it in place (Windows cannot replace an
+    open file); a failure removes the temp file. A reader (another import's
+    cache check) never sees a half-written image. The temp file is opened
+    like ``img.save`` opens a file, so the image keeps the umask's mode.
     """
-    from concurrent.futures import ThreadPoolExecutor
+    import secrets
 
+    while True:
+        temp = local_path.parent / (
+            f"{_PART_PREFIX}{secrets.token_hex(8)}{_PART_SUFFIX}"
+        )
+        try:
+            handle = open(temp, "xb")
+        except FileExistsError:
+            continue
+        break
+    try:
+        with handle:
+            image.save(handle, "JPEG", quality=85)
+        os.replace(temp, local_path)
+    except BaseException:
+        try:
+            os.remove(temp)
+        except OSError:
+            pass
+        raise
+
+
+def sweep_stale_downloads(cache_dir: Path) -> None:
+    """Remove ``.pm-*.part`` files a killed download left in the image cache.
+
+    Only that exact pattern, only in ``cache_dir`` and its LoRA folders, and
+    only once older than ``STALE_PART_SECONDS``; a file that cannot be read
+    or removed is left for a later import.
+    """
+    import time
+
+    cutoff = time.time() - STALE_PART_SECONDS
+    try:
+        folders = [cache_dir] + [p for p in cache_dir.iterdir() if p.is_dir()]
+    except OSError:
+        return
+    for folder in folders:
+        try:
+            candidates = list(folder.glob(f"{_PART_PREFIX}*{_PART_SUFFIX}"))
+        except OSError:
+            continue
+        for path in candidates:
+            try:
+                if path.is_file() and path.stat().st_mtime < cutoff:
+                    os.remove(path)
+            except OSError:
+                logger.debug(f"Could not remove stale download {path}")
+
+
+def _civitai_cache_plan(
+    metadata: Dict, metadata_path: Path, cache_dir: Path
+) -> Tuple[Path, List[str], List[Tuple[str, Path]]]:
+    """``(lora_cache, cached, tasks)`` for a LoRA's CivitAI example images.
+
+    ``cached`` are the images already in the cache, ``tasks`` the
+    ``(url, local_path)`` downloads still needed. Reads only; creates nothing.
+    """
     civitai = _get_civitai(metadata)
     images = civitai.get("images", []) or []
-    if not images:
-        return []
 
     file_name = metadata.get("file_name", "")
     if not file_name:
         file_name = metadata_path.name.replace(".metadata.json", "")
-    lora_stem = Path(file_name).stem
+    lora_cache = cache_dir / Path(file_name).stem
 
-    lora_cache = cache_dir / lora_stem
-    lora_cache.mkdir(parents=True, exist_ok=True)
-
-    # Build download tasks
     cached = []
     tasks = []  # (url, local_path)
     for img in images:
@@ -548,9 +759,42 @@ def download_civitai_images(
             cached.append(str(local_path.resolve()))
         else:
             tasks.append((url, local_path))
+    return lora_cache, cached, tasks
 
+
+def planned_civitai_downloads(
+    metadata: Dict, metadata_path: Path, cache_dir: Path
+) -> int:
+    """How many example images an import would download (no request, no write)."""
+    return len(_civitai_cache_plan(metadata, metadata_path, cache_dir)[2])
+
+
+def download_civitai_images(
+    metadata: Dict,
+    metadata_path: Path,
+    cache_dir: Path,
+    api_key: str = "",
+    stats: Optional[Dict[str, int]] = None,
+) -> List[str]:
+    """Download civitai example images to a local cache directory.
+
+    Uses thumbnail URLs (512px) instead of full-size originals, and
+    downloads in parallel (up to 8 concurrent) for speed.
+
+    Args:
+        api_key: CivitAI API key for authenticated downloads (NSFW content).
+        stats: When given, ``downloaded`` and ``download_errors`` are
+            increased by the downloads that succeeded and failed.
+
+    Returns:
+        List of absolute paths to downloaded image files.
+    """
+    from concurrent.futures import ThreadPoolExecutor
+
+    lora_cache, cached, tasks = _civitai_cache_plan(metadata, metadata_path, cache_dir)
     if not tasks:
         return cached
+    lora_cache.mkdir(parents=True, exist_ok=True)
 
     # Download in parallel
     downloaded = []
@@ -563,15 +807,33 @@ def download_civitai_images(
             if result:
                 downloaded.append(result)
 
+    if stats is not None:
+        stats["downloaded"] = stats.get("downloaded", 0) + len(downloaded)
+        stats["download_errors"] = (
+            stats.get("download_errors", 0) + len(tasks) - len(downloaded)
+        )
     return cached + downloaded
 
 
-def get_lora_image_cache_dir() -> Path:
-    """Get the directory used to cache downloaded LoRA example images."""
-    # Store in the extension's own directory
+def get_lora_image_cache_dir(create: bool = True) -> Path:
+    """Get the directory used to cache downloaded LoRA example images.
+
+    ``<data folder>/data/lora_images`` (``utils.library_location``): the node
+    folder for a library that was not moved, else ComfyUI's
+    ``user/__promptmanager``. ``create=False`` only names it (a preview
+    writes nothing).
+    """
+    try:
+        from ..utils import library_location
+    except ImportError:
+        from utils import library_location
+
     ext_root = Path(__file__).resolve().parent.parent
-    cache = ext_root / "data" / "lora_images"
-    cache.mkdir(parents=True, exist_ok=True)
+    cache = Path(
+        library_location.cache_dir("lora_images", extension_root=str(ext_root))
+    )
+    if create:
+        cache.mkdir(parents=True, exist_ok=True)
     return cache
 
 

pyproject.toml

@@ -7,7 +7,7 @@ requires-python = ">=3.10"
 dependencies = ["watchdog>=2.1.0", "Pillow>=8.0.0"]
 
 [build-system]
-requires = ["setuptools>=84.0.0"]
+requires = ["setuptools>=84.2.1"]
 build-backend = "setuptools.build_meta"
 
 [project.urls]

tests/browser/classic-node.spec.mjs

@@ -149,3 +149,49 @@ test('Classic test button reports success and failure and releases expired notif
     await page.clock.fastForward(3001);
     await expect(page.locator('.pm-classic-notification')).toHaveCount(0);
 });
+
+test('Classic shows linked text, keeps the typed text through save and refuses to overwrite it (#343)',async({page})=>{
+    await page.route('**/prompt_manager/recent?**',route=>route.fulfill({json:{success:true,results:[{text:'Saved prompt',tags:[]}]}}));
+    const note=page.locator('.pm-classic').getByText('Text comes from a link. Your typed text is kept for when you disconnect it.',{exact:true});
+    await expect(note).toBeHidden();
+    await page.evaluate(()=>{
+        const widget=node.widgets.find(item=>item.name==='text');widget.value=widget.inputEl.value='Typed classic';
+        node.inputs=[{name:'text',type:'STRING',link:3,widget:{name:'text'}}];node.onConnectionsChange();
+    });
+    await expect(note).toBeVisible();
+    // The link drives the run; the saved workflow keeps what the user typed, not a stale or empty value.
+    expect(await page.evaluate(()=>node.serialize().widgets_values[0])).toBe('Typed classic');
+    await page.getByRole('button',{name:'📋 Recent',exact:true}).click();
+    await page.getByRole('button',{name:/Saved prompt/}).click();
+    expect(await page.evaluate(()=>node.widgets.find(item=>item.name==='text').value)).toBe('Typed classic');
+    await expect(page.getByRole('alert').filter({hasText:'Text comes from a link. Disconnect it to use a saved prompt.'})).toBeVisible();
+    await page.evaluate(()=>{node.inputs[0].link=null;node.onConnectionsChange();});
+    await expect(note).toBeHidden();
+    await page.getByRole('button',{name:/Saved prompt/}).click();
+    expect(await page.evaluate(()=>node.widgets.find(item=>item.name==='text').value)).toBe('Saved prompt');
+    // A workflow load re-evaluates the link state.
+    await page.evaluate(()=>{node.inputs[0].link=8;node.configure({});});
+    await expect(note).toBeVisible();
+});
+
+test('PromptManagerText shows linked text in its legacy controls and keeps the typed text (#343)',async({page})=>{
+    await page.evaluate(async()=>{
+        class TextNode {
+            constructor(){this.widgets=['text','category','tags','search_text'].map(name=>({name,value:'',inputEl:document.createElement('textarea')}));this.widgets_values=[];this.inputs=[{name:'text',type:'STRING',link:null,widget:{name:'text'}}];}
+            addDOMWidget(name,type,element){element.id='legacy-text-node';document.body.append(element);return {element};}
+            setSize(){} setDirtyCanvas(){} serialize(){return {properties:{...this.properties}};}
+        }
+        await fixtureApp.extensions[0].beforeRegisterNodeDef(TextNode,{name:'PromptManagerText'},fixtureApp);
+        window.textNode=new TextNode();textNode.onNodeCreated();
+        const widget=textNode.widgets[0];widget.value=widget.inputEl.value='Typed text node';
+    });
+    const note=page.locator('#legacy-text-node').getByText('Text comes from a link. Your typed text is kept for when you disconnect it.',{exact:true});
+    await expect(note).toBeHidden();
+    await page.evaluate(()=>{textNode.inputs[0].link=5;textNode.onConnectionsChange();});
+    await expect(note).toBeVisible();
+    expect(await page.evaluate(()=>textNode.serialize().widgets_values[0])).toBe('Typed text node');
+    await page.evaluate(()=>{textNode.usePrompt({text:'Replacement'},0);});
+    expect(await page.evaluate(()=>textNode.widgets[0].value)).toBe('Typed text node');
+    await page.evaluate(()=>{textNode.inputs[0].link=null;textNode.onConnectionsChange();textNode.onRemoved();});
+    await expect(note).toBeHidden();
+});

tests/browser/concept-inventory.mjs

@@ -127,6 +127,8 @@ export async function openProduction(page,route,theme,motion='no-preference') {
     await expect(page.locator('#primary-nav .nav-count')).toHaveCount(3);
     // SAVED VIEWS' Favorites count (D51), the concept's starred images in the concept fixture.
     await expect(page.locator('#saved-nav a[data-route="favorites"] .nav-count')).toHaveCount(1);
+    // SAVED VIEWS' Needs review count (ruling R5): the exact pending count.
+    await expect(page.locator('#saved-nav a[data-route="review"] .nav-count')).toHaveCount(1);
 }
 
 /** Computed outline of the focused element, after keyboard focus so `:focus-visible` applies. */

tests/browser/focused-node.spec.mjs

@@ -26,7 +26,8 @@ test.beforeEach(async({page,browserName})=>{
         window.fixtureApp={registerExtension(extension){this.extension=extension;},ui:{settings:new EventTarget()},graph:{setDirtyCanvas(){}},canvas:{}};
         await import('/extensions/promptmanager/prompt_manager.js');
         class Node {
-            constructor(){this.widgets=['text','category','tags','search_text'].map(name=>({name,type:'text',value:'',options:{},inputEl:document.createElement('textarea')}));this.inputs=['clip','prepend_text','append_text'].map(name=>({name,link:null}));this.properties={};this.size=[550,700];}
+            constructor(){this.widgets=['text','category','tags','search_text'].map(name=>({name,type:'text',value:'',options:{},inputEl:document.createElement('textarea')}));this.inputs=[...['clip','prepend_text','append_text'].map(name=>({name,type:name==='clip'?'CLIP':'STRING',link:null})),...['text','category','tags','search_text'].map(name=>({name,type:'STRING',link:null,widget:{name}}))];this.properties={};this.size=[550,700];}
+            findInputByType(type){const index=this.inputs.findIndex(input=>input.type===type&&input.link==null);return index<0?undefined:{index,slot:this.inputs[index]};}
             addWidget(type,name,value,callback,options){const widget={type,name,value,callback,options};this.widgets.push(widget);return widget;}
             addDOMWidget(name,type,element){const host=document.createElement('div');host.style.height='650px';host.className='fixture-dom-widget';host.append(element);document.body.append(host);return {element};}
             setSize(size){this.size=size;}setDirtyCanvas(){}
@@ -246,13 +247,39 @@ test(`${variant} restores workflow values and disclosures and protects connected
     await page.evaluate(()=>{const saved=node.serialize();node.configure(saved);});
     await expect(page.getByLabel('Category',{exact:true})).toBeVisible();
     await expect(page.getByLabel('Category',{exact:true})).toHaveValue('Saved category');
-    await page.evaluate(()=>{node.inputs.push({name:'text',link:9});node.onConnectionsChange();});
+    await page.evaluate(()=>{node.inputs.find(input=>input.name==='text').link=9;node.onConnectionsChange();});
     await expect(page.getByRole('textbox',{name:'Main prompt',exact:true})).toBeHidden();
-    await expect(page.getByText('Text is supplied by an upstream connection.',{exact:true})).toBeVisible();
+    await expect(page.getByText('Main prompt comes from a link. Your typed text is kept for when you disconnect it.',{exact:true})).toBeVisible();
     await page.evaluate(()=>{node.inputs.find(input=>input.name==='text').link=null;node.onConnectionsChange();});
     await expect(page.getByRole('textbox',{name:'Main prompt',exact:true})).toHaveValue('Saved draft');
 });
 
+test(`${variant} offers text as a link socket, keeps typed text while linked and through a reload (#343)`,async({page})=>{
+    const sockets=()=>page.evaluate(()=>Object.fromEntries(node.inputs.map(input=>[input.name,input.widget?.name??null])));
+    // The hidden text widget no longer owns the input, so the host draws it as a socket; the other widget inputs are unchanged.
+    expect(await sockets()).toEqual({clip:null,prepend_text:null,append_text:null,text:null,category:'category',tags:'tags',search_text:'search_text'});
+    expect(await page.evaluate(()=>node.findInputByType('STRING').slot.name)).toBe('text');
+    expect(await page.evaluate(()=>node.findInputByType('CLIP').slot.name)).toBe('clip');
+    const main=page.getByRole('textbox',{name:'Main prompt',exact:true});
+    await main.fill('Typed main');
+    await page.evaluate(()=>{node.inputs.find(input=>input.name==='text').link=21;node.onConnectionsChange();});
+    await expect(main).toBeHidden();
+    const note=page.getByText('Main prompt comes from a link. Your typed text is kept for when you disconnect it.',{exact:true});
+    await expect(note).toBeVisible();
+    await expect(page.locator('[data-composed-preview]')).toHaveText('[text supplied by connection]');
+    // A second STRING link dropped on the editor falls back to the frontend's own choice.
+    expect(await page.evaluate(()=>node.findInputByType('STRING').slot.name)).toBe('prepend_text');
+    // An older saved workflow brings the widget binding back with its inputs: configure exposes the socket again.
+    const saved=await page.evaluate(()=>{const saved=node.serialize();node.inputs.find(input=>input.name==='text').widget={name:'text'};node.configure(saved);return saved;});
+    expect(saved.widgets_values[0]).toBe('Typed main');
+    expect((await sockets()).text).toBeNull();
+    await expect(note).toBeVisible();
+    await page.evaluate(()=>{node.inputs.find(input=>input.name==='text').link=null;node.onConnectionsChange();});
+    await expect(main).toBeVisible();
+    await expect(main).toHaveValue('Typed main');
+    await expect(note).toBeHidden();
+});
+
 test(`${variant} searches quoted tags with Enter and explicitly loads metadata`, async ({page}) => {
     let requested;
     await page.route('**/prompt_manager/search?**', async route => {

tests/browser/pair-node.spec.mjs

@@ -17,7 +17,8 @@ test.beforeEach(async({page,browserName})=>{
         window.fixtureApp={registerExtension(extension){this.extension=extension;},ui:{settings},graph:{_nodes:[],setDirtyCanvas(){}},canvas:{},graphToPrompt:async()=>({})};
         await import('/extensions/promptmanager/prompt_manager.js');
         class Node {
-            constructor(){this.id=1;this.type='PromptManagerPair';this.widgets=['text','negative_text','category','tags','search_text'].map(name=>({name,type:'text',value:'',options:{},inputEl:document.createElement('textarea')}));this.inputs=['clip','prepend_text','append_text'].map(name=>({name,link:null}));this.properties={};this.size=[1100,700];}
+            constructor(){this.id=1;this.type='PromptManagerPair';this.widgets=['text','negative_text','category','tags','search_text'].map(name=>({name,type:'text',value:'',options:{},inputEl:document.createElement('textarea')}));this.inputs=[...['clip','prepend_text','append_text'].map(name=>({name,type:name==='clip'?'CLIP':'STRING',link:null})),...['text','negative_text','category','tags','search_text'].map(name=>({name,type:'STRING',link:null,widget:{name}}))];this.properties={};this.size=[1100,700];}
+            findInputByType(type){const index=this.inputs.findIndex(input=>input.type===type&&input.link==null);return index<0?undefined:{index,slot:this.inputs[index]};}
             addWidget(type,name,value,callback,options){const widget={type,name,value,callback,options};this.widgets.push(widget);return widget;}
             addDOMWidget(name,type,element){const host=document.createElement('div');host.style.cssText='height:700px;width:1100px;max-width:100%';host.className='fixture-dom-widget';host.append(element);document.body.append(host);return {element};}
             setSize(size){this.size=size;}setDirtyCanvas(){}
@@ -123,6 +124,46 @@ test('a superseded library response never replaces the latest pair selection',as
     await expect(page.locator('.pm-editor-result')).not.toContainText('Stale positive');
 });
 
+test('paired editor offers positive and negative link sockets and keeps both typed texts (#343)',async({page})=>{
+    await draft(page,'Typed positive','Typed negative');
+    expect(await page.evaluate(()=>node.inputs.filter(input=>!input.widget).map(input=>input.name))).toEqual(['clip','prepend_text','append_text','text','negative_text']);
+    const target=()=>page.evaluate(()=>node.findInputByType('STRING').slot.name);
+    expect(await target()).toBe('text');
+    const positive=page.getByRole('textbox',{name:'Positive prompt',exact:true}),negative=page.getByRole('textbox',{name:'Negative prompt',exact:true});
+    const positiveNote=page.getByText('Positive prompt comes from a link. Your typed text is kept for when you disconnect it.',{exact:true});
+    const negativeNote=page.getByText('Negative prompt comes from a link. Your typed text is kept for when you disconnect it.',{exact:true});
+    const link=(name,value)=>page.evaluate(({name,value})=>{node.inputs.find(input=>input.name===name).link=value;node.onConnectionsChange();},{name,value});
+    for(const [linked,next] of [[['text'],'negative_text'],[['negative_text'],'text'],[['text','negative_text'],'prepend_text'],[[],'text']]){
+        for(const name of ['text','negative_text'])await link(name,linked.includes(name)?30:null);
+        expect(await target()).toBe(next);
+        await expect(positive).toBeVisible({visible:!linked.includes('text')});
+        await expect(negative).toBeVisible({visible:!linked.includes('negative_text')});
+        await expect(positiveNote).toBeVisible({visible:linked.includes('text')});
+        await expect(negativeNote).toBeVisible({visible:linked.includes('negative_text')});
+        const saved=await page.evaluate(()=>{const saved=node.serialize();for(const input of node.inputs)if(['text','negative_text'].includes(input.name))input.widget={name:input.name};node.configure(saved);return saved.widgets_values.slice(0,2);});
+        expect(saved).toEqual(['Typed positive','Typed negative']);
+        expect(await page.evaluate(()=>node.inputs.filter(input=>input.widget&&['text','negative_text'].includes(input.name)).length)).toBe(0);
+    }
+    await expect(positive).toHaveValue('Typed positive');await expect(negative).toHaveValue('Typed negative');
+});
+
+test('a link dropped on either prompt box, or its note, fills that box (#343 review M1)',async({page})=>{
+    const keys=await page.evaluate(()=>[...document.querySelectorAll('.pm-pair .lg-node-widget [data-slot-key]')].map(key=>key.dataset.slotKey));
+    // Nodes 2.0 resolves a drop through the nearest .lg-node-widget and its slot key: positive box and note, negative box and note.
+    expect(keys).toEqual(['1-in-3','1-in-3','1-in-4','1-in-4']);
+    const at=(name,connecting=true)=>page.evaluate(({name,connecting})=>{
+        fixtureApp.canvas={linkConnector:{state:{connectingTo:connecting?'input':undefined}},ds:{convertOffsetToCanvas:point=>point},canvas:{getBoundingClientRect:()=>({left:0,top:0})}};
+        const box=[...document.querySelectorAll('.pm-pair .lg-node-widget')].find(element=>element.getClientRects().length&&element.textContent.includes(name)).getBoundingClientRect();
+        return node.getInputOnPos([box.left+box.width/2,box.top+box.height/2])?.name??null;
+    },{name,connecting});
+    expect(await at('Negative prompt')).toBe('negative_text');
+    expect(await at('Positive prompt')).toBe('text');
+    expect(await at('Negative prompt',false)).toBeNull();
+    await page.evaluate(()=>{node.inputs.find(input=>input.name==='negative_text').link=4;node.onConnectionsChange();});
+    expect(await at('Negative prompt comes from a link')).toBe('negative_text');
+    expect(await page.evaluate(()=>{fixtureApp.canvas={};return node.getInputOnPos([1,1])??null;})).toBeNull();
+});
+
 test('queue hook synchronizes both editors, preserves links and forwards branch execution arguments',async({page})=>{
     await draft(page);
     const args=await page.evaluate(async()=>{

tests/browser/review-concept.spec.mjs

@@ -0,0 +1,212 @@
+// Needs review against the approved concept (#249 PR F, plan Task F3, Mock inventory M4: app.js renderReview
+// a749–760, style.css s407–415, s796–814 and their breakpoints, screenshot needs-review-tagging.png). Production runs
+// on the review fixture's concept-shaped queue (workspace_review_fixture.py `concept: true`: the concept's first three
+// image names and sizes, and the concept's first prompt on the open item), so every remaining difference is a recorded
+// deviation applied by mapConceptReview (D3, D29, D119) or a test failure. Paired captures of every state are attached
+// as artifacts; no screenshot baseline is added.
+import { test, expect } from './fixtures.mjs';
+import { openConcept, openProduction, inventoryOf, mutate, saveImageTags, diffInventory, SIZES, THEMES } from './concept-inventory.mjs';
+import { reviewInventory, mapConceptReview, taggingInventory, mapConceptTagging, diffTaggingInventory } from './tagging-canonical-comparison.mjs';
+
+const CONCEPT_FILE = 'alpine_00001.png';
+const CONCEPT_TAGS = ['cinematic', 'blue_hour', 'architecture'];
+const SURFACE = ['h2', 'p.small', 'div.row-actions.spaced-15', 'div.field', 'section.positive.prompt-section',
+    'section.negative.prompt-section', 'div.dialog-actions'];
+// The fake model's server default instructions (tests/browser/server.py TestModel.default_prompt), D84.
+const INSTRUCTIONS = 'Describe the image';
+
+const panel = page => page.locator('#workspace-main section.review-panel');
+const tagDialog = page => page.getByRole('dialog', { name: 'Tag image', exact: true });
+
+async function seed(request, data = {}) {
+    await expect(await request.post('/__test__/review/reset', { data: { items: 3, concept: true, ...data } })).toBeOK();
+}
+/** Production's Needs review page with its first item's sampler paths loaded. */
+async function openReview(page, theme) {
+    await openProduction(page, 'review', theme);
+    await expect(panel(page).getByRole('combobox', { name: 'Sampler context', exact: true })).toBeEnabled();
+    await settle(page);
+}
+async function settle(page) {
+    await page.mouse.move(0, 0);
+    await page.evaluate(async () => {
+        await document.fonts.ready;
+        await Promise.all([...document.images].map(image => image.decode().catch(() => {})));
+    });
+}
+const conceptInventory = page => page.evaluate(reviewInventory, '#main');
+const productionInventory = page => page.evaluate(reviewInventory, '#workspace-main');
+const node = (tree, prefix) => tree.tag?.startsWith(prefix) ? tree : tree.children?.map(child => node(child, prefix)).find(Boolean) ?? null;
+/** Computed values of CSS tokens, read through a probe element in the open page. */
+const tokens = (page, declarations) => page.evaluate(text => {
+    const probe = document.createElement('i');
+    probe.style.cssText = text;
+    document.body.append(probe);
+    const style = getComputedStyle(probe), values = [style.borderTopColor, style.backgroundColor];
+    probe.remove();
+    return values;
+}, declarations);
+
+async function compareAt(page, request, width, height, theme) {
+    await seed(request);
+    await page.setViewportSize({ width, height });
+    await openConcept(page, 'review', theme);
+    await settle(page);
+    const concept = await conceptInventory(page);
+    await openReview(page, theme);
+    const actual = await productionInventory(page);
+    return { concept, actual, reference: mapConceptReview(concept, actual) };
+}
+
+test.beforeEach(async ({ page }) => {
+    page.errors = [];
+    page.on('pageerror', error => page.errors.push(error.message));
+});
+test.afterEach(async ({ page, request }) => {
+    expect(page.errors).toEqual([]);
+    await request.post('/__test__/jobs/restart');
+});
+
+for (const [width, height] of SIZES) for (const theme of THEMES) {
+    test(`concept and production Metadata review match at ${width}x${height} ${theme}`, async ({ page, request }) => {
+        const { actual, reference } = await compareAt(page, request, width, height, theme);
+        expect(diffInventory(reference, actual), `${width}x${height} ${theme}`).toEqual([]);
+        // Pinned concept values (M4), so a mapping mistake on both sides cannot pass unseen.
+        const main = actual.main;
+        expect(main.children.map(child => child.tag)).toEqual(['div.heading', 'div.notice', 'div.gallery-layout']);
+        const notice = node(main, 'div.notice');
+        const [accent, soft] = await tokens(page, 'border-top:1px solid var(--ca-accent);background:var(--soft-blue)');
+        expect([notice.borderTopColor, notice.borderLeftColor, notice.backgroundColor]).toEqual([accent, accent, soft]);
+        expect([notice.borderTopWidth, notice.borderTopLeftRadius, notice.paddingTop, notice.paddingLeft, notice.marginBottom])
+            .toEqual(['1px', '6px', '15px', '18px', '22px']);
+        expect(notice.flexDirection).toBe(width <= 700 ? 'column' : 'row');
+        expect(notice.children.map(child => child.children.map(item => [item.tag, item.text])))
+            .toEqual([[['h2', '3 images need a decision'], ['p', 'Multiple sampler paths were found. The existing image links were preserved. Choose the correct context or leave them unresolved.']]]);
+        const layout = node(main, 'div.gallery-layout');
+        expect(layout.gridTemplateColumns).toBe(width <= 700 ? `${layout.width}px` : `${layout.width - 22 - 310}px 310px`);
+        const surface = node(main, 'section.review-panel');
+        expect(surface.children.map(child => child.tag)).toEqual(SURFACE);
+        expect(surface.children[0].text).toBe('Resolve the association');
+        expect(surface.children[1].text).toBe(CONCEPT_FILE);
+        const actions = surface.children.at(-1);
+        expect(actions.children.map(button => [button.text, button.primary])).toEqual([['Leave for later', false], ['Apply association', true]]);
+        expect(node(surface, 'select').options.at(-1)).toEqual(['Leave unresolved', false]);
+        expect(node(main, 'div.image-grid').children.map(card => node(card, 'h3').text))
+            .toEqual(['alpine_00001.png', 'dunes_00001.png', 'forest_00001.png']);
+        expect(actual.noPageScroll).toBe(true);
+    });
+}
+
+test('the gallery layout follows the concept at every breakpoint', async ({ page, request }) => {
+    await seed(request);
+    // 310px beside the queue, 275px and a 15px gap at ≤1250px, 280px at ≤950px, one column at ≤700px.
+    for (const [width, columns, gap] of [[1600, '310px', '22px'], [1200, '275px', '15px'], [900, '280px', '15px'], [390, null, '15px']]) {
+        await page.setViewportSize({ width, height: 1000 });
+        await openConcept(page, 'review', 'dark');
+        const concept = node((await conceptInventory(page)).main, 'div.gallery-layout');
+        await openReview(page, 'dark');
+        const actual = node((await productionInventory(page)).main, 'div.gallery-layout');
+        expect([actual.gridTemplateColumns, actual.columnGap], `${width}px`).toEqual([concept.gridTemplateColumns, concept.columnGap]);
+        expect([actual.gridTemplateColumns.split(' ').at(-1), actual.columnGap], `${width}px`).toEqual([columns ?? `${actual.width}px`, gap]);
+        expect(actual.gridTemplateColumns.split(' ').length, `${width}px`).toBe(width <= 700 ? 1 : 2);
+    }
+});
+
+test('SAVED VIEWS rows match the concept with Needs review after Favorites', async ({ page, request }) => {
+    await seed(request);
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await openConcept(page, 'review', 'dark');
+    const concept = (await inventoryOf(page, '#main')).chrome.navs.find(nav => nav.id === 'saved-nav');
+    await openReview(page, 'dark');
+    const actual = (await inventoryOf(page, '#workspace-main')).chrome.navs.find(nav => nav.id === 'saved-nav');
+    // Sample data: the concept stars three images; this queue's fixture stars none. Needs review counts the queue (3).
+    const reference = { ...concept, rows: concept.rows.map(row => row.text === 'Favorites' ? { ...row, count: { ...row.count, text: '0' } } : row) };
+    expect(diffInventory(reference, actual)).toEqual([]);
+    expect(actual.rows.map(row => [row.text, row.count?.text, row.current])).toEqual([['Favorites', '0', null], ['Needs review', '3', 'page']]);
+    // The count's auto start margin follows the row's own text; every other count token is shared.
+    const { text: favoriteCount, marginInlineStart: favoriteMargin, ...favoriteStyle } = actual.rows[0].count;
+    const { text: reviewCount, marginInlineStart: reviewMargin, ...reviewStyle } = actual.rows[1].count;
+    expect(reviewStyle).toEqual(favoriteStyle);
+    expect(actual.rows[1].icon.d).toBe('M4 3h16v18H4zM8 7h8M8 12h8M8 17h5');
+});
+
+test('review Tag dialog matches the needs-review-tagging reference', async ({ page, request }) => {
+    await seed(request);
+    await saveImageTags(request, `review/${CONCEPT_FILE}`, CONCEPT_TAGS);
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await openConcept(page, 'review', 'dark');
+    await page.locator('#main section.surface').getByRole('button', { name: 'Tag image', exact: true }).click();
+    await expect(tagDialog(page)).toBeVisible();
+    await settle(page);
+    const opened = await page.locator('dialog#modal').evaluate(taggingInventory);
+    await page.keyboard.press('Escape');
+    await openReview(page, 'dark');
+    await panel(page).getByRole('button', { name: 'Tag image', exact: true }).click();
+    await expect(tagDialog(page).locator('img.tag-image-preview')).toHaveAttribute('src', /\/image-annotations\/capture\//);
+    await expect(tagDialog(page).locator('#manual-image-tags')).toHaveValue(CONCEPT_TAGS.join(', '));
+    await settle(page);
+    const actual = await page.locator('dialog#modal').evaluate(taggingInventory);
+    const numberField = opened.modelPanel.fields.find(field => field.control.id === 'image-general-threshold');
+    const mapped = mapConceptTagging(opened, { instructions: INSTRUCTIONS, chip: opened.heading.size, numberField });
+    // D119: an undecided queue item names no prompt, so the heading and the preview's alt are the file name.
+    const reference = { ...mapped, heading: { ...mapped.heading, h3: { ...mapped.heading.h3, text: CONCEPT_FILE },
+        preview: { ...mapped.heading.preview, alt: CONCEPT_FILE } } };
+    expect(actual.scopeNote.text).toBe('Tags belong to this image. Resolve its prompt association separately in Needs review.');
+    expect(diffTaggingInventory(reference, actual)).toEqual([]);
+    await page.keyboard.press('Escape');
+    await expect(tagDialog(page)).toHaveCount(0);
+});
+
+test('the comparison notices a dropped notice border and reordered actions', async ({ page, request }) => {
+    const { actual, reference } = await compareAt(page, request, 1600, 1100, 'dark');
+    expect(diffInventory(reference, actual)).toEqual([]);
+    const undoBorder = await mutate(page, { css: '#workspace-main .notice { border: 0 !important; }' });
+    const borderless = await productionInventory(page);
+    expect(diffInventory(reference, borderless).map(item => item.path)).toEqual(expect.arrayContaining([
+        'main.children.1.borderTopWidth', 'main.children.1.borderTopStyle']));
+    await undoBorder();
+    await panel(page).locator('.dialog-actions').evaluate(row => row.prepend(row.lastElementChild));
+    const reordered = await productionInventory(page);
+    expect(diffInventory(reference, reordered).map(item => item.path)).toEqual(expect.arrayContaining([
+        'main.children.2.children.1.children.6.children.0.text', 'main.children.2.children.1.children.6.children.0.primary']));
+    await panel(page).locator('.dialog-actions').evaluate(row => row.prepend(row.lastElementChild));
+    expect(diffInventory(reference, await productionInventory(page))).toEqual([]);
+});
+
+// Paired captures for the PR (no baselines): the populated queue beside the concept in both themes and widths, then
+// the states the concept lacks (conflict, limited item, unavailable file, empty queue) as production captures.
+test('paired Needs review captures', async ({ page, request }, testInfo) => {
+    test.setTimeout(120_000);
+    const shot = async name => {
+        await settle(page);
+        const file = testInfo.outputPath(`${name}.png`);
+        await page.screenshot({ path: file, fullPage: true });
+        await testInfo.attach(name, { path: file, contentType: 'image/png' });
+    };
+    await seed(request);
+    for (const [width, height] of SIZES) for (const theme of THEMES) {
+        await page.setViewportSize({ width, height });
+        await openConcept(page, 'review', theme);
+        await shot(`concept-review-${width}-${theme}`);
+        await openReview(page, theme);
+        await shot(`production-review-${width}-${theme}`);
+    }
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await seed(request, { items: 0, conflict: true, limited: true, unavailable: true });
+    await openReview(page, 'dark');
+    await panel(page).getByRole('combobox', { name: 'Sampler context', exact: true }).selectOption({ index: 0 });
+    const decided = page.waitForResponse(item => /\/decision$/.test(item.url()));
+    await panel(page).getByRole('button', { name: 'Apply association', exact: true }).click();
+    expect((await decided).status()).toBe(409);
+    await expect(panel(page).locator('.warning-note')).toBeVisible();
+    await shot('production-review-conflict');
+    for (const [index, name] of [[1, 'limited'], [2, 'unavailable']]) {
+        await page.locator('#workspace-main .review-queue article').nth(index).getByRole('button', { name: /^Inspect / }).click();
+        await expect(panel(page).locator('.warning-note')).toBeVisible();
+        await shot(`production-review-${name}`);
+    }
+    await seed(request, { items: 0 });
+    await openProduction(page, 'review', 'dark');
+    await expect(page.locator('#workspace-main .notice h2')).toHaveText('No images need a decision');
+    await shot('production-review-empty');
+});

tests/browser/server.py

@@ -3,6 +3,7 @@
 import argparse
 import asyncio
 import json
+import logging
 import os
 import shutil
 import socket
@@ -22,6 +23,9 @@ from tests.browser.request_hold import register_request_holds
 from tests.browser import slow_reset_watch
 from tests.browser.workspace_activity_fixture import register_activity_commands
 from tests.browser.workspace_system_fixture import register_system_commands
+from tests.browser.workspace_integrations_fixture import (
+    register_integrations_commands,
+)
 from tests.browser.workspace_concept_fixture import (
     MAX_EXTRA_IMAGES as CONCEPT_MAX_EXTRA_IMAGES,
     MAX_SEEDLESS_IMAGES as CONCEPT_MAX_SEEDLESS_IMAGES,
@@ -40,6 +44,7 @@ from tests.browser.workspace_library_editor_fixture import (
 )
 from tests.browser.workspace_vocabulary_fixture import register_vocabulary_commands
 from tests.browser.workspace_tagging_fixture import register_tagging_commands
+from tests.browser.workspace_review_fixture import register_review_commands
 
 CANONICAL_ROOT = Path(__file__).resolve().parents[2]
 CANONICAL_ASSETS = {
@@ -197,9 +202,11 @@ def create_app(root: Path) -> web.Application:
     library_editor_commands = register_library_editor_commands(routes, api, root)
     register_vocabulary_commands(routes, api, root)
     register_tagging_commands(routes, api, root, model)
+    register_review_commands(routes, api, root)
     reveal_stub = register_reveal_stub(routes, api, root)
     register_activity_commands(app, routes, api)
     register_system_commands(app, routes, api, root)
+    register_integrations_commands(app, routes, api, root)
     request_holds = register_request_holds(app, routes)
     slow_reset_watch.install(app, api)
 
@@ -226,6 +233,8 @@ def create_app(root: Path) -> web.Application:
             for table in (
                 "saved_views",
                 "image_favorites",
+                "media_review_decisions",
+                "media_review_items",
                 "media_image_tags",
                 "media_annotation_bytes",
                 "media_annotation_files",
@@ -351,7 +360,12 @@ def create_app(root: Path) -> web.Application:
                 with Image.new("RGB", (64, 64), (100, 80, 120)) as image:
                     image.save(root / "output" / name, pnginfo=info)
                 os.utime(root / "output" / name, (time.time() - 100, time.time() - 100))
-        api._generate_gallery_thumbnails_sync(api._get_all_output_dirs(), (150, 150))
+        from py.api.thumbnail_settings import ThumbnailSettings
+
+        # 150 px previews in the default format (#317 thumbnail settings).
+        api._generate_gallery_thumbnails_sync(
+            api._get_all_output_dirs(), ThumbnailSettings("webp", 80, 150)
+        )
         if include_video:
             # Seed after thumbnail generation to exercise a real unthumbnailed video.
             video = root / "output" / "clip.webm"
@@ -382,6 +396,8 @@ def create_app(root: Path) -> web.Application:
     async def reset(request: web.Request) -> web.Response:
         nonlocal history_fixture
         request_holds.release()
+        # No preview queued by the last test may land in the new fixture.
+        await api._run_in_executor(api.close_auto_thumbnails)
         library_editor_commands.reset()
         data = await request.json() if request.can_read_body else {}
         if not isinstance(data, dict):
@@ -591,9 +607,13 @@ def create_app(root: Path) -> web.Application:
         return web.json_response("dark")
 
     async def cleanup(application: web.Application) -> None:
+        # A scan of an ambiguous fixture file captures it for Needs review.
+        api.close_annotation_captures()
         api.db.close_all()
 
     seed()
+    # Open Needs review change streams end first, as on the real host.
+    app.on_shutdown.append(api.close_review_events)
     app.on_cleanup.append(cleanup)
     app.add_routes(routes)
     return app
@@ -646,6 +666,18 @@ def exit_when_stdin_closes(loop: asyncio.AbstractEventLoop) -> threading.Thread:
     return thread
 
 
+def close_owned_log_files() -> None:
+    """Close Prompt Manager's own log handlers before the temp root goes.
+
+    The logs live in the library's data folder (#249 S6b), which for this
+    server is <root>/user/__promptmanager; Windows cannot remove a file
+    this process still has open.
+    """
+    for handler in logging.getLogger("prompt_manager").handlers[:]:
+        if getattr(handler, "_prompt_manager_owned", False) is True:
+            handler.close()
+
+
 def main(argv: list[str] | None = None) -> None:
     parser = argparse.ArgumentParser()
     parser.add_argument(
@@ -670,6 +702,7 @@ def main(argv: list[str] | None = None) -> None:
         finally:
             # create_app works inside the root; Windows cannot remove a process's cwd.
             os.chdir(original_cwd)
+            close_owned_log_files()
 
 
 if __name__ == "__main__":

tests/browser/shell-concept.spec.mjs

@@ -68,12 +68,12 @@ function remainingFooter(footer,spans) {
 const OVERVIEW_GLYPH='M3 11 12 4l9 7M5 10v10h14V10M10 20v-6h4v6';
 
 /**
- * The concept's SAVED VIEWS rows (app.js a331–335) as production lists them: Favorites with its count (D51), then the
- * saved views. D50: no "Needs review" row until the tag-review slice (maintainer ruling 2026-10-21).
+ * The concept's SAVED VIEWS rows (app.js a331–335) as production lists them: Favorites with its count (D51), Needs
+ * review with the exact pending count (ruling R5), then the saved views. The concept's "3" is sample data: the concept
+ * fixture records no review items, so production's count reads "0".
  */
 function savedNav(nav) {
-    const rows=nav.rows.filter(row=>row.text!=='Needs review');
-    return {...nav,rows:rows.map((row,index)=>index===rows.length-1?{...row,gapAfter:null}:row)};
+    return {...nav,rows:nav.rows.map(row=>row.text==='Needs review'?{...row,count:{...row.count,text:'0'}}:row)};
 }
 
 /** Recorded shell deviations only (spec §8). Everything else in the concept inventory must equal production. */
@@ -243,8 +243,9 @@ for(const [width,height] of SIZES)test(`a saved view row matches the concept's $
     await openProduction(page,'images','dark');
     const actual=await save('Save','#workspace-main');
     expect(diffInventory(mapShellConcept(reference).chrome.navs,actual.chrome.navs)).toEqual([]);
+    const referenceRows=reference.chrome.navs.find(nav=>nav.id==='saved-nav').rows;
     expect(actual.chrome.navs.find(nav=>nav.id==='saved-nav').rows.map(row=>[row.text,row.count]))
-        .toEqual([['Favorites',reference.chrome.navs.find(nav=>nav.id==='saved-nav').rows[0].count],['Golden hour',null]]);
+        .toEqual([['Favorites',referenceRows[0].count],['Needs review',{...referenceRows[1].count,text:'0'}],['Golden hour',null]]);
 });
 
 test('the inventory reports a missing shell element by its path instead of failing',async({page})=>{

tests/browser/system-backups-concept.spec.mjs

@@ -0,0 +1,329 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { SIZES, THEMES, seedConcept, openConcept, openProduction, diffInventory, mutate } from './concept-inventory.mjs';
+
+// #249 System S9 Task 25: System › Backup & export (app.js renderSystem 691–693), its "Restore preview" (`restore`,
+// 1472–1476) and its "Import & inspect" (`import`, 1483–1487) against the immutable concept, on the concept-shaped
+// fixture. Each concept measurement is mapped only by the recorded deviations (D103, D104, D105; the Import dialog's
+// D15 and D55), each commented where it applies; after that the difference must be empty, and a mutated label, row,
+// danger mark or token must be noticed.
+test.use({ locale: 'en-US', timezoneId: 'UTC' });
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await seedConcept(request);
+    await expect(await request.post('/__test__/system/reset')).toBeOK();
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    page.conceptErrors = [];
+    page.on('pageerror', error => page.conceptErrors.push(error.message));
+});
+
+test.afterEach(async ({ page, request, browserName }) => {
+    await saveCoverage(page, browserName);
+    await request.post('/__test__/jobs/restart');
+    await request.post('/__test__/system/reset');
+    expect(page.conceptErrors).toEqual([]);
+});
+
+const PREVIEW_URL = '/prompt_manager/restore/preview';
+
+/** Runs in the page: the section's surfaces under `mainSelector`, their text, controls, geometry and tokens. */
+function measureBackups(mainSelector) {
+    const layout = document.querySelector(`${mainSelector} .settings-layout`);
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const text = node => node?.textContent.trim() ?? null;
+    const button = node => ({ text: text(node), className: node.className,
+        ...css(node, 'backgroundColor', 'color', 'fontSize', 'paddingTop', 'paddingLeft', 'borderTopColor') });
+    const base = layout.getBoundingClientRect();
+    const box = node => {
+        const rect = node.getBoundingClientRect();
+        return { left: Math.round(rect.left - base.left), top: Math.round(rect.top - base.top), width: Math.round(rect.width) };
+    };
+    const control = row => {
+        const select = row.querySelector(':scope > select');
+        if (select) return { kind: 'select', id: select.id, options: [...select.options].map(option => [option.textContent, option.disabled]),
+            selected: select.selectedOptions[0]?.textContent ?? null, disabled: select.disabled };
+        const toggle = row.querySelector(':scope > * input[type="checkbox"]');
+        return toggle ? { kind: 'switch', id: toggle.id, wrapper: name(toggle.parentElement), checked: toggle.checked,
+            disabled: toggle.disabled, ...css(toggle.parentElement, 'width', 'height') } : null;
+    };
+    const columns = layout.querySelector(':scope > .two-col');
+    const surfaces = [...columns.querySelectorAll(':scope > section.surface')];
+    const policy = layout.querySelector(':scope > section.surface');
+    const chip = policy.querySelector(':scope > h2 > .chip');
+    const row = policy.querySelector('.setting-row');
+    const status = surfaces[0].querySelector(':scope > p.small');
+    const warning = policy.querySelector(':scope > .warning-note');
+    return {
+        layout: [...layout.children].map(name),
+        columns: { ...css(columns, 'display', 'gridTemplateColumns', 'columnGap'), box: box(columns) },
+        surfaces: surfaces.map(surface => ({ tree: [...surface.children].map(name), heading: text(surface.querySelector(':scope > h2')),
+            intro: text(surface.querySelector(':scope > p:not(.small)')), box: box(surface),
+            actions: [...surface.querySelectorAll(':scope > .row-actions')].map(group => ({ tree: [...group.children].map(name),
+                ...css(group, 'display', 'columnGap', 'flexWrap', 'marginTop'),
+                buttons: [...group.children].map(button) })) })),
+        status: { text: text(status), ...css(status, 'fontSize', 'color', 'marginTop') },
+        surface: css(surfaces[0], 'paddingTop', 'paddingLeft', 'backgroundColor', 'borderTopWidth', 'borderTopColor', 'borderTopLeftRadius'),
+        h2: css(surfaces[0].querySelector('h2'), 'fontSize', 'fontWeight', 'color', 'marginBottom'),
+        intro: css(surfaces[0].querySelector(':scope > p'), 'fontSize', 'color', 'lineHeight'),
+        // Its place below the columns (the concept's `.surface + .surface` 18px), whatever the columns' height.
+        policy: { tree: [...policy.children].map(name), heading: text(policy.querySelector(':scope > h2')),
+            box: { left: box(policy).left, width: box(policy).width,
+                gap: Math.round(policy.getBoundingClientRect().top - columns.getBoundingClientRect().bottom) },
+            chip: { text: text(chip), className: chip.className, ...css(chip, 'color', 'fontSize', 'borderTopColor', 'backgroundColor') },
+            rows: [...policy.querySelectorAll(':scope > .setting-row')].map(item => ({ tree: [...item.children].map(name),
+                text: [...item.firstElementChild.children].map(node => [name(node), text(node), node.localName === 'label' ? node.htmlFor : null]),
+                control: control(item) })),
+            warning: { text: text(warning), ...css(warning, 'fontSize', 'color', 'marginTop', 'marginBottom') } },
+        row: css(row, 'display', 'alignItems', 'justifyContent', 'columnGap', 'paddingTop', 'paddingBottom', 'borderTopWidth', 'borderTopColor',
+            'marginTop'),
+        label: css(row.querySelector('label'), 'fontSize', 'fontWeight', 'color'),
+        description: css(row.querySelector('p'), 'fontSize', 'color', 'marginTop', 'maxWidth'),
+        select: css(policy.querySelector('.setting-row > select'), 'fontSize', 'minWidth', 'maxWidth', 'backgroundColor', 'color',
+            'borderTopColor'),
+        pageScroll: document.documentElement.scrollWidth > document.documentElement.clientWidth,
+    };
+}
+
+const SCHEDULE_REASON = 'Daily and Weekly are not available yet: back up with Back up whenever you choose.';
+const SAFETY_DESCRIPTION = 'Keep a verified copy of the database on disk before maintenance, cleanups and LoRA imports change ' +
+    'records. A restore always keeps one.';
+
+/**
+ * D103: "Back up" (the concept's "Simulate backup"), the status line from /backup/status, "Export JSON" (its "Export
+ * sample JSON") and the two secondary exports in a second `.row-actions.spaced` with the concept's plain buttons.
+ * D104: the toggle's line says what the policy does, the schedule's reason replaces the prototype's proposal line,
+ * Daily and Weekly are disabled, and the warning note is truthful. The fixture has no backup yet.
+ */
+function mapBackupsConcept(reference) {
+    const [database, portable] = reference.surfaces;
+    const [backup, restore] = database.actions[0].buttons;
+    const [exportButton, importButton] = portable.actions[0].buttons;
+    const secondary = ['Export all prompts JSON', 'Export saved pairs JSON'].map(label => ({ ...exportButton, text: label }));
+    return {
+        ...reference,
+        surfaces: [
+            { ...database, actions: [{ ...database.actions[0], buttons: [{ ...backup, text: 'Back up' }, restore] }] },
+            { ...portable, tree: [...portable.tree, 'div.row-actions.spaced'],
+                actions: [{ ...portable.actions[0], buttons: [{ ...exportButton, text: 'Export JSON' }, importButton] },
+                    { ...portable.actions[0], tree: ['button', 'button'], buttons: secondary }] },
+        ],
+        status: { ...reference.status, text: 'No backup recorded.' },
+        policy: { ...reference.policy,
+            rows: reference.policy.rows.map(item => (item.control.kind !== 'select'
+                // D104 (M2): what the safety-backup policy really does.
+                ? { ...item, text: item.text.map(([node, value, target]) => [node, node === 'p' ? SAFETY_DESCRIPTION : value, target]) }
+                : { ...item,
+                    text: item.text.map(([node, value, target]) => [node, node === 'p' ? SCHEDULE_REASON : value, target]),
+                    control: { ...item.control, options: item.control.options.map(([label]) => [label, label !== 'Manual only']) } })),
+            warning: { ...reference.policy.warning, text: 'Restores are staged, migrated and validated before replacing live data.' } },
+    };
+}
+
+async function conceptBackups(page, theme) {
+    await openConcept(page, 'system', theme);
+    await page.locator('#main .section-nav').getByRole('button', { name: 'Backup & export', exact: true }).click();
+    await expect(page.locator('#main .settings-layout > .two-col > section.surface')).toHaveCount(2);
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureBackups, '#main');
+}
+
+async function productionBackups(page, theme, status = 'No backup recorded.') {
+    await openProduction(page, 'system/backups', theme);
+    await expect(page.locator('#workspace-main .settings-layout > .two-col > section.surface')).toHaveCount(2);
+    // The status line and the policy row are their own reads: compare once both answered.
+    await expect(page.locator('#workspace-main #backup-status')).toHaveText(status);
+    await expect(page.locator('#workspace-main #backup-before')).toBeEnabled();
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureBackups, '#workspace-main');
+}
+
+for (const theme of THEMES) for (const [width, height] of SIZES) {
+    test(`backup & export matches the concept ${theme} ${width}x${height}`, async ({ page }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        const concept = await conceptBackups(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`concept-backups-${theme}-${width}.png`), fullPage: true });
+        const production = await productionBackups(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`production-backups-${theme}-${width}.png`), fullPage: true });
+        expect(diffInventory(mapBackupsConcept(concept), production)).toEqual([]);
+        expect(production.pageScroll).toBe(false);
+    });
+}
+
+/** Runs in the page: the open dialog's title, body tree, grid, note, backup box and actions with the concept's tokens. */
+function measureDialog() {
+    const dialog = document.querySelector('dialog#modal[open]');
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const text = node => node?.textContent.trim() ?? null;
+    const body = dialog.querySelector('#modal-body');
+    const grid = body.querySelector(':scope > dl.meta-grid');
+    const note = body.querySelector(':scope > p.small');
+    const actions = body.querySelector(':scope > .dialog-actions');
+    const list = body.querySelector(':scope > .operation-list');
+    return {
+        title: text(dialog.querySelector('#modal-title')),
+        tree: [...body.children].map(name),
+        grid: grid && { rows: [...grid.children].map(row => [text(row.querySelector('dt')), text(row.querySelector('dd'))]),
+            ...css(grid, 'display', 'gridTemplateColumns', 'columnGap', 'rowGap'),
+            dt: css(grid.querySelector('dt'), 'fontSize', 'color', 'textTransform'), dd: css(grid.querySelector('dd'), 'fontSize', 'color') },
+        note: note && { text: text(note), ...css(note, 'fontSize', 'color') },
+        backup: body.querySelector(':scope > .notice') && { tree: [...body.querySelector(':scope > .notice').children].map(name),
+            text: [...body.querySelectorAll(':scope > .notice > div:first-child > *')].map(node => [node.localName, text(node)]),
+            buttons: [...body.querySelectorAll(':scope > .notice button')].map(text) },
+        list: list && { ...css(list, 'display', 'rowGap'),
+            rows: [...list.children].map(row => ({ tree: [...row.children].map(name), title: text(row.querySelector('h3')),
+                description: text(row.querySelector('p')), buttons: [...row.querySelectorAll('button')].map(text),
+                ...css(row, 'display', 'alignItems', 'paddingTop', 'borderTopColor') })) },
+        actions: actions && { tree: [...actions.children].map(name), ...css(actions, 'display', 'justifyContent', 'columnGap', 'marginTop'),
+            buttons: [...actions.children].map(item => ({ text: text(item), className: item.className,
+                ...css(item, 'backgroundColor', 'color', 'fontSize', 'paddingTop', 'paddingLeft', 'borderTopColor') })) },
+    };
+}
+
+const RESTORE_BACKUP_BOX = Object.freeze({ tree: ['div', 'div.row-actions'], text: [['h3', 'Back up the database first (recommended)'],
+    ['p', 'Downloads a copy of the prompts database before the restore replaces it.']], buttons: ['Back up now'] });
+
+/**
+ * D105: the server's review in the concept's "Restore preview": no sample note; the four rows with the review's values,
+ * then "In the backup" and "In the library now"; the hold line in the concept's dialog `p.small` (its Import dialog's
+ * intro, `small`); the D55 backup box before the actions; "Restore" (the concept's "Simulate restore", still danger).
+ */
+function mapRestoreConcept(reference, small, rows) {
+    const [cancel, restore] = reference.actions.buttons;
+    return {
+        ...reference,
+        tree: ['dl.meta-grid', 'p.small', 'div.notice', 'div.dialog-actions'],
+        grid: { ...reference.grid, rows },
+        note: { ...small, text: 'Restore replaces the whole library with this backup and runs alone in Activity. ' +
+            'Nothing changes until you restore. This review holds for 15 minutes.' },
+        backup: RESTORE_BACKUP_BOX,
+        actions: { ...reference.actions, buttons: [cancel, { ...restore, text: 'Restore' }] },
+    };
+}
+
+/** D15 and D55, as on Images: Rescan for "Scan an output folder", then "Scan for metadata"; no portable recipe import. */
+function mapImportConcept(reference) {
+    return { ...reference,
+        note: { ...reference.note, text: 'Image inspection and output scanning have different effects. Choose the workflow you want.' },
+        list: { ...reference.list, rows: reference.list.rows.filter(row => row.title !== 'Import portable recipes').flatMap(row =>
+            row.title === 'Scan an output folder'
+                ? [{ ...row, description: 'Find files added or removed in the output folders.', buttons: ['Rescan'] },
+                    { ...row, title: 'Scan for metadata' }] : [row]) } };
+}
+
+async function conceptDialog(page, theme, action, title) {
+    await conceptBackups(page, theme);
+    await page.locator(`#main .settings-layout [data-action="${action}"]`).click();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText(title);
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureDialog);
+}
+
+/** Production's restore review of a fresh backup of this server's library; the review's own answer too. */
+async function productionRestore(page, request, theme) {
+    const copy = await request.get('/prompt_manager/backup');
+    await expect(copy).toBeOK();
+    // That copy is this session's download now.
+    await productionBackups(page, theme, /^Downloaded backup · .+ · verified\.$/);
+    const chooser = page.waitForEvent('filechooser');
+    const answer = page.waitForResponse(response => response.url().endsWith(PREVIEW_URL));
+    await page.locator('#workspace-main').getByRole('button', { name: 'Review restore…', exact: true }).click();
+    await (await chooser).setFiles({ name: 'prompts_backup_20261025_093000.db', mimeType: 'application/octet-stream',
+        buffer: await copy.body() });
+    const preview = await (await answer).json();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Restore preview');
+    await page.mouse.move(0, 0);
+    return { preview, production: await page.evaluate(measureDialog) };
+}
+
+const counts = summary => `${summary.prompts} ${summary.prompts === 1 ? 'prompt' : 'prompts'} · ${summary.image_links} ` +
+    `${summary.image_links === 1 ? 'image link' : 'image links'} · ${summary.pairs} ${summary.pairs === 1 ? 'saved pair' : 'saved pairs'}` +
+    ` · ${summary.runs} ${summary.runs === 1 ? 'run' : 'runs'}`;
+
+function restoreRows(preview, snapshot) {
+    return [['Snapshot', snapshot], ['Integrity', 'Verified'], ['Migration', 'Current schema'],
+        ['Safety backup', `Created before replacing (${preview.safety_backup.destination_label})`],
+        ['In the backup', counts(preview.summary)], ['In the library now', counts(preview.live)]];
+}
+
+for (const theme of THEMES) for (const [width, height] of SIZES) {
+    test(`restore preview and import dialogs match the concept ${theme} ${width}x${height}`, async ({ page, request }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        // The concept's own dialog `p.small` (its Import dialog's intro) is the reference for the review's note.
+        const conceptImport = await conceptDialog(page, theme, 'import', 'Import & inspect');
+        await page.screenshot({ path: testInfo.outputPath(`concept-import-${theme}-${width}.png`) });
+        const conceptRestore = await conceptDialog(page, theme, 'restore', 'Restore preview');
+        expect(conceptRestore.tree).toEqual(['p.demo-note', 'dl.meta-grid', 'div.dialog-actions']);
+        await page.screenshot({ path: testInfo.outputPath(`concept-restore-${theme}-${width}.png`) });
+        const { preview, production } = await productionRestore(page, request, theme);
+        await page.screenshot({ path: testInfo.outputPath(`production-restore-${theme}-${width}.png`) });
+        const snapshot = production.grid.rows[0][1];
+        expect(snapshot).toMatch(/^prompts_backup_20261025_093000.db · (\d+ KB|\d+\.\d MB) · .+$/);
+        const { text: _intro, ...small } = conceptImport.note;
+        expect(diffInventory(mapRestoreConcept(conceptRestore, small, restoreRows(preview, snapshot)), production)).toEqual([]);
+        await page.keyboard.press('Escape');
+        await expect(page.locator('dialog#modal[open]')).toHaveCount(0);
+        await page.locator('#workspace-main').getByRole('button', { name: 'Import / inspect file', exact: true }).click();
+        await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Import & inspect');
+        await page.mouse.move(0, 0);
+        await page.screenshot({ path: testInfo.outputPath(`production-import-${theme}-${width}.png`) });
+        expect(diffInventory(mapImportConcept(conceptImport), await page.evaluate(measureDialog))).toEqual([]);
+    });
+}
+
+test('backup & export comparison detects mutations', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const concept = await conceptBackups(page, 'dark');
+    const expected = mapBackupsConcept(concept);
+    await productionBackups(page, 'dark');
+    const measure = () => page.evaluate(measureBackups, '#workspace-main');
+    const paths = async () => diffInventory(expected, await measure()).map(item => item.path);
+    expect(await paths()).toEqual([]);
+    // Unmapped, the section differs exactly on the D103 and D104 paths (the added row's own paths, then the rest).
+    const unmapped = diffInventory(concept, await measure()).map(item => item.path).sort();
+    const added = 'surfaces.1.actions.1.';
+    expect(unmapped.some(path => path.startsWith(added))).toBe(true);
+    expect(unmapped.filter(path => !path.startsWith(added))).toEqual([
+        'policy.rows.0.text.1.1', 'policy.rows.1.control.options.1.1', 'policy.rows.1.control.options.2.1', 'policy.rows.1.text.1.1',
+        'policy.warning.text',
+        'status.text', 'surfaces.0.actions.0.buttons.0.text', 'surfaces.1.actions.0.buttons.0.text', 'surfaces.1.actions.length',
+        'surfaces.1.tree.3', 'surfaces.1.tree.length']);
+    // A renamed label, a removed row, a lost danger mark and a swapped token are noticed.
+    await page.evaluate(() => { document.querySelector('#workspace-main .setting-row label').textContent = 'Safety backup'; });
+    expect(await paths()).toEqual(['policy.rows.0.text.0.1']);
+    await page.evaluate(() => { document.querySelector('#workspace-main .setting-row label').textContent = 'Create a safety backup before maintenance'; });
+    const undoRow = await mutate(page, { remove: ['#workspace-main .settings-layout > section.surface > .setting-row:last-of-type'] });
+    expect(await paths()).toEqual(expect.arrayContaining(['policy.rows.length', 'policy.tree.length']));
+    await undoRow();
+    await page.evaluate(() => { document.querySelector('#workspace-main button.danger').classList.remove('danger'); });
+    expect(await paths()).toEqual(expect.arrayContaining(['surfaces.0.actions.0.buttons.1.className']));
+    await page.evaluate(() => { document.querySelector('#workspace-main .two-col .row-actions > button:nth-child(2)').classList.add('danger'); });
+    const undoToken = await mutate(page, { css: '#workspace-main .settings-layout { --line: rgb(255, 0, 0); }' });
+    expect(await paths()).toEqual(expect.arrayContaining(['row.borderTopColor']));
+    await undoToken();
+    const undoChip = await mutate(page, { css: '#workspace-main .chip.blue { color: rgb(255, 0, 0); }' });
+    expect(await paths()).toEqual(['policy.chip.color']);
+    await undoChip();
+    expect(await paths()).toEqual([]);
+
+    // The restore review: a renamed term, a lost danger mark and the grid's token are noticed.
+    const conceptImport = await conceptDialog(page, 'dark', 'import', 'Import & inspect');
+    const conceptRestore = await conceptDialog(page, 'dark', 'restore', 'Restore preview');
+    const { preview, production } = await productionRestore(page, request, 'dark');
+    const { text: _intro, ...small } = conceptImport.note;
+    const expectedRestore = mapRestoreConcept(conceptRestore, small, restoreRows(preview, production.grid.rows[0][1]));
+    const restorePaths = async () => diffInventory(expectedRestore, await page.evaluate(measureDialog)).map(item => item.path);
+    expect(await restorePaths()).toEqual([]);
+    await page.evaluate(() => { document.querySelector('dialog#modal[open] dl.meta-grid dt').textContent = 'Backup'; });
+    expect(await restorePaths()).toEqual(['grid.rows.0.0']);
+    await page.evaluate(() => { document.querySelector('dialog#modal[open] dl.meta-grid dt').textContent = 'Snapshot'; });
+    await page.evaluate(() => { document.querySelector('dialog#modal[open] .dialog-actions .danger').classList.remove('danger'); });
+    expect(await restorePaths()).toEqual(expect.arrayContaining(['actions.buttons.1.className']));
+    await page.evaluate(() => { document.querySelector('dialog#modal[open] .dialog-actions button:last-child').classList.add('danger'); });
+    const undoGrid = await mutate(page, { css: 'dialog#modal dl.meta-grid { column-gap: 3px; }' });
+    expect(await restorePaths()).toEqual(expect.arrayContaining(['grid.columnGap']));
+    await undoGrid();
+    expect(await restorePaths()).toEqual([]);
+});

tests/browser/system-concept.spec.mjs

@@ -169,11 +169,11 @@ function mapOverviewConcept(reference, overview) {
     const relabel = { 'Database integrity': 'Not checked', 'Positive prompts': number(overview.library.positive_prompts),
         'Negative variants': number(overview.library.negative_variants), Images: number(overview.images.indexed) };
     const rows = {
-        // D93 (Q6): no review queue yet, so no count and the action is unavailable (dimmed, as the Save row's D92).
-        '3 ambiguous image links': row => ({ ...row, title: 'Ambiguous image links', description: 'Not available yet.',
-            action: { ...row.action, opacity: '0.55', cursor: 'not-allowed' } }),
-        // D93: no backup has been recorded (verified backups arrive with S8).
-        'Backup status': row => ({ ...row, description: 'No retained backup record.' }),
+        // D93: the real pending count; Review metadata opens Needs review (the concept's go-review).
+        '3 ambiguous image links': row => ({ ...row,
+            title: `${number(overview.needs_review.pending)} ambiguous image link${overview.needs_review.pending === 1 ? '' : 's'}` }),
+        // D93 (S9): what GET /backup/status reports; the fixture has no backup yet.
+        'Backup status': row => ({ ...row, description: 'No backup recorded.' }),
         // D93: there is no paging, so the shared settings are grid and density.
         'One display configuration': row => ({ ...row, description: 'Grid and density settings are shared across views.' }),
         // D93: the real sources, not samples.
@@ -181,6 +181,17 @@ function mapOverviewConcept(reference, overview) {
         // D96: the dialog shows runs and ratings by category and library totals, not prompt, tag or date usage.
         Statistics: row => ({ ...row, description: 'Runs and ratings by category, with library totals.' }),
     };
+    const surfaces = reference.columns.surfaces.map(surface => ({ ...surface,
+        rows: surface.rows.map(row => (rows[row.title] ?? (value => value))(row)) }));
+    // D129: "Library location" after Backup status, in the backup row's own markup; the fixture's database is configured
+    // explicitly (config.json), so it does not move and its action is Details.
+    const [health] = surfaces;
+    const backup = health.rows.find(row => row.title === 'Backup status');
+    const location = { ...backup, title: 'Library location',
+        description: `${overview.location.path} · The database path set in config.json.`,
+        action: { ...backup.action, text: 'Details' } };
+    surfaces[0] = { ...health, tree: [...health.tree, 'div.operation'],
+        rows: [...health.rows.slice(0, 2), location, ...health.rows.slice(2)] };
     return {
         ...reference,
         // D92: no "Sample configuration" chip.
@@ -188,8 +199,7 @@ function mapOverviewConcept(reference, overview) {
         // D122: the concept's literal label is its prototype action name ("system-tab sections").
         nav: { ...reference.nav, label: 'System sections' },
         metrics: { ...reference.metrics, items: reference.metrics.items.map(item => ({ ...item, value: relabel[item.label] })) },
-        columns: { ...reference.columns, surfaces: reference.columns.surfaces.map(surface => ({ ...surface,
-            rows: surface.rows.map(row => (rows[row.title] ?? (value => value))(row)) })) },
+        columns: { ...reference.columns, surfaces },
         save: { ...reference.save,
             // D92: truthful status copy, and "Save preferences" is aria-disabled (dimmed) while nothing is unsaved.
             status: { ...reference.save.status, text: 'No unsaved changes.' },
@@ -209,6 +219,9 @@ async function productionOverview(page, theme) {
     await expect(page.locator('#workspace-main .summary-metrics')).toBeVisible();
     // The thumbnail row is its own read (I2): compare once it answered.
     await expect(page.locator('#workspace-main .operation h3').filter({ hasText: 'thumbnails' })).toHaveText('No missing thumbnails');
+    // So is the backup row (S9).
+    await expect(page.locator('#workspace-main .operation').filter({ has: page.locator('h3', { hasText: 'Backup status' }) })
+        .locator('p')).toHaveText('No backup recorded.');
     await page.mouse.move(0, 0);
     return page.evaluate(measureSystem, '#workspace-main');
 }
@@ -230,16 +243,23 @@ for (const theme of THEMES) for (const [width, height] of SIZES) {
     });
 }
 
-// The recorded differences, by path: D93 the review row (title, Not available yet, dimmed action), the backup row, the
+// The recorded differences, by path: D93 the review row (its real count), the backup row, the
 // preferences row and the sources row, and metric 4; D96 the statistics row; D92 the chip, the status and the dimmed
-// Save; D122 the nav label. (The fixture's first three metrics are the concept's own counts.)
+// Save; D122 the nav label; D129 the inserted "Library location" row, which shifts the thumbnail row to the fourth place
+// (row 2 takes its title, text and action; row 3 and the surface's fifth child are new). (The fixture's first three
+// metrics are the concept's own counts.)
+const D129_ROW_ACTION = ['backgroundColor', 'borderTopColor', 'borderTopLeftRadius', 'borderTopWidth', 'className', 'color',
+    'cursor', 'fontSize', 'opacity', 'paddingLeft', 'paddingTop', 'text'].map(key => `columns.surfaces.0.rows.3.action.${key}`);
 const UNMAPPED_PATHS = [
-    'columns.surfaces.0.rows.0.action.cursor', 'columns.surfaces.0.rows.0.action.opacity',
-    'columns.surfaces.0.rows.0.description', 'columns.surfaces.0.rows.0.title', 'columns.surfaces.0.rows.1.description',
+    'columns.surfaces.0.rows.0.title', 'columns.surfaces.0.rows.1.description',
+    'columns.surfaces.0.rows.2.action.text', 'columns.surfaces.0.rows.2.description', 'columns.surfaces.0.rows.2.title',
+    ...D129_ROW_ACTION, 'columns.surfaces.0.rows.3.description', 'columns.surfaces.0.rows.3.title',
+    'columns.surfaces.0.rows.3.tree.0', 'columns.surfaces.0.rows.3.tree.1', 'columns.surfaces.0.rows.3.tree.length',
+    'columns.surfaces.0.rows.length', 'columns.surfaces.0.tree.4', 'columns.surfaces.0.tree.length',
     'columns.surfaces.1.rows.0.description', 'columns.surfaces.1.rows.1.title', 'columns.surfaces.1.rows.2.description',
     'heading.actions.0', 'heading.actions.length', 'metrics.items.3.value', 'nav.label',
     'save.button.cursor', 'save.button.opacity', 'save.status.text',
-];
+].sort();
 
 test('system comparison detects mutations', async ({ page, request }) => {
     await page.setViewportSize({ width: 1600, height: 1100 });
@@ -408,3 +428,589 @@ for (const theme of THEMES) test(`statistics and health dialogs match the concep
     await page.evaluate(() => { document.querySelector('#modal-body caption').textContent = 'Runs per category'; });
     expect(diffInventory(expectedStatistics, await page.evaluate(measureDialog)).map(item => item.path)).toEqual(['tables.0.caption']);
 });
+
+/** Runs in the page: Appearance's surface, every row's text and control, and the concept's row geometry and tokens. */
+function measureAppearance(mainSelector) {
+    const layout = document.querySelector(`${mainSelector} .settings-layout`);
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const text = node => node?.textContent.trim() ?? null;
+    const surface = layout.querySelector(':scope > section.surface');
+    const control = row => {
+        const select = row.querySelector(':scope > select');
+        if (select) return { kind: 'select', id: select.id, options: [...select.options].map(option => option.textContent),
+            selected: select.selectedOptions[0]?.textContent ?? null };
+        const input = row.querySelector(':scope > input');
+        if (input) return { kind: `input.${input.type}`, id: input.id, value: input.value };
+        const toggle = row.querySelector(':scope > * input[type="checkbox"]');
+        if (toggle) return { kind: 'switch', id: toggle.id, wrapper: name(toggle.parentElement), checked: toggle.checked,
+            ...css(toggle.parentElement, 'width', 'height') };
+        const chip = row.querySelector(':scope > .chip');
+        return chip ? { kind: name(chip), text: text(chip), ...css(chip, 'color', 'backgroundColor', 'fontSize') } : null;
+    };
+    const rows = [...surface.querySelectorAll(':scope > .setting-row')];
+    const operations = [...surface.querySelectorAll(':scope > .operation')];
+    const firstRow = rows[0];
+    return {
+        layout: [...layout.children].map(name),
+        surface: { tree: [...surface.children].map(name), heading: text(surface.querySelector(':scope > h2')),
+            intro: text(surface.querySelector(':scope > p')),
+            ...css(surface, 'paddingTop', 'paddingLeft', 'backgroundColor', 'borderTopWidth', 'borderTopColor', 'borderTopLeftRadius') },
+        rows: rows.map(row => ({ tree: [...row.children].map(name), text: [...row.firstElementChild.children].map(node => [node.localName, text(node),
+            node.localName === 'label' ? node.htmlFor : null]), control: control(row) })),
+        operations: operations.map(row => ({ tree: [...row.children].map(name), title: text(row.querySelector('h3')),
+            description: text(row.querySelector('p')), action: text(row.querySelector('.row-actions > button')) })),
+        row: css(firstRow, 'display', 'alignItems', 'justifyContent', 'columnGap', 'paddingTop', 'paddingBottom', 'borderTopWidth',
+            'borderTopColor', 'marginTop'),
+        label: css(firstRow.querySelector('label'), 'fontSize', 'fontWeight', 'color'),
+        description: css(firstRow.querySelector('p'), 'fontSize', 'color', 'marginTop', 'maxWidth'),
+        select: css(firstRow.querySelector('select'), 'fontSize', 'minWidth', 'maxWidth', 'backgroundColor', 'color', 'borderTopColor'),
+        heading3: css(surface.querySelector('.setting-row h3'), 'fontSize', 'fontWeight', 'color'),
+        number: css(surface.querySelector('.setting-row input[type="number"]'), 'fontSize', 'minWidth', 'maxWidth', 'backgroundColor'),
+        pageScroll: document.documentElement.scrollWidth > document.documentElement.clientWidth,
+    };
+}
+
+// D97: the rows Appearance adds for the legacy gallery settings, after the concept's own, as production renders them.
+const ADDED_APPEARANCE_ROWS = [
+    ['card-details', 'Show image details on cards', 'Show each card’s title and file details under the preview.', true],
+    ['viewer-details', 'Collapse viewer details by default', 'Open the image viewer with its details panel hidden.', false],
+];
+
+/** The concept's Appearance with the recorded deviations applied, given the server's real settings. */
+function mapAppearanceConcept(reference, settings) {
+    const toggleRow = reference.rows.find(row => row.control?.kind === 'switch');
+    const added = ADDED_APPEARANCE_ROWS.map(([id, label, description, checked]) => ({
+        tree: toggleRow.tree, text: [['label', label, id], ['p', description, null]],
+        control: { ...toggleRow.control, id, checked } }));
+    return {
+        ...reference,
+        // #317: the server's thumbnail settings follow in their own surface ("Thumbnails", README: retained in Appearance).
+        layout: [reference.layout[0], 'section.surface', ...reference.layout.slice(1)],
+        // D97: two added toggles and the "Reset display defaults" operation close the surface.
+        surface: { ...reference.surface, tree: [...reference.surface.tree, 'div.setting-row', 'div.setting-row', 'div.operation'] },
+        rows: [...reference.rows.map(row => row.control?.id === 'timeout'
+            // The node search timeout is the server's real `result_timeout`, not the concept's sample 30.
+            ? { ...row, control: { ...row.control, value: String(settings.result_timeout) } } : row), ...added],
+        operations: [{ tree: ['div', 'div.row-actions'], title: 'Reset display defaults',
+            description: 'Restore this browser’s display defaults, then save. Other settings are kept.', action: 'Reset' }],
+    };
+}
+
+async function conceptAppearance(page, theme) {
+    await openConcept(page, 'system', theme);
+    await page.locator('#main .section-nav').getByRole('button', { name: 'Appearance', exact: true }).click();
+    await expect(page.locator('#main .settings-layout > section.surface > h2')).toHaveText('Browsing & display');
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureAppearance, '#main');
+}
+
+async function productionAppearance(page, theme) {
+    await openProduction(page, 'system/appearance', theme);
+    await expect(page.locator('#workspace-main #timeout')).toBeEnabled();
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureAppearance, '#workspace-main');
+}
+
+for (const theme of THEMES) for (const [width, height] of SIZES) {
+    test(`appearance matches the concept ${theme} ${width}x${height}`, async ({ page, request }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        const { settings } = await serverJson(request, '/prompt_manager/settings');
+        const concept = await conceptAppearance(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`concept-appearance-${theme}-${width}.png`), fullPage: true });
+        const production = await productionAppearance(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`production-appearance-${theme}-${width}.png`), fullPage: true });
+        expect(diffInventory(mapAppearanceConcept(concept, settings), production)).toEqual([]);
+        expect(production.pageScroll).toBe(false);
+    });
+}
+
+test('appearance comparison detects mutations', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const { settings } = await serverJson(request, '/prompt_manager/settings');
+    const concept = await conceptAppearance(page, 'dark');
+    const expected = mapAppearanceConcept(concept, settings);
+    const production = await productionAppearance(page, 'dark');
+    expect(diffInventory(expected, production)).toEqual([]);
+    // Unmapped, the concept differs only where D97 and the real timeout are recorded.
+    expect(diffInventory(concept, production).map(item => item.path.split('.').slice(0, 2).join('.'))
+        .filter((path, index, all) => all.indexOf(path) === index).sort())
+        .toEqual(['layout.1', 'layout.2', 'layout.length', 'operations.0', 'operations.length', 'rows.11', 'rows.12', 'rows.13',
+            'rows.length', 'surface.tree'].sort());
+    const measure = () => page.evaluate(measureAppearance, '#workspace-main');
+    const paths = async () => diffInventory(expected, await measure()).map(item => item.path);
+    // A removed row.
+    const undoRow = await mutate(page, { remove: ['#workspace-main .setting-row:nth-of-type(3)'] });
+    expect(await paths()).toEqual(expect.arrayContaining(['rows.length', 'surface.tree.length']));
+    await undoRow();
+    // A changed label and a changed option.
+    await page.evaluate(() => { document.querySelector('#workspace-main label[for="density"]').textContent = 'Thumbnail sizes'; });
+    expect(await paths()).toEqual(['rows.1.text.0.1']);
+    await page.evaluate(() => { document.querySelector('#workspace-main label[for="density"]').textContent = 'Thumbnail size'; });
+    await page.evaluate(() => { document.querySelector('#workspace-main #image-quality option').textContent = 'Medium'; });
+    expect(await paths()).toEqual(expect.arrayContaining(['rows.5.control.options.0']));
+    await page.evaluate(() => { document.querySelector('#workspace-main #image-quality option').textContent = 'Optimized'; });
+    // A swapped token.
+    const undoToken = await mutate(page, { css: '#workspace-main .settings-layout { --line: rgb(255, 0, 0); }' });
+    expect(await paths()).toEqual(expect.arrayContaining(['row.borderTopColor']));
+    await undoToken();
+    expect(diffInventory(expected, await measure())).toEqual([]);
+});
+
+/**
+ * Runs in the page: Sources & scans (app.js 679–681): the optional notice, then the "Image sources" surface with its
+ * panel heading, the source list, the two setting rows and the operations, with the concept's geometry and tokens.
+ */
+function measureSources(mainSelector) {
+    const layout = document.querySelector(`${mainSelector} .settings-layout`);
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const text = node => node?.textContent.trim() ?? null;
+    const button = node => ({ text: text(node), className: node.className,
+        ...css(node, 'backgroundColor', 'color', 'fontSize', 'paddingTop', 'paddingLeft', 'borderTopColor') });
+    const operation = row => ({ tree: [...row.children].map(name), title: text(row.querySelector('h3')),
+        description: text(row.querySelector('p')), actions: [...row.querySelectorAll('.row-actions > button')].map(button) });
+    const notice = layout.querySelector(':scope > .notice');
+    const surface = layout.querySelector(':scope > section.surface');
+    const heading = surface.querySelector(':scope > .panel-heading');
+    const list = surface.querySelector(':scope > #source-list');
+    const control = row => {
+        const toggle = row.querySelector(':scope > * input[type="checkbox"]');
+        if (toggle) return { kind: 'switch', id: toggle.id, wrapper: name(toggle.parentElement), checked: toggle.checked,
+            ...css(toggle.parentElement, 'width', 'height') };
+        const input = row.querySelector(':scope > input');
+        return { kind: `input.${input.type}`, id: input.id, min: input.min, max: input.max, value: input.value,
+            ...css(input, 'width', 'accentColor') };
+    };
+    const rows = [...surface.querySelectorAll(':scope > .setting-row')];
+    return {
+        layout: [...layout.children].map(name),
+        notice: notice && { tree: [...notice.children].map(name),
+            text: [...notice.querySelectorAll(':scope > div > *')].map(node => [node.localName, text(node)]),
+            actions: [...notice.querySelectorAll(':scope > .row-actions > button')].map(button),
+            ...css(notice, 'display', 'alignItems', 'columnGap', 'borderTopColor', 'backgroundColor', 'paddingTop', 'marginBottom') },
+        surface: { tree: [...surface.children].map(name), intro: text(surface.querySelector(':scope > p')),
+            ...css(surface, 'paddingTop', 'paddingLeft', 'backgroundColor', 'borderTopColor', 'borderTopLeftRadius') },
+        heading: { tree: [...heading.children].map(name), title: text(heading.querySelector('h2')),
+            action: button(heading.querySelector('button')), ...css(heading, 'display', 'alignItems', 'justifyContent', 'marginBottom'),
+            h2: css(heading.querySelector('h2'), 'fontSize', 'fontWeight', 'color') },
+        sources: [...list.children].map(operation),
+        rows: rows.map(row => ({ tree: [...row.children].map(name), text: [...row.firstElementChild.children].map(node => [node.localName, text(node),
+            node.localName === 'label' ? node.htmlFor : null]), control: control(row) })),
+        operations: [...surface.querySelectorAll(':scope > .operation')].map(operation),
+        operation: css(list.querySelector('.operation'), 'display', 'alignItems', 'justifyContent', 'columnGap', 'paddingTop',
+            'paddingBottom', 'borderTopWidth', 'borderTopColor'),
+        h3: css(list.querySelector('.operation h3'), 'fontSize', 'fontWeight', 'color'),
+        p: css(list.querySelector('.operation p'), 'fontSize', 'color', 'marginTop'),
+        row: css(rows[0], 'display', 'alignItems', 'justifyContent', 'columnGap', 'paddingTop', 'paddingBottom', 'borderTopColor'),
+        pageScroll: document.documentElement.scrollWidth > document.documentElement.clientWidth,
+    };
+}
+
+// D128: "watching until restart" after monitoring was switched off while the observer still runs.
+const WATCH_TEXT = { watching: 'watching', stopping: 'watching until restart', manual: 'manual scan', restart_pending: 'restart pending' };
+const WATCHED = new Set(['watching', 'stopping']);
+// D98: the operation Sources adds after the concept's own, as production renders it.
+const REFRESH_FILES = { title: 'Refresh files', description: 'Read every source again to find files added or removed outside ComfyUI.',
+    label: 'Refresh' };
+
+/** The concept's Sources with the recorded deviations applied, given the server's real settings and sources. */
+function mapSourcesConcept(reference, { settings, sources }) {
+    const [sample] = reference.sources;
+    const scan = sample.actions[0];
+    return {
+        ...reference,
+        // The real sources replace the two samples (without the "sample path" note). D98: each configured one has Remove,
+        // a plain button after its scan.
+        sources: sources.effective.map(source => ({ ...sample, title: source.label,
+            description: `${source.path} · ${WATCH_TEXT[source.watch]}`,
+            actions: [{ ...scan, text: WATCHED.has(source.watch) ? 'Scan changes' : 'Scan folder' }, { ...scan, text: 'Remove' }] })),
+        rows: reference.rows.map(row => {
+            if (row.control.id === 'monitoring') return { ...row, control: { ...row.control, checked: settings.monitoring_enabled } };
+            // D113: the range ends at the server's core count (the concept's fixed 16) and shows the real worker count.
+            return { ...row, control: { ...row.control, max: String(settings.cpu_count), value: String(settings.worker_threads) } };
+        }),
+        // D98: "Refresh files" closes the surface.
+        surface: { ...reference.surface, tree: [...reference.surface.tree, 'div.operation'] },
+        operations: [...reference.operations, { ...reference.operations[0], title: REFRESH_FILES.title,
+            description: REFRESH_FILES.description, actions: [{ ...reference.operations[0].actions[0], text: REFRESH_FILES.label }] }],
+    };
+}
+
+async function conceptSources(page, theme, { notice }) {
+    await openConcept(page, 'system', theme);
+    await page.locator('#main .section-nav').getByRole('button', { name: 'Sources & scans', exact: true }).click();
+    await expect(page.locator('#main .panel-heading > h2')).toHaveText('Image sources');
+    if (!notice) await page.locator('#main .notice').getByRole('button', { name: 'Later', exact: true }).click();
+    await expect(page.locator('#main .settings-layout > .notice')).toHaveCount(notice ? 1 : 0);
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureSources, '#main');
+}
+
+async function productionSources(page, theme, { notice }) {
+    // about:blank has no storage; the workspace page reads the dismissal.
+    if (!notice) await page.addInitScript(() => { if (location.protocol.startsWith('http')) localStorage.setItem('pm_update_notice_dismissed', '3.2.0'); });
+    await openProduction(page, 'system/sources', theme);
+    await expect(page.locator('#workspace-main #source-list .operation')).toHaveCount(2);
+    await expect(page.locator('#workspace-main #workers')).toBeEnabled();
+    await expect(page.locator('#workspace-main .settings-layout > .notice')).toHaveCount(notice ? 1 : 0);
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureSources, '#workspace-main');
+}
+
+/** The fixture's sources as the concept shows its samples: the first one watched, the second not. */
+async function watchedSources(request) {
+    await expect(await request.post('/__test__/system/monitor', { data: { watching: ['output'] } })).toBeOK();
+    return serverJson(request, '/prompt_manager/settings');
+}
+
+for (const theme of THEMES) for (const [width, height] of SIZES) for (const notice of [true, false]) {
+    const variant = notice ? 'with' : 'without';
+    test(`sources matches the concept ${variant} the notice ${theme} ${width}x${height}`, async ({ page, request }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        const server = await watchedSources(request);
+        const concept = await conceptSources(page, theme, { notice });
+        await page.screenshot({ path: testInfo.outputPath(`concept-sources-${variant}-notice-${theme}-${width}.png`), fullPage: true });
+        const production = await productionSources(page, theme, { notice });
+        await page.screenshot({ path: testInfo.outputPath(`production-sources-${variant}-notice-${theme}-${width}.png`), fullPage: true });
+        expect(diffInventory(mapSourcesConcept(concept, server), production)).toEqual([]);
+        expect(production.pageScroll).toBe(false);
+    });
+}
+
+test('sources comparison detects mutations', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const server = await watchedSources(request);
+    const concept = await conceptSources(page, 'dark', { notice: true });
+    const expected = mapSourcesConcept(concept, server);
+    const production = await productionSources(page, 'dark', { notice: true });
+    expect(diffInventory(expected, production)).toEqual([]);
+    // Unmapped, the concept differs only in the real sources, the D98 operation and the D113 range.
+    expect(diffInventory(concept, production).map(item => item.path.split('.').slice(0, 2).join('.'))
+        .filter((path, index, all) => all.indexOf(path) === index).sort())
+        .toEqual(['operations.2', 'operations.length', 'rows.1', 'sources.0', 'sources.1', 'surface.tree'].sort());
+    const measure = () => page.evaluate(measureSources, '#workspace-main');
+    const paths = async () => diffInventory(expected, await measure()).map(item => item.path);
+    // A removed notice and a removed source row.
+    const undoNotice = await mutate(page, { remove: ['#workspace-main .settings-layout > .notice'] });
+    expect(await paths()).toEqual(expect.arrayContaining(['layout.length', 'notice.tree.length']));
+    await undoNotice();
+    const undoRow = await mutate(page, { remove: ['#workspace-main #source-list > .operation:nth-child(2)'] });
+    expect(await paths()).toEqual(expect.arrayContaining(['sources.length']));
+    await undoRow();
+    // A changed label and a changed button.
+    await page.evaluate(() => { document.querySelector('#workspace-main label[for="monitoring"]').textContent = 'Watch for outputs'; });
+    expect(await paths()).toEqual(['rows.0.text.0.1']);
+    await page.evaluate(() => { document.querySelector('#workspace-main label[for="monitoring"]').textContent = 'Watch for new outputs'; });
+    await page.evaluate(() => { document.querySelector('#workspace-main .panel-heading button').textContent = 'Add source'; });
+    expect(await paths()).toEqual(['heading.action.text']);
+    await page.evaluate(() => { document.querySelector('#workspace-main .panel-heading button').textContent = '+ Add source'; });
+    // A swapped token.
+    const undoToken = await mutate(page, { css: '#workspace-main .settings-layout { --line: rgb(255, 0, 0); }' });
+    expect(await paths()).toEqual(expect.arrayContaining(['operation.borderTopColor']));
+    await undoToken();
+    expect(diffInventory(expected, await measure())).toEqual([]);
+});
+
+/**
+ * Runs in the page: the open "Add image source" dialog (the concept's `simpleInput`, app.js 1138 and 1497): its title,
+ * the body's tree, the field's label and input, and the actions, with the concept's geometry and tokens.
+ */
+function measureAddSource() {
+    const dialog = document.querySelector('dialog#modal[open]');
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const text = node => node?.textContent.trim() ?? null;
+    const body = dialog.querySelector('#modal-body');
+    const field = body.querySelector(':scope > .field');
+    const label = field?.querySelector(':scope > label');
+    const input = field?.querySelector(':scope > input');
+    const actions = body.querySelector(':scope > .dialog-actions');
+    const rect = dialog.getBoundingClientRect();
+    return {
+        title: text(dialog.querySelector('#modal-title')),
+        tree: [...body.children].map(name),
+        field: field && { tree: [...field.children].map(name), ...css(field, 'display', 'flexDirection', 'rowGap', 'marginBottom') },
+        label: label && { text: text(label), for: label.htmlFor, ...css(label, 'fontSize', 'fontWeight', 'color') },
+        input: input && { id: input.id, type: input.type, value: input.value,
+            ...css(input, 'height', 'paddingLeft', 'fontSize', 'color', 'backgroundColor', 'borderTopColor', 'borderTopLeftRadius') },
+        actions: { tree: [...actions.children].map(name), ...css(actions, 'display', 'justifyContent', 'columnGap', 'marginTop'),
+            buttons: [...actions.children].map(button => ({ text: text(button), className: button.className,
+                ...css(button, 'backgroundColor', 'color', 'fontSize', 'paddingTop', 'paddingLeft', 'borderTopColor') })) },
+        width: Math.round(rect.width),
+    };
+}
+
+/** D127: the field is "Folder path", starts empty (no sample folder) and its action is "Add". */
+function mapAddSourceConcept(reference) {
+    const [cancel, apply] = reference.actions.buttons;
+    return { ...reference, label: { ...reference.label, text: 'Folder path' }, input: { ...reference.input, value: '' },
+        actions: { ...reference.actions, buttons: [cancel, { ...apply, text: 'Add' }] } };
+}
+
+async function conceptAddSource(page, theme) {
+    await conceptSources(page, theme, { notice: false });
+    await page.locator('#main .panel-heading').getByRole('button', { name: '+ Add source', exact: true }).click();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Add image source');
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureAddSource);
+}
+
+async function productionAddSource(page, theme) {
+    await productionSources(page, theme, { notice: false });
+    await page.locator('#workspace-main .panel-heading').getByRole('button', { name: '+ Add source', exact: true }).click();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Add image source');
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureAddSource);
+}
+
+for (const theme of THEMES) for (const [width, height] of SIZES) {
+    test(`add source dialog matches the concept ${theme} ${width}x${height}`, async ({ page, request }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        await watchedSources(request);
+        const concept = await conceptAddSource(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`concept-add-source-${theme}-${width}.png`) });
+        const production = await productionAddSource(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`production-add-source-${theme}-${width}.png`) });
+        expect(diffInventory(mapAddSourceConcept(concept), production)).toEqual([]);
+    });
+}
+
+test('add source comparison detects mutations', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await watchedSources(request);
+    const concept = await conceptAddSource(page, 'dark');
+    const expected = mapAddSourceConcept(concept);
+    const production = await productionAddSource(page, 'dark');
+    expect(diffInventory(expected, production)).toEqual([]);
+    // Unmapped, the concept differs only where D127 is recorded.
+    expect(diffInventory(concept, production).map(item => item.path).sort())
+        .toEqual(['actions.buttons.1.text', 'input.value', 'label.text']);
+    const paths = async () => diffInventory(expected, await page.evaluate(measureAddSource)).map(item => item.path);
+    // A changed label, a swapped action order and a changed style.
+    await page.evaluate(() => { document.querySelector('dialog#modal[open] label[for="action-input"]').textContent = 'Folder'; });
+    expect(await paths()).toEqual(['label.text']);
+    await page.evaluate(() => { document.querySelector('dialog#modal[open] label[for="action-input"]').textContent = 'Folder path'; });
+    await page.evaluate(() => { const actions = document.querySelector('dialog#modal[open] .dialog-actions'); actions.prepend(actions.lastElementChild); });
+    expect(await paths()).toEqual(expect.arrayContaining(['actions.buttons.0.text', 'actions.buttons.1.text']));
+    await page.evaluate(() => { const actions = document.querySelector('dialog#modal[open] .dialog-actions'); actions.prepend(actions.lastElementChild); });
+    const undoStyle = await mutate(page, { css: 'dialog#modal #action-input { border-color: rgb(255, 0, 0); } dialog#modal .dialog-actions { gap: 31px; }' });
+    expect(await paths()).toEqual(expect.arrayContaining(['input.borderTopColor', 'actions.columnGap']));
+    await undoStyle();
+    expect(diffInventory(expected, await page.evaluate(measureAddSource))).toEqual([]);
+});
+
+/**
+ * Runs in the page: the open "Thumbnail maintenance" dialog (the concept's `thumbnail-review`, app.js 1433–1437): its
+ * title, the body's tree, each `.field` (label, control, options, selection, limits), the `p.small` line and the
+ * actions, with the concept's geometry and tokens. The concept has no `p.small`, so a probe one stands in for its style.
+ */
+function measureThumbnailReview() {
+    const dialog = document.querySelector('dialog#modal[open]');
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const text = node => node?.textContent.trim() ?? null;
+    const body = dialog.querySelector('#modal-body');
+    const fields = [...body.querySelectorAll(':scope > .field')].map(field => {
+        const label = field.querySelector(':scope > label');
+        const control = field.querySelector(':scope > select, :scope > input');
+        return {
+            tree: [...field.children].map(name),
+            ...css(field, 'display', 'flexDirection', 'rowGap', 'marginBottom'),
+            label: { text: text(label), for: label.htmlFor, ...css(label, 'fontSize', 'fontWeight', 'color') },
+            control: { id: control.id, tag: control.localName, type: control.type,
+                options: control.options ? [...control.options].map(option => option.textContent) : null,
+                selected: control.options ? control.selectedIndex : null,
+                value: control.localName === 'input' ? control.value : null,
+                min: control.getAttribute('min'), max: control.getAttribute('max'),
+                ...css(control, 'height', 'paddingLeft', 'fontSize', 'color', 'backgroundColor', 'borderTopColor', 'borderTopLeftRadius') },
+        };
+    });
+    let line = body.querySelector(':scope > p.small');
+    const probe = !line;
+    if (probe) { line = document.createElement('p'); line.className = 'small'; body.append(line); }
+    const plan = { text: probe ? null : text(line), role: probe ? null : line.getAttribute('role'),
+        ...css(line, 'fontSize', 'color', 'marginTop', 'marginBottom') };
+    if (probe) line.remove();
+    const actions = body.querySelector(':scope > .dialog-actions');
+    const rect = dialog.getBoundingClientRect();
+    return {
+        title: text(dialog.querySelector('#modal-title')),
+        tree: [...body.children].map(name),
+        fields,
+        plan,
+        actions: { tree: [...actions.children].map(name), ...css(actions, 'display', 'justifyContent', 'columnGap', 'marginTop'),
+            buttons: [...actions.children].map(button => ({ text: text(button), className: button.className,
+                ...css(button, 'backgroundColor', 'color', 'fontSize', 'paddingTop', 'paddingLeft', 'borderTopColor') })) },
+        width: Math.round(rect.width),
+    };
+}
+
+/**
+ * D99: the planned counts line (`p.small[role=status]`) before the actions, from the server's plan for the chosen
+ * options, and the primary "Start" (the concept's "Simulate thumbnail job"). D131 (#317): the Quality and Preview size
+ * limit fields give way to a second `p.small` naming the server's thumbnail settings, and Scope gains "Convert
+ * outdated (removes older formats)".
+ */
+function mapThumbnailConcept(reference, plan) {
+    const [cancel, start] = reference.actions.buttons;
+    const [scope] = reference.fields;
+    const tree = ['div.field', 'p.small', 'p.small', 'div.dialog-actions'];
+    const fields = [{ ...scope, control: { ...scope.control, options: [...scope.control.options, 'Convert outdated (removes older formats)'] } }];
+    return { ...reference, tree, fields,
+        plan: { ...reference.plan, role: 'status',
+            text: `${number(plan.targets)} ${plan.targets === 1 ? 'preview' : 'previews'} to generate · ${number(plan.fresh)} already up to date.` },
+        actions: { ...reference.actions, buttons: [cancel, { ...start, text: 'Start' }] } };
+}
+
+async function conceptThumbnailReview(page, theme) {
+    await conceptSources(page, theme, { notice: false });
+    const row = page.locator('#main .operation').filter({ has: page.getByRole('heading', { name: 'Thumbnail generation', exact: true }) });
+    await row.getByRole('button', { name: 'Review options', exact: true }).click();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Thumbnail maintenance');
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureThumbnailReview);
+}
+
+/** Production's dialog from Sources' Review options or Overview's Review thumbnails, once its plan line answered. */
+async function productionThumbnailReview(page, theme, entry) {
+    if (entry === 'sources') {
+        await productionSources(page, theme, { notice: false });
+        const row = page.locator('#workspace-main .operation').filter({ has: page.getByRole('heading', { name: 'Thumbnail generation', exact: true }) });
+        await row.getByRole('button', { name: 'Review options', exact: true }).click();
+    } else {
+        await openProduction(page, 'system/overview', theme);
+        await page.locator('#workspace-main').getByRole('button', { name: 'Review thumbnails', exact: true }).click();
+    }
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Thumbnail maintenance');
+    await expect(page.locator('dialog#modal[open] #modal-body > p.small').first()).toHaveText(/ already up to date\.$/);
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureThumbnailReview);
+}
+
+const thumbnailPlan = request => serverJson(request, '/prompt_manager/images/thumbnails/plan?mode=missing');
+
+for (const entry of ['sources', 'overview']) for (const theme of THEMES) for (const [width, height] of SIZES) {
+    test(`thumbnail dialog matches the concept from ${entry} ${theme} ${width}x${height}`, async ({ page, request }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        await watchedSources(request);
+        const plan = await thumbnailPlan(request);
+        const concept = await conceptThumbnailReview(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`concept-thumbnail-review-${theme}-${width}.png`) });
+        const production = await productionThumbnailReview(page, theme, entry);
+        await page.screenshot({ path: testInfo.outputPath(`production-thumbnail-review-${entry}-${theme}-${width}.png`) });
+        expect(diffInventory(mapThumbnailConcept(concept, plan), production)).toEqual([]);
+    });
+}
+
+test('thumbnail dialog comparison detects mutations', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await watchedSources(request);
+    const plan = await thumbnailPlan(request);
+    const concept = await conceptThumbnailReview(page, 'dark');
+    const expected = mapThumbnailConcept(concept, plan);
+    const production = await productionThumbnailReview(page, 'dark', 'sources');
+    expect(diffInventory(expected, production)).toEqual([]);
+    // Unmapped, the concept differs only where D99 and D131 are recorded.
+    expect(diffInventory(concept, production).map(item => item.path.split('.').slice(0, 2).join('.'))
+        .filter((path, index, all) => all.indexOf(path) === index).sort())
+        .toEqual(['actions.buttons', 'fields.0', 'fields.1', 'fields.2', 'fields.length', 'plan.role', 'plan.text', 'tree.1', 'tree.2']
+            .sort());
+    const paths = async () => diffInventory(expected, await page.evaluate(measureThumbnailReview)).map(item => item.path);
+    // A changed option label, a swapped option order, a swapped action order and a changed style.
+    await page.evaluate(() => { document.querySelector('#thumb-mode option').textContent = 'Missing only'; });
+    expect(await paths()).toEqual(['fields.0.control.options.0']);
+    await page.evaluate(() => { document.querySelector('#thumb-mode option').textContent = 'Missing thumbnails only'; });
+    await page.evaluate(() => { const select = document.querySelector('#thumb-mode'); select.prepend(select.lastElementChild); });
+    expect(await paths()).toEqual(expect.arrayContaining(['fields.0.control.options.0', 'fields.0.control.options.1']));
+    await page.evaluate(() => { const select = document.querySelector('#thumb-mode'); select.append(select.firstElementChild); select.selectedIndex = 0; });
+    await page.evaluate(() => { const actions = document.querySelector('dialog#modal[open] .dialog-actions'); actions.prepend(actions.lastElementChild); });
+    expect(await paths()).toEqual(expect.arrayContaining(['actions.buttons.0.text', 'actions.buttons.1.text']));
+    await page.evaluate(() => { const actions = document.querySelector('dialog#modal[open] .dialog-actions'); actions.prepend(actions.lastElementChild); });
+    const undoStyle = await mutate(page, { css: 'dialog#modal #thumb-mode { border-color: rgb(255, 0, 0); } dialog#modal #modal-body > p.small { color: rgb(255, 0, 0); }' });
+    expect(await paths()).toEqual(expect.arrayContaining(['fields.0.control.borderTopColor', 'plan.color']));
+    await undoStyle();
+    expect(diffInventory(expected, await page.evaluate(measureThumbnailReview))).toEqual([]);
+});
+
+/**
+ * Runs in the page: one `.notice` (the concept's markup: `div > h2 + p`, then `.row-actions` buttons) with its tokens and
+ * geometry, and its left edge against `edgeSelector` (the content it lines up with).
+ */
+function measureNoticeOf([selector, edgeSelector]) {
+    const notice = document.querySelector(selector);
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const text = node => node?.textContent.trim() ?? null;
+    const button = node => ({ text: text(node), className: node.className,
+        ...css(node, 'backgroundColor', 'color', 'fontSize', 'paddingTop', 'paddingLeft', 'borderTopColor', 'borderTopLeftRadius') });
+    const edge = document.querySelector(edgeSelector);
+    return {
+        tree: [...notice.children].map(name),
+        text: [...notice.querySelectorAll(':scope > div:not(.row-actions) > *')].map(node => [node.localName, text(node)]),
+        actions: [...notice.querySelectorAll(':scope > .row-actions > button')].map(button),
+        frame: css(notice, 'display', 'alignItems', 'justifyContent', 'columnGap', 'borderTopWidth', 'borderTopColor',
+            'borderTopLeftRadius', 'backgroundColor', 'paddingTop', 'paddingLeft', 'marginBottom', 'flexDirection'),
+        h2: css(notice.querySelector('h2'), 'fontSize', 'fontWeight', 'color'),
+        p: css(notice.querySelector('p'), 'fontSize', 'color', 'marginTop'),
+        rowActions: css(notice.querySelector(':scope > .row-actions'), 'display', 'columnGap', 'flexShrink'),
+        alignedWith: Math.round(notice.getBoundingClientRect().left - edge.getBoundingClientRect().left),
+        pageScroll: document.documentElement.scrollWidth > document.documentElement.clientWidth,
+    };
+}
+
+/** D129: the concept's Sources notice as the library notice: its own copy and actions, no bottom margin (main's padding). */
+function mapLibraryNotice(reference) {
+    return {
+        ...reference,
+        text: [['h2', 'Your library is inside the node folder'], ['p', 'Your library is stored inside the node folder, where an '
+            + 'update or reinstall can delete it. Move it to ComfyUI\'s user folder: it is copied and verified first, and nothing '
+            + 'is deleted.']],
+        actions: reference.actions.map((action, index) => ({ ...action, text: ['Keep it here', 'Move library'][index] })),
+        frame: { ...reference.frame, marginBottom: '0px' },
+    };
+}
+
+async function conceptNotice(page, theme) {
+    await openConcept(page, 'system', theme);
+    await page.locator('#main .section-nav').getByRole('button', { name: 'Sources & scans', exact: true }).click();
+    await expect(page.locator('#main .settings-layout > .notice')).toBeVisible();
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureNoticeOf, ['#main .settings-layout > .notice', '#main .heading']);
+}
+
+async function productionNotice(page, theme) {
+    await openProduction(page, 'system/overview', theme);
+    await expect(page.locator('#library-banner > .notice')).toBeVisible();
+    await expect(page.locator('#workspace-main .summary-metrics')).toBeVisible();
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureNoticeOf, ['#library-banner > .notice', '#workspace-main .heading']);
+}
+
+for (const theme of THEMES) for (const [width, height] of SIZES) {
+    test(`library notice matches the concept notice ${theme} ${width}x${height}`, async ({ page, request }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        await expect(await request.post('/__test__/system/library', { data: { state: 'node_folder' } })).toBeOK();
+        const concept = await conceptNotice(page, theme);
+        const production = await productionNotice(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`production-library-notice-${theme}-${width}.png`), fullPage: true });
+        expect(diffInventory(mapLibraryNotice(concept), production)).toEqual([]);
+        expect(production.alignedWith).toBe(0);
+        expect(production.pageScroll).toBe(false);
+    });
+}
+
+test('library notice comparison detects mutations', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await expect(await request.post('/__test__/system/library', { data: { state: 'node_folder' } })).toBeOK();
+    const expected = mapLibraryNotice(await conceptNotice(page, 'dark'));
+    await productionNotice(page, 'dark');
+    const paths = async () => diffInventory(expected,
+        await page.evaluate(measureNoticeOf, ['#library-banner > .notice', '#workspace-main .heading'])).map(item => item.path);
+    expect(await paths()).toEqual([]);
+    const undoToken = await mutate(page, { css: '#library-banner { --soft-blue: rgb(255, 0, 0); }' });
+    expect(await paths()).toEqual(['frame.backgroundColor']);
+    await undoToken();
+    await page.evaluate(() => { document.querySelector('#library-banner .notice h2').textContent = 'Library'; });
+    expect(await paths()).toEqual(['text.0.1']);
+});

tests/browser/system-integrations-concept.spec.mjs

@@ -0,0 +1,343 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { SIZES, THEMES, seedConcept, openConcept, openProduction, diffInventory, mutate } from './concept-inventory.mjs';
+
+// #249 System S10 Task 28: System › Integrations (app.js renderSystem 682–684) and the LoRA import review against the
+// immutable concept, on the concept-shaped fixture with a fake LoraManager install. Each concept measurement is mapped
+// only by the recorded deviations (D106, D107, D114), each commented where it applies; after that the difference must
+// be empty, and a mutated label, option, row or token must be noticed. The concept starts its sample import without a
+// review, so the import review is compared with the concept's own record-changing review, `maintenancePlan`
+// (953–958), whose shell, grid, note and actions it shares.
+test.use({ locale: 'en-US', timezoneId: 'UTC' });
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await seedConcept(request);
+    await expect(await request.post('/__test__/system/reset')).toBeOK();
+    await expect(await request.post('/__test__/integrations/reset')).toBeOK();
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    page.conceptErrors = [];
+    page.on('pageerror', error => page.conceptErrors.push(error.message));
+});
+
+test.afterEach(async ({ page, request, browserName }) => {
+    await saveCoverage(page, browserName);
+    await request.post('/__test__/jobs/restart');
+    await request.post('/__test__/integrations/reset');
+    await request.post('/__test__/system/reset');
+    expect(page.conceptErrors).toEqual([]);
+});
+
+const PREVIEW_URL = '/prompt_manager/lora/import/preview';
+
+/** Runs in the page: Integrations' surfaces under `mainSelector`, every row's text and control, geometry and tokens. */
+function measureIntegrations(mainSelector) {
+    const layout = document.querySelector(`${mainSelector} .settings-layout`);
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const text = node => node?.textContent.trim() ?? null;
+    const control = row => {
+        const select = row.querySelector(':scope > select');
+        if (select) return { kind: 'select', id: select.id, options: [...select.options].map(option => [option.textContent, option.disabled]),
+            selected: select.selectedOptions[0]?.textContent ?? null, disabled: select.disabled };
+        const input = row.querySelector(':scope > input');
+        if (input) return { kind: `input.${input.type}`, id: input.id, value: input.value, readOnly: input.readOnly };
+        const toggle = row.querySelector(':scope > * input[type="checkbox"]');
+        return toggle ? { kind: 'switch', id: toggle.id, wrapper: name(toggle.parentElement), checked: toggle.checked,
+            disabled: toggle.disabled, ...css(toggle.parentElement, 'width', 'height') } : null;
+    };
+    const surfaces = [...layout.querySelectorAll(':scope > section.surface')];
+    const firstRow = surfaces[0].querySelector('.setting-row');
+    const note = layout.querySelector('.setting-row p.small');
+    return {
+        layout: [...layout.children].map(name),
+        surfaces: surfaces.map(surface => ({ tree: [...surface.children].map(name), heading: text(surface.querySelector(':scope > h2')),
+            intro: text(surface.querySelector(':scope > p')),
+            rows: [...surface.querySelectorAll(':scope > .setting-row')].map(row => ({ tree: [...row.children].map(name),
+                text: [...row.firstElementChild.children].map(node => [name(node), text(node), node.localName === 'label' ? node.htmlFor : null]),
+                control: control(row) })),
+            operations: [...surface.querySelectorAll(':scope > .operation')].map(row => ({ tree: [...row.children].map(name),
+                title: text(row.querySelector('h3')), description: text(row.querySelector('p')),
+                actions: [...row.querySelectorAll('.row-actions > button')].map(item => [text(item), item.className]) })) })),
+        surface: css(surfaces[1], 'paddingTop', 'paddingLeft', 'backgroundColor', 'borderTopWidth', 'borderTopColor', 'borderTopLeftRadius',
+            'marginTop'),
+        row: css(firstRow, 'display', 'alignItems', 'justifyContent', 'columnGap', 'paddingTop', 'paddingBottom', 'borderTopWidth',
+            'borderTopColor', 'marginTop'),
+        label: css(firstRow.querySelector('label'), 'fontSize', 'fontWeight', 'color'),
+        description: css(firstRow.querySelector('p'), 'fontSize', 'color', 'marginTop', 'maxWidth'),
+        select: css(firstRow.querySelector('select'), 'fontSize', 'minWidth', 'maxWidth', 'backgroundColor', 'color', 'borderTopColor'),
+        password: css(layout.querySelector('.setting-row input[type="password"]'), 'fontSize', 'minWidth', 'maxWidth', 'backgroundColor',
+            'color', 'borderTopColor'),
+        // The concept's `.small` text (its Save row status); production's row notes use the same class.
+        small: css(layout.querySelector('#settings-status'), 'fontSize', 'color'),
+        note: note && css(note, 'fontSize', 'color'),
+        // Whether each select is as wide as the browser lays out a copy holding only its chosen option, i.e. it shows
+        // that option whole (the browser's own select sizing, arrow included).
+        selectsFit: [...layout.querySelectorAll('.setting-row > select')].map(select => {
+            const copy = select.cloneNode(false);
+            copy.removeAttribute('id');
+            copy.append(new Option(select.selectedOptions[0]?.textContent ?? ''));
+            Object.assign(copy.style, { position: 'absolute', visibility: 'hidden', width: 'max-content', minWidth: '0',
+                maxWidth: 'none', flex: 'none' });
+            select.parentElement.append(copy);
+            const needed = copy.getBoundingClientRect().width;
+            copy.remove();
+            return select.getBoundingClientRect().width + 0.5 >= needed;
+        }),
+        pageScroll: document.documentElement.scrollWidth > document.documentElement.clientWidth,
+    };
+}
+
+const SEND_REASON = 'Sending always asks for the ComfyUI window and node, so “Ask each time” is the only option.';
+const RENDERER_REASON = 'Prompt Manager nodes always follow ComfyUI’s own renderer setting.';
+const RENDERER_NONE = 'No ComfyUI window is open in this browser, so its renderer is not known.';
+const RETURN_REASON = 'Not available: sending applies the text in ComfyUI and keeps this page open.';
+const PATH_DESCRIPTION = 'Found automatically in ComfyUI’s custom_nodes folders; read-only, as on the existing settings page.';
+
+/**
+ * The concept's Integrations with the recorded deviations applied, for the fixture's LoraManager (detected, disabled,
+ * no key, trigger words off and not loaded).
+ */
+function mapIntegrationsConcept(reference) {
+    const [comfy, lora] = reference.surfaces;
+    const small = text => ['p.small', text, null];
+    const firstOnly = row => ({ ...row, control: { ...row.control, options: row.control.options.map(([label], index) => [label, index > 0]) } });
+    const [send, renderer, back] = comfy.rows;
+    const [enable, triggers, key] = lora.rows;
+    return {
+        ...reference,
+        surfaces: [
+            { ...comfy, rows: [
+                // D106: only "Ask each time" can be chosen, and the row says why.
+                { ...firstOnly(send), text: [...send.text, small(SEND_REASON)] },
+                // D106: only "Follow host renderer" can be chosen; the reason, then the detected renderer.
+                { ...firstOnly(renderer), text: [...renderer.text, small(RENDERER_REASON), small(RENDERER_NONE)] },
+                // D106: Return to canvas is not available: off, disabled and saying why.
+                { ...back, text: [...back.text, small(RETURN_REASON)], control: { ...back.control, checked: false, disabled: true } },
+            ] },
+            { ...lora,
+                // D106: the LoraManager path row (legacy, read-only) follows the integration toggle.
+                tree: [lora.tree[0], lora.tree[1], 'div.setting-row', 'div.setting-row', 'div.setting-row', 'div.setting-row', 'div.operation'],
+                rows: [
+                    // The real detection replaces the concept's sample line; the integration is off in the fixture.
+                    { ...enable, text: [enable.text[0], ['p', 'Detected: custom_nodes/ComfyUI-Lora-Manager.', null]],
+                        control: { ...enable.control, checked: false } },
+                    { tree: ['div', 'input'],
+                        text: [['label', 'LoraManager path', 'lora-path'], ['p', PATH_DESCRIPTION, null]],
+                        control: { kind: 'input.text', id: 'lora-path', value: 'custom_nodes/ComfyUI-Lora-Manager', readOnly: true } },
+                    // The trigger cache is a separate fact from the setting: its own line.
+                    { ...triggers, text: [...triggers.text, small('Trigger words are not loaded.')], control: { ...triggers.control, checked: false } },
+                    // D114: no prototype warning; the saved-key line under it.
+                    // (No key is saved in the fixture, so "Clear saved key" is not offered.)
+                    { ...key, text: [key.text[0], ['p', 'Credentials stay in the server configuration.', null], small('No key saved.')],
+                        control: { ...key.control, value: '' } },
+                ],
+                // D107: the import is reviewed first ("Review import"; the concept's button only simulated a job).
+                operations: lora.operations.map(operation => ({ ...operation, actions: [['Review import', '']] })) },
+        ],
+        // D106: both selects show their whole chosen option at every width (at 390 the concept cuts "Follow host
+        // renderer"; production lets the two selects grow to 160px and never shrink for the reason lines).
+        selectsFit: reference.selectsFit.map(() => true),
+        select: reference.select.maxWidth === '120px' ? { ...reference.select, maxWidth: '160px' } : reference.select,
+        // The D106/D114 row notes are `p.small` inside the row text, so they read as its description (`.setting-row p`).
+        note: { fontSize: reference.description.fontSize, color: reference.description.color },
+    };
+}
+
+async function conceptIntegrations(page, theme) {
+    await openConcept(page, 'system', theme);
+    await page.locator('#main .section-nav').getByRole('button', { name: 'Integrations', exact: true }).click();
+    await expect(page.locator('#main .settings-layout > section.surface')).toHaveCount(2);
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureIntegrations, '#main');
+}
+
+async function productionIntegrations(page, theme) {
+    await openProduction(page, 'system/integrations', theme);
+    // Compare once the LoRA state and the renderer check answered.
+    await expect(page.locator('#workspace-main #lora-path')).toHaveValue('custom_nodes/ComfyUI-Lora-Manager');
+    await expect(page.locator('#workspace-main #renderer-status')).toHaveText(RENDERER_NONE);
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureIntegrations, '#workspace-main');
+}
+
+const fakeLoraManager = async (request, data = {}) =>
+    expect(await request.post('/__test__/integrations/lora-manager', { data })).toBeOK();
+
+for (const theme of THEMES) for (const [width, height] of SIZES) {
+    test(`integrations matches the concept ${theme} ${width}x${height}`, async ({ page, request }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        await fakeLoraManager(request);
+        const concept = await conceptIntegrations(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`concept-integrations-${theme}-${width}.png`), fullPage: true });
+        const production = await productionIntegrations(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`production-integrations-${theme}-${width}.png`), fullPage: true });
+        expect(diffInventory(mapIntegrationsConcept(concept), production)).toEqual([]);
+        expect(production.pageScroll).toBe(false);
+    });
+}
+
+// D106 below the concept's smallest size: on a 320px phone both selects still show their whole option, without page
+// scroll (S10 re-review N9).
+for (const theme of THEMES) test(`integrations selects fit at 320 wide ${theme}`, async ({ page, request }) => {
+    await page.setViewportSize({ width: 320, height: 700 });
+    await fakeLoraManager(request);
+    const production = await productionIntegrations(page, theme);
+    expect(production.selectsFit).toEqual([true, true]);
+    expect(production.pageScroll).toBe(false);
+});
+
+test('integrations comparison detects mutations', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await fakeLoraManager(request);
+    const concept = await conceptIntegrations(page, 'dark');
+    const expected = mapIntegrationsConcept(concept);
+    const production = await productionIntegrations(page, 'dark');
+    expect(diffInventory(expected, production)).toEqual([]);
+    // Unmapped, the section differs only where D106, D107 and D114 are recorded.
+    expect(diffInventory(concept, production).map(item => item.path.split('.').slice(0, 4).join('.'))
+        .filter((path, index, all) => all.indexOf(path) === index).sort()).toEqual([
+        'note', 'note.color', 'note.fontSize', 'surfaces.0.rows.0', 'surfaces.0.rows.1', 'surfaces.0.rows.2', 'surfaces.1.operations.0',
+        'surfaces.1.rows.0', 'surfaces.1.rows.1', 'surfaces.1.rows.2', 'surfaces.1.rows.3', 'surfaces.1.rows.length',
+        'surfaces.1.tree.5', 'surfaces.1.tree.6', 'surfaces.1.tree.length'].sort());
+    const measure = () => page.evaluate(measureIntegrations, '#workspace-main');
+    const paths = async () => diffInventory(expected, await measure()).map(item => item.path);
+    // A removed row.
+    const undoRow = await mutate(page, { remove: ['#workspace-main section.surface:nth-of-type(2) > .setting-row:nth-of-type(3)'] });
+    expect(await paths()).toEqual(expect.arrayContaining(['surfaces.1.rows.length', 'surfaces.1.tree.length']));
+    await undoRow();
+    // A changed label and a changed option.
+    await page.evaluate(() => { document.querySelector('#workspace-main label[for="renderer"]').textContent = 'Renderer'; });
+    expect(await paths()).toEqual(['surfaces.0.rows.1.text.0.1']);
+    await page.evaluate(() => { document.querySelector('#workspace-main label[for="renderer"]').textContent = 'Host compatibility'; });
+    await page.evaluate(() => { document.querySelector('#workspace-main #send-destination option').textContent = 'Always ask'; });
+    expect(await paths()).toEqual(expect.arrayContaining(['surfaces.0.rows.0.control.options.0.0']));
+    await page.evaluate(() => { document.querySelector('#workspace-main #send-destination option').textContent = 'Ask each time'; });
+    // An unsupported option that became selectable.
+    await page.evaluate(() => { document.querySelectorAll('#workspace-main #renderer option')[1].disabled = false; });
+    expect(await paths()).toEqual(['surfaces.0.rows.1.control.options.1.1']);
+    await page.evaluate(() => { document.querySelectorAll('#workspace-main #renderer option')[1].disabled = true; });
+    // A select squeezed until its chosen option is cut (S10 review M3).
+    const undoSqueeze = await mutate(page, { css: '#workspace-main #renderer { max-width: 70px !important; }' });
+    expect(await paths()).toEqual(['selectsFit.1']);
+    await undoSqueeze();
+    // A swapped token.
+    const undoToken = await mutate(page, { css: '#workspace-main .settings-layout { --line: rgb(255, 0, 0); }' });
+    expect(await paths()).toEqual(expect.arrayContaining(['row.borderTopColor']));
+    await undoToken();
+    expect(diffInventory(expected, await measure())).toEqual([]);
+});
+
+/** Runs in the page: the open review dialog: its title, body and the concept's tokens. */
+function measureReview() {
+    const dialog = document.querySelector('dialog#modal[open]');
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const text = node => node?.textContent.trim() ?? null;
+    const body = dialog.querySelector('#modal-body');
+    const grid = body.querySelector(':scope > dl.meta-grid');
+    const note = [...body.querySelectorAll(':scope > p.small')].at(-1);
+    const actions = body.querySelector(':scope > .dialog-actions');
+    return {
+        title: text(dialog.querySelector('#modal-title')),
+        tree: [...body.children].map(name),
+        heading: { text: text(body.querySelector(':scope > h3')),
+            ...css(body.querySelector(':scope > h3'), 'fontSize', 'fontWeight', 'color', 'marginBottom') },
+        grid: { rows: [...grid.children].map(row => [text(row.querySelector('dt')), text(row.querySelector('dd'))]),
+            ...css(grid, 'display', 'gridTemplateColumns', 'columnGap', 'rowGap'),
+            dt: css(grid.querySelector('dt'), 'fontSize', 'color', 'textTransform'), dd: css(grid.querySelector('dd'), 'fontSize', 'color') },
+        details: body.querySelector(':scope > details') && { summary: text(body.querySelector(':scope > details > summary')),
+            tree: [...body.querySelector(':scope > details').children].map(name) },
+        backup: body.querySelector(':scope > .notice') && { tree: [...body.querySelector(':scope > .notice').children].map(name),
+            text: [...body.querySelectorAll(':scope > .notice > div:first-child > *')].map(node => [node.localName, text(node)]),
+            buttons: [...body.querySelectorAll(':scope > .notice button')].map(text) },
+        note: { text: text(note), ...css(note, 'fontSize', 'color', 'marginTop') },
+        actions: { tree: [...actions.children].map(name), ...css(actions, 'display', 'justifyContent', 'columnGap', 'marginTop'),
+            buttons: [...actions.children].map(item => ({ text: text(item), className: item.className,
+                ...css(item, 'backgroundColor', 'color', 'fontSize', 'paddingTop', 'paddingLeft', 'borderTopColor') })) },
+    };
+}
+
+/**
+ * D107: the server's import plan in the concept's review: "Review LoRA import" with "LoRA reference data" as its `h3`,
+ * the concept's four rows with the plan's values plus Found and Network, the LoRAs it found (`details`), the hold
+ * line with the cache sentence in the concept's `p.small`, the D55 backup box, and Cancel / "Start import".
+ */
+function mapImportConcept(reference, plan) {
+    const [cancel, start] = reference.actions.buttons;
+    return {
+        ...reference,
+        title: 'Review LoRA import',
+        tree: ['h3', 'dl.meta-grid', 'details', 'p.small', 'div.notice', 'div.dialog-actions'],
+        heading: { ...reference.heading, text: 'LoRA reference data' },
+        grid: { ...reference.grid, rows: [['Scope', plan.scope.label], ['Found', '2 metadata files · 2 readable'],
+            ['Protected', 'Nothing is protected'], ['Network', 'Downloads up to 2 example images from CivitAI'],
+            ['Backup', `Create and verify before changes (${plan.backup.destination_label})`],
+            ['Media on disk', 'No files are removed; image links are replaced']] },
+        details: { summary: 'LoRAs found (2)', tree: ['summary', 'pre'] },
+        backup: { tree: ['div', 'div.row-actions'], text: [['h3', 'Back up the database first (recommended)'],
+            ['p', 'Downloads a copy of the prompts database before this operation changes any records.']], buttons: ['Back up now'] },
+        note: { ...reference.note, text: 'Nothing changes until you apply. This review holds for 15 minutes. '
+            + 'Example images downloaded before a failure stay in the image cache.' },
+        actions: { ...reference.actions, buttons: [cancel, { ...start, text: 'Start import' }] },
+    };
+}
+
+async function conceptReview(page, theme) {
+    await openConcept(page, 'system', theme);
+    await page.locator('#main .section-nav').getByRole('button', { name: 'Maintenance', exact: true }).click();
+    await page.locator('#main [data-plan="duplicate prompts"]').click();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Review maintenance plan');
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureReview);
+}
+
+async function productionReview(page, request, theme) {
+    await openProduction(page, 'system/integrations', theme);
+    await expect(page.locator('#workspace-main #lora-path')).toHaveValue('custom_nodes/ComfyUI-Lora-Manager');
+    // The renderer line above settles first: its new text moves the rows below (a click must not land mid-shift).
+    await expect(page.locator('#workspace-main #renderer-status')).toHaveText(RENDERER_NONE);
+    // The import reviews what is enabled: save the integration on first.
+    await page.locator('#workspace-main #lora-enable').check();
+    await page.getByRole('button', { name: 'Save preferences', exact: true }).click();
+    await expect(page.locator('#settings-status')).toHaveText('Saved to the server configuration.');
+    const answer = page.waitForResponse(response => response.url().endsWith(PREVIEW_URL));
+    await page.locator('#workspace-main').getByRole('button', { name: 'Review import', exact: true }).click();
+    const plan = await (await answer).json();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Review LoRA import');
+    await page.mouse.move(0, 0);
+    return { plan, production: await page.evaluate(measureReview) };
+}
+
+for (const theme of THEMES) for (const [width, height] of SIZES) {
+    test(`LoRA import review matches the concept ${theme} ${width}x${height}`, async ({ page, request }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        await fakeLoraManager(request, { loras: 2, civitai: true });
+        const concept = await conceptReview(page, theme);
+        expect(concept.tree).toEqual(['p.demo-note', 'h3', 'dl.meta-grid', 'p.small', 'div.dialog-actions']);
+        await page.screenshot({ path: testInfo.outputPath(`concept-plan-review-${theme}-${width}.png`) });
+        const { plan, production } = await productionReview(page, request, theme);
+        await page.screenshot({ path: testInfo.outputPath(`production-lora-review-${theme}-${width}.png`) });
+        expect(diffInventory(mapImportConcept(concept, plan), production)).toEqual([]);
+    });
+}
+
+test('LoRA import review comparison detects mutations', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await fakeLoraManager(request, { loras: 2, civitai: true });
+    const concept = await conceptReview(page, 'dark');
+    const { plan } = await productionReview(page, request, 'dark');
+    const expected = mapImportConcept(concept, plan);
+    const paths = async () => diffInventory(expected, await page.evaluate(measureReview)).map(item => item.path);
+    expect(await paths()).toEqual([]);
+    await page.evaluate(() => { document.querySelectorAll('dialog#modal[open] dl.meta-grid dt')[3].textContent = 'Downloads'; });
+    expect(await paths()).toEqual(['grid.rows.3.0']);
+    await page.evaluate(() => { document.querySelectorAll('dialog#modal[open] dl.meta-grid dt')[3].textContent = 'Network'; });
+    const undoGrid = await mutate(page, { css: 'dialog#modal dl.meta-grid { column-gap: 3px; }' });
+    expect(await paths()).toEqual(expect.arrayContaining(['grid.columnGap']));
+    await undoGrid();
+    const undoBox = await mutate(page, { remove: ['dialog#modal[open] #modal-body > .notice'] });
+    expect(await paths()).toEqual(expect.arrayContaining(['backup', 'tree.length']));
+    await undoBox();
+    expect(await paths()).toEqual([]);
+});

tests/browser/system-maintenance-concept.spec.mjs

@@ -0,0 +1,332 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { SIZES, THEMES, seedConcept, openConcept, openProduction, diffInventory, mutate } from './concept-inventory.mjs';
+
+// #249 System S7 Task 20: System › Maintenance (app.js renderSystem 688–690), its plan dialog (`maintenancePlan`,
+// 953–958) for each operation and its duplicates dialog (`duplicates`, 1457–1461) against the immutable concept, on
+// the concept-shaped real fixture. Each concept measurement is mapped only by the recorded deviations (D100, D101,
+// D102; the health report is D95, compared in system-concept.spec), each commented where it applies; after that the
+// difference must be empty, and a mutated label, row or token must be noticed.
+test.use({ locale: 'en-US', timezoneId: 'UTC' });
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await seedConcept(request);
+    await expect(await request.post('/__test__/system/reset')).toBeOK();
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    page.conceptErrors = [];
+    page.on('pageerror', error => page.conceptErrors.push(error.message));
+});
+
+test.afterEach(async ({ page, request, browserName }) => {
+    await saveCoverage(page, browserName);
+    await request.post('/__test__/jobs/restart');
+    await request.post('/__test__/system/reset');
+    expect(page.conceptErrors).toEqual([]);
+});
+
+const PREVIEW_URL = '/prompt_manager/maintenance/preview';
+
+/** Runs in the page: Maintenance's notice and surfaces under `mainSelector`, with the concept's geometry and tokens. */
+function measureMaintenance(mainSelector) {
+    const layout = document.querySelector(`${mainSelector} .settings-layout`);
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const text = node => node?.textContent.trim() ?? null;
+    const button = node => ({ text: text(node), className: node.className,
+        ...css(node, 'backgroundColor', 'color', 'fontSize', 'paddingTop', 'paddingLeft', 'borderTopColor', 'opacity', 'cursor') });
+    const box = node => {
+        const rect = node.getBoundingClientRect(), base = layout.getBoundingClientRect();
+        return { left: Math.round(rect.left - base.left), width: Math.round(rect.width) };
+    };
+    const notice = layout.querySelector(':scope > .notice');
+    const surfaces = [...layout.querySelectorAll(':scope > section.surface')];
+    const operation = surfaces[0].querySelector('.operation');
+    return {
+        layout: [...layout.children].map(name),
+        notice: { tree: [...notice.children].map(name), text: [...notice.querySelectorAll(':scope > div > *')].map(node => [node.localName, text(node)]),
+            run: button(notice.querySelector(':scope > button')),
+            ...css(notice, 'display', 'alignItems', 'justifyContent', 'columnGap', 'borderTopColor', 'backgroundColor', 'paddingTop', 'marginBottom') },
+        surfaces: surfaces.map(surface => ({ tree: [...surface.children].map(name), heading: text(surface.querySelector(':scope > h2')),
+            box: box(surface),
+            rows: [...surface.querySelectorAll(':scope > .operation')].map(row => ({ tree: [...row.children].map(name),
+                title: text(row.querySelector('h3')), description: text(row.querySelector('p')),
+                actions: [...row.querySelectorAll('.row-actions > button')].map(button) })) })),
+        surface: css(surfaces[0], 'paddingTop', 'paddingLeft', 'backgroundColor', 'borderTopWidth', 'borderTopColor', 'borderTopLeftRadius', 'marginTop'),
+        h2: css(surfaces[0].querySelector('h2'), 'fontSize', 'fontWeight', 'color', 'marginBottom'),
+        operation: css(operation, 'display', 'alignItems', 'justifyContent', 'columnGap', 'paddingTop', 'paddingBottom',
+            'borderTopWidth', 'borderTopColor'),
+        h3: css(operation.querySelector('h3'), 'fontSize', 'fontWeight', 'color'),
+        p: css(operation.querySelector('p'), 'fontSize', 'color', 'marginTop'),
+        actions: css(operation.querySelector('.row-actions'), 'display', 'columnGap', 'flexShrink'),
+        pageScroll: document.documentElement.scrollWidth > document.documentElement.clientWidth,
+    };
+}
+
+/** D102: the Metadata cache row says why its review is unavailable and its button is aria-disabled (D93's dimmed style). */
+function mapMaintenanceConcept(reference) {
+    return {
+        ...reference,
+        surfaces: reference.surfaces.map(surface => ({ ...surface, rows: surface.rows.map(row => row.title !== 'Metadata cache' ? row : {
+            ...row, description: `${row.description} Nothing is cached in this browser.`,
+            actions: row.actions.map(action => ({ ...action, opacity: '0.55', cursor: 'not-allowed' })) }) })),
+    };
+}
+
+async function conceptMaintenance(page, theme) {
+    await openConcept(page, 'system', theme);
+    await page.locator('#main .section-nav').getByRole('button', { name: 'Maintenance', exact: true }).click();
+    await expect(page.locator('#main .settings-layout > section.surface')).toHaveCount(2);
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureMaintenance, '#main');
+}
+
+async function productionMaintenance(page, theme) {
+    await openProduction(page, 'system/maintenance', theme);
+    await expect(page.locator('#workspace-main .settings-layout > section.surface')).toHaveCount(2);
+    // The Metadata cache row reads this browser's storage once: compare after it answered.
+    await expect(page.locator('#workspace-main .operation').filter({ hasText: 'Metadata cache' }).locator('p'))
+        .toHaveText(/Nothing is cached in this browser\.$/);
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureMaintenance, '#workspace-main');
+}
+
+for (const theme of THEMES) for (const [width, height] of SIZES) {
+    test(`maintenance matches the concept ${theme} ${width}x${height}`, async ({ page }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        const concept = await conceptMaintenance(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`concept-maintenance-${theme}-${width}.png`), fullPage: true });
+        const production = await productionMaintenance(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`production-maintenance-${theme}-${width}.png`), fullPage: true });
+        expect(diffInventory(mapMaintenanceConcept(concept), production)).toEqual([]);
+        expect(production.pageScroll).toBe(false);
+    });
+}
+
+/** Runs in the page: the open review dialog (plan or duplicates): its title, body and the concept's tokens. */
+function measureReview() {
+    const dialog = document.querySelector('dialog#modal[open]');
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const text = node => node?.textContent.trim() ?? null;
+    const body = dialog.querySelector('#modal-body');
+    const grid = body.querySelector(':scope > dl.meta-grid');
+    const compare = body.querySelector('.compare-grid');
+    const item = compare?.querySelector('.compare-item');
+    const notes = [...body.querySelectorAll(':scope > p.small')];
+    const note = notes.at(-1);
+    const actions = body.querySelector(':scope > .dialog-actions');
+    return {
+        title: text(dialog.querySelector('#modal-title')),
+        tree: [...body.children].map(name),
+        heading: body.querySelector(':scope > h3') && { text: text(body.querySelector(':scope > h3')),
+            ...css(body.querySelector(':scope > h3'), 'fontSize', 'fontWeight', 'color', 'marginBottom') },
+        grid: grid && { rows: [...grid.children].map(row => [text(row.querySelector('dt')), text(row.querySelector('dd'))]),
+            ...css(grid, 'display', 'gridTemplateColumns', 'columnGap', 'rowGap'),
+            dt: css(grid.querySelector('dt'), 'fontSize', 'color', 'textTransform'), dd: css(grid.querySelector('dd'), 'fontSize', 'color') },
+        details: body.querySelector(':scope > details') && { summary: text(body.querySelector(':scope > details > summary')),
+            tree: [...body.querySelector(':scope > details').children].map(name) },
+        backup: body.querySelector(':scope > .notice') && { tree: [...body.querySelector(':scope > .notice').children].map(name),
+            text: [...body.querySelectorAll(':scope > .notice > div:first-child > *')].map(node => [node.localName, text(node)]),
+            buttons: [...body.querySelectorAll(':scope > .notice button')].map(text) },
+        compare: compare && { tree: [...compare.children].map(name), ...css(compare, 'display', 'gridTemplateColumns', 'columnGap'),
+            items: [...compare.children].map(entry => ({ tree: [...entry.children].map(name), label: text(entry.querySelector('label')),
+                checked: entry.querySelector('input[type=radio]').checked, image: entry.querySelector('img')?.className ?? null })),
+            item: css(item, 'paddingTop', 'paddingLeft', 'backgroundColor', 'borderTopWidth', 'borderTopColor', 'borderTopLeftRadius'),
+            image: css(item.querySelector('img'), 'width', 'objectFit'),
+            label: css(item.querySelector('label'), 'fontSize', 'color'),
+            radio: { name: item.querySelector('input[type=radio]').name.startsWith('keep-') ? 'keep-*' : 'other',
+                type: item.querySelector('input').type } },
+        note: note && { text: text(note), ...css(note, 'fontSize', 'color', 'marginTop') },
+        actions: { tree: [...actions.children].map(name), ...css(actions, 'display', 'justifyContent', 'columnGap', 'marginTop'),
+            buttons: [...actions.children].map(item => ({ text: text(item), className: item.className,
+                ...css(item, 'backgroundColor', 'color', 'fontSize', 'paddingTop', 'paddingLeft', 'borderTopColor') })) },
+    };
+}
+
+// The concept's plan names (`data-plan`) and production's operation, row and button for each.
+const PLANS = Object.freeze([
+    ['duplicate prompts', 'duplicate_prompts', 'Duplicate prompt text'],
+    ['database optimization', 'optimize', 'Optimize database'],
+    ['unused prompt components', 'unused_components', 'Unused prompt components'],
+    ['missing-file links', 'missing_links', 'Missing-file links'],
+]);
+const BACKUP_BOX = Object.freeze({ tree: ['div', 'div.row-actions'], text: [['h3', 'Back up the database first (recommended)'],
+    ['p', 'Downloads a copy of the prompts database before this operation changes any records.']], buttons: ['Back up now'] });
+
+/**
+ * D100: the server's plan in the concept's dialog: the operation's row title as its `h3` (the concept prints its
+ * `data-plan` name), the four rows with the plan's values, the listed records (`details`), the hold line in the
+ * concept's `p.small`, the D55 backup box before the actions, and "Apply reviewed operation". No sample note.
+ */
+function mapPlanConcept(reference, title, plan) {
+    const backup = plan.backup.policy === 'off' ? 'No safety backup (the policy is off)'
+        : `Create and verify before changes (${plan.backup.destination_label})`;
+    const tree = ['h3', 'dl.meta-grid', ...(plan.details.length ? ['details'] : []), 'p.small', 'div.notice', 'div.dialog-actions'];
+    const [cancel, apply] = reference.actions.buttons;
+    return {
+        ...reference,
+        tree,
+        heading: { ...reference.heading, text: title },
+        grid: { ...reference.grid, rows: [['Scope', plan.scope.label],
+            ['Protected', plan.protected.reasons.length ? plan.protected.reasons.join(' · ') : 'Nothing is protected'],
+            ['Backup', backup], ['Media on disk', plan.media.label]] },
+        details: plan.details.length ? { summary: `Listed records (${plan.details.length})`, tree: ['summary', 'pre'] } : null,
+        backup: BACKUP_BOX,
+        note: { ...reference.note, text: 'Nothing changes until you apply. This review holds for 15 minutes.' },
+        actions: { ...reference.actions, buttons: [cancel, { ...apply, text: 'Apply reviewed operation' }] },
+    };
+}
+
+async function conceptPlan(page, theme, name) {
+    await conceptMaintenance(page, theme);
+    await page.locator(`#main [data-plan="${name}"]`).click();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Review maintenance plan');
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureReview);
+}
+
+/** Production's plan dialog for the row `title`, with the server's answer its review read. */
+async function productionPlan(page, title) {
+    const answer = page.waitForResponse(response => response.url().endsWith(PREVIEW_URL));
+    await page.locator('#workspace-main .operation').filter({ has: page.locator('h3', { hasText: title }) })
+        .getByRole('button', { name: 'Review plan', exact: true }).click();
+    const plan = await (await answer).json();
+    await expect(page.locator('dialog#modal[open] #modal-body > h3')).toHaveText(title);
+    await page.mouse.move(0, 0);
+    return { plan, production: await page.evaluate(measureReview) };
+}
+
+for (const theme of THEMES) for (const [width, height] of SIZES) {
+    test(`plan dialogs match the concept ${theme} ${width}x${height}`, async ({ page, request }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        // Something to merge, and a missing-file link, so no plan is empty.
+        await expect(await request.post('/__test__/system/duplicate-prompts')).toBeOK();
+        await expect(await request.post('/__test__/system/missing-file')).toBeOK();
+        const concepts = [];
+        for (const [name] of PLANS) {
+            concepts.push(await conceptPlan(page, theme, name));
+            await page.screenshot({ path: testInfo.outputPath(`concept-plan-${name.replace(/\W+/g, '-')}-${theme}-${width}.png`) });
+        }
+        expect(concepts[0].tree).toEqual(['p.demo-note', 'h3', 'dl.meta-grid', 'p.small', 'div.dialog-actions']);
+        await productionMaintenance(page, theme);
+        for (const [index, [, operation, title]] of PLANS.entries()) {
+            const { plan, production } = await productionPlan(page, title);
+            expect(plan.operation).toBe(operation);
+            await page.screenshot({ path: testInfo.outputPath(`production-plan-${operation}-${theme}-${width}.png`) });
+            expect(diffInventory(mapPlanConcept(concepts[index], title, plan), production)).toEqual([]);
+            await page.keyboard.press('Escape');
+            await expect(page.locator('dialog#modal[open]')).toHaveCount(0);
+        }
+    });
+}
+
+/**
+ * D101: the real group in the concept's markup: the status line (the concept's sample note's place), a group's
+ * `p.small` and `.compare-grid` in one wrapper, a "Keep <source>/<path>" radio per copy, the oldest checked, and the
+ * production note in the concept's `p.small`.
+ */
+function mapDuplicatesConcept(reference) {
+    const items = reference.compare.items.map((item, index) => ({ ...item,
+        label: `Keep output/s7-dupes/group_00_${index ? 'b' : 'a'}.png` }));
+    return {
+        ...reference,
+        tree: ['p.small', 'div.duplicate-groups', 'p.small', 'div.dialog-actions'],
+        compare: { ...reference.compare, items },
+        note: { ...reference.note, text: 'Removing a copy deletes its file from disk; its database links move to the kept copy. '
+            + 'History keeps the removed paths in its run records. Nothing is deleted until you review and apply the cleanup.' },
+    };
+}
+
+async function conceptDuplicates(page, theme) {
+    await conceptMaintenance(page, theme);
+    await page.locator('#main').getByRole('button', { name: 'Find duplicates', exact: true }).click();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Review duplicate image files');
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureReview);
+}
+
+async function productionDuplicates(page, theme) {
+    await productionMaintenance(page, theme);
+    await page.locator('#workspace-main').getByRole('button', { name: 'Find duplicates', exact: true }).click();
+    await page.locator('#workspace-main').getByRole('button', { name: 'Review groups', exact: true }).click();
+    await expect(page.locator('dialog#modal[open] .compare-item img')).toHaveCount(2);
+    await page.locator('dialog#modal[open] .compare-item img').evaluateAll(images => Promise.all(images.map(image => image.decode())));
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureReview);
+}
+
+for (const theme of THEMES) for (const [width, height] of SIZES) {
+    test(`duplicates dialog matches the concept ${theme} ${width}x${height}`, async ({ page, request }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        await expect(await request.post('/__test__/system/duplicate-files', { data: { groups: 1, trio: false } })).toBeOK();
+        const concept = await conceptDuplicates(page, theme);
+        expect(concept.tree).toEqual(['p.demo-note', 'div.compare-grid', 'p.small', 'div.dialog-actions']);
+        await page.screenshot({ path: testInfo.outputPath(`concept-duplicates-${theme}-${width}.png`) });
+        const production = await productionDuplicates(page, theme);
+        await page.screenshot({ path: testInfo.outputPath(`production-duplicates-${theme}-${width}.png`) });
+        expect(diffInventory(mapDuplicatesConcept(concept), production)).toEqual([]);
+    });
+}
+
+test('maintenance comparison detects mutations', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const concept = await conceptMaintenance(page, 'dark');
+    const expected = mapMaintenanceConcept(concept);
+    const production = await productionMaintenance(page, 'dark');
+    expect(diffInventory(expected, production)).toEqual([]);
+    // Unmapped, the section differs only on the D102 row.
+    expect(diffInventory(concept, production).map(item => item.path).sort()).toEqual([
+        'surfaces.1.rows.3.actions.0.cursor', 'surfaces.1.rows.3.actions.0.opacity', 'surfaces.1.rows.3.description']);
+    const measure = () => page.evaluate(measureMaintenance, '#workspace-main');
+    const paths = async () => diffInventory(expected, await measure()).map(item => item.path);
+    // A removed row, a changed label, a lost danger mark and a swapped token.
+    const undoRow = await mutate(page, { remove: ['#workspace-main section.surface:nth-of-type(1) > .operation:nth-of-type(2)'] });
+    expect(await paths()).toEqual(expect.arrayContaining(['surfaces.0.rows.length', 'surfaces.0.tree.length']));
+    await undoRow();
+    await page.evaluate(() => { document.querySelector('#workspace-main section.surface h3').textContent = 'Integrity checks'; });
+    expect(await paths()).toEqual(['surfaces.0.rows.0.title']);
+    await page.evaluate(() => { document.querySelector('#workspace-main section.surface h3').textContent = 'Integrity & relationship checks'; });
+    await page.evaluate(() => { document.querySelector('#workspace-main button.danger').classList.remove('danger'); });
+    expect(await paths()).toEqual(expect.arrayContaining(['surfaces.0.rows.3.actions.0.className']));
+    await page.evaluate(() => { document.querySelectorAll('#workspace-main section.surface')[0].querySelectorAll('.row-actions > button')[3].classList.add('danger'); });
+    const undoToken = await mutate(page, { css: '#workspace-main .settings-layout { --line: rgb(255, 0, 0); }' });
+    expect(await paths()).toEqual(expect.arrayContaining(['operation.borderTopColor']));
+    await undoToken();
+    expect(diffInventory(expected, await measure())).toEqual([]);
+
+    // The plan dialog: a changed grid term and the duplicates dialog's grid token are noticed.
+    await expect(await request.post('/__test__/system/duplicate-prompts')).toBeOK();
+    const conceptPlanDialog = await conceptPlan(page, 'dark', 'duplicate prompts');
+    await productionMaintenance(page, 'dark');
+    const { plan } = await productionPlan(page, 'Duplicate prompt text');
+    const expectedPlan = mapPlanConcept(conceptPlanDialog, 'Duplicate prompt text', plan);
+    const planPaths = async () => diffInventory(expectedPlan, await page.evaluate(measureReview)).map(item => item.path);
+    expect(await planPaths()).toEqual([]);
+    await page.evaluate(() => { document.querySelector('dialog#modal[open] dl.meta-grid dt').textContent = 'Impact'; });
+    expect(await planPaths()).toEqual(['grid.rows.0.0']);
+    await page.evaluate(() => { document.querySelector('dialog#modal[open] dl.meta-grid dt').textContent = 'Scope'; });
+    const undoGrid = await mutate(page, { css: 'dialog#modal dl.meta-grid { column-gap: 3px; }' });
+    expect(await planPaths()).toEqual(expect.arrayContaining(['grid.columnGap']));
+    await undoGrid();
+    expect(await planPaths()).toEqual([]);
+});
+
+test('duplicates comparison detects mutations', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await expect(await request.post('/__test__/system/duplicate-files', { data: { groups: 1, trio: false } })).toBeOK();
+    const expected = mapDuplicatesConcept(await conceptDuplicates(page, 'dark'));
+    await productionDuplicates(page, 'dark');
+    const paths = async () => diffInventory(expected, await page.evaluate(measureReview)).map(item => item.path);
+    expect(await paths()).toEqual([]);
+    const undoToken = await mutate(page, { css: 'dialog#modal .compare-item { background: rgb(255, 0, 0); }' });
+    expect(await paths()).toEqual(['compare.item.backgroundColor']);
+    await undoToken();
+    await page.evaluate(() => { document.querySelector('dialog#modal[open] .dialog-actions button:last-child').classList.add('ca-primary'); });
+    expect(await paths()).toEqual(expect.arrayContaining(['actions.buttons.1.className']));
+    await page.evaluate(() => { document.querySelector('dialog#modal[open] .dialog-actions button:last-child').classList.remove('ca-primary'); });
+    const undoItem = await mutate(page, { remove: ['dialog#modal[open] .compare-item:last-child'] });
+    expect(await paths()).toEqual(expect.arrayContaining(['compare.items.length']));
+    await undoItem();
+    expect(await paths()).toEqual([]);
+});

tests/browser/tagging-canonical-comparison.mjs

@@ -140,3 +140,152 @@ export function mapConceptTagging(reference,{instructions,limit=10,chip,numberFi
 export function withoutChipGeometry(inventory) {
     return {...inventory,suggestions:{...inventory.suggestions,rows:inventory.suggestions.rows.map(({paddingTop,paddingLeft,alignItems,...row})=>row)}};
 }
+
+/**
+ * Needs review (plan Task F3, Mock inventory M4: app.js renderReview a749–760, style.css s407–415, s796–814 and their
+ * breakpoints): the page's main element as a tree, runs in the page. Every shown box below `main` to `depth` levels is
+ * recorded with its tag and classes, its box relative to its parent, its fonts, edges and layout, a leaf's text, a
+ * button's label and icon, a select's options; a `display: contents` node is replaced by its children (D20). A flex
+ * row of actions also records the gaps between its children and its right inset, so a row whose button copy differs
+ * (D29) still compares by order, spacing and alignment.
+ */
+export function reviewInventory(selector) {
+    const main=document.querySelector(selector);
+    // Half pixels: the concept's 13.5px line heights add up exactly, so a box that loses one line moves by 13.5px.
+    const px=value=>Math.round(value*2)/2;
+    const css=(node,...keys)=>{const style=getComputedStyle(node);return Object.fromEntries(keys.map(key=>[key,style[key]]));};
+    const rect=node=>node.getBoundingClientRect();
+    const shown=node=>node.getClientRects().length>0&&getComputedStyle(node).visibility!=='hidden';
+    const relative=(node,origin)=>{const a=rect(node),b=rect(origin);return {left:px(a.left-b.left),top:px(a.top-b.top),width:px(a.width),height:px(a.height)};};
+    const font=node=>css(node,'fontFamily','fontSize','fontWeight','lineHeight','letterSpacing','color','textTransform','textAlign');
+    const edges=node=>css(node,'paddingTop','paddingRight','paddingBottom','paddingLeft','marginTop','marginRight','marginBottom','marginLeft',
+        'borderTopWidth','borderTopStyle','borderTopColor','borderRightWidth','borderRightStyle','borderRightColor','borderBottomWidth',
+        'borderBottomStyle','borderBottomColor','borderLeftWidth','borderLeftStyle','borderLeftColor','borderTopLeftRadius','backgroundColor',
+        'boxShadow','outlineStyle');
+    const layout=node=>css(node,'display','position','flexDirection','flexWrap','justifyContent','alignItems','columnGap','rowGap',
+        'gridTemplateColumns','overflowX','overflowY','objectFit','minHeight','minWidth');
+    const tagOf=node=>`${node.localName}${[...node.classList].sort().map(name=>`.${name}`).join('')}`;
+    const textOf=node=>node.textContent.replace(/\s+/g,' ').trim();
+    const boxed=node=>[...node.children].flatMap(child=>getComputedStyle(child).display==='contents'?boxed(child):[child]);
+    const LEAVES=new Set(['button','select','input','img','svg','textarea','progress']);
+    function nodeOf(node,origin,depth) {
+        const base={tag:tagOf(node),...relative(node,origin),...font(node),...edges(node),...layout(node)};
+        const name=node.localName;
+        if(name==='svg')return {tag:base.tag,width:base.width,height:base.height,d:node.querySelector('path')?.getAttribute('d')??null,
+            ...css(node,'strokeWidth','color','verticalAlign')};
+        if(name==='button')return {...base,text:textOf(node),label:node.getAttribute('aria-label'),pressed:node.getAttribute('aria-pressed'),
+            disabled:node.getAttribute('aria-disabled')==='true'||node.disabled,primary:node.classList.contains('ca-primary'),
+            children:boxed(node).filter(shown).map(child=>nodeOf(child,node,0))};
+        if(name==='select')return {...base,id:node.id,options:[...node.options].map(option=>[option.textContent,option.disabled])};
+        if(name==='input')return {...base,id:node.id,type:node.type,label:node.getAttribute('aria-label')};
+        if(name==='img')return {...base,alt:node.getAttribute('alt')};
+        const children=boxed(node).filter(shown);
+        const item={...base,id:node.id||null,role:node.getAttribute('role'),label:node.getAttribute('aria-label'),
+            text:children.length?null:textOf(node),htmlFor:node.htmlFor||null};
+        if(/(^|\s)(dialog-actions|row-actions|image-card-actions)(\s|$)/.test(node.className)&&children.length) {
+            const boxes=children.map(rect);
+            item.gaps=boxes.slice(1).map((box,index)=>px(box.left-boxes[index].right));
+            item.rightInset=px(rect(node).right-boxes.at(-1).right);
+        }
+        if(depth>0&&!LEAVES.has(name))item.children=children.map(child=>nodeOf(child,node,depth-1));
+        return item;
+    }
+    return {main:nodeOf(main,main,8),noPageScroll:document.documentElement.scrollWidth<=innerWidth+1};
+}
+
+/**
+ * `tree` with `edit(node)` applied to every node `match` picks (a tag prefix or a predicate), depth first, new objects
+ * only.
+ */
+function editNodes(tree,match,edit) {
+    const children=tree.children?.map(child=>editNodes(child,match,edit));
+    const node=children?{...tree,children}:tree;
+    const picked=typeof match==='function'?match(node):node.tag?.startsWith(match);
+    return picked?edit(node):node;
+}
+const findNode=(tree,prefix)=>tree.tag?.startsWith(prefix)?tree:tree.children?.map(child=>findNode(child,prefix)).find(Boolean)??null;
+
+/**
+ * The concept's Metadata review inventory (reviewInventory) with the recorded deviations applied, the remaining sample
+ * data taken from production (`actual`) only where the concept's own copy cannot say it:
+ * - D29: no "Sample review queue" chip in the notice; "Resolve the association" and "Apply association" without the
+ *   prototype's "sample";
+ * - D119: queue cards carry no selection checkbox and no star (the overlay row stays, empty); a card's title is its
+ *   file name (an undecided item names no prompt) and its line is the extension only (D11 omits the unknown size and
+ *   seed, which a queue item does not carry); the image's alt is the file name; the prompt blocks' Copy and Send names
+ *   carry no prompt title;
+ * - D3: the grid keeps the Images grid's `position: relative` (its cards stay in its flow);
+ * - production's hooks and names: the `review-queue` / `review-panel` classes, the queue's list roles and name, the
+ *   panel heading's id (the region's name) and the prompt sections' region names;
+ * - sample data: the Sampler context's candidate options (the file's own evidence; the last option, Leave unresolved,
+ *   stays compared) and the widths that follow from copy the deviations above change (a card's text column, the
+ *   panel's action buttons; their gaps and right inset stay compared).
+ * Where that copy changes the height of a box, the boxes after it move by exactly that much: the stacked notice (390)
+ * loses the chip and its row gap; a card whose concept line wraps (390: "1536 × 1152 · PNG · Seed 42001") takes
+ * production's one-line height, its row of the grid shrinks by the most any of its cards lost, and in one column the
+ * panel below the grid moves up by the grid's loss. The actions keep production's centred place in the card's info.
+ */
+export function mapConceptReview(reference,actual) {
+    const named=(node,id)=>({...node,id});
+    const actualCards=findNode(actual.main,'div.image-grid')?.children??[];
+    const actualActions=findNode(actual.main,'div.dialog-actions');
+    let cardIndex=0;
+    let main={...reference.main,id:actual.main.id};
+    let noticeLoss=0;
+    main=editNodes(main,'div.notice',notice=>{
+        const chip=notice.children.find(child=>child.tag==='span.chip');
+        if(chip&&notice.flexDirection==='column')noticeLoss=chip.height+parseFloat(notice.rowGap);
+        return {...notice,height:notice.height-noticeLoss,children:notice.children.filter(child=>child!==chip)};
+    });
+    const noticeIndex=main.children.findIndex(child=>child.tag==='div.notice');
+    main={...main,height:main.height-noticeLoss,children:main.children.map((child,index)=>index>noticeIndex?{...child,top:child.top-noticeLoss}:child)};
+    const losses=[];
+    main=editNodes(main,'div.image-grid',grid=>({...grid,tag:'div.image-grid.review-queue',position:'relative',role:'list',label:'Review queue'}));
+    main=editNodes(main,'article.media-card',card=>{
+        const twin=actualCards[cardIndex++];
+        const filename=findNode(card,'button.image-open').label.replace(/^Open /,'');
+        const art=editNodes(card.children[0],'div.image-overlays',overlays=>({...overlays,height:0,text:'',children:[]}));
+        const withAlt=editNodes(art,'img',img=>({...img,alt:filename}));
+        const info=card.children[1];
+        const [copy,...rest]=info.children;
+        const twinCopy=twin?.children[1]?.children[0];
+        const [h3,p]=copy.children;
+        const twinLine=twinCopy?.children[1];
+        const loss=twinLine?p.height-twinLine.height:0;
+        losses.push({top:card.top,loss});
+        const mappedCopy={...copy,width:twinCopy?.width,height:copy.height-loss,children:[{...h3,text:filename,width:twinCopy?.children[0]?.width},
+            {...p,text:'PNG',width:twinLine?.width,height:p.height-loss}]};
+        const [actions,...after]=rest;
+        const twinActions=twin?.children[1]?.children[1];
+        const mappedActions=actions&&loss?{...actions,top:twinActions?.top}:actions;
+        return {...card,role:'listitem',height:card.height-loss,
+            children:[withAlt,{...info,height:info.height-loss,children:[mappedCopy,...(actions?[mappedActions]:[]),...after]},...card.children.slice(2)]};
+    });
+    // Each grid row loses what its most shortened card lost; later rows move up by the rows before them.
+    const rowLoss=new Map();
+    for(const {top,loss} of losses)rowLoss.set(top,Math.max(rowLoss.get(top)??0,loss));
+    const lossBefore=top=>[...rowLoss].filter(([rowTop])=>rowTop<top).reduce((sum,[,loss])=>sum+loss,0);
+    const gridLoss=[...rowLoss.values()].reduce((sum,loss)=>sum+loss,0);
+    main=editNodes(main,'div.image-grid',grid=>({...grid,height:grid.height-gridLoss,
+        children:grid.children.map(card=>({...card,top:card.top-lossBefore(card.top)}))}));
+    main=editNodes(main,'div.gallery-layout',layout=>{
+        if(!gridLoss||layout.gridTemplateColumns.trim().split(/\s+/).length>1)return layout;
+        return {...layout,height:layout.height-gridLoss,children:layout.children.map((child,index)=>index?{...child,top:child.top-gridLoss}:child)};
+    });
+    if(gridLoss&&findNode(main,'div.gallery-layout').gridTemplateColumns.trim().split(/\s+/).length===1)main={...main,height:main.height-gridLoss};
+    main=editNodes(main,'section.surface',surface=>{
+        const [h2,...rest]=surface.children;
+        return {...surface,tag:'section.review-panel.surface',children:[named({...h2,text:h2.text.replace('Resolve the sample association','Resolve the association')},'review-panel-title'),...rest]};
+    });
+    main=editNodes(main,'select',select=>{
+        const twin=findNode(actual.main,'select');
+        return select.id==='review-context'?{...select,options:[...twin.options.slice(0,-1),select.options.at(-1)]}:select;
+    });
+    main=editNodes(main,node=>/^section\..*\bprompt-section\b/.test(node.tag),section=>({...section,label:section.tag.includes('positive')?'Positive prompt':'Negative prompt'}));
+    main=editNodes(main,node=>node.tag?.startsWith('button')&&/^(Copy|Send) (positive|negative) prompt/.test(node.label??''),
+        button=>({...button,label:button.label.replace(/: .+$/,'')}));
+    main=editNodes(main,'div.dialog-actions',actions=>({...actions,children:actions.children.map((button,index)=>({...button,
+        text:button.text.replace('Apply sample association','Apply association'),
+        left:actualActions?.children[index]?.left,width:actualActions?.children[index]?.width}))}));
+    return {...reference,main};
+}

tests/browser/workflows.spec.mjs

@@ -19,6 +19,13 @@ test.afterEach(async ({ page, browserName }) => {
     expect(page.workflowErrors).toEqual([]);
 });
 
+// #249 S6b: the legacy admin page says where the library lives (the fixture's database is configured explicitly).
+test('the admin page names the library location', async ({ page }) => {
+    await page.goto('/prompt_manager/admin');
+    await expect(page.locator('#libraryLocation')).toHaveText('Library: browser.db (set in config.json)');
+    await expect(page.locator('#totalPrompts')).not.toHaveText('-');
+});
+
 test('actual gallery form saves a prompt that the admin page can edit and reload', async ({ page, request }) => {
     await page.goto('/prompt_manager/gallery');
     await page.locator('#addPromptBtn').click();
@@ -92,6 +99,34 @@ for (const leave of ['beforeunload', 'pagehide']) {
     });
 }
 
+// #222: the gallery's Clear cache clears the server's thumbnails by its own request and keeps this browser's
+// preferences and other tools' storage; nothing of Prompt Manager's is cached in a browser, and the toast says so.
+test('the gallery cache clear keeps preferences and other tools caches', async ({ page }) => {
+    await page.addInitScript(() => {
+        if (sessionStorage.getItem('seeded')) return;
+        sessionStorage.setItem('seeded', '1');
+        localStorage.setItem('pm_workspace_theme', 'light');
+        localStorage.setItem('other-tool-setting', 'keep');
+        localStorage.setItem('pm_other_tool', 'keep');
+    });
+    await page.goto('/prompt_manager/gallery');
+    await expect(page.locator('#galleryGrid .image-item')).toHaveCount(2);
+    await page.evaluate(async () => { await (await caches.open('other-tool-gallery-thumbnails')).put('/x', new Response('x')); });
+    const clears = [];
+    page.on('request', req => { if (req.url().includes('/clear-thumbnails')) clears.push(req.method()); });
+    page.once('dialog', dialog => dialog.accept());
+    await page.locator('#settingsBtn').click();
+    await page.locator('#clearCacheBtn').click();
+    await expect(page.getByText("Thumbnails cleared; original images untouched. Nothing of Prompt Manager's is cached in this browser."))
+        .toBeVisible();
+    expect(clears).toEqual(['POST']);
+    expect(await page.evaluate(async () => ({
+        theme: localStorage.getItem('pm_workspace_theme'), other: localStorage.getItem('other-tool-setting'),
+        prefixed: localStorage.getItem('pm_other_tool'), notice: localStorage.getItem('pm_update_notice_dismissed'),
+        caches: await caches.keys(),
+    }))).toEqual({ theme: 'light', other: 'keep', prefixed: 'keep', notice: '3.2.0', caches: ['other-tool-gallery-thumbnails'] });
+});
+
 test('actual gallery review generates and persists tags for the selected root', async ({ page, request }) => {
     await page.goto('/prompt_manager/gallery');
     await expect(page.locator('#galleryGrid .image-item')).toHaveCount(2);

tests/browser/workspace-activity.spec.mjs

@@ -54,8 +54,8 @@ async function step(request, id, data) {
     await expect(await request.post(`/__test__/jobs/${id}/step`, { data })).toBeOK();
 }
 
-async function finish(request, id, state = 'finished') {
-    const response = await request.post(`/__test__/jobs/${id}/finish`, { data: { state } });
+async function finish(request, id, state = 'finished', extra = {}) {
+    const response = await request.post(`/__test__/jobs/${id}/finish`, { data: { state, ...extra } });
     await expect(response).toBeOK();
     return (await response.json()).job;
 }
@@ -284,6 +284,19 @@ test('reload during a scan reattaches to the running job', async ({ page, reques
     await expect(pill(page)).toBeHidden();
 });
 
+test('an empty Activity says no job has run, and a list that cannot be read says so', async ({ page }) => {
+    // The empty and failed states were only reached in passing by other tests, so their coverage depended on timing.
+    const empty = main(page).locator('section.surface > p.empty-state');
+    await page.goto(`${workspace}#/activity`);
+    await expect(empty).toHaveText('No jobs have run since ComfyUI started. Scans and other long operations appear here.');
+    await expect(empty).not.toHaveAttribute('role');
+    await expect(items(page)).toHaveCount(0);
+    await page.route(url => url.pathname === '/prompt_manager/jobs', route => route.abort());
+    await page.reload();
+    await expect(empty).toHaveText('Activity could not be read. It is tried again shortly.');
+    await expect(empty).toHaveAttribute('role', 'alert');
+});
+
 test('lost server clears the pill and marks jobs ended', async ({ page, request }) => {
     // A poll interval after the restart, then failed re-reads backing off for 1 + 2 + 4 s.
     test.setTimeout(90_000);
@@ -724,6 +737,42 @@ test('a held legacy job shows no Cancel in the list or its view', async ({ page,
     await expect(heading(page).locator('.heading-actions > button')).toHaveText(['Download report']);
 });
 
+// Since #289 an item dropped its Cancel job only when it was already in the page, so the first render of jobs the
+// store already knew (Activity opened from another page) kept a Cancel job on a job that had ended, and moved a
+// running job's progress after its actions. The read Activity starts on opening is held, so that first render is
+// what the page shows (the read's own render would otherwise repair it a moment later).
+test('jobs that ended before Activity opened show no Cancel job, a running one keeps its progress first', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const finished = await startJob(request, { title: 'Finished scan' });
+    await finish(request, finished.id);
+    const cancelled = await startJob(request, { title: 'Cancelled scan' });
+    await finish(request, cancelled.id, 'cancelled');
+    await startJob(request, { title: 'Running scan' });
+    // The page's first list read has all three jobs once the running one shows in the pill.
+    await page.goto(`${workspace}#/images`);
+    await expect(pill(page)).toBeVisible();
+    let hold;
+    const held = new Promise(resolve => { hold = resolve; });
+    // Only the first read is held; any later one goes through.
+    await page.route(url => url.pathname === '/prompt_manager/jobs', route => {
+        if (!hold) return route.continue();
+        hold(route);
+        hold = null;
+    });
+    await activityButton(page).click();
+    const route = await held;
+    await expect(items(page)).toHaveCount(3);
+    const item = title => items(page).filter({ has: page.getByRole('link', { name: new RegExp(`${title}$`) }) });
+    for (const ended of ['Finished scan', 'Cancelled scan']) {
+        await expect(item(ended).locator('progress, .row-actions')).toHaveCount(0);
+        await expect(item(ended).getByRole('button', { name: 'Cancel job', exact: true })).toHaveCount(0);
+    }
+    await expect(item('Running scan').getByRole('button', { name: 'Cancel job', exact: true })).toHaveCount(1);
+    expect(await item('Running scan').evaluate(node => [...node.children].map(child => child.localName + (child.className ? `.${child.className}` : ''))))
+        .toEqual(['div.panel-heading', 'p', 'progress', 'div.row-actions']);
+    await route.continue();
+});
+
 test('busy start names the running job', async ({ page, request }) => {
     await page.setViewportSize({ width: 1600, height: 1100 });
     // The page's timers are Playwright's, so the toast's lifetime below is run out rather than waited for.
@@ -959,3 +1008,96 @@ test('the report download names the kind', async ({ page, request }) => {
     expect(report.outcomes.tagged.rows.map(row => [row.path, row.detail])).toEqual([['sub/a.png', 'Added 1 tag']]);
     await expect(toast(page)).toHaveText('Job report downloaded.');
 });
+
+// D111 (System S5): each kind's own descriptor. A thumbnail job counts Generated (green), Skipped and Errors (red),
+// its pill says "Generating thumbnails" and its toasts "Thumbnails finished · N generated · M errors".
+const THUMB_JOB = { kind: 'thumbnails', total: 10, output_folders: 2 };
+
+test('a thumbnail job shows Generated Skipped Errors, its pill verb and its toasts', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request, THUMB_JOB);
+    await step(request, job.id, { processed: 4, records: [
+        { group: 'generated', path: 'sub/a.png', root: 'output', detail: 'Preview written' },
+        { group: 'skipped', path: 'b.png', root: 'input', detail: 'Preview already up to date' },
+        { group: 'errors', path: 'broken.png', root: 'output', detail: 'Not a valid image file' },
+    ] });
+    await page.goto(`${workspace}#/images`);
+    await expect(pill(page)).toHaveText('Generating thumbnails · 40% · 4 / 10');
+    await page.goto(`${workspace}#/activity`);
+    await expect(items(page).first().locator('p')).toHaveText(/^Started \d\d:\d\d · 2 output folders · closing this view does not cancel it$/);
+    await expect(items(page).first().locator('progress')).toHaveAttribute('value', '40');
+    await openJob(page, job.id);
+    await expect(heading(page).locator('h1')).toHaveText('Thumbnail generation');
+    await expect(heading(page).locator('.heading-actions > button')).toHaveText(['Download report', 'Cancel job']);
+    expect(await tileValues(page)).toEqual([['stat added', 'Generated', '1'], ['stat', 'Skipped', '1'], ['stat bad', 'Errors', '1']]);
+    await expect(outcomeButtons(page)).toHaveText(['Generated1', 'Errors1', 'Skipped1']);
+    await expect(fileRows(page).first().locator('.path')).toHaveText('sub/a.png');
+    expect(await fileRows(page).first().evaluate(node => node.localName)).toBe('button');
+    await outcomeButtons(page).filter({ hasText: 'Errors' }).click();
+    expect(await fileRows(page).first().evaluate(node => node.localName)).toBe('div');
+    await expect(scanLog(page).locator('summary')).toHaveText('● Job log — raw detail, click to show');
+
+    await finish(request, job.id);
+    await expect(toast(page)).toHaveText('Thumbnails finished · 1 generated · 1 error');
+    await expect(heading(page).locator('p.muted')).toHaveText(/^Finished \d\d:\d\d · 1 generated · 1 error$/);
+    await expect(heading(page).locator('.heading-actions > button')).toHaveText(['Download report']);
+});
+
+test('a held legacy job and the health check show no tiles, no Results and no made-up percentage', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const response = await request.post('/__test__/jobs/hold',
+        { data: { kind: 'thumbnails', title: 'Thumbnail clear (gallery page)', admission: 'guarded' } });
+    await expect(response).toBeOK();
+    const held = (await response.json()).job;
+    await page.goto(`${workspace}#/images`);
+    // D112: the pill names the held operation and shows no percentage; its bar is indeterminate, not an empty fill
+    // (S5 review M5), and stays hidden from assistive tech, which reads the label.
+    await expect(pill(page)).toHaveText('Thumbnail clear (gallery page)');
+    await expect(pill(page)).toHaveAttribute('aria-label', 'Thumbnail clear (gallery page)');
+    await expect(pill(page).locator('.activity-pill-bar')).toHaveClass('activity-pill-bar indeterminate');
+    await expect(pill(page).locator('.activity-pill-bar')).toHaveAttribute('aria-hidden', 'true');
+    expect(await pill(page).locator('.activity-pill-bar i').evaluate(node => node.style.width)).toBe('');
+    await page.goto(`${workspace}#/activity`);
+    const item = items(page).filter({ has: page.getByRole('link', { name: /Thumbnail clear \(gallery page\)$/ }) });
+    await expect(item.locator('p')).toHaveText(/^Started \d\d:\d\d · closing this view does not cancel it$/);
+    await expect(item.locator('progress')).toHaveCount(1);
+    await expect(item.locator('progress')).not.toHaveAttribute('value');
+    await expect(item.getByRole('button', { name: 'Cancel job', exact: true })).toHaveCount(0);
+    await item.getByRole('link').click();
+    await expect(heading(page).locator('h1')).toHaveText('Thumbnail clear (gallery page)');
+    await expect(progressSection(page).locator('progress')).not.toHaveAttribute('value');
+    await expect(progressSection(page).locator('dl.stat-row')).toHaveCount(0);
+    await expect(resultsSection(page)).toHaveCount(0);
+    await expect(scanLog(page)).toHaveCount(1);
+    await finish(request, held.id);
+    await expect(toast(page)).toHaveText('Thumbnail clear (gallery page) finished.');
+    await expect(heading(page).locator('p.muted')).toHaveText(/^Finished \d\d:\d\d$/);
+    await expect(progressSection(page).locator('progress')).toHaveAttribute('value', '100');
+
+    // The health check (a read job of its own kind): its status line, no tiles, no Cancel.
+    const health = await startJob(request, { kind: 'health', total: 0 });
+    await openJob(page, health.id);
+    await expect(heading(page).locator('h1')).toHaveText('Health check');
+    await expect(progressSection(page).locator('.panel-heading > span.small')).toHaveText('Checking the database and image links');
+    await expect(progressSection(page).locator('progress')).not.toHaveAttribute('value');
+    await expect(progressSection(page).locator('dl.stat-row')).toHaveCount(0);
+    await expect(resultsSection(page)).toHaveCount(0);
+    await expect(heading(page).locator('.heading-actions > button')).toHaveText(['Download report']);
+    await expect(pill(page)).toHaveText('Health check');
+    await finish(request, health.id);
+    await expect(toast(page)).toHaveText('Health check finished.');
+});
+
+// S5 review I3: a thumbnail job with nothing to generate ends on the server's final line ("No previews to generate · N
+// already up to date"), never on a stale "Processing file 0 of 0" under the Completed chip.
+test('a finished thumbnail job with nothing to do says so', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request, { ...THUMB_JOB, total: 0 });
+    await step(request, job.id, { total: 0, processed: 0 }); // the stale line an older server left
+    await openJob(page, job.id);
+    const line = progressSection(page).locator('.panel-heading > span.small');
+    await finish(request, job.id, 'finished', { status_line: 'No previews to generate · 24 already up to date' });
+    await expect(line).toHaveText('No previews to generate · 24 already up to date');
+    await expect(page.getByText('Processing file 0 of 0')).toHaveCount(0);
+    await expect(progressSection(page).locator('progress')).toHaveAttribute('value', '100');
+});

tests/browser/workspace-images.spec.mjs

@@ -398,18 +398,20 @@ test('preview uses actual Viewer.js and cleans up when closing or leaving Images
 test('real video media has a usable card and native playback cleans up on close and navigation', async ({ page, request }) => {
     await expect(await request.post('/__test__/reset', { data: { include_video: true } })).toBeOK();
     const media = await (await request.get('/prompt_manager/images/output?limit=40')).json();
-    expect(media.images.find(image => image.filename === 'clip.webm').thumbnail_url).toBeNull();
+    // #249: a video with no preview yet still lists its preview URL; the server makes the frame on first view.
+    expect(media.images.find(image => image.filename === 'clip.webm').thumbnail_url).toMatch(/\/thumbnails\/clip_thumb\.webp\?root=0/);
     await page.goto(workspace);
     await refine(page, { Media: 'video' });
     await expect(cards(page)).toHaveCount(1);
     const card = cards(page).first();
     await expect(card).toHaveAttribute('data-image-key', '0:clip.webm');
-    await expect(card.locator('img')).toHaveCount(0);
     await expect(card.getByRole('button', { name: 'Open clip.webm', exact: true })).toBeVisible();
-    // Legacy video art inside the concept card; D11 names the video's own extension.
-    await expect(card.locator('.media-art > .image-open > video')).toHaveCount(1);
+    // The card shows the preview frame, never the video itself; D11 names the video's own extension.
+    await expect(card.locator('video')).toHaveCount(0);
+    await expect(card.locator('.media-art > .image-open > img')).toHaveCount(1);
     await expect(card.locator('.media-info p')).toHaveText(/(?:^|· )WEBM$/);
-    expect(await card.locator('video').evaluate(node => node.getBoundingClientRect().height)).toBeGreaterThan(20);
+    await expect.poll(() => card.locator('img').evaluate(node => node.complete && node.naturalHeight > 0)).toBe(true);
+    expect(await card.locator('img').evaluate(node => node.getBoundingClientRect().height)).toBeGreaterThan(20);
     await card.getByRole('button', { name: 'Open clip.webm', exact: true }).click();
     const video = page.locator('dialog[open] video');
     await expect(video).toBeVisible();
@@ -463,6 +465,50 @@ test('collection viewer ignores delayed media callbacks and keeps inspection ret
     await page.evaluate(()=>{location.hash='/overview';});await expect(page.locator('.viewer-container,#viewer-dialog')).toHaveCount(0);
 });
 
+test('collection viewer leaving an image Viewer.js has not built yet releases it at once',async({page})=>{
+    await page.goto(workspace);await expect(cards(page)).toHaveCount(2);
+    let release,held;const waiting=new Promise(resolve=>{held=resolve;});const pending=new Promise(resolve=>{release=resolve;});
+    await page.route('**/images/serve/shared/same.png?*',async route=>{
+        const url=new URL(route.request().url());
+        if(url.searchParams.get('root')==='0'&&url.searchParams.has('_pm_viewer')) {held();await pending;}
+        await route.continue().catch(()=>{});
+    });
+    await cards(page).first().getByRole('button',{name:'Open same.png',exact:true}).click();await waiting;
+    const preview=page.locator('dialog#viewer-dialog');
+    await page.evaluate(()=>{window.unbuiltImage=document.querySelector('#viewer-stage > img');});
+    await preview.getByRole('button',{name:'Next media',exact:true}).click();
+    await expect(preview.getByRole('button',{name:'Zoom in',exact:true})).toHaveAttribute('aria-disabled','false');
+    // The left image is off the stage. Viewer.js has not built it, so the viewer is destroyed and the src released at
+    // once: its late load must never build Viewer.js into an image without a parent (getComputedStyle(null)).
+    release();
+    await expect.poll(()=>page.evaluate(()=>[window.unbuiltImage.isConnected,window.unbuiltImage.hasAttribute('src'),!!window.unbuiltImage.viewer])).toEqual([false,false,false]);
+    await page.evaluate(()=>{location.hash='/overview';});await expect(page.locator('.viewer-container,#viewer-dialog')).toHaveCount(0);
+});
+
+test('collection viewer closed while its image finishes loading never builds Viewer.js afterwards',async({page})=>{
+    await page.goto(workspace);await expect(cards(page)).toHaveCount(2);
+    let held;const waiting=new Promise(resolve=>{held=resolve;});
+    // The image is held for the whole test: its late load is delivered below, at the moment Viewer.js cannot cancel.
+    await page.route('**/images/serve/shared/same.png?*',async route=>{
+        const url=new URL(route.request().url());
+        if(url.searchParams.get('root')==='0'&&url.searchParams.has('_pm_viewer')) {held();return;}
+        await route.continue().catch(()=>{});
+    });
+    await cards(page).first().getByRole('button',{name:'Open same.png',exact:true}).click();await waiting;
+    const preview=page.locator('dialog#viewer-dialog');
+    // Viewer.js's own cancel removes its image listeners only while `image.complete` is false. An image that has
+    // finished downloading but whose load event is still queued is already complete: close in that state, then deliver it.
+    await page.evaluate(()=>{window.finishingImage=document.querySelector('#viewer-stage > img');Object.defineProperty(window.finishingImage,'complete',{get:()=>true});});
+    await page.keyboard.press('Escape');await expect(preview).toHaveCount(0);
+    const after=await page.evaluate(async()=>{
+        const image=window.finishingImage;image.dispatchEvent(new Event('load'));
+        // Viewer.js builds an inline viewer in a zero-delay timeout after its image loads; this runs after it.
+        await new Promise(resolve=>setTimeout(resolve));
+        return {src:image.hasAttribute('src'),built:!!image.parentNode?.querySelector('.viewer-container')};
+    });
+    expect(after).toEqual({src:false,built:false});
+});
+
 test('collection viewer describes video transforms and releases native playback on navigation',async({page,request})=>{
     await expect(await request.post('/__test__/reset',{data:{include_video:true}})).toBeOK();await page.goto(workspace);
     await page.locator('article[data-image-key="0:clip.webm"] .image-open').click();
@@ -669,16 +715,45 @@ test('selected layout stays blue with readable text on hover in either theme', a
     }
 });
 
-test('refresh releases the previous inspector video source', async ({ page, request }) => {
+test('refresh releases the previous inspector cover source', async ({ page, request }) => {
     await expect(await request.post('/__test__/reset', { data: { include_video: true } })).toBeOK();
     await page.goto(workspace);
     const card = cards(page).filter({ hasText: 'clip.webm' });
     await card.getByRole('button', { name: 'Inspect clip.webm', exact: true }).click();
+    // #249: a video's cover is its preview frame, not the video.
+    const cover = details(page).locator('img.detail-cover');
+    await expect(cover).toHaveAttribute('src', /\/thumbnails\/clip_thumb\.webp\?/);
+    await expect(details(page).locator('video')).toHaveCount(0);
+    await cover.evaluate(element => { window.__oldInspectorCover = element; });
+    await rescan(page);
+    await expect.poll(() => page.evaluate(() => !window.__oldInspectorCover.isConnected)).toBe(true);
+    expect(await page.evaluate(() => window.__oldInspectorCover.getAttribute('src'))).toBeNull();
+});
+
+/** A listing that names no preview for its videos (the fallback a card and the cover keep for one). */
+async function videosWithoutPreview(page) {
+    await page.route(url => url.pathname === '/prompt_manager/images/output', async route => {
+        const response = await route.fetch();
+        const body = await response.json();
+        if (Array.isArray(body.images)) body.images = body.images.map(image => image.is_video ? { ...image, thumbnail_url: null } : image);
+        await route.fulfill({ response, json: body });
+    });
+}
+
+test('a video listed without a preview keeps its own element, released on refresh', async ({ page, request }) => {
+    await expect(await request.post('/__test__/reset', { data: { include_video: true } })).toBeOK();
+    await videosWithoutPreview(page);
+    await page.goto(workspace);
+    const card = cards(page).filter({ hasText: 'clip.webm' });
+    await expect(card.locator('.media-art > .image-open > video')).toHaveCount(1);
+    await expect(card.locator('img')).toHaveCount(0);
+    await card.getByRole('button', { name: 'Inspect clip.webm', exact: true }).click();
     await expect(details(page).locator('video')).toBeVisible();
     await details(page).locator('video').evaluate(element => { window.__oldInspectorVideo = element; });
+    await card.locator('video').evaluate(element => { window.__oldCardVideo = element; });
     await rescan(page);
-    await expect.poll(() => page.evaluate(() => !window.__oldInspectorVideo.isConnected)).toBe(true);
-    expect(await page.evaluate(() => window.__oldInspectorVideo.getAttribute('src'))).toBeNull();
+    await expect.poll(() => page.evaluate(() => !window.__oldInspectorVideo.isConnected && !window.__oldCardVideo.isConnected)).toBe(true);
+    expect(await page.evaluate(() => [window.__oldInspectorVideo.getAttribute('src'), window.__oldCardVideo.getAttribute('src')])).toEqual([null, null]);
 });
 
 test('Import Rescan rescans cached files and preserves the collection when rescan fails', async ({ page, request }) => {
@@ -2109,6 +2184,8 @@ test('scan for metadata opens the review dialog from Import', async ({ page, req
     await dialog.getByRole('button', { name: 'Cancel', exact: true }).click();
     await expect(scanReview(page)).toHaveCount(0);
     await expect(page.getByRole('button', { name: 'Import', exact: true })).toBeFocused();
-    const jobs = await (await request.get('/prompt_manager/jobs')).json();
-    expect(jobs.jobs).toEqual([]);
+    // No scan started: the one job is the backup's finished registry hold
+    // (#249 S8: a backup download holds a guarded slot while it streams).
+    await expect.poll(async () => (await (await request.get('/prompt_manager/jobs')).json()).jobs
+        .map(job => [job.kind, job.state])).toEqual([['backup', 'finished']]);
 });

tests/browser/workspace-review.spec.mjs

@@ -0,0 +1,588 @@
+// Needs review (#249 PR F, plan Tasks F1 and F2, Mock inventory M4): the SAVED VIEWS row and its count, the Metadata
+// review page over the real review routes, and Activity's Review metadata. Items are recorded by the real recorder
+// (tests/browser/workspace_review_fixture.py) through the scan's recorder (only scans add items); the conflict item's file was linked
+// to another prompt after it was queued. An open page re-reads its queue from the review change stream (F2).
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+
+const review = '/prompt_manager/workspace#/review';
+const main = page => page.locator('#workspace-main');
+const savedNav = page => page.getByRole('navigation', { name: 'Saved views', exact: true });
+const reviewRow = page => savedNav(page).locator('a[data-route="review"]');
+const panel = page => main(page).getByRole('region', { name: 'Resolve the association', exact: true });
+const context = page => panel(page).getByRole('combobox', { name: 'Sampler context', exact: true });
+const cards = page => main(page).locator('.review-queue article.media-card');
+const toast = page => page.locator('#workspace-toast');
+const NOTICE = 'Multiple sampler paths were found. The existing image links were preserved. Choose the correct context or leave them unresolved.';
+const EMPTY = 'Ambiguous images are added when a metadata scan or a new generation finds more than one sampler path.';
+const OPTIONS = ['Sampler 11 · Golden dunes at dusk / Soft negative, blur', 'Sampler 13 · Harbor lights at night / Soft negative, blur',
+    'Leave unresolved'];
+
+async function seed(request, items = 3, special = {}) {
+    const response = await request.post('/__test__/review/reset', { data: { items, ...special } });
+    await expect(response).toBeOK();
+    return response.json();
+}
+async function pending(request) {
+    return (await (await request.get('/prompt_manager/review/items?limit=1')).json()).total;
+}
+const links = async request => (await (await request.get('/__test__/review/links')).json()).links;
+const streams = async request => (await (await request.get('/__test__/review/streams')).json());
+/**
+ * Wait until the server has dropped every stream a page closed. It notices a closed stream only when a write to it
+ * fails, and the close can reach it after any one write (WebKit under load): each poll sends one more change notice,
+ * which changes nothing in the queue, until the count is 0.
+ */
+async function closedStreamsDropped(request) {
+    await expect.poll(async () => {
+        await expect(await request.post('/__test__/review/notify')).toBeOK();
+        return (await streams(request)).streams;
+    }).toBe(0);
+}
+const apply = page => panel(page).getByRole('button', { name: 'Apply association', exact: true });
+const warning = page => panel(page).locator('.warning-note');
+/** The page with its first item's sampler paths loaded. */
+async function open(page) {
+    await page.goto(review);
+    await expect(context(page)).toBeEnabled();
+}
+
+test.beforeEach(async ({ page, browserName }) => {
+    await startCoverage(page, browserName);
+    page.reviewErrors = [];
+    page.on('pageerror', error => page.reviewErrors.push(error.message));
+});
+test.afterEach(async ({ page, browserName, request }) => {
+    await saveCoverage(page, browserName);
+    expect(page.reviewErrors).toEqual([]);
+    await request.post('/__test__/jobs/restart');
+});
+
+test('queue shows persisted items and the nav count', async ({ page, request }) => {
+    await seed(request, 3);
+    await open(page);
+    // SAVED VIEWS: Favorites, then Needs review with the exact pending count (ruling R5).
+    await expect(savedNav(page).locator('a').nth(1)).toHaveAttribute('data-route', 'review');
+    await expect(reviewRow(page)).toHaveText('Needs review3');
+    await expect(reviewRow(page)).toHaveAttribute('aria-current', 'page');
+    await expect(page).toHaveTitle('Review · Prompt Manager');
+    await expect(page.locator('#workspace-breadcrumb')).toHaveText('Review');
+    await expect(main(page).getByRole('heading', { level: 1 })).toHaveText('Metadata review');
+    await expect(main(page).locator('.heading p.muted')).toHaveText('Uncertain evidence stays visible until you decide.');
+    await expect(main(page).locator('.notice h2')).toHaveText('3 images need a decision');
+    await expect(main(page).locator('.notice p')).toHaveText(NOTICE);
+    await expect(cards(page)).toHaveCount(3);
+    await expect(cards(page).first()).toHaveClass(/selected/);
+    await expect(panel(page).locator('p.small')).toHaveText('review_0000.png');
+    await expect(context(page).locator('option')).toHaveText(OPTIONS);
+    await expect(context(page)).toHaveValue(/^[0-9a-f]{64}$/);
+    await expect(panel(page).locator('.prompt-section.positive .prompt-text')).toHaveText('Golden dunes at dusk');
+    await expect(panel(page).locator('.prompt-section.negative .prompt-text')).toHaveText('Soft negative, blur');
+    await context(page).selectOption({ label: OPTIONS[1] });
+    await expect(panel(page).locator('.prompt-section.positive .prompt-text')).toHaveText('Harbor lights at night');
+    await context(page).selectOption({ label: 'Leave unresolved' });
+    await expect(panel(page).locator('.prompt-section.positive .prompt-text')).toHaveText('Multiple possible prompts. Source could not be determined.');
+    // Info selects another item.
+    await cards(page).nth(1).getByRole('button', { name: 'Inspect review_0001.png', exact: true }).click();
+    await expect(panel(page).locator('p.small')).toHaveText('review_0001.png');
+    await expect(cards(page).nth(1)).toHaveClass(/selected/);
+    await expect(context(page)).toBeEnabled();
+    // The card's image opens the shared viewer.
+    await cards(page).nth(1).getByRole('button', { name: 'Open review_0001.png', exact: true }).click();
+    await expect(page.locator('#viewer-dialog')).toBeVisible();
+    await page.keyboard.press('Escape');
+    await expect(page.locator('#viewer-dialog')).toHaveCount(0);
+    // Open activity.
+    await main(page).getByRole('button', { name: 'Open activity', exact: true }).click();
+    await expect(page).toHaveURL(/#\/activity$/);
+});
+
+test('apply candidate links the pair and the item leaves the queue and the count drops', async ({ page, request }) => {
+    await seed(request, 2);
+    await open(page);
+    await expect(reviewRow(page)).toHaveText('Needs review2');
+    const decided = page.waitForResponse(item => /\/review\/items\/[^/]+\/decision$/.test(item.url()));
+    await panel(page).getByRole('button', { name: 'Apply association', exact: true }).click();
+    expect((await decided).status()).toBe(200);
+    await expect(toast(page)).toHaveText('Association accepted.');
+    await expect(page).toHaveURL(/#\/images$/);
+    await expect(reviewRow(page)).toHaveText('Needs review1');
+    expect(await pending(request)).toBe(1);
+    // The first sampler path's pair is linked to that file, and only to it.
+    expect(await links(request)).toEqual([{ filename: 'review_0000.png', prompt: 'Golden dunes at dusk',
+        pair_id: expect.any(Number), positive: 'Golden dunes at dusk', negative: 'Soft negative, blur' }]);
+});
+
+test('conflict leaves links unchanged and explains', async ({ page, request }) => {
+    // Queued first, then linked to another prompt (before a scan or monitor pass could settle it).
+    await seed(request, 0, { conflict: true });
+    const before = await links(request);
+    expect(before).toEqual([{ filename: 'conflict.png', prompt: 'Misty forest path', pair_id: null, positive: null,
+        negative: null }]);
+    await open(page);
+    await expect(panel(page).locator('p.small')).toHaveText('conflict.png');
+    await expect(context(page).locator('option')).toHaveText(OPTIONS);
+    const decided = page.waitForResponse(item => /\/decision$/.test(item.url()));
+    await apply(page).click();
+    const answer = await decided;
+    expect(answer.status()).toBe(409);
+    expect((await answer.json()).code).toBe('association-conflict');
+    await expect(warning(page)).toHaveText('This image is already linked to another prompt or negative, so this sampler path cannot be attached safely. The existing links were preserved.');
+    await expect(page).toHaveURL(/#\/review$/);
+    await expect(context(page)).toBeEnabled();
+    await expect(context(page)).toHaveValue(/^[0-9a-f]{64}$/);
+    expect(await links(request)).toEqual(before);
+    expect(await pending(request)).toBe(1);
+    await expect(reviewRow(page)).toHaveText('Needs review1');
+    // The file can still be left unresolved, which links nothing either.
+    await context(page).selectOption({ label: 'Leave unresolved' });
+    await apply(page).click();
+    await expect(toast(page)).toHaveText('Left unresolved.');
+    expect(await links(request)).toEqual(before);
+    expect(await pending(request)).toBe(0);
+});
+
+test('a limited item and an unavailable file can only be left unresolved', async ({ page, request }) => {
+    await seed(request, 0, { limited: true, unavailable: true });
+    await open(page);
+    await expect(cards(page)).toHaveCount(2);
+    await expect(panel(page).locator('p.small')).toHaveText('limited.png');
+    await expect(context(page).locator('option')).toHaveText(['Leave unresolved']);
+    await expect(warning(page)).toHaveText('This file has too many sampler paths to list. You can leave it unresolved.');
+    // The unavailable file: no current root lists it, so its media and Tag are inert.
+    const unavailable = cards(page).nth(1);
+    await expect(unavailable.locator('.image-open')).toHaveAttribute('aria-disabled', 'true');
+    await expect(unavailable.locator('.image-card-actions button').last()).toHaveAttribute('aria-disabled', 'true');
+    // F3: its empty media button keeps the concept's 1.33 media area, so the card lines up with its neighbours.
+    await expect(cards(page).first().locator('.image-open img')).toBeVisible();
+    const sizes = await cards(page).evaluateAll(nodes => nodes.map(node => {
+        const art = node.querySelector('.image-open').getBoundingClientRect();
+        return [Math.round(art.width), Math.round(art.height), Math.round(node.getBoundingClientRect().height)];
+    }));
+    expect(sizes[1]).toEqual(sizes[0]);
+    await unavailable.getByRole('button', { name: 'Inspect unavailable.png', exact: true }).click();
+    await expect(panel(page).locator('p.small')).toHaveText('unavailable.png');
+    await expect(warning(page)).toHaveText('This file is not under a current image source, so it cannot be opened. You can leave it unresolved.');
+    await expect(panel(page).getByRole('button', { name: 'Tag image', exact: true })).toHaveAttribute('aria-disabled', 'true');
+    const observes = [];
+    page.on('request', item => { if (item.url().endsWith('/image-annotations/observe')) observes.push(item.url()); });
+    await apply(page).click();
+    await expect(toast(page)).toHaveText('Left unresolved.');
+    expect(observes).toEqual([]);
+    expect(await pending(request)).toBe(1);
+});
+
+test('leave unresolved removes the item from pending', async ({ page, request }) => {
+    await seed(request, 2);
+    await open(page);
+    await context(page).selectOption({ label: 'Leave unresolved' });
+    await panel(page).getByRole('button', { name: 'Apply association', exact: true }).click();
+    await expect(toast(page)).toHaveText('Left unresolved.');
+    await expect(page).toHaveURL(/#\/images$/);
+    expect(await pending(request)).toBe(1);
+});
+
+test('leave for later writes nothing and goes to Images', async ({ page, request }) => {
+    await seed(request, 2);
+    await open(page);
+    const writes = [];
+    page.on('request', item => { if (item.method() !== 'GET') writes.push(item.url()); });
+    await panel(page).getByRole('button', { name: 'Leave for later', exact: true }).click();
+    await expect(page).toHaveURL(/#\/images$/);
+    expect(writes).toEqual([]);
+    expect(await pending(request)).toBe(2);
+});
+
+test('tag image from review saves tags and the item remains pending', async ({ page, request }) => {
+    await seed(request, 1);
+    await open(page);
+    const before = await links(request);
+    await panel(page).getByRole('button', { name: 'Tag image', exact: true }).click();
+    const dialog = page.getByRole('dialog', { name: 'Tag image', exact: true });
+    await expect(dialog).toBeVisible();
+    await expect(dialog.locator('p.tag-scope-note')).toHaveText('Tags belong to this image. Resolve its prompt association separately in Needs review.');
+    await dialog.getByRole('textbox', { name: 'Image tags · edit manually', exact: true }).fill('dunes');
+    await dialog.getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await expect(toast(page)).toHaveText('1 tags saved for review_0000.png. Prompt association still awaits review.');
+    await expect(dialog).toHaveCount(0);
+    expect(await pending(request)).toBe(1);
+    await expect(page).toHaveURL(/#\/review$/);
+    // The item is untouched: still listed, still open, nothing linked.
+    await expect(cards(page)).toHaveCount(1);
+    await expect(context(page)).toBeEnabled();
+    expect(await links(request)).toEqual(before);
+    const [item] = (await (await request.get('/prompt_manager/review/items')).json()).items;
+    expect([item.state, item.revision]).toEqual(['pending', 0]);
+    // The card's Tag opens the same dialog.
+    await cards(page).first().getByRole('button', { name: 'Tag or auto-tag review_0000.png', exact: true }).click();
+    await expect(dialog).toBeVisible();
+    await expect(dialog.locator('p.tag-scope-note')).toBeVisible();
+    await page.keyboard.press('Escape');
+    await expect(dialog).toHaveCount(0);
+});
+
+test('an empty queue shows the empty notice only', async ({ page, request }) => {
+    await seed(request, 0);
+    await page.goto(review);
+    await expect(main(page).locator('.notice h2')).toHaveText('No images need a decision');
+    await expect(main(page).locator('.notice p')).toHaveText(EMPTY);
+    await expect(main(page).locator('.gallery-layout')).toHaveCount(0);
+    await expect(reviewRow(page)).toHaveText('Needs review0');
+});
+
+test('load more appends the next page', async ({ page, request }) => {
+    await seed(request, 45);
+    await open(page);
+    await expect(cards(page)).toHaveCount(40);
+    const continuation = main(page).locator('.infinite-continuation');
+    await expect(continuation.locator('p')).toHaveText('40 of 45 images');
+    await continuation.getByRole('button', { name: 'Load more images', exact: true }).click();
+    await expect(cards(page)).toHaveCount(45);
+    await expect(continuation).toHaveCount(0);
+});
+
+test('a scan job with review items offers Review metadata in Activity', async ({ page, request }) => {
+    await seed(request, 1);
+    const started = await (await request.post('/__test__/jobs/start', { data: { total: 10, review_items: 2 } })).json();
+    await expect(await request.post(`/__test__/jobs/${started.job.id}/finish`, { data: {} })).toBeOK();
+    const plain = await (await request.post('/__test__/jobs/start', { data: { total: 10 } })).json();
+    await expect(await request.post(`/__test__/jobs/${plain.job.id}/finish`, { data: {} })).toBeOK();
+    await page.goto('/prompt_manager/workspace#/activity');
+    const item = main(page).locator(`.activity-item[data-job-id="${started.job.id}"]`);
+    await expect(item.getByRole('button', { name: 'Review metadata', exact: true })).toBeVisible();
+    await expect(main(page).locator(`.activity-item[data-job-id="${plain.job.id}"] button`)).toHaveCount(0);
+    await page.goto(`/prompt_manager/workspace#/activity/${started.job.id}`);
+    const actions = main(page).locator('.heading-actions button');
+    await expect(actions).toHaveText(['Download report', 'Review metadata']);
+    await actions.nth(1).click();
+    await expect(page).toHaveURL(/#\/review$/);
+    await expect(main(page).getByRole('heading', { level: 1 })).toHaveText('Metadata review');
+});
+
+test('a failed item read says so and Retry reads it again', async ({ page, request }) => {
+    await seed(request, 1);
+    await page.route(url => /\/prompt_manager\/review\/items\/[0-9a-f-]{36}$/.test(url.pathname),
+        route => route.fulfill({ status: 500, contentType: 'application/json', body: JSON.stringify({ success: false, code: 'review-failed', error: 'x' }) }),
+        { times: 1 });
+    await page.goto(review);
+    await expect(panel(page).locator('.warning-note')).toHaveText('This item could not be read. Select it again to retry.');
+    await expect(panel(page).getByText('Could not read prompts from this file.', { exact: true })).toBeVisible();
+    await expect(panel(page).getByRole('button', { name: 'Apply association', exact: true })).toHaveAttribute('aria-disabled', 'true');
+    await panel(page).getByRole('button', { name: 'Retry prompt details', exact: true }).click();
+    await expect(context(page)).toBeEnabled();
+    await expect(context(page).locator('option')).toHaveText(OPTIONS);
+    await expect(panel(page).locator('.warning-note')).toBeHidden();
+});
+
+test('a failed queue read offers Retry', async ({ page, request }) => {
+    await seed(request, 1);
+    await page.route(url => url.pathname.endsWith('/prompt_manager/review/items') && url.searchParams.get('limit') === '40',
+        route => route.fulfill({ status: 500, contentType: 'application/json', body: JSON.stringify({ success: false, code: 'review-failed', error: 'x' }) }),
+        { times: 1 });
+    await page.goto(review);
+    await expect(main(page).getByRole('alert')).toHaveText('The review queue could not be read.');
+    await main(page).getByRole('button', { name: 'Retry', exact: true }).click();
+    await expect(context(page)).toBeEnabled();
+    await expect(main(page).locator('.notice h2')).toHaveText('1 image needs a decision');
+});
+
+test('keyboard focus labels and touch targets', async ({ page, request }) => {
+    await seed(request, 2);
+    await open(page);
+    const first = cards(page).first();
+    for (const [name, role] of [['Open review_0000.png', 'button'], ['Inspect review_0000.png', 'button'],
+        ['Tag or auto-tag review_0000.png', 'button']]) await expect(first.getByRole(role, { name, exact: true })).toBeVisible();
+    await expect(main(page).getByRole('list', { name: 'Review queue', exact: true })).toBeVisible();
+    await expect(panel(page)).toBeVisible();
+    // Keyboard: Info on the second card opens it, and the panel's controls take focus in their order.
+    const info = cards(page).nth(1).getByRole('button', { name: 'Inspect review_0001.png', exact: true });
+    await info.focus();
+    await page.keyboard.press('Enter');
+    await expect(panel(page).locator('p.small')).toHaveText('review_0001.png');
+    await expect(context(page)).toBeEnabled();
+    await context(page).focus();
+    await expect(context(page)).toBeFocused();
+    const order = await panel(page).evaluate(node => [...node.querySelectorAll('button, select')]
+        .filter(control => control.offsetParent !== null).map(control => control.getAttribute('aria-label') || control.textContent.trim()));
+    expect(order[0]).toBe('Tag image');
+    expect(order.slice(-2)).toEqual(['Leave for later', 'Apply association']);
+    // Targets: the panel's controls are 40px on a coarse pointer (the concept's coarse buttons) and 24px otherwise (the
+    // WCAG 2.2 minimum); the card's buttons keep the concept's compact size, never under 24px (its ≤700px rule).
+    const coarse = await page.evaluate(() => matchMedia('(pointer: coarse)').matches);
+    const sized = [
+        [panel(page).getByRole('button', { name: 'Tag image', exact: true }), coarse ? 40 : 24],
+        [context(page), coarse ? 40 : 24],
+        [panel(page).getByRole('button', { name: 'Leave for later', exact: true }), coarse ? 40 : 24],
+        [apply(page), coarse ? 40 : 24],
+        [first.getByRole('button', { name: 'Inspect review_0000.png', exact: true }), 24],
+        [first.getByRole('button', { name: 'Tag or auto-tag review_0000.png', exact: true }), 24],
+    ];
+    for (const [control, minimum] of sized) {
+        const box = await control.boundingBox();
+        const label = await control.evaluate(node => node.getAttribute('aria-label') || node.textContent.trim().slice(0, 40));
+        expect(box.height, label).toBeGreaterThanOrEqual(minimum);
+        expect(box.width, label).toBeGreaterThanOrEqual(24);
+    }
+    // Enter on Leave for later returns to Images.
+    await panel(page).getByRole('button', { name: 'Leave for later', exact: true }).focus();
+    await page.keyboard.press('Enter');
+    await expect(page).toHaveURL(/#\/images$/);
+});
+
+test('an open page shows items a scan adds and keeps the open choice', async ({ page, request }) => {
+    await seed(request, 1);
+    await open(page);
+    await expect.poll(async () => (await streams(request)).streams).toBe(1);
+    await context(page).selectOption({ label: OPTIONS[1] });
+    await expect(reviewRow(page)).toHaveText('Needs review1');
+    await expect(await request.post('/__test__/review/add', { data: { kind: 'scan' } })).toBeOK();
+    await expect(cards(page)).toHaveCount(2);
+    await expect(main(page).locator('.notice h2')).toHaveText('2 images need a decision');
+    await expect(reviewRow(page)).toHaveText('Needs review2');
+    await expect(cards(page).first()).toHaveClass(/selected/);
+    await expect(panel(page).locator('p.small')).toHaveText('review_0000.png');
+    await expect(context(page).locator('option:checked')).toHaveText(OPTIONS[1]);
+    await expect(warning(page)).toBeHidden();
+});
+
+test('an open page shows items a metadata scan adds', async ({ page, request }) => {
+    await seed(request, 1);
+    await expect(await request.post('/__test__/review/add', { data: { kind: 'file' } })).toBeOK();
+    await open(page);
+    await expect.poll(async () => (await streams(request)).streams).toBe(1);
+    await expect(cards(page)).toHaveCount(1);
+    const started = await request.post('/prompt_manager/jobs/scan', { data: { scope: 'new' } });
+    expect(started.status()).toBe(202);
+    await expect(cards(page)).toHaveCount(2);
+    await expect(cards(page).nth(1).getByRole('button', { name: 'Inspect added_0000.png', exact: true })).toBeVisible();
+    await expect(reviewRow(page)).toHaveText('Needs review2');
+});
+
+test('a decision in another tab leaves the open page and opens the next image', async ({ page, request, context: browserContext }) => {
+    await seed(request, 2);
+    await open(page);
+    await expect.poll(async () => (await streams(request)).streams).toBe(1);
+    const other = await browserContext.newPage();
+    await open(other);
+    await context(other).selectOption({ label: 'Leave unresolved' });
+    await apply(other).click();
+    await expect(other).toHaveURL(/#\/images$/);
+    await other.close();
+    await expect(cards(page)).toHaveCount(1);
+    await expect(panel(page).locator('p.small')).toHaveText('review_0001.png');
+    await expect(warning(page)).toHaveText('review_0000.png was decided elsewhere, so the next image is open.');
+    await expect(main(page).locator('.notice h2')).toHaveText('1 image needs a decision');
+    await expect(reviewRow(page)).toHaveText('Needs review1');
+    await expect(context(page)).toBeEnabled();
+});
+
+/** The queue reads (`?limit=40`, cursors) and count reads (`?limit=1`) the page sends from now on. */
+function reviewReads(page) {
+    const reads = [];
+    page.on('request', item => {
+        const url = new URL(item.url());
+        if (url.pathname === '/prompt_manager/review/items') reads.push(url.searchParams.get('cursor') ? 'more' : url.search);
+    });
+    return reads;
+}
+
+test('a visit reads its queue once, and a change reads it once more', async ({ page, request }) => {
+    // F3 ruling: the stream's ready must not read a queue the first read already holds.
+    await seed(request, 1);
+    const reads = reviewReads(page);
+    await open(page);
+    await expect.poll(async () => (await streams(request)).streams).toBe(1);
+    await expect(await request.post('/__test__/review/add', { data: { kind: 'scan' } })).toBeOK();
+    await expect(cards(page)).toHaveCount(2);
+    await expect(reviewRow(page)).toHaveText('Needs review2');
+    // The page's first read and the change's re-read; the shell's count read at start, and the row follows the page.
+    expect(reads.filter(search => search === '?limit=40')).toHaveLength(2);
+    expect(reads.filter(search => search === '?limit=1')).toHaveLength(1);
+});
+
+test('a ready whose version cannot be read re-reads the queue once', async ({ page, request }) => {
+    // The stream's ready names no readable version (an older server, a proxy that rewrote it): the page reads again.
+    await seed(request, 1);
+    const reads = reviewReads(page);
+    // M1: `retry` keeps the browser from reconnecting the ended stream during the test, so exactly one re-read follows.
+    await page.route(url => url.pathname === '/prompt_manager/review/events', route => route.fulfill({
+        status: 200, headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store' },
+        body: 'retry: 3600000\nevent: ready\ndata: not json\n\n' }));
+    let reread = 0;
+    const second = page.waitForResponse(item => item.url().endsWith('/prompt_manager/review/items?limit=40') && ++reread === 2);
+    await open(page);
+    await second;
+    await expect(cards(page)).toHaveCount(1);
+    expect(reads.filter(search => search === '?limit=40')).toHaveLength(2);
+});
+
+const live = page => main(page).locator('.heading .review-live');
+const NOT_LIVE = 'Live updates are paused: changes made elsewhere appear once the connection returns.';
+
+test('a stream the browser gives up on is opened again, and the page says it is not live meanwhile', async ({ page, request }) => {
+    // I3: a 503 (shutdown, or a proxy while the backend restarts) fails an EventSource for good.
+    await seed(request, 1);
+    let attempts = 0;
+    await page.route(url => url.pathname === '/prompt_manager/review/events', route => {
+        attempts += 1;
+        if (attempts === 1) return route.fulfill({ status: 503, contentType: 'application/json', body: '{"success":false}' });
+        return route.fallback();
+    });
+    await open(page);
+    await expect(live(page)).toHaveText(NOT_LIVE);
+    await expect(live(page)).toBeVisible();
+    // The page opens the stream again (after 3 s) and is live once it sends ready.
+    await expect.poll(async () => (await streams(request)).streams, { timeout: 15000 }).toBe(1);
+    await expect(live(page)).toBeHidden();
+    await expect(await request.post('/__test__/review/add', { data: { kind: 'scan' } })).toBeOK();
+    await expect(cards(page)).toHaveCount(2);
+    expect(attempts).toBe(2);
+});
+
+/** Make the page hidden or visible as a tab switch does. */
+async function setVisible(page, visible) {
+    await page.evaluate(shown => {
+        Object.defineProperty(document, 'hidden', { configurable: true, get: () => !shown });
+        Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => (shown ? 'visible' : 'hidden') });
+        document.dispatchEvent(new Event('visibilitychange'));
+    }, visible);
+}
+
+test('a hidden tab closes its stream and a visible one reads only what changed meanwhile', async ({ page, request }) => {
+    // I4: background tabs must not hold one of the origin's six connections.
+    await seed(request, 1);
+    const reads = reviewReads(page);
+    await open(page);
+    await expect.poll(async () => (await streams(request)).streams).toBe(1);
+    await setVisible(page, false);
+    await expect(await request.post('/__test__/review/add', { data: { kind: 'scan' } })).toBeOK();
+    await closedStreamsDropped(request);
+    await expect(cards(page)).toHaveCount(1);
+    expect(reads.filter(search => search === '?limit=40')).toHaveLength(1);
+    // Visible again: the reopened stream's ready names a newer version, so the page reads once.
+    const reread = page.waitForResponse(item => item.url().endsWith('/prompt_manager/review/items?limit=40'));
+    await setVisible(page, true);
+    await expect.poll(async () => (await streams(request)).streams).toBe(1);
+    await reread;
+    await expect(cards(page)).toHaveCount(2);
+    await expect(live(page)).toBeHidden();
+    expect(reads.filter(search => search === '?limit=40')).toHaveLength(2);
+});
+
+test('a stream whose close reaches the server after a change is dropped at a later write', async ({ page, request }) => {
+    // The CI ordering made certain: the hidden page's close arrives only after the scan addition's change was
+    // written to its stream, so that write succeeds and a later one finds the stream closed.
+    await seed(request, 1);
+    await open(page);
+    await expect.poll(async () => (await streams(request)).streams).toBe(1);
+    await page.evaluate(() => {
+        const close = EventSource.prototype.close;
+        window.lateChanges = 0;
+        window.heldCloses = [];
+        EventSource.prototype.close = function () {
+            this.addEventListener('change', () => { window.lateChanges += 1; });
+            window.heldCloses.push(() => close.call(this));
+        };
+    });
+    await setVisible(page, false);
+    await expect(await request.post('/__test__/review/add', { data: { kind: 'scan' } })).toBeOK();
+    await expect.poll(() => page.evaluate(() => window.lateChanges)).toBe(1);
+    await page.evaluate(() => window.heldCloses.splice(0).forEach(close => close()));
+    expect((await streams(request)).streams).toBe(1);
+    await closedStreamsDropped(request);
+    await expect(cards(page)).toHaveCount(1);
+});
+
+test('a re-read refreshes a card whose media or target changed', async ({ page, request }) => {
+    // M6 and M10: a root came or went between reads; the card follows, and a known thumbnail is its media.
+    await seed(request, 2);
+    let rewrite = false;
+    await page.route(url => url.pathname === '/prompt_manager/review/items' && url.search === '?limit=40', async route => {
+        if (!rewrite) return route.fallback();
+        const response = await route.fetch();
+        const body = await response.json();
+        body.items[0] = { ...body.items[0], thumbnail_url: `${body.items[0].url}&thumb=1` };
+        body.items[1] = { ...body.items[1], url: null, thumbnail_url: null, target: null, unavailable: true };
+        return route.fulfill({ response, json: body });
+    });
+    await open(page);
+    await expect.poll(async () => (await streams(request)).streams).toBe(1);
+    const second = cards(page).nth(1);
+    await expect(second.getByRole('button', { name: 'Open review_0001.png', exact: true })).not.toHaveAttribute('aria-disabled', 'true');
+    rewrite = true;
+    await expect(await request.post('/__test__/review/add', { data: { kind: 'scan' } })).toBeOK();
+    await expect(cards(page)).toHaveCount(3);
+    await expect(cards(page).first().locator('img')).toHaveAttribute('src', /&thumb=1$/);
+    await expect(second.getByRole('button', { name: 'Open review_0001.png', exact: true })).toHaveAttribute('aria-disabled', 'true');
+    await expect(second.locator('img')).toHaveCount(0);
+    await expect(second.locator('.image-card-actions button').last()).toHaveAttribute('aria-disabled', 'true');
+    await expect(cards(page).first()).toHaveClass(/selected/);
+});
+
+test('leaving during the observe releases the capture it answers', async ({ page, request }) => {
+    // M4: the server made the capture; the page left before the answer came.
+    await seed(request, 1);
+    await open(page);
+    let held;
+    const sent = new Promise(resolve => { held = resolve; });
+    await page.route(url => url.pathname === '/prompt_manager/image-annotations/observe', async route => {
+        const response = await route.fetch();
+        held(() => route.fulfill({ response }));
+    });
+    await apply(page).click();
+    const answer = await sent;
+    expect((await streams(request)).captures).toBe(1);
+    await page.evaluate(() => { window.location.hash = '#/tags'; });
+    await expect(main(page).getByRole('heading', { level: 1 })).toHaveText('Tags & categories');
+    await answer();
+    await expect.poll(async () => (await streams(request)).captures).toBe(0);
+});
+
+test('a live re-read keeps the loaded depth and the scroll position', async ({ page, request }) => {
+    // F3 ruling: a queue change re-reads as many items as Load more had shown, and the page does not jump.
+    await seed(request, 45);
+    await open(page);
+    await expect.poll(async () => (await streams(request)).streams).toBe(1);
+    await main(page).getByRole('button', { name: 'Load more images', exact: true }).click();
+    await expect(cards(page)).toHaveCount(45);
+    await cards(page).last().scrollIntoViewIfNeeded();
+    const scrollTop = () => cards(page).first().evaluate(node => {
+        for (let el = node.parentElement; el; el = el.parentElement) {
+            const style = getComputedStyle(el);
+            if (/(auto|scroll)/.test(style.overflowY) && el.scrollHeight > el.clientHeight) return el.scrollTop;
+        }
+        return document.scrollingElement.scrollTop;
+    });
+    const before = await scrollTop();
+    expect(before).toBeGreaterThan(0);
+    const reads = reviewReads(page);
+    await expect(await request.post('/__test__/review/add', { data: { kind: 'scan' } })).toBeOK();
+    await expect(main(page).locator('.notice h2')).toHaveText('46 images need a decision');
+    await expect(cards(page)).toHaveCount(46);
+    expect(await scrollTop()).toBe(before);
+    expect(reads).toEqual(['?limit=40', 'more']);
+    await expect(main(page).locator('.infinite-continuation')).toHaveCount(0);
+});
+
+test('teardown releases captures listeners and requests', async ({ page, request }) => {
+    await seed(request, 1);
+    await open(page);
+    await expect.poll(async () => (await streams(request)).streams).toBe(1);
+    const inFlight = new Set();
+    page.on('request', item => { if (item.url().includes('/prompt_manager/review/')) inFlight.add(item); });
+    page.on('requestfinished', item => inFlight.delete(item));
+    page.on('requestfailed', item => inFlight.delete(item));
+    // A decision whose answer never comes: leaving the page must still release its capture.
+    let held;
+    const sent = new Promise(resolve => { held = resolve; });
+    await page.route(url => /\/decision$/.test(url.pathname), route => held(route));
+    await apply(page).click();
+    const route = await sent;
+    expect((await streams(request)).captures).toBe(1);
+    await page.evaluate(() => { window.location.hash = '#/tags'; });
+    await expect(main(page).getByRole('heading', { level: 1 })).toHaveText('Tags & categories');
+    await expect.poll(async () => (await streams(request)).captures).toBe(0);
+    await route.abort().catch(() => {});
+    await closedStreamsDropped(request);
+    await expect.poll(() => inFlight.size).toBe(0);
+});

tests/browser/workspace-saved-views.spec.mjs

@@ -372,7 +372,7 @@ test('Favorites is the first SAVED VIEWS row, with a real count that follows eve
     expect(await favoritesRow(page).evaluate(link => [...link.childNodes].map(node => node.nodeType === Node.TEXT_NODE
         ? `text:${node.textContent}` : `${node.localName}.${node.getAttribute('class')}`)))
         .toEqual(['svg.icon', 'text:Favorites', 'span.nav-count']);
-    expect(await savedNav(page).locator('a').evaluateAll(links => links.map(link => link.dataset.route))).toEqual(['favorites']);
+    expect(await savedNav(page).locator('a').evaluateAll(links => links.map(link => link.dataset.route))).toEqual(['favorites', 'review']);
 
     await star(page, '1:shared/same.png');
     await expect(toast(page)).toHaveText('Added to favorites.');

tests/browser/workspace-system-backups.spec.mjs

@@ -0,0 +1,489 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { seedConcept } from './concept-inventory.mjs';
+
+// System › Backup & export (#249 System S9 Task 24) on the S8 backend and the concept-shaped fixture: Back up and its
+// status line (D103), the restore review (D105) and its job, the exports, Import / inspect and the recovery policy
+// (D104). A restore here replaces this worker's own temp database; every test starts from a fresh concept fixture.
+const workspace = '/prompt_manager/workspace';
+const STATUS_URL = '/prompt_manager/backup/status';
+const PREVIEW_URL = '/prompt_manager/restore/preview';
+const APPLY_URL = '/prompt_manager/restore/apply';
+const WHEN = { dateStyle: 'medium', timeStyle: 'short' };
+const SAFETY_DESCRIPTION = 'Keep a verified copy of the database on disk before maintenance, cleanups and LoRA imports change ' +
+    'records. A restore always keeps one.';
+
+test.use({ locale: 'en-US', timezoneId: 'UTC' });
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await seedConcept(request);
+    await expect(await request.post('/__test__/system/reset')).toBeOK();
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    page.systemErrors = [];
+    page.on('pageerror', error => page.systemErrors.push(error.message));
+});
+
+test.afterEach(async ({ page, request, browserName }) => {
+    await saveCoverage(page, browserName);
+    await request.post('/__test__/release');
+    await request.post('/__test__/jobs/restart');
+    await request.post('/__test__/system/reset');
+    expect(page.systemErrors).toEqual([]);
+});
+
+const toast = page => page.locator('#workspace-toast');
+const layoutOf = page => page.locator('#workspace-main .settings-layout');
+const dialog = page => page.locator('dialog#modal[open]');
+const statusLine = page => layoutOf(page).locator('#backup-status');
+const settingsStatus = page => page.locator('#settings-status');
+const save = page => page.getByRole('button', { name: 'Save preferences', exact: true });
+const buttonOf = (page, name) => layoutOf(page).getByRole('button', { name, exact: true });
+const settingOf = (page, label) => layoutOf(page).locator('.setting-row').filter({ has: page.locator(`label:text-is("${label}")`) });
+
+async function serverJson(request, url) {
+    const response = await request.get(url);
+    await expect(response).toBeOK();
+    return response.json();
+}
+
+async function openBackups(page) {
+    // A fresh page each time: the drafts live for the page session (Q10), and a hash-only goto would not reload.
+    if (page.url().endsWith('#/system/backups')) await page.reload();
+    else await page.goto(`${workspace}#/system/backups`);
+    await expect(layoutOf(page).locator(':scope > .two-col > section.surface')).toHaveCount(2);
+    await expect(statusLine(page)).not.toHaveText('Checking backups…');
+    // The policy row is painted once the server settings were read.
+    await expect(settingOf(page, 'Create a safety backup before maintenance').locator('input')).toBeEnabled();
+    return layoutOf(page);
+}
+
+/** The status line the page should show for the server's current status (its own wording, in this locale). */
+async function expectedStatus(page, request) {
+    const status = await serverJson(request, STATUS_URL);
+    return page.evaluate(([answer, options]) => {
+        const when = value => new Date(value).toLocaleString(undefined, options);
+        const parts = [];
+        if (answer.last_download) parts.push(`Downloaded backup · ${when(answer.last_download.at)} · ${answer.last_download.verified ? 'verified' : 'not verified'}.`);
+        if (answer.safety_backups.length) parts.push(`Safety backup · ${when(answer.safety_backups[0].modified_at)} · ${answer.safety_backups.length} on disk.`);
+        return parts.join(' ') || 'No backup recorded.';
+    }, [status, WHEN]);
+}
+
+/** A verified copy of the library as it is now (this records the session's last download, as Back up does). */
+async function backupBytes(request) {
+    const response = await request.get('/prompt_manager/backup');
+    await expect(response).toBeOK();
+    expect(response.headers()['x-promptmanager-verify']).toBe('ok');
+    return response.body();
+}
+
+/** Pick `buffer` as the backup file through Review restore…'s file chooser; resolves with the preview's answer. */
+async function chooseBackup(page, buffer, name = 'prompts_backup_20261025_093000.db') {
+    const chooser = page.waitForEvent('filechooser');
+    const answer = page.waitForResponse(response => response.url().endsWith(PREVIEW_URL) && response.request().method() === 'POST');
+    await buttonOf(page, 'Review restore…').click();
+    await (await chooser).setFiles({ name, mimeType: 'application/octet-stream', buffer });
+    return answer;
+}
+
+const gridOf = page => dialog(page).locator('dl.meta-grid > div').evaluateAll(items => items.map(item =>
+    [item.querySelector('dt').textContent, item.querySelector('dd').textContent]));
+
+const libraryTotal = async request => (await serverJson(request, '/prompt_manager/library?limit=1')).total;
+
+test('Back up downloads through the api client and revokes the object URL (D103)', async ({ page, request }) => {
+    await page.addInitScript(() => {
+        window.objectUrls = { created: [], revoked: [] };
+        const create = URL.createObjectURL.bind(URL), revoke = URL.revokeObjectURL.bind(URL);
+        URL.createObjectURL = blob => { const url = create(blob); window.objectUrls.created.push(url); return url; };
+        URL.revokeObjectURL = url => { window.objectUrls.revoked.push(url); revoke(url); };
+    });
+    await openBackups(page);
+    await expect(statusLine(page)).toHaveText('No backup recorded.');
+    const download = page.waitForEvent('download');
+    const answer = page.waitForResponse(response => new URL(response.url()).pathname === '/prompt_manager/backup');
+    await buttonOf(page, 'Back up').click();
+    expect((await answer).headers()['x-promptmanager-verify']).toBe('ok');
+    expect((await download).suggestedFilename()).toMatch(/^prompts_backup_\d{8}_\d{6}\.db$/);
+    await expect(toast(page)).toHaveText('Database backup downloaded.');
+    // The status line is read again: this session's verified download, as the server records it.
+    await expect(statusLine(page)).toHaveText(/^Downloaded backup · .+ · verified\.$/);
+    await expect(statusLine(page)).toHaveText(await expectedStatus(page, request));
+    await expect(buttonOf(page, 'Back up')).not.toHaveAttribute('aria-disabled', 'true');
+    const urls = await page.evaluate(() => window.objectUrls.created);
+    expect(urls).toHaveLength(1);
+    await expect.poll(() => page.evaluate(() => window.objectUrls.revoked)).toEqual(urls);
+});
+
+test('status line shows only server-reported backups (D103)', async ({ page, request }) => {
+    await openBackups(page);
+    await expect(statusLine(page)).toHaveText('No backup recorded.');
+    await expect(await request.post('/__test__/system/safety-backup')).toBeOK();
+    await openBackups(page);
+    await expect(statusLine(page)).toHaveText(/^Safety backup · .+ · 1 on disk\.$/);
+    await expect(statusLine(page)).toHaveText(await expectedStatus(page, request));
+    // A status the server could not report is never shown as "no backup".
+    await page.route(`**${STATUS_URL}`, route => route.fulfill({ status: 500, json: { success: false, error: 'Failed' } }));
+    await page.reload();
+    await expect(statusLine(page)).toHaveText('The backup status could not be read.');
+});
+
+test('Overview backup row uses the same status (D93)', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/safety-backup')).toBeOK();
+    await backupBytes(request);
+    await page.goto(`${workspace}#/system/overview`);
+    const row = layoutOf(page).locator('.operation').filter({ has: page.locator('h3', { hasText: 'Backup status' }) });
+    const expected = await expectedStatus(page, request);
+    expect(expected).toMatch(/^Downloaded backup · .+ · verified\. Safety backup · .+ · 1 on disk\.$/);
+    await expect(row.locator('p')).toHaveText(expected);
+    await row.getByRole('button', { name: 'View backups', exact: true }).click();
+    await expect(page).toHaveURL(`${workspace}#/system/backups`);
+    await expect(statusLine(page)).toHaveText(expected);
+});
+
+test('Review restore stages the chosen file and shows the real summary with the backup box (D105)', async ({ page, request }) => {
+    const bytes = await backupBytes(request);
+    await expect(await request.post('/prompt_manager/save', { data: { text: 'S9 prompt saved after the backup' } })).toBeOK();
+    const before = await serverJson(request, '/__test__/system/digest');
+    await openBackups(page);
+    const answer = await chooseBackup(page, bytes);
+    const preview = await answer.json();
+    expect(preview.integrity).toBe('ok');
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Restore preview');
+    const counts = summary => `${summary.prompts.toLocaleString('en-US')} ${summary.prompts === 1 ? 'prompt' : 'prompts'} · ` +
+        `${summary.image_links} ${summary.image_links === 1 ? 'image link' : 'image links'} · ` +
+        `${summary.pairs} ${summary.pairs === 1 ? 'saved pair' : 'saved pairs'} · ${summary.runs} ${summary.runs === 1 ? 'run' : 'runs'}`;
+    const rows = await gridOf(page);
+    expect(rows.map(([term]) => term)).toEqual(['Snapshot', 'Integrity', 'Migration', 'Safety backup', 'In the backup', 'In the library now']);
+    expect(rows[0][1]).toMatch(/^prompts_backup_20261025_093000.db · (\d+ KB|\d+\.\d MB) · .+$/);
+    expect(rows.slice(1)).toEqual([['Integrity', 'Verified'], ['Migration', 'Current schema'],
+        ['Safety backup', `Created before replacing (${preview.safety_backup.destination_label})`],
+        ['In the backup', counts(preview.summary)], ['In the library now', counts(preview.live)]]);
+    // The prompt saved after the backup is the difference the review shows.
+    expect(preview.live.prompts).toBe(preview.summary.prompts + 1);
+    await expect(dialog(page).locator('#modal-body > p.small')).toHaveText('Restore replaces the whole library with this backup ' +
+        'and runs alone in Activity. Nothing changes until you restore. This review holds for 15 minutes.');
+    await expect(dialog(page).locator('.notice h3')).toHaveText('Back up the database first (recommended)');
+    await expect(dialog(page).locator('.notice p')).toHaveText('Downloads a copy of the prompts database before the restore replaces it.');
+    const actions = dialog(page).locator('.dialog-actions > button');
+    await expect(actions).toHaveText(['Cancel', 'Restore']);
+    await expect(actions.nth(1)).toHaveClass('danger');
+    // The backup box downloads a copy and keeps the review open.
+    const download = page.waitForEvent('download');
+    await dialog(page).getByRole('button', { name: 'Back up now', exact: true }).click();
+    await download;
+    await expect(toast(page)).toHaveText('Database backup downloaded.');
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Restore preview');
+    // A review writes nothing: the rows and the media are as they were.
+    expect(await serverJson(request, '/__test__/system/digest')).toEqual(before);
+    expect((await serverJson(request, '/__test__/system/backups')).stages).toBe(1);
+});
+
+test('Cancel discards the stage; Escape too', async ({ page, request }) => {
+    const bytes = await backupBytes(request);
+    const before = await serverJson(request, '/__test__/system/digest');
+    await openBackups(page);
+    await chooseBackup(page, bytes);
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Restore preview');
+    expect((await serverJson(request, '/__test__/system/backups')).stages).toBe(1);
+    let discarded = page.waitForResponse(response => response.url().includes(`${PREVIEW_URL}/`) && response.request().method() === 'DELETE');
+    await dialog(page).getByRole('button', { name: 'Cancel', exact: true }).click();
+    expect((await discarded).status()).toBe(200);
+    await expect(dialog(page)).toHaveCount(0);
+    await expect(buttonOf(page, 'Review restore…')).toBeFocused();
+    expect((await serverJson(request, '/__test__/system/backups')).stages).toBe(0);
+    await chooseBackup(page, bytes);
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Restore preview');
+    discarded = page.waitForResponse(response => response.url().includes(`${PREVIEW_URL}/`) && response.request().method() === 'DELETE');
+    await page.keyboard.press('Escape');
+    expect((await discarded).status()).toBe(200);
+    expect((await serverJson(request, '/__test__/system/backups')).stages).toBe(0);
+    expect(await serverJson(request, '/__test__/system/digest')).toEqual(before);
+});
+
+test('Restore starts the job, opens Activity; views reload after it finishes', async ({ page, request }) => {
+    const bytes = await backupBytes(request);
+    const restoredTotal = await libraryTotal(request);
+    await expect(await request.post('/prompt_manager/save', { data: { text: 'S9 prompt the restore removes' } })).toBeOK();
+    expect(await libraryTotal(request)).toBe(restoredTotal + 1);
+    await openBackups(page);
+    const libraryCount = page.locator('aside.sidebar a[data-route="library"] .nav-count');
+    await expect(libraryCount).toHaveText((restoredTotal + 1).toLocaleString('en-US'));
+    await chooseBackup(page, bytes);
+    const applied = page.waitForResponse(response => response.url().endsWith(APPLY_URL));
+    await dialog(page).getByRole('button', { name: 'Restore', exact: true }).click();
+    const { job } = await (await applied).json();
+    expect([job.kind, job.title, job.cancellable]).toEqual(['restore', 'Database restore', false]);
+    await expect(page).toHaveURL(`${workspace}#/activity/${job.id}`);
+    await expect(toast(page)).toHaveText(/^Database restore finished · Restored \d+ prompts?, /);
+    // The library is the backup's again, and the page says so without a reload: the sidebar counts were read again.
+    expect(await libraryTotal(request)).toBe(restoredTotal);
+    await expect(libraryCount).toHaveText(restoredTotal.toLocaleString('en-US'));
+    expect((await serverJson(request, '/__test__/system/backups')).safety).toHaveLength(1);
+    // The Activity job view stayed, and Backup & export now names the safety backup the restore kept.
+    await expect(page).toHaveURL(`${workspace}#/activity/${job.id}`);
+    await page.goto(`${workspace}#/system/backups`);
+    await expect(statusLine(page)).toHaveText(/Safety backup · .+ · 1 on disk\.$/);
+});
+
+test('a finished restore shows the open page again from the restored data', async ({ page, request }) => {
+    const bytes = await backupBytes(request);
+    const restoredTotal = await libraryTotal(request);
+    await expect(await request.post('/prompt_manager/save', { data: { text: 'S9 prompt the restore removes' } })).toBeOK();
+    await openBackups(page);
+    await chooseBackup(page, bytes);
+    const preview = page.locator('dialog#modal[open] #modal-title');
+    await expect(preview).toHaveText('Restore preview');
+    // The restore is held at its start, so the reader is on the Library (showing the prompt) when it finishes.
+    await expect(await request.post('/__test__/hold', { data: { path: APPLY_URL } })).toBeOK();
+    const applied = page.waitForResponse(response => response.url().endsWith(APPLY_URL));
+    await dialog(page).getByRole('button', { name: 'Restore', exact: true }).click();
+    await expect.poll(async () => (await serverJson(request, '/__test__/hold')).held[APPLY_URL]).toBe(1);
+    await page.evaluate(() => { window.location.hash = '#/library'; });
+    const card = page.locator('#workspace-main article.prompt-card').filter({ hasText: 'S9 prompt the restore removes' });
+    await expect(card).toHaveCount(1);
+    await expect(await request.post('/__test__/release')).toBeOK();
+    await applied;
+    await expect(toast(page)).toHaveText(/^Database restore finished · /);
+    // The shelf was read again from the restored library, on the same route.
+    await expect(card).toHaveCount(0);
+    await expect(page).toHaveURL(`${workspace}#/library`);
+    expect(await libraryTotal(request)).toBe(restoredTotal);
+});
+
+test('invalid file shows the validator message; nothing is staged', async ({ page, request }) => {
+    const before = await serverJson(request, '/__test__/system/digest');
+    await openBackups(page);
+    const answer = await chooseBackup(page, Buffer.from('this is not a database'), 'notes.db');
+    expect(answer.status()).toBe(400);
+    const body = await answer.json();
+    expect(body.code).toBe('invalid-backup');
+    await expect(toast(page)).toHaveText(`This file can't be restored: ${body.error.replace(/\.?$/, '.')}`);
+    await expect(dialog(page)).toHaveCount(0);
+    await expect(buttonOf(page, 'Review restore…')).not.toHaveAttribute('aria-disabled', 'true');
+    expect((await serverJson(request, '/__test__/system/backups')).stages).toBe(0);
+    expect(await serverJson(request, '/__test__/system/digest')).toEqual(before);
+});
+
+test('Export JSON downloads /library/export; secondary buttons download all prompts (/export) and /pairs/export (D103)', async ({ page }) => {
+    const layout = await openBackups(page);
+    const portable = layout.locator('section.surface').filter({ has: page.locator('h2', { hasText: 'Portable export' }) });
+    expect(await portable.locator('.row-actions > button').allTextContents())
+        .toEqual(['Export JSON', 'Import / inspect file', 'Export all prompts JSON', 'Export saved pairs JSON']);
+    for (const [label, url, name, kind] of [
+        ['Export JSON', '/prompt_manager/library/export', /^prompt-manager-library-v1\.json$/, 'prompt-manager-library'],
+        ['Export all prompts JSON', '/prompt_manager/export', /^prompt_manager_\d{8}_\d{6}\.json$/, null],
+        ['Export saved pairs JSON', '/prompt_manager/pairs/export', /^prompt-pairs\.json$/, 'prompt-manager-pairs']]) {
+        const download = page.waitForEvent('download');
+        const answer = page.waitForResponse(response => new URL(response.url()).pathname === url);
+        await portable.getByRole('button', { name: label, exact: true }).click();
+        expect((await answer).status()).toBe(200);
+        const file = await download;
+        expect(file.suggestedFilename()).toMatch(name);
+        const parsed = JSON.parse(await (await file.createReadStream()).toArray().then(chunks => Buffer.concat(chunks).toString('utf8')));
+        if (kind) expect(parsed.kind).toBe(kind);
+        else expect(Array.isArray(parsed.prompts)).toBe(true);
+    }
+    // A failed export says so and saves nothing.
+    await page.route('**/prompt_manager/pairs/export', route => route.fulfill({ status: 500, json: { success: false } }));
+    await portable.getByRole('button', { name: 'Export saved pairs JSON', exact: true }).click();
+    await expect(toast(page)).toHaveText('The export could not be downloaded. Nothing was saved to this device.');
+});
+
+test('Import / inspect lists Inspect, Rescan and the shared scan review (D15, D55)', async ({ page, request }) => {
+    await openBackups(page);
+    const open = async () => {
+        await buttonOf(page, 'Import / inspect file').click();
+        await expect(dialog(page).locator('#modal-title')).toHaveText('Import & inspect');
+    };
+    await open();
+    const rows = dialog(page).locator('.operation-list > .operation');
+    expect(await rows.locator('h3').allTextContents()).toEqual(['Inspect a local image', 'Scan an output folder', 'Scan for metadata']);
+    expect(await rows.locator('button').allTextContents()).toEqual(['Open inspector', 'Rescan', 'Review scan']);
+    // Rescan reads the output folders again and says what it found; while it runs, a reopened dialog says so.
+    await expect(await request.post('/__test__/hold', { data: { path: '/prompt_manager/gallery/rescan' } })).toBeOK();
+    const rescan = page.waitForResponse(response => response.url().endsWith('/prompt_manager/gallery/rescan'));
+    await rows.getByRole('button', { name: 'Rescan', exact: true }).click();
+    await expect(dialog(page)).toHaveCount(0);
+    await expect(toast(page)).toHaveText('Rescanning output folders…');
+    await open();
+    await expect(rows.nth(1).locator('button')).toHaveText('Rescanning…');
+    await expect(rows.nth(1).locator('button')).toHaveAttribute('aria-disabled', 'true');
+    await expect(await request.post('/__test__/release')).toBeOK();
+    expect((await rescan).status()).toBe(200);
+    await expect(toast(page)).toHaveText(/^Rescan finished\. \d+ files? in \d+ output folders?\.$/);
+    await expect(rows.nth(1).locator('button')).toHaveText('Rescan');
+    // Scan for metadata opens the shared review over the server's output folders; Cancel starts nothing.
+    await dialog(page).getByRole('button', { name: 'Review scan', exact: true }).click();
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Review metadata scan');
+    await expect(dialog(page).locator('dl.meta-grid dd').first()).toHaveText(/^\d+ output folders?$/);
+    await dialog(page).getByRole('button', { name: 'Cancel', exact: true }).click();
+    await expect(dialog(page)).toHaveCount(0);
+    // Open inspector goes to Inspect a file.
+    await open();
+    await dialog(page).getByRole('button', { name: 'Open inspector', exact: true }).click();
+    await expect(page).toHaveURL(`${workspace}#/inspect`);
+    await expect(dialog(page)).toHaveCount(0);
+});
+
+test('safety backup toggle saves through Save preferences with revision (D104)', async ({ page, request }) => {
+    const before = await serverJson(request, '/prompt_manager/settings');
+    expect(before.settings.safety_backup).toBe(true);
+    await openBackups(page);
+    const row = settingOf(page, 'Create a safety backup before maintenance');
+    // D104: what the policy really does (the concept's "Preview a verified backup…" line does not say it).
+    await expect(row.locator('p').first()).toHaveText(SAFETY_DESCRIPTION);
+    const toggle = row.locator('input');
+    await expect(toggle).toBeChecked();
+    await toggle.uncheck();
+    await expect(settingsStatus(page)).toHaveText('Unsaved changes.');
+    const saved = page.waitForRequest(item => item.url().endsWith('/prompt_manager/settings') && item.method() === 'POST');
+    await save(page).click();
+    const body = (await saved).postDataJSON();
+    expect(body).toEqual({ safety_backup: false, expected_revision: before.revision });
+    await expect(settingsStatus(page)).toHaveText('Saved to the server configuration.');
+    expect((await serverJson(request, '/prompt_manager/settings')).settings.safety_backup).toBe(false);
+    // A maintenance review now says so.
+    const plan = await request.post('/prompt_manager/maintenance/preview', { data: { operation: 'optimize', options: {} } });
+    expect((await plan.json()).backup.policy).toBe('off');
+    await openBackups(page);
+    await expect(toggle).not.toBeChecked();
+    // A configuration changed elsewhere is a conflict, never a blind write.
+    await toggle.check();
+    await expect(await request.post('/prompt_manager/settings', { data: { result_timeout: 7,
+        expected_revision: (await serverJson(request, '/prompt_manager/settings')).revision } })).toBeOK();
+    await save(page).click();
+    await expect(settingsStatus(page)).toHaveText('Settings changed elsewhere. Reload this section to see them.');
+    expect((await serverJson(request, '/prompt_manager/settings')).settings.safety_backup).toBe(false);
+});
+
+test('schedule offers Manual only; Daily/Weekly disabled with reason (D104)', async ({ page }) => {
+    await openBackups(page);
+    const schedule = settingOf(page, 'Scheduled database backups');
+    expect(await schedule.locator('option').evaluateAll(options => options.map(option => [option.textContent, option.disabled])))
+        .toEqual([['Manual only', false], ['Daily', true], ['Weekly', true]]);
+    await expect(schedule.locator('select')).toHaveValue('Manual only');
+    await expect(schedule.locator('p')).toHaveText('Daily and Weekly are not available yet: back up with Back up whenever you choose.');
+    const policy = layoutOf(page).locator(':scope > section.surface');
+    await expect(policy.locator('h2')).toHaveText('Recovery policy Proposed');
+    await expect(policy.locator('h2 > span.chip.blue')).toHaveText('Proposed');
+    await expect(policy.locator('p.warning-note')).toHaveText('Restores are staged, migrated and validated before replacing live data.');
+    // Nothing on the schedule is ever drafted.
+    await expect(settingsStatus(page)).toHaveText('No unsaved changes.');
+});
+
+test('a failed settings read leaves the policy disabled with the reason', async ({ page }) => {
+    await page.route('**/prompt_manager/settings', route => (route.request().method() === 'GET'
+        ? route.fulfill({ status: 500, json: { success: false, error: 'Failed' } }) : route.continue()));
+    await page.goto(`${workspace}#/system/backups`);
+    const row = settingOf(page, 'Create a safety backup before maintenance');
+    await expect(row.locator('p.small')).toHaveText('Server settings could not be read.');
+    await expect(row.locator('input')).toBeDisabled();
+});
+
+test('the legacy admin Backup and Restore keep working', async ({ page, request }) => {
+    const bytes = await backupBytes(request);
+    const restored = await request.post('/prompt_manager/restore', { multipart: { database_file: {
+        name: 'prompts_backup.db', mimeType: 'application/octet-stream', buffer: bytes } } });
+    await expect(restored).toBeOK();
+    expect((await restored.json()).success).toBe(true);
+    await page.goto('/prompt_manager/admin');
+    await expect(page.locator('#restoreFileInput')).toHaveCount(1);
+});
+
+/** Start a fake running job (a metadata scan another tab started), which an exclusive restore must wait for. */
+async function runningScan(request) {
+    const response = await request.post('/__test__/jobs/start', { data: { kind: 'scan', title: 'Metadata scan', total: 4 } });
+    await expect(response).toBeOK();
+    return (await response.json()).job;
+}
+
+const stagesOf = async request => (await serverJson(request, '/__test__/system/backups')).stages;
+const deleted = page => page.waitForResponse(response => response.url().includes(`${PREVIEW_URL}/`) &&
+    response.request().method() === 'DELETE');
+
+test('a refused restore reopens its review: Restore retries it, Discard releases it (I1)', async ({ page, request }) => {
+    const bytes = await backupBytes(request);
+    await openBackups(page);
+    await chooseBackup(page, bytes);
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Restore preview');
+    const scan = await runningScan(request);
+    const refused = page.waitForResponse(response => response.url().endsWith(APPLY_URL));
+    await dialog(page).getByRole('button', { name: 'Restore', exact: true }).click();
+    expect((await refused).status()).toBe(409);
+    await expect(toast(page)).toHaveText('Another job is running: Metadata scan.');
+    // The same review is open again, its stage still held: Restore retries, Discard releases it.
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Restore preview');
+    await expect(dialog(page).locator('.dialog-actions > button')).toHaveText(['Discard', 'Restore']);
+    expect(await stagesOf(request)).toBe(1);
+    await expect(await request.post(`/__test__/jobs/${scan.id}/finish`, { data: { state: 'finished' } })).toBeOK();
+    const applied = page.waitForResponse(response => response.url().endsWith(APPLY_URL));
+    await dialog(page).getByRole('button', { name: 'Restore', exact: true }).click();
+    const { job } = await (await applied).json();
+    await expect(page).toHaveURL(`${workspace}#/activity/${job.id}`);
+    await expect(toast(page)).toHaveText(/^Database restore finished · /);
+    expect(await stagesOf(request)).toBe(0);
+});
+
+test('two refused restores in a row, then a third Review restore… still opens the preview (I1)', async ({ page, request }) => {
+    const bytes = await backupBytes(request);
+    await openBackups(page);
+    await runningScan(request);
+    for (const leave of ['discard', 'escape']) {
+        await chooseBackup(page, bytes);
+        await expect(dialog(page).locator('#modal-title')).toHaveText('Restore preview');
+        const refused = page.waitForResponse(response => response.url().endsWith(APPLY_URL));
+        await dialog(page).getByRole('button', { name: 'Restore', exact: true }).click();
+        expect((await refused).status()).toBe(409);
+        await expect(dialog(page).locator('.dialog-actions > button')).toHaveText(['Discard', 'Restore']);
+        const released = deleted(page);
+        if (leave === 'discard') await dialog(page).getByRole('button', { name: 'Discard', exact: true }).click();
+        else await page.keyboard.press('Escape');
+        expect((await released).status()).toBe(200);
+        await expect(dialog(page)).toHaveCount(0);
+        expect(await stagesOf(request)).toBe(0);
+    }
+    const answer = await chooseBackup(page, bytes);
+    expect((await answer).status()).toBe(200);
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Restore preview');
+    expect(await stagesOf(request)).toBe(1);
+});
+
+test('× and leaving the section or the page discard the stage (M1)', async ({ page, request }) => {
+    const bytes = await backupBytes(request);
+    await openBackups(page);
+    const leaves = [
+        ['×', () => page.locator('#modal-close').click()],
+        // The modal covers the page, so the section changes as a link or the Back button changes it: by its hash.
+        ['section', () => page.evaluate(() => { window.location.hash = '#/system/maintenance'; })],
+        ['route', () => page.evaluate(() => { window.location.hash = '#/images'; })],
+    ];
+    for (const [name, leave] of leaves) {
+        if (!page.url().endsWith('#/system/backups')) {
+            await page.goto(`${workspace}#/system/backups`);
+            await expect(statusLine(page)).not.toHaveText('Checking backups…');
+        }
+        await chooseBackup(page, bytes);
+        await expect(dialog(page).locator('#modal-title')).toHaveText('Restore preview');
+        expect(await stagesOf(request), name).toBe(1);
+        // A keepalive DELETE (it may outlive the page) is asserted by its request and the server's stage count.
+        const released = page.waitForRequest(item => item.url().includes(`${PREVIEW_URL}/`) && item.method() === 'DELETE');
+        await leave();
+        await released;
+        await expect(dialog(page)).toHaveCount(0);
+        await expect.poll(() => stagesOf(request), { message: name }).toBe(0);
+    }
+});
+
+test('a safety backup file (no .db extension) can be picked and reviewed (M3)', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/safety-backup')).toBeOK();
+    const bytes = await backupBytes(request);
+    await openBackups(page);
+    // The picker lists every file; the server decides what is a database.
+    await expect(page.locator('#restore-file')).not.toHaveAttribute('accept', /./);
+    const answer = await chooseBackup(page, bytes, 'prompts.db.backup_20261025_093000_000000');
+    expect((await answer).status()).toBe(200);
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Restore preview');
+    expect((await gridOf(page))[0][1]).toMatch(/^prompts\.db\.backup_20261025_093000_000000 · \d+ KB · .+$/);
+});

tests/browser/workspace-system-integrations.spec.mjs

@@ -0,0 +1,432 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { seedConcept } from './concept-inventory.mjs';
+
+// System › Integrations (#249 System S10 Task 27) on the concept-shaped fixture with a fake LoraManager install
+// (workspace_integrations_fixture.py): the D106 ComfyUI rows and renderer status, the LoRA rows and the D114 key, saved
+// through the one Save row, and the D107 import review run as an Activity job. No test reaches the network: CivitAI
+// downloads are answered by the fixture's stub opener.
+const workspace = '/prompt_manager/workspace';
+const PREVIEW_URL = '/prompt_manager/lora/import/preview';
+const APPLY_URL = '/prompt_manager/lora/import/apply';
+const ENABLE_URL = '/prompt_manager/lora/enable';
+const KEPT = 'The import failed; the previous LoRA imports were kept. Images already downloaded stay in the image cache.';
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await seedConcept(request);
+    await expect(await request.post('/__test__/system/reset')).toBeOK();
+    await expect(await request.post('/__test__/integrations/reset')).toBeOK();
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    page.systemErrors = [];
+    page.on('pageerror', error => page.systemErrors.push(error.message));
+});
+
+test.afterEach(async ({ page, request, browserName }) => {
+    await saveCoverage(page, browserName);
+    await request.post('/__test__/integrations/gate', { data: { hold: false } });
+    await request.post('/__test__/release');
+    await request.post('/__test__/jobs/restart');
+    await request.post('/__test__/integrations/reset');
+    await request.post('/__test__/system/reset');
+    expect(page.systemErrors).toEqual([]);
+});
+
+const toast = page => page.locator('#workspace-toast');
+const layoutOf = page => page.locator('#workspace-main .settings-layout');
+const dialog = page => page.locator('dialog#modal[open]');
+const status = page => page.locator('#settings-status');
+const save = page => page.getByRole('button', { name: 'Save preferences', exact: true });
+const settingOf = (page, label) => layoutOf(page).locator('.setting-row').filter({ has: page.locator(`label:text-is("${label}")`) });
+
+async function serverJson(request, url) {
+    const response = await request.get(url);
+    await expect(response).toBeOK();
+    return response.json();
+}
+
+async function lora(request, data = {}) {
+    await expect(await request.post('/__test__/integrations/lora-manager', { data })).toBeOK();
+}
+
+async function openIntegrations(page) {
+    // A fresh page each time: the drafts live for the page session (Q10), and a hash-only goto would not reload.
+    if (page.url().endsWith('#/system/integrations')) await page.reload();
+    else await page.goto(`${workspace}#/system/integrations`);
+    await expect(layoutOf(page).locator(':scope > section.surface')).toHaveCount(2);
+    // The LoRA rows are painted once the server's LoRA state was read.
+    await expect(settingOf(page, 'LoraManager integration').locator('input')).toBeEnabled();
+    // The renderer line settles first: its new text moves the rows below, so no click lands mid-shift.
+    await expect(settingOf(page, 'Host compatibility').getByRole('status')).not.toHaveText('Looking for open ComfyUI windows…');
+    return layoutOf(page);
+}
+
+/** Enable the integration (and optionally its trigger words) through the Save row. */
+async function enable(page, { triggers = false } = {}) {
+    await settingOf(page, 'LoraManager integration').locator('input').check();
+    if (triggers) await settingOf(page, 'Automatically include trigger words').locator('input').check();
+    await save(page).click();
+    await expect(status(page)).toHaveText('Saved to the server configuration.');
+}
+
+/** The open review's `[dt, dd]` rows. */
+const gridOf = page => dialog(page).locator('dl.meta-grid > div').evaluateAll(items => items.map(item =>
+    [item.querySelector('dt').textContent, item.querySelector('dd').textContent]));
+
+async function ended(request, id) {
+    await expect.poll(async () => (await serverJson(request, `/prompt_manager/jobs/${id}`)).job.state).not.toBe('running');
+    return (await serverJson(request, `/prompt_manager/jobs/${id}`)).job;
+}
+
+/** A second page of this origin that serves a fake ComfyUI window on the send bridge. */
+async function fakeComfyWindow(context, renderer) {
+    const host = await context.newPage();
+    await host.goto(`${workspace}#/overview`);
+    await host.evaluate(async drawn => {
+        const { createBridgeHost } = await import('/prompt_manager/js/shared/toolkit/prompt-bridge.js');
+        window.fakeHost = createBridgeHost({ namespace: '/', origin: location.origin, label: 'PromptManager — ComfyUI',
+            adapter: { listTargets: () => (drawn ? [{ id: '7', label: 'Prompt Manager', type: 'PromptManager', roles: ['positive'],
+                renderer: drawn }] : []), preview() { throw new Error('unused'); }, apply() { throw new Error('unused'); } } });
+    }, renderer);
+    return host;
+}
+
+test('send destination offers Ask each time; unsupported options disabled with the reason (D106)', async ({ page }) => {
+    const layout = await openIntegrations(page);
+    expect(await layout.locator(':scope > section.surface > h2').allTextContents()).toEqual(['ComfyUI', 'LoRA & resources']);
+    const send = settingOf(page, 'Default send destination');
+    expect(await send.locator('option').evaluateAll(options => options.map(option => [option.textContent, option.disabled])))
+        .toEqual([['Ask each time', false], ['Selected Prompt Manager node', true], ['Create a Prompt Manager (+/-) node', true]]);
+    await expect(send.locator('select')).toHaveValue('Ask each time');
+    await expect(send.locator('p.small')).toHaveText(
+        'Sending always asks for the ComfyUI window and node, so “Ask each time” is the only option.');
+    const renderer = settingOf(page, 'Host compatibility');
+    expect(await renderer.locator('option').evaluateAll(options => options.map(option => [option.textContent, option.disabled])))
+        .toEqual([['Follow host renderer', false], ['Classic', true], ['Nodes 2.0', true]]);
+    await expect(renderer.locator('p.small').first()).toHaveText('Prompt Manager nodes always follow ComfyUI’s own renderer setting.');
+    const back = settingOf(page, 'Return to canvas after send');
+    await expect(back.locator('input')).toBeDisabled();
+    await expect(back.locator('input')).not.toBeChecked();
+    await expect(back.locator('p.small')).toHaveText('Not available: sending applies the text in ComfyUI and keeps this page open.');
+    // Nothing on this surface is ever drafted: the Save row stays clean.
+    await expect(status(page)).toHaveText('No unsaved changes.');
+    await expect(save(page)).toHaveAttribute('aria-disabled', 'true');
+});
+
+test('host compatibility shows the detected renderer as status (D106)', async ({ page, context }) => {
+    await openIntegrations(page);
+    const line = settingOf(page, 'Host compatibility').getByRole('status');
+    await expect(line).toHaveText('No ComfyUI window is open in this browser, so its renderer is not known.');
+    const host = await fakeComfyWindow(context, 'nodes2');
+    try {
+        await page.reload();
+        await expect(line).toHaveText('Detected: Nodes 2.0 (1 ComfyUI window).');
+        await host.evaluate(() => window.fakeHost.dispose());
+        await host.evaluate(async () => {
+            const { createBridgeHost } = await import('/prompt_manager/js/shared/toolkit/prompt-bridge.js');
+            window.fakeHost = createBridgeHost({ namespace: '/', origin: location.origin, label: 'PromptManager — ComfyUI',
+                adapter: { listTargets: () => [], preview() {}, apply() {} } });
+        });
+        await page.reload();
+        await expect(line).toHaveText('ComfyUI is open; add a Prompt Manager node to see which renderer it uses.');
+    } finally {
+        await host.close();
+    }
+});
+
+test('LoRA rows show detected / enabled / cache-loaded separately', async ({ page, request }) => {
+    await openIntegrations(page);
+    const integration = settingOf(page, 'LoraManager integration');
+    const triggers = settingOf(page, 'Automatically include trigger words');
+    await expect(integration.locator('p').first()).toHaveText('Not detected in ComfyUI’s custom_nodes folders.');
+    await expect(integration.locator('input')).not.toBeChecked();
+    await expect(triggers.locator('p.small')).toHaveText('Trigger words are not loaded.');
+    // Enabling what is not installed is refused by the server: the toggle stays highlighted, nothing was saved.
+    await integration.locator('input').check();
+    await save(page).click();
+    await expect(status(page)).toHaveText('Some changes were not saved. Review the highlighted settings.');
+    await expect(integration.locator('input')).toHaveAttribute('aria-invalid', 'true');
+    expect((await serverJson(request, '/__test__/integrations/state')).enabled).toBe(false);
+
+    await lora(request);
+    await openIntegrations(page);
+    await expect(integration.locator('p').first()).toHaveText('Detected: custom_nodes/ComfyUI-Lora-Manager.');
+    await expect(integration.locator('input')).not.toBeChecked();
+    await enable(page, { triggers: true });
+    await expect(integration.locator('input')).toBeChecked();
+    await expect(triggers.locator('p.small')).toHaveText('Trigger words are loaded.');
+    expect(await serverJson(request, '/__test__/integrations/state')).toMatchObject({ enabled: true, trigger_words: true });
+    // A reload reads the saved state back.
+    await openIntegrations(page);
+    await expect(integration.locator('input')).toBeChecked();
+    await expect(triggers.locator('input')).toBeChecked();
+    await expect(status(page)).toHaveText('No unsaved changes.');
+});
+
+test('LoraManager path row shows the detected path read-only, as legacy (D106)', async ({ page, request }) => {
+    await openIntegrations(page);
+    const row = settingOf(page, 'LoraManager path');
+    const input = row.locator('input');
+    await expect(input).toHaveAttribute('readonly', '');
+    await expect(input).toHaveValue('');
+    await expect(input).toHaveAttribute('placeholder', 'Not detected');
+    await lora(request);
+    await openIntegrations(page);
+    await expect(input).toHaveValue('custom_nodes/ComfyUI-Lora-Manager');
+    await input.focus();
+    await page.keyboard.type('elsewhere');
+    await expect(input).toHaveValue('custom_nodes/ComfyUI-Lora-Manager');
+    await expect(status(page)).toHaveText('No unsaved changes.');
+});
+
+test('key never prefilled; blank keeps; Clear saved key clears; saved through Save preferences (D114)', async ({ page, request }) => {
+    const enables = [];
+    page.on('request', item => { if (item.url().endsWith(ENABLE_URL)) enables.push(item.postDataJSON()); });
+    await lora(request);
+    await openIntegrations(page);
+    const key = settingOf(page, 'CivitAI API key');
+    const field = key.locator('input[type="password"]');
+    const clear = key.getByRole('button', { name: 'Clear saved key', exact: true });
+    await expect(field).toHaveValue('');
+    await expect(key.locator('p.small')).toHaveText('No key saved.');
+    await expect(clear).toHaveCount(0);
+    // A typed key is dropped when the section is left: the field comes back empty with nothing hidden to save (N4).
+    await field.fill('sk-dropped');
+    await expect(status(page)).toHaveText('Unsaved changes.');
+    await page.locator('#workspace-main .section-nav').getByRole('button', { name: 'Appearance', exact: true }).click();
+    await page.locator('#workspace-main .section-nav').getByRole('button', { name: 'Integrations', exact: true }).click();
+    await expect(status(page)).toHaveText('No unsaved changes.');
+    await expect(key.locator('p.small')).toHaveText('No key saved.');
+    // Typing a key drafts it; Save sends it once through /lora/enable with the settings revision.
+    await field.fill('sk-test-key');
+    await expect(key.locator('p.small')).toHaveText('The new key replaces the saved one when you save.');
+    await expect(status(page)).toHaveText('Unsaved changes.');
+    await save(page).click();
+    await expect(status(page)).toHaveText('Saved to the server configuration.');
+    expect(enables).toHaveLength(1);
+    expect(enables[0]).toMatchObject({ civitai_api_key: 'sk-test-key', enabled: false });
+    expect(enables[0].expected_revision).toMatch(/^(sha256:|absent)/);
+    await expect(field).toHaveValue('');
+    await expect(key.locator('p.small')).toHaveText('A key is saved.');
+    expect((await serverJson(request, '/__test__/integrations/state')).key_saved).toBe(true);
+    // Never prefilled, even after a reload; the page never receives the key.
+    const statusBodies = [];
+    page.on('response', async response => {
+        if (response.url().endsWith('/prompt_manager/lora/status')) statusBodies.push(await response.text());
+    });
+    await openIntegrations(page);
+    await expect(field).toHaveValue('');
+    await expect(key.locator('p.small')).toHaveText('A key is saved.');
+    expect(statusBodies.join('')).not.toContain('sk-test-key');
+    // The announced line is rewritten only when its text changes, not on every edit elsewhere (S10 re-review N8).
+    await page.evaluate(() => {
+        window.__keyNoteWrites = 0;
+        new MutationObserver(records => { window.__keyNoteWrites += records.length; })
+            .observe(document.querySelector('#civitai-key-status'), { childList: true, characterData: true, subtree: true });
+    });
+    const triggers = settingOf(page, 'Automatically include trigger words').locator('input');
+    await triggers.check();
+    await expect(status(page)).toHaveText('Unsaved changes.');
+    await triggers.uncheck();
+    await expect(status(page)).toHaveText('No unsaved changes.');
+    expect(await page.evaluate(() => window.__keyNoteWrites)).toBe(0);
+    // A blank field keeps the saved key: nothing to save.
+    await field.fill('   ');
+    await expect(status(page)).toHaveText('No unsaved changes.');
+    await field.fill('');
+    // Clear saved key drafts the removal; Save removes it. The keyboard stays on the key field, and the line that
+    // says so is announced (S10 review M2).
+    await expect(key.locator('p.small')).toHaveAttribute('role', 'status');
+    await expect(field).toHaveAttribute('aria-describedby', 'civitai-key-status');
+    await clear.focus();
+    await page.keyboard.press('Enter');
+    await expect(key.locator('p.small')).toHaveText('The saved key is removed when you save.');
+    await expect(clear).toHaveCount(0);
+    await expect(field).toBeFocused();
+    await save(page).click();
+    await expect(status(page)).toHaveText('Saved to the server configuration.');
+    expect(enables.at(-1)).toMatchObject({ clear_civitai_api_key: true });
+    expect(enables.at(-1)).not.toHaveProperty('civitai_api_key');
+    await expect(key.locator('p.small')).toHaveText('No key saved.');
+    expect((await serverJson(request, '/__test__/integrations/state')).key_saved).toBe(false);
+});
+
+test('a LoRA save over settings changed elsewhere is a conflict, never a blind write', async ({ page, request }) => {
+    await lora(request);
+    await openIntegrations(page);
+    await settingOf(page, 'Automatically include trigger words').locator('input').check();
+    // Another page saves the settings meanwhile: the revision this page read is stale.
+    await expect(await request.post('/prompt_manager/settings', { data: { result_timeout: 42 } })).toBeOK();
+    await save(page).click();
+    await expect(status(page)).toHaveText('Settings changed elsewhere. Reload this section to see them.');
+    expect((await serverJson(request, '/__test__/integrations/state')).trigger_words).toBe(false);
+    // The draft stays; the next Save carries the reread revision and succeeds.
+    await save(page).click();
+    await expect(status(page)).toHaveText('Saved to the server configuration.');
+    expect((await serverJson(request, '/__test__/integrations/state')).trigger_words).toBe(true);
+});
+
+test('a save where only the LoRA part is written says so; the next save needs no conflict (S10 review I3)',
+    async ({ page, request }) => {
+        await lora(request);
+        await expect(await request.post('/__test__/system/missing-source', { data: { inside: true } })).toBeOK();
+        await openIntegrations(page);
+        const triggers = settingOf(page, 'Automatically include trigger words').locator('input');
+        await triggers.check();
+        // In Sources, the drive is unplugged after the page read the list, and another source is removed.
+        const nav = page.locator('#workspace-main .section-nav');
+        await nav.getByRole('button', { name: 'Sources & scans', exact: true }).click();
+        const sourceRow = title => layoutOf(page).locator('#source-list .operation').filter({ has: page.locator('h3', { hasText: title }) });
+        await expect(sourceRow('unplugged')).toBeVisible();
+        await expect(await request.post('/__test__/system/unplug')).toBeOK();
+        await sourceRow('ComfyUI input').getByRole('button', { name: 'Remove', exact: true }).click();
+        await save(page).click();
+        // The LoRA part was saved, the sources were refused: the status gives the server's reason for the source, and
+        // only the source row is highlighted.
+        await expect(status(page)).toHaveText("output/unplugged can't be used: Gallery root does not exist. Remove it or reconnect it, then save.");
+        await expect(sourceRow('unplugged')).toHaveAttribute('aria-invalid', 'true');
+        expect((await serverJson(request, '/__test__/integrations/state')).trigger_words).toBe(true);
+        await nav.getByRole('button', { name: 'Integrations', exact: true }).click();
+        await expect(triggers).toBeChecked();
+        await expect(triggers).not.toHaveAttribute('aria-invalid', 'true');
+        // The next save carries the revision the saved part left: it saves, with no "changed elsewhere".
+        await nav.getByRole('button', { name: 'Sources & scans', exact: true }).click();
+        await sourceRow('unplugged').getByRole('button', { name: 'Remove', exact: true }).click();
+        await save(page).click();
+        await expect(status(page)).toHaveText('Saved to the server configuration.');
+        expect((await serverJson(request, '/prompt_manager/settings')).sources.configured.map(source => source.path)).toEqual(['output']);
+    });
+
+test('a partial save made from Integrations keeps its outcome when Sources opens (S10 re-review R1)',
+    async ({ page, request }) => {
+        await lora(request);
+        await expect(await request.post('/__test__/system/missing-source', { data: { inside: true } })).toBeOK();
+        await openIntegrations(page);
+        const nav = page.locator('#workspace-main .section-nav');
+        const sourceRow = title => layoutOf(page).locator('#source-list .operation').filter({ has: page.locator('h3', { hasText: title }) });
+        await nav.getByRole('button', { name: 'Sources & scans', exact: true }).click();
+        await expect(sourceRow('unplugged')).toBeVisible();
+        await expect(await request.post('/__test__/system/unplug')).toBeOK();
+        await sourceRow('ComfyUI input').getByRole('button', { name: 'Remove', exact: true }).click();
+        // Back in Integrations, a LoRA change, then Save from there.
+        await nav.getByRole('button', { name: 'Integrations', exact: true }).click();
+        await settingOf(page, 'Automatically include trigger words').locator('input').check();
+        await save(page).click();
+        const reason = "output/unplugged can't be used: Gallery root does not exist. Remove it or reconnect it, then save.";
+        await expect(status(page)).toHaveText(reason);
+        // Leaving Integrations (no key was typed) keeps the outcome: Sources shows the reason on the refused row.
+        await nav.getByRole('button', { name: 'Sources & scans', exact: true }).click();
+        await expect(sourceRow('unplugged')).toHaveAttribute('aria-invalid', 'true');
+        await expect(status(page)).toHaveText(reason);
+    });
+
+test('Review import shows replacement, blocked items and network effects with the backup box; Start opens the job (D107)',
+    async ({ page, request }) => {
+        await lora(request, { loras: 3, civitai: true, previous: 2 });
+        const previews = [];
+        const applies = [];
+        page.on('request', item => {
+            if (item.url().endsWith(PREVIEW_URL)) previews.push(item.postDataJSON());
+            if (item.url().endsWith(APPLY_URL)) applies.push(item.postDataJSON());
+        });
+        await openIntegrations(page);
+        await enable(page);
+        const before = await serverJson(request, '/__test__/integrations/state');
+        const review = layoutOf(page).locator('.operation').filter({ hasText: 'LoRA reference data' })
+            .getByRole('button', { name: 'Review import', exact: true });
+        await review.click();
+        await expect(dialog(page).locator('#modal-title')).toHaveText('Review LoRA import');
+        await expect(dialog(page).locator('#modal-body > h3')).toHaveText('LoRA reference data');
+        expect(previews).toEqual([{}]);
+        expect(await gridOf(page)).toEqual([
+            ['Scope', 'Replace 2 imported prompts with 3 LoRAs'],
+            ['Found', '3 metadata files · 3 readable'],
+            ['Protected', 'Nothing is protected'],
+            ['Network', 'Downloads up to 3 example images from CivitAI'],
+            ['Backup', 'Create and verify before changes (browser.db.backup_<date and time>)'],
+            ['Media on disk', 'No files are removed; image links are replaced'],
+        ]);
+        await expect(dialog(page).locator('details > summary')).toHaveText('LoRAs found (3)');
+        await expect(dialog(page).locator('.notice h3')).toHaveText('Back up the database first (recommended)');
+        await expect(dialog(page).locator('p.small').last()).toContainText('stay in the image cache');
+        // The review wrote and downloaded nothing; Cancel neither.
+        await dialog(page).getByRole('button', { name: 'Cancel', exact: true }).click();
+        await expect(dialog(page)).toHaveCount(0);
+        await expect(review).toBeFocused();
+        expect(await serverJson(request, '/__test__/integrations/state')).toEqual(before);
+
+        await review.click();
+        await dialog(page).getByRole('button', { name: 'Start import', exact: true }).click();
+        await expect(dialog(page)).toHaveCount(0);
+        await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+        await expect(toast(page)).toHaveText(/LoRA reference import started\.|LoRA import finished · 3 imported · 0 errors/);
+        expect(applies).toHaveLength(1);
+        expect(Object.keys(applies[0])).toEqual(['token']);
+        const job = await ended(request, page.url().split('/').pop());
+        expect([job.kind, job.title, job.state]).toEqual(['lora_import', 'LoRA reference import', 'finished']);
+        expect(job.counters).toMatchObject({ imported: 3, downloaded: 3, download_errors: 0, errors: 0 });
+        const main = page.locator('#workspace-main');
+        await expect(main.locator('h1')).toHaveText('LoRA reference import');
+        await expect(main.locator('.stat-row .stat dt')).toHaveText(['Imported', 'Linked to existing', 'Skipped', 'Images downloaded',
+            'Download errors', 'Errors']);
+        await expect(main.getByRole('button', { name: 'Cancel import', exact: true })).toHaveCount(0);
+        const after = await serverJson(request, '/__test__/integrations/state');
+        expect(after.imports).toEqual(['style_01 example prompt', 'style_02 example prompt', 'style_03 example prompt']);
+        expect(after.downloads).toBe(3);
+    });
+
+test('saved pairs block the import: the review explains it and offers only Close', async ({ page, request }) => {
+    await lora(request, { previous: 1 });
+    await expect(await request.post('/__test__/integrations/pair')).toBeOK();
+    await openIntegrations(page);
+    await enable(page);
+    await layoutOf(page).getByRole('button', { name: 'Review import', exact: true }).click();
+    expect((await gridOf(page))[2]).toEqual(['Protected', '1 imported prompt used by saved pairs']);
+    await expect(dialog(page).locator('p.small')).toHaveText(
+        'Delete or change the saved pairs that use these prompts, then review the import again. Nothing was changed.');
+    expect(await dialog(page).locator('.dialog-actions button').allTextContents()).toEqual(['Close']);
+    await dialog(page).getByRole('button', { name: 'Close', exact: true }).click();
+    await expect(dialog(page)).toHaveCount(0);
+});
+
+test('a failed import keeps old imports and its job says so', async ({ page, request }) => {
+    await lora(request, { loras: 2, previous: 2 });
+    await openIntegrations(page);
+    await enable(page);
+    const before = await serverJson(request, '/__test__/integrations/state');
+    await expect(await request.post('/__test__/integrations/fail-import')).toBeOK();
+    await layoutOf(page).getByRole('button', { name: 'Review import', exact: true }).click();
+    await dialog(page).getByRole('button', { name: 'Start import', exact: true }).click();
+    await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+    await expect(toast(page)).toHaveText(`LoRA import failed · ${KEPT}`);
+    const job = await ended(request, page.url().split('/').pop());
+    expect([job.state, job.scope.failure, job.counters.errors]).toEqual(['failed', 'import-failed', 1]);
+    await expect(page.locator('#workspace-main')).toContainText(KEPT);
+    expect((await serverJson(request, '/__test__/integrations/state')).imports).toEqual(before.imports);
+    expect(before.imports).toEqual(['previous lora import 1', 'previous lora import 2']);
+});
+
+test('the import can be cancelled while it downloads; then nothing is written', async ({ page, request }) => {
+    await lora(request, { loras: 2, civitai: true, previous: 1 });
+    await openIntegrations(page);
+    await enable(page);
+    const before = await serverJson(request, '/__test__/integrations/state');
+    await expect(await request.post('/__test__/integrations/gate', { data: { hold: true } })).toBeOK();
+    await layoutOf(page).getByRole('button', { name: 'Review import', exact: true }).click();
+    await dialog(page).getByRole('button', { name: 'Start import', exact: true }).click();
+    await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+    const id = page.url().split('/').pop();
+    await expect.poll(async () => (await serverJson(request, '/__test__/integrations/state')).downloads).toBeGreaterThan(0);
+    const cancel = page.locator('#workspace-main').getByRole('button', { name: 'Cancel import', exact: true });
+    await expect(cancel).toBeVisible();
+    // The cancel must have reached the server before the held download goes on (S10 review M1).
+    await Promise.all([
+        page.waitForResponse(response => /\/prompt_manager\/jobs\/[0-9a-f]+\/cancel$/.test(response.url()) && response.ok()),
+        cancel.click(),
+    ]);
+    await expect(await request.post('/__test__/integrations/gate', { data: { hold: false } })).toBeOK();
+    const job = await ended(request, id);
+    expect(job.state).toBe('cancelled');
+    expect((await serverJson(request, '/__test__/integrations/state')).imports).toEqual(before.imports);
+    await expect(cancel).toHaveCount(0);
+});

tests/browser/workspace-system-maintenance.spec.mjs

@@ -0,0 +1,483 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { seedConcept } from './concept-inventory.mjs';
+
+// System › Maintenance (#249 System S7 Task 19) on the concept-shaped real fixture and the S6 backend: the concept's
+// rows, the read-only health check, the D100 plan review applied as an Activity job, the D101 duplicate search and
+// review, the S5 thumbnail dialog and the D102 metadata cache row. The hooks are workspace_system_fixture.py's.
+const workspace = '/prompt_manager/workspace';
+const PREVIEW_URL = '/prompt_manager/maintenance/preview';
+const APPLY_URL = '/prompt_manager/maintenance/apply';
+const CHANGED = 'The library changed since the review; nothing was changed. Review the plan again.';
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await seedConcept(request);
+    await expect(await request.post('/__test__/system/reset')).toBeOK();
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    page.systemErrors = [];
+    page.on('pageerror', error => page.systemErrors.push(error.message));
+});
+
+test.afterEach(async ({ page, request, browserName }) => {
+    await saveCoverage(page, browserName);
+    await request.post('/__test__/release');
+    await request.post('/__test__/jobs/restart');
+    await request.post('/__test__/system/reset');
+    expect(page.systemErrors).toEqual([]);
+});
+
+const toast = page => page.locator('#workspace-toast');
+const layoutOf = page => page.locator('#workspace-main .settings-layout');
+const dialog = page => page.locator('dialog#modal[open]');
+const row = (page, title) => layoutOf(page).locator('.operation').filter({ has: page.locator('h3', { hasText: title }) });
+
+async function serverJson(request, url) {
+    const response = await request.get(url);
+    await expect(response).toBeOK();
+    return response.json();
+}
+
+async function openMaintenance(page) {
+    await page.goto(`${workspace}#/system/maintenance`);
+    await expect(layoutOf(page).locator(':scope > section.surface')).toHaveCount(2);
+    return layoutOf(page);
+}
+
+/** The open plan dialog's `[dt, dd]` rows. */
+const gridOf = page => dialog(page).locator('dl.meta-grid > div').evaluateAll(items => items.map(item =>
+    [item.querySelector('dt').textContent, item.querySelector('dd').textContent]));
+
+/** Wait until the job `id` ended on the server; answers its summary. */
+async function ended(request, id) {
+    await expect.poll(async () => (await serverJson(request, `/prompt_manager/jobs/${id}`)).job.state).not.toBe('running');
+    return (await serverJson(request, `/prompt_manager/jobs/${id}`)).job;
+}
+
+test('the section shows the concept rows; Metadata cache follows Q5 (D102)', async ({ page }) => {
+    const layout = await openMaintenance(page);
+    await expect(layout.locator(':scope > .notice h2')).toHaveText('Check first. Review changes. Then apply.');
+    await expect(layout.locator(':scope > section.handoff')).toHaveCount(0);
+    expect(await layout.locator(':scope > section.surface').evaluateAll(surfaces => surfaces.map(surface => [
+        surface.querySelector('h2').textContent,
+        [...surface.querySelectorAll('.operation')].map(item => [item.querySelector('h3').textContent,
+            item.querySelector('.row-actions > button').textContent, item.querySelector('.row-actions > button').className]),
+    ]))).toEqual([
+        ['Database', [['Integrity & relationship checks', 'Check', ''], ['Duplicate prompt text', 'Review plan', ''],
+            ['Optimize database', 'Review plan', ''], ['Unused prompt components', 'Review plan', 'danger']]],
+        ['Images & cache', [['Missing-file links', 'Review plan', 'danger'], ['Duplicate image files', 'Find duplicates', ''],
+            ['Thumbnail cache', 'Review options', ''], ['Metadata cache', 'Review plan', '']]],
+    ]);
+    // Nothing of Prompt Manager's is cached in a browser (#222): the row says so and its review is unavailable.
+    const cache = row(page, 'Metadata cache');
+    await expect(cache.locator('p')).toHaveText('Clear only Prompt Manager metadata cached by this browser. Nothing is cached in this browser.');
+    const review = cache.getByRole('button', { name: 'Review plan', exact: true });
+    await expect(review).toHaveAttribute('aria-disabled', 'true');
+    // An aria-disabled button stays focusable and clickable; its press opens nothing.
+    await review.dispatchEvent('click');
+    await expect(review).toHaveAttribute('aria-disabled', 'true');
+    await expect(dialog(page)).toHaveCount(0);
+});
+
+test('Metadata cache reviews and clears only owned browser entries when there are some (D102)', async ({ page }) => {
+    // The shipped inventory is empty (#222); this test names one owned entry through the module's inventory seam.
+    await page.addInitScript(() => {
+        localStorage.setItem('pm-owned-test-entry', 'cached');
+        localStorage.setItem('pm_workspace_theme', 'dark');
+        let wrapped;
+        Object.defineProperty(window, 'CacheOwnership', { configurable: true, get: () => wrapped, set(api) {
+            const owned = { storageKeys: ['pm-owned-test-entry'], cacheNames: [] };
+            wrapped = { ...api, ownedEntries: options => api.ownedEntries({ ...options, owned }),
+                clearOwned: options => api.clearOwned({ ...options, owned }) };
+        } });
+    });
+    await openMaintenance(page);
+    const cache = row(page, 'Metadata cache');
+    const review = cache.getByRole('button', { name: 'Review plan', exact: true });
+    await expect(review).not.toHaveAttribute('aria-disabled', 'true');
+    await expect(cache.locator('p')).toHaveText('Clear only Prompt Manager metadata cached by this browser.');
+    await review.click();
+    await expect(dialog(page).locator('#modal-body > h3')).toHaveText('Metadata cache');
+    expect(await gridOf(page)).toEqual([['Scope', '1 cached entry in this browser'],
+        ['Protected', 'Preferences and other tools’ data in this browser'], ['Backup', 'Not needed: the database is not changed'],
+        ['Media on disk', 'No files are removed']]);
+    await dialog(page).getByRole('button', { name: 'Clear browser cache', exact: true }).click();
+    await expect(toast(page)).toHaveText('Cleared 1 cached entry from this browser.');
+    await expect(review).toHaveAttribute('aria-disabled', 'true');
+    expect(await page.evaluate(() => [localStorage.getItem('pm-owned-test-entry'), localStorage.getItem('pm_workspace_theme')]))
+        .toEqual([null, 'dark']);
+});
+
+test('Run health checks and Check open the Health report; Review missing links starts a fresh preview, never a cleanup',
+    async ({ page, request }) => {
+        await expect(await request.post('/__test__/system/missing-file')).toBeOK();
+        const before = await serverJson(request, '/__test__/system/digest');
+        const previews = [];
+        page.on('request', item => { if (item.url().endsWith(PREVIEW_URL)) previews.push(item.postDataJSON()); });
+        await openMaintenance(page);
+        const check = row(page, 'Integrity & relationship checks').getByRole('button', { name: 'Check', exact: true });
+        await check.click();
+        await expect(dialog(page).locator('#modal-title')).toHaveText('Health report');
+        await expect(dialog(page).locator('.operation').filter({ hasText: 'Missing files · output' }).locator('.chip'))
+            .toHaveText('1 link needs review');
+        await expect(check).toHaveText('Check');
+        await dialog(page).getByRole('button', { name: 'Review missing links', exact: true }).click();
+        await expect(dialog(page).locator('#modal-title')).toHaveText('Review maintenance plan');
+        await expect(dialog(page).locator('#modal-body > h3')).toHaveText('Missing-file links');
+        expect(previews).toEqual([{ operation: 'missing_links', options: {} }]);
+        expect((await gridOf(page))[0]).toEqual(['Scope', '1 link to a missing file']);
+        await dialog(page).getByRole('button', { name: 'Cancel', exact: true }).click();
+        await expect(dialog(page)).toHaveCount(0);
+        await expect(check).toBeFocused();
+        // The notice's Run health checks opens the same report.
+        await layoutOf(page).getByRole('button', { name: 'Run health checks', exact: true }).click();
+        await expect(dialog(page).locator('#modal-title')).toHaveText('Health report');
+        expect(await serverJson(request, '/__test__/system/digest')).toEqual(before);
+    });
+
+test("plan dialog shows the server's scope, protected, backup policy and media lines with the backup box (D100); Cancel writes nothing",
+    async ({ page, request }) => {
+        await expect(await request.post('/__test__/system/duplicate-prompts')).toBeOK();
+        const before = await serverJson(request, '/__test__/system/digest');
+        const answers = [];
+        page.on('response', response => { if (response.url().endsWith(PREVIEW_URL)) answers.push(response.json()); });
+        await openMaintenance(page);
+        const reviewButton = row(page, 'Duplicate prompt text').getByRole('button', { name: 'Review plan', exact: true });
+        await reviewButton.click();
+        const plan = dialog(page);
+        await expect(plan.locator('#modal-title')).toHaveText('Review maintenance plan');
+        const answer = await answers[0];
+        expect(answer.scope.count).toBe(1);
+        await expect(plan.locator('#modal-body > h3')).toHaveText('Duplicate prompt text');
+        expect(await gridOf(page)).toEqual([
+            ['Scope', answer.scope.label],
+            ['Protected', answer.protected.reasons.length ? answer.protected.reasons.join(' · ') : 'Nothing is protected'],
+            ['Backup', `Create and verify before changes (${answer.backup.destination_label})`],
+            ['Media on disk', answer.media.label],
+        ]);
+        expect(await plan.locator('#modal-body').evaluate(body => [...body.children].map(node =>
+            [node.localName, ...node.classList].join('.')))).toEqual(['h3', 'dl.meta-grid', 'details', 'p.small', 'div.notice',
+            'div.dialog-actions']);
+        await expect(plan.locator('details > summary')).toHaveText('Listed records (1)');
+        await expect(plan.locator('#modal-body > p.small')).toHaveText(/^Nothing changes until you apply\. This review holds for 1[45] minutes\.$/);
+        await expect(plan.locator('.notice h3')).toHaveText('Back up the database first (recommended)');
+        await expect(plan.locator('.dialog-actions button')).toHaveText(['Cancel', 'Apply reviewed operation']);
+        await plan.getByRole('button', { name: 'Cancel', exact: true }).click();
+        await expect(dialog(page)).toHaveCount(0);
+        await expect(reviewButton).toBeFocused();
+        // Optimize and Unused prompt components are reviewed the same way.
+        for (const [title, scope] of [['Optimize database', 'The whole database'], ['Unused prompt components', null]]) {
+            await row(page, title).getByRole('button', { name: 'Review plan', exact: true }).click();
+            await expect(dialog(page).locator('#modal-body > h3')).toHaveText(title);
+            const value = (await answers.at(-1)).scope.label;
+            expect((await gridOf(page))[0]).toEqual(['Scope', scope ?? value]);
+            await page.keyboard.press('Escape');
+            await expect(dialog(page)).toHaveCount(0);
+        }
+        expect(await serverJson(request, '/__test__/system/digest')).toEqual(before);
+    });
+
+test('a plan with nothing to do shows only Close, never Apply', async ({ page, request }) => {
+    const applies = [];
+    page.on('request', item => { if (item.url().endsWith(APPLY_URL)) applies.push(item.url()); });
+    await openMaintenance(page);
+    // The concept fixture has no duplicate prompt text.
+    const reviewButton = row(page, 'Duplicate prompt text').getByRole('button', { name: 'Review plan', exact: true });
+    await reviewButton.click();
+    await expect(dialog(page).locator('#modal-body > h3')).toHaveText('Duplicate prompt text');
+    expect((await gridOf(page))[0]).toEqual(['Scope', 'No duplicate prompt text']);
+    await expect(dialog(page).locator('#modal-body > p.small')).toHaveText('There is nothing to apply; nothing was changed.');
+    await expect(dialog(page).locator('.dialog-actions button')).toHaveText(['Close']);
+    await expect(dialog(page).locator('.notice')).toHaveCount(0);
+    await dialog(page).getByRole('button', { name: 'Close', exact: true }).click();
+    await expect(dialog(page)).toHaveCount(0);
+    await expect(reviewButton).toBeFocused();
+    expect(applies).toEqual([]);
+});
+
+test('Apply reviewed operation closes, toasts, opens the job in Activity', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/duplicate-prompts')).toBeOK();
+    const applies = [];
+    page.on('request', item => { if (item.url().endsWith(APPLY_URL)) applies.push(item.postDataJSON()); });
+    await openMaintenance(page);
+    await row(page, 'Duplicate prompt text').getByRole('button', { name: 'Review plan', exact: true }).click();
+    await dialog(page).getByRole('button', { name: 'Apply reviewed operation', exact: true }).click();
+    await expect(dialog(page)).toHaveCount(0);
+    await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+    await expect(toast(page)).toHaveText(/Duplicate prompt text (started|finished · 1 changed)/);
+    expect(applies).toHaveLength(1);
+    expect(Object.keys(applies[0])).toEqual(['token']);
+    const job = await ended(request, page.url().split('/').pop());
+    expect([job.kind, job.state, job.counters.changed]).toEqual(['maintenance', 'finished', 1]);
+    const main = page.locator('#workspace-main');
+    await expect(main.locator('h1')).toHaveText('Duplicate prompt text');
+    await expect(main.locator('.stat-row .stat dt')).toHaveText(['Changed', 'Protected', 'Errors']);
+    await expect(main.locator('.stat-row .stat dd').first()).toHaveText('1');
+    // Not cancellable: no Cancel, a report like every job.
+    await expect(main.getByRole('button', { name: 'Cancel job', exact: true })).toHaveCount(0);
+    await expect(main.getByRole('button', { name: 'Download report', exact: true })).toBeVisible();
+});
+
+test('plan-changed asks for a new review', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/duplicate-prompts')).toBeOK();
+    await openMaintenance(page);
+    await row(page, 'Duplicate prompt text').getByRole('button', { name: 'Review plan', exact: true }).click();
+    await expect(dialog(page).locator('#modal-body > h3')).toHaveText('Duplicate prompt text');
+    // The library changes after the review: the apply's recheck refuses it and nothing is changed.
+    await expect(await request.post('/__test__/system/duplicate-prompts', { data: { again: true } })).toBeOK();
+    const before = await serverJson(request, '/__test__/system/digest');
+    await dialog(page).getByRole('button', { name: 'Apply reviewed operation', exact: true }).click();
+    await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+    await expect(toast(page)).toHaveText(`Duplicate prompt text failed · ${CHANGED}`);
+    await expect(page.locator('#workspace-main')).toContainText(CHANGED);
+    expect((await serverJson(request, '/__test__/system/digest')).rows).toEqual(before.rows);
+    // S7 review M2: the failed job offers Review again, which reviews the same operation afresh.
+    const previews = [];
+    page.on('request', item => { if (item.url().endsWith(PREVIEW_URL)) previews.push(item.postDataJSON()); });
+    await page.locator('#workspace-main').getByRole('button', { name: 'Review again', exact: true }).click();
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Review maintenance plan');
+    await expect(dialog(page).locator('#modal-body > h3')).toHaveText('Duplicate prompt text');
+    expect(previews).toEqual([{ operation: 'duplicate_prompts', options: {} }]);
+});
+
+test('a review button pressed twice sends one preview (S7 review M4)', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/missing-file')).toBeOK();
+    await expect(await request.post('/__test__/system/duplicate-files')).toBeOK();
+    const previews = [];
+    page.on('request', item => { if (item.url().endsWith(PREVIEW_URL)) previews.push(item.postDataJSON().operation); });
+    await openMaintenance(page);
+    await row(page, 'Integrity & relationship checks').getByRole('button', { name: 'Check', exact: true }).click();
+    // Hold the preview at the server so the second press lands while it is read.
+    await expect(await request.post('/__test__/hold', { data: { path: PREVIEW_URL } })).toBeOK();
+    // The pressed button reads "Reviewing…" while held, so it is found by its place, not its name.
+    const missing = dialog(page).locator('.dialog-actions > button').last();
+    await expect(missing).toHaveText('Review missing links');
+    await missing.click();
+    await expect(missing).toHaveAttribute('aria-disabled', 'true');
+    await expect(missing).toHaveText('Reviewing…');
+    await missing.dispatchEvent('click');
+    await expect.poll(async () => (await serverJson(request, '/__test__/hold')).held[PREVIEW_URL]).toBe(1);
+    await expect(await request.post('/__test__/release')).toBeOK();
+    await expect(dialog(page).locator('#modal-body > h3')).toHaveText('Missing-file links');
+    expect(previews).toEqual(['missing_links']);
+    await page.keyboard.press('Escape');
+
+    await row(page, 'Duplicate image files').getByRole('button', { name: 'Find duplicates', exact: true }).click();
+    await page.locator('#workspace-main').getByRole('button', { name: 'Review groups', exact: true }).click();
+    await expect(await request.post('/__test__/hold', { data: { path: PREVIEW_URL } })).toBeOK();
+    const cleanup = dialog(page).locator('.dialog-actions > button').last();
+    await expect(cleanup).toHaveText('Review duplicate cleanup');
+    await cleanup.click();
+    await expect(cleanup).toHaveAttribute('aria-disabled', 'true');
+    await cleanup.dispatchEvent('click');
+    await expect.poll(async () => (await serverJson(request, '/__test__/hold')).held[PREVIEW_URL]).toBe(1);
+    await expect(await request.post('/__test__/release')).toBeOK();
+    await expect(dialog(page).locator('#modal-body > h3')).toHaveText('Duplicate image files');
+    expect(previews).toEqual(['missing_links', 'duplicate_files']);
+});
+
+test('plan-used links the job that applied it', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/duplicate-prompts')).toBeOK();
+    // A double-submitted apply: the first request applies the plan, the second one's answer reaches the page.
+    await page.route(`**${APPLY_URL}`, async route => {
+        await route.fetch();
+        await route.fulfill({ response: await route.fetch() });
+    });
+    await openMaintenance(page);
+    await row(page, 'Duplicate prompt text').getByRole('button', { name: 'Review plan', exact: true }).click();
+    await dialog(page).getByRole('button', { name: 'Apply reviewed operation', exact: true }).click();
+    await expect(toast(page)).toHaveText('This plan was already applied: Duplicate prompt text.');
+    const link = toast(page).getByRole('link', { name: 'Duplicate prompt text', exact: true });
+    const { jobs } = await serverJson(request, '/prompt_manager/jobs');
+    const applied = jobs.find(job => job.kind === 'maintenance');
+    await expect(link).toHaveAttribute('href', `#/activity/${applied.id}`);
+    await expect(page).toHaveURL(`${workspace}#/system/maintenance`);
+});
+
+/**
+ * Record every toast the page shows (`[text, [link hrefs]]`): a job's finish toast may replace an earlier one before a
+ * test reads it.
+ */
+async function recordToasts(page) {
+    await page.addInitScript(() => {
+        window.toastLog = [];
+        const record = node => window.toastLog.push([node.textContent, [...node.querySelectorAll('a')].map(a => a.getAttribute('href'))]);
+        new MutationObserver(() => {
+            const node = document.getElementById('workspace-toast');
+            const last = window.toastLog.at(-1);
+            if (node && node.textContent && last?.[0] !== node.textContent) record(node);
+        }).observe(document, { subtree: true, childList: true, characterData: true });
+    });
+    return () => page.evaluate(() => window.toastLog);
+}
+
+const NOT_CONFIRMED = ['Outcome not confirmed. Check Activity before applying it again.', ['#/activity']];
+
+/** The maintenance jobs the server lists (the apply ran even though its answer was lost). */
+async function maintenanceJobs(request) {
+    return (await serverJson(request, '/prompt_manager/jobs')).jobs.filter(job => job.kind === 'maintenance');
+}
+
+test('lost apply response says Outcome not confirmed and points to Activity', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/duplicate-prompts')).toBeOK();
+    // The server applies the plan; its answer never reaches the page.
+    const reads = [];
+    await page.route(`**${APPLY_URL}`, async route => {
+        await route.fetch();
+        page.on('request', item => { if (item.url().endsWith('/prompt_manager/jobs')) reads.push(item.url()); });
+        await route.abort('failed');
+    });
+    const toasts = await recordToasts(page);
+    await openMaintenance(page);
+    await row(page, 'Duplicate prompt text').getByRole('button', { name: 'Review plan', exact: true }).click();
+    await dialog(page).getByRole('button', { name: 'Apply reviewed operation', exact: true }).click();
+    await expect.poll(toasts).toContainEqual(NOT_CONFIRMED);
+    await expect(page).toHaveURL(`${workspace}#/system/maintenance`);
+    // The Activity list is read again at once, and the job the lost answer started is in it.
+    await expect.poll(() => reads.length).toBeGreaterThan(0);
+    expect((await maintenanceJobs(request)).map(job => job.title)).toEqual(['Duplicate prompt text']);
+    await page.evaluate(() => { location.hash = '#/activity'; });
+    await expect(page.locator('#workspace-main')).toContainText('Duplicate prompt text');
+});
+
+test('a proxy error or an unreadable answer is not a refusal: Outcome not confirmed (S7 review I1)', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/duplicate-prompts')).toBeOK();
+    const reads = [];
+    // A reverse proxy times out after the server started the job.
+    await page.route(`**${APPLY_URL}`, async route => {
+        await route.fetch();
+        page.on('request', item => { if (item.url().endsWith('/prompt_manager/jobs')) reads.push(item.url()); });
+        await route.fulfill({ status: 504, contentType: 'text/html', body: '<html><body>Gateway Timeout</body></html>' });
+    });
+    const toasts = await recordToasts(page);
+    await openMaintenance(page);
+    await row(page, 'Duplicate prompt text').getByRole('button', { name: 'Review plan', exact: true }).click();
+    await dialog(page).getByRole('button', { name: 'Apply reviewed operation', exact: true }).click();
+    await expect.poll(toasts).toContainEqual(NOT_CONFIRMED);
+    await expect.poll(() => reads.length).toBeGreaterThan(0);
+    expect(await maintenanceJobs(request)).toHaveLength(1);
+});
+
+test('a refused apply names the running job', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/duplicate-prompts')).toBeOK();
+    await openMaintenance(page);
+    await row(page, 'Duplicate prompt text').getByRole('button', { name: 'Review plan', exact: true }).click();
+    await expect(dialog(page).locator('#modal-body > h3')).toHaveText('Duplicate prompt text');
+    const hold = await (await request.post('/__test__/jobs/hold', { data: { title: 'Database restore (admin page)' } })).json();
+    await dialog(page).getByRole('button', { name: 'Apply reviewed operation', exact: true }).click();
+    await expect(toast(page)).toHaveText('Another job is running: Database restore (admin page).');
+    await expect(toast(page).getByRole('link')).toHaveAttribute('href', `#/activity/${hold.job.id}`);
+    await expect(page).toHaveURL(`${workspace}#/system/maintenance`);
+});
+
+test('Find duplicates starts a job; its view links Review groups; Keep radios build a duplicate_files plan (D101)',
+    async ({ page, request }) => {
+        await expect(await request.post('/__test__/system/duplicate-files')).toBeOK();
+        const previews = [];
+        page.on('request', item => { if (item.url().endsWith(PREVIEW_URL)) previews.push(item.postDataJSON()); });
+        await openMaintenance(page);
+        await row(page, 'Duplicate image files').getByRole('button', { name: 'Find duplicates', exact: true }).click();
+        await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+        const jobId = page.url().split('/').pop();
+        const main = page.locator('#workspace-main');
+        await expect(main.locator('h1')).toHaveText('Find duplicate image files');
+        const reviewGroups = main.getByRole('button', { name: 'Review groups', exact: true });
+        await expect(reviewGroups).toBeVisible();
+        await expect(main.locator('.stat-row .stat dt')).toHaveText(['Groups found']);
+        await reviewGroups.click();
+        const review = dialog(page);
+        await expect(review.locator('#modal-title')).toHaveText('Review duplicate image files');
+        const group = review.locator('.compare-grid').filter({ hasText: 's7-dupes/copy.png' });
+        await expect(group.locator('.compare-item img')).toHaveCount(3);
+        const labels = (await group.locator('.compare-item label').allTextContents()).map(text => text.trim());
+        expect([...labels].sort()).toEqual(['Keep input/s7-dupes/same.png', 'Keep output/s7-dupes/copy.png',
+            'Keep output/s7-dupes/same.png']);
+        await expect(review.locator('#modal-body > p.small').last())
+            .toHaveText(/History keeps the removed paths in its run records\./);
+        // Keep the input copy: the same relative path as the output copy, told apart by its source index.
+        await group.locator('.compare-item').filter({ hasText: 'input/s7-dupes/same.png' }).getByRole('radio').check();
+        await review.getByRole('button', { name: 'Review duplicate cleanup', exact: true }).click();
+        await expect(dialog(page).locator('#modal-title')).toHaveText('Review maintenance plan');
+        await expect(dialog(page).locator('#modal-body > h3')).toHaveText('Duplicate image files');
+        expect(previews).toHaveLength(1);
+        expect(previews[0].operation).toBe('duplicate_files');
+        expect(previews[0].options.job_id).toBe(jobId);
+        expect(previews[0].options.keep).toContainEqual(expect.objectContaining({ root_index: 1, path: 's7-dupes/same.png' }));
+        for (const entry of previews[0].options.keep) expect(Object.keys(entry).sort()).toEqual(['group_id', 'path', 'root_index']);
+        expect((await gridOf(page))[3][1]).toMatch(/^Deletes 2 files \(.+\) from disk; the kept copies stay\./);
+        await dialog(page).getByRole('button', { name: 'Apply reviewed operation', exact: true }).click();
+        await expect(page).not.toHaveURL(new RegExp(jobId));
+        await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+        const cleanup = await ended(request, page.url().split('/').pop());
+        expect([cleanup.kind, cleanup.state, cleanup.counters.removed]).toEqual(['duplicate_cleanup', 'finished', 2]);
+        await expect(main.locator('.stat-row .stat dt')).toHaveText(['Removed', 'Kept', 'Errors']);
+        expect((await request.get('/prompt_manager/images/serve/s7-dupes/same.png?root=1')).status()).toBe(200);
+        expect((await request.get('/prompt_manager/images/serve/s7-dupes/same.png?root=0')).status()).toBe(404);
+        expect((await request.get('/prompt_manager/images/serve/s7-dupes/copy.png?root=0')).status()).toBe(404);
+    });
+
+test('the duplicates review pages ten groups at a time and keeps each choice (D101)', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/duplicate-files', { data: { groups: 11 } })).toBeOK();
+    const groupReads = [];
+    page.on('request', item => { if (item.url().includes('/maintenance/duplicates/')) groupReads.push(new URL(item.url()).search); });
+    const previews = [];
+    page.on('request', item => { if (item.url().endsWith(PREVIEW_URL)) previews.push(item.postDataJSON()); });
+    await openMaintenance(page);
+    await row(page, 'Duplicate image files').getByRole('button', { name: 'Find duplicates', exact: true }).click();
+    const main = page.locator('#workspace-main');
+    await main.getByRole('button', { name: 'Review groups', exact: true }).click();
+    const review = dialog(page);
+    const status = review.locator('#modal-body > p.small[role=status]');
+    await expect(status).toHaveText('Groups 1–10 of 12');
+    await expect(review.locator('.compare-grid')).toHaveCount(10);
+    await expect(review.getByRole('button', { name: 'Previous groups', exact: true })).toBeDisabled();
+    // The three-copy group sorts first (the most bytes to free): keep its input copy.
+    const first = review.locator('.compare-grid').first();
+    await first.locator('.compare-item').filter({ hasText: 'input/s7-dupes/same.png' }).getByRole('radio').check();
+    await review.getByRole('button', { name: 'Next groups', exact: true }).click();
+    await expect(status).toHaveText('Groups 11–12 of 12');
+    await expect(review.locator('.compare-grid')).toHaveCount(2);
+    await expect(review.getByRole('button', { name: 'Next groups', exact: true })).toBeDisabled();
+    await review.getByRole('button', { name: 'Previous groups', exact: true }).click();
+    await expect(status).toHaveText('Groups 1–10 of 12');
+    await expect(first.locator('.compare-item').filter({ hasText: 'input/s7-dupes/same.png' }).getByRole('radio')).toBeChecked();
+    expect(groupReads).toEqual(['?offset=0&limit=10', '?offset=10&limit=10', '?offset=0&limit=10']);
+    await review.getByRole('button', { name: 'Review duplicate cleanup', exact: true }).click();
+    await expect(dialog(page).locator('#modal-body > h3')).toHaveText('Duplicate image files');
+    // Every group shown so far is reviewed, each with its chosen copy.
+    expect(previews[0].options.keep).toHaveLength(12);
+    expect(previews[0].options.keep).toContainEqual(expect.objectContaining({ root_index: 1, path: 's7-dupes/same.png' }));
+    await dialog(page).getByRole('button', { name: 'Cancel', exact: true }).click();
+    await expect(dialog(page)).toHaveCount(0);
+});
+
+for (const [width, height] of [[1600, 1100], [390, 844]]) {
+    test(`long copy paths wrap; the duplicates review never scrolls sideways ${width}x${height}`, async ({ page, request }) => {
+        await page.setViewportSize({ width, height });
+        await expect(await request.post('/__test__/system/duplicate-files', { data: { long: true, trio: false } })).toBeOK();
+        await openMaintenance(page);
+        await row(page, 'Duplicate image files').getByRole('button', { name: 'Find duplicates', exact: true }).click();
+        await page.locator('#workspace-main').getByRole('button', { name: 'Review groups', exact: true }).click();
+        const review = dialog(page);
+        await expect(review.locator('.compare-item')).toHaveCount(2);
+        const overflow = await review.evaluate(node => {
+            const body = node.querySelector('#modal-body');
+            // An item wider than its box, or a label (inline: measured by its boxes) past its item's right edge.
+            const wide = [...node.querySelectorAll('.compare-item')].filter(item => item.scrollWidth > item.clientWidth + 1
+                || [...item.querySelector('label').getClientRects()].some(rect => rect.right > item.getBoundingClientRect().right + 1)).length;
+            return { dialog: node.scrollWidth > node.clientWidth + 1, body: body.scrollWidth > body.clientWidth + 1, wide,
+                page: document.documentElement.scrollWidth > document.documentElement.clientWidth };
+        });
+        expect(overflow).toEqual({ dialog: false, body: false, wide: 0, page: false });
+    });
+}
+
+test('Thumbnail cache opens the S5 dialog', async ({ page }) => {
+    await openMaintenance(page);
+    const options = row(page, 'Thumbnail cache').getByRole('button', { name: 'Review options', exact: true });
+    await options.click();
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Thumbnail maintenance');
+    await expect(dialog(page).locator('.field > label')).toHaveText(['Scope']);
+    await page.keyboard.press('Escape');
+    await expect(options).toBeFocused();
+});

tests/browser/workspace-system-sources.spec.mjs

@@ -0,0 +1,537 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { seedConcept } from './concept-inventory.mjs';
+
+// System › Sources & scans (#249 System S4 Task 11) on the concept-shaped real fixture, whose two sources are this
+// server's `output` and `input` folders: the source list, monitoring and worker rows read GET /settings (S4 Task 9),
+// Add/Remove edit the host draft behind the one Save row, and every scan starts the session job through the shared
+// "Review metadata scan" (D55), scoped to one source from its row (S4 Task 10). The hooks are workspace_system_fixture.py's.
+const workspace = '/prompt_manager/workspace';
+const SETTINGS_URL = '/prompt_manager/settings';
+const NOTICE_KEY = 'pm_update_notice_dismissed';
+const OUTSIDE_REASON = 'Gallery root must be inside a ComfyUI directory (output, input, temp, user) or one listed in PROMPT_MANAGER_EXTRA_GALLERY_ROOTS';
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await seedConcept(request);
+    await expect(await request.post('/__test__/system/reset')).toBeOK();
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    page.systemErrors = [];
+    page.on('pageerror', error => page.systemErrors.push(error.message));
+});
+
+test.afterEach(async ({ page, request, browserName }) => {
+    await saveCoverage(page, browserName);
+    await request.post('/__test__/release');
+    await request.post('/__test__/jobs/restart');
+    await request.post('/__test__/system/reset');
+    expect(page.systemErrors).toEqual([]);
+});
+
+const toast = page => page.locator('#workspace-toast');
+const layoutOf = page => page.locator('#workspace-main .settings-layout');
+const sourceList = page => layoutOf(page).locator('#source-list');
+const statusOf = page => layoutOf(page).locator('#settings-status');
+const saveButton = page => layoutOf(page).getByRole('button', { name: 'Save preferences', exact: true });
+const dialog = page => page.locator('dialog#modal[open]');
+
+async function serverJson(request, url) {
+    const response = await request.get(url);
+    await expect(response).toBeOK();
+    return response.json();
+}
+
+/** Open Sources with the update notice dismissed (or shown, `notice: true`) once the source list has loaded. */
+async function openSources(page, { notice = false } = {}) {
+    if (!notice) await page.addInitScript(key => { if (location.protocol.startsWith('http')) localStorage.setItem(key, '3.2.0'); }, NOTICE_KEY);
+    await page.goto(`${workspace}#/system/sources`);
+    await expect(sourceList(page).locator('.operation').first()).toBeVisible();
+    await expect(layoutOf(page).locator('#workers')).toBeEnabled();
+    return layoutOf(page);
+}
+
+/** The source list's rows: `[h3, p, [buttons]]`, then its note line when there is one. */
+function rowsOf(page) {
+    return sourceList(page).evaluate(list => [...list.children].map(row => row.matches('.operation')
+        ? [row.querySelector('h3').textContent, row.querySelector('p').textContent,
+            [...row.querySelectorAll('.row-actions > button')].map(button => button.textContent)]
+        : [row.localName, row.className, row.textContent]));
+}
+
+const sourceRow = (page, title) => sourceList(page).locator('.operation').filter({ has: page.getByRole('heading', { name: title, exact: true }) });
+
+test('notice Later persists the 3.2.0 dismissal (pm_update_notice_dismissed) without scanning', async ({ page, request }) => {
+    const writes = [];
+    page.on('request', item => { if (!['GET', 'HEAD', 'OPTIONS'].includes(item.method())) writes.push(item.url()); });
+    const layout = await openSources(page, { notice: true });
+    const notice = layout.locator(':scope > .notice');
+    await expect(notice.locator('h2')).toHaveText('Bring older images into your prompt history');
+    await expect(notice.locator('p')).toHaveText('The schema upgrades automatically. An optional metadata scan links existing positives and negatives without regenerating all thumbnails.');
+    await expect(notice.locator('.row-actions > button')).toHaveText(['Later', 'Review scan']);
+    await notice.getByRole('button', { name: 'Later', exact: true }).click();
+    await expect(layout.locator(':scope > .notice')).toHaveCount(0);
+    expect(await page.evaluate(key => localStorage.getItem(key), NOTICE_KEY)).toBe('3.2.0');
+    await expect(dialog(page)).toHaveCount(0);
+    // The dismissal is the legacy admin page's own, so neither page shows the notice again.
+    await page.reload();
+    await expect(sourceList(page).locator('.operation').first()).toBeVisible();
+    await expect(layout.locator(':scope > .notice')).toHaveCount(0);
+    expect(writes).toEqual([]);
+    expect((await serverJson(request, '/prompt_manager/jobs')).jobs).toEqual([]);
+});
+
+test('Review scan opens the shared Review metadata scan with all sources', async ({ page, request }) => {
+    const layout = await openSources(page, { notice: true });
+    // The notice's Review scan dismisses it, as the legacy page's does, and reviews every source.
+    await layout.locator(':scope > .notice').getByRole('button', { name: 'Review scan', exact: true }).click();
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Review metadata scan');
+    await expect(dialog(page).locator('dl.meta-grid > div > dd')).toHaveText(['2 output folders', 'New and unresolved files']);
+    expect(await page.evaluate(key => localStorage.getItem(key), NOTICE_KEY)).toBe('3.2.0');
+    await dialog(page).getByRole('button', { name: 'Cancel', exact: true }).click();
+    await expect(layout.locator(':scope > .notice')).toHaveCount(0);
+    // Enrich existing metadata is the same review.
+    const enrich = layout.locator('.operation').filter({ hasText: 'Enrich existing metadata' });
+    await expect(enrich.locator('p')).toHaveText('Resolve both prompts, deduplicate recipes, preserve uncertain links.');
+    await enrich.getByRole('button', { name: 'Review scan', exact: true }).click();
+    await expect(dialog(page).locator('dl.meta-grid > div > dd')).toHaveText(['2 output folders', 'New and unresolved files']);
+    await dialog(page).getByRole('button', { name: 'Cancel', exact: true }).click();
+    expect((await serverJson(request, '/prompt_manager/jobs')).jobs).toEqual([]);
+});
+
+test('Scan changes opens it with that one source ("1 output folder") and starts a scoped job that opens in Activity', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/monitor', { data: { watching: ['input'] } })).toBeOK();
+    const bodies = [];
+    page.on('request', item => { if (item.method() === 'POST' && item.url().endsWith('/prompt_manager/jobs/scan')) bodies.push(item.postDataJSON()); });
+    await openSources(page);
+    const input = sourceRow(page, 'ComfyUI input');
+    await expect(input.locator('p')).toHaveText('input · watching');
+    await input.getByRole('button', { name: 'Scan changes', exact: true }).click();
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Review metadata scan');
+    await expect(dialog(page).locator('dl.meta-grid > div > dd')).toHaveText(['1 output folder', 'New and unresolved files']);
+    await dialog(page).getByRole('button', { name: 'Start scan', exact: true }).click();
+    await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+    // The toast says it started (or, for a scan this quick, that it already finished); Activity shows its progress.
+    await expect(toast(page)).toHaveText(/^Scan (started\.|finished · )/);
+    expect(bodies).toEqual([{ scope: 'new', roots: [1], paths: ['input'] }]);
+    const id = page.url().split('/').pop();
+    // The job walks only that source (the count is recorded once the walk has listed it).
+    await expect.poll(async () => (await serverJson(request, `/prompt_manager/jobs/${id}`)).job.scope)
+        .toMatchObject({ files: 'new', roots: [1], output_folders: 1 });
+    await expect(page.locator('#workspace-main h1')).toHaveText('Scan for metadata');
+});
+
+test('Add source validates on the server, then marks the host draft dirty; Save persists', async ({ page, request }) => {
+    // A folder inside ComfyUI's output folder that is not a source yet.
+    await expect(await request.post('/__test__/system/unthumbnailed', { data: { count: 1 } })).toBeOK();
+    const layout = await openSources(page);
+    expect(await rowsOf(page)).toEqual([
+        ['ComfyUI output', 'output · manual scan', ['Scan folder', 'Remove']],
+        ['ComfyUI input', 'input · manual scan', ['Scan folder', 'Remove']],
+    ]);
+    await expect(layout.locator('.panel-heading > h2')).toHaveText('Image sources');
+    const add = layout.locator('.panel-heading').getByRole('button', { name: '+ Add source', exact: true });
+    await add.click();
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Add image source');
+    await expect(dialog(page).locator('label[for="action-input"]')).toHaveText('Folder path');
+    await expect(dialog(page).locator('#action-input')).toHaveValue('');
+    await expect(dialog(page).locator('.dialog-actions > button')).toHaveText(['Cancel', 'Add']);
+    await dialog(page).locator('#action-input').fill('output/unthumbnailed');
+    const validated = page.waitForResponse(response => response.url().endsWith('/prompt_manager/settings/validate-source'));
+    await dialog(page).getByRole('button', { name: 'Add', exact: true }).click();
+    expect(await (await validated).json()).toEqual({ success: true, valid: true, label: 'unthumbnailed', path: 'output/unthumbnailed', code: null, reason: null });
+    await expect(dialog(page)).toHaveCount(0);
+    await expect(add).toBeFocused();
+    // Validation wrote nothing: the draft is dirty and the server still has two sources.
+    expect(await rowsOf(page)).toEqual([
+        ['ComfyUI output', 'output · manual scan', ['Scan folder', 'Remove']],
+        ['ComfyUI input', 'input · manual scan', ['Scan folder', 'Remove']],
+        ['unthumbnailed', 'output/unthumbnailed · not saved yet', ['Remove']],
+    ]);
+    await expect(statusOf(page)).toHaveText('Unsaved changes.');
+    expect((await serverJson(request, SETTINGS_URL)).sources.effective).toHaveLength(2);
+    const saved = page.waitForRequest(item => item.method() === 'POST' && item.url().endsWith(SETTINGS_URL));
+    await saveButton(page).click();
+    const body = (await saved).postDataJSON();
+    expect(body.gallery_root_paths).toEqual(['output', 'input', 'output/unthumbnailed']);
+    expect(typeof body.expected_revision).toBe('string');
+    await expect(statusOf(page)).toHaveText('Saved to the server configuration.');
+    // The list is the server's again: three effective sources, each scannable.
+    await expect(sourceRow(page, 'unthumbnailed').locator('p')).toHaveText('output/unthumbnailed · manual scan');
+    await expect(sourceRow(page, 'unthumbnailed').getByRole('button', { name: 'Scan folder', exact: true })).toBeVisible();
+    expect((await serverJson(request, SETTINGS_URL)).sources.effective.map(source => source.path)).toEqual(['output', 'input', 'output/unthumbnailed']);
+});
+
+test('invalid source shows the server reason', async ({ page, request }) => {
+    const layout = await openSources(page);
+    await layout.getByRole('button', { name: '+ Add source', exact: true }).click();
+    const field = dialog(page).locator('#action-input');
+    for (const [path, reason, submit] of [
+        ['output/not-there', 'Gallery root does not exist', 'click'],
+        // Enter in the field adds too (M6).
+        ['/etc', OUTSIDE_REASON, 'Enter'],
+    ]) {
+        await field.fill(path);
+        if (submit === 'Enter') await field.press('Enter');
+        else await dialog(page).getByRole('button', { name: 'Add', exact: true }).click();
+        await expect(dialog(page).locator('p.small[role="alert"]')).toHaveText(reason);
+        await expect(field).toHaveAttribute('aria-invalid', 'true');
+        await expect(field).toHaveValue(path);
+    }
+    // A folder already listed (the server's answer names it) is not added twice.
+    await field.fill('input');
+    await dialog(page).getByRole('button', { name: 'Add', exact: true }).click();
+    await expect(dialog(page).locator('p.small[role="alert"]')).toHaveText('This folder is already a source.');
+    // A check that cannot finish says so and adds nothing.
+    await page.route('**/prompt_manager/settings/validate-source', route => route.fulfill({ status: 500,
+        json: { success: false, code: null, error: 'Failed to check the source' } }));
+    await field.fill('output/not-checked');
+    await dialog(page).getByRole('button', { name: 'Add', exact: true }).click();
+    await expect(dialog(page).locator('p.small[role="alert"]')).toHaveText('The folder could not be checked. Try again.');
+    await page.unroute('**/prompt_manager/settings/validate-source');
+    // Typing again clears the reason.
+    await field.fill('output/unthumbnailed');
+    await expect(dialog(page).locator('p.small[role="alert"]')).toHaveCount(0);
+    await expect(field).not.toHaveAttribute('aria-invalid', 'true');
+    await dialog(page).getByRole('button', { name: 'Cancel', exact: true }).click();
+    await expect(statusOf(page)).toHaveText('No unsaved changes.');
+    expect((await serverJson(request, SETTINGS_URL)).sources.configured).toHaveLength(2);
+});
+
+test('Remove marks the draft; removing the last entry states auto-detect', async ({ page, request }) => {
+    await openSources(page);
+    await sourceRow(page, 'ComfyUI input').getByRole('button', { name: 'Remove', exact: true }).click();
+    expect(await rowsOf(page)).toEqual([['ComfyUI output', 'output · manual scan', ['Scan folder', 'Remove']]]);
+    await expect(statusOf(page)).toHaveText('Unsaved changes.');
+    await sourceRow(page, 'ComfyUI output').getByRole('button', { name: 'Remove', exact: true }).click();
+    expect(await rowsOf(page)).toEqual([['p', 'small', 'No source is configured. After saving, ComfyUI’s output folder is used.']]);
+    await saveButton(page).click();
+    await expect(statusOf(page)).toHaveText('Saved to the server configuration.');
+    // Saved: ComfyUI's output folder is detected and listed without Remove, its row saying it is the default.
+    await expect.poll(rowsOf.bind(null, page)).toEqual([
+        ['ComfyUI output', 'ComfyUI/output · manual scan · default', ['Scan folder']],
+    ]);
+    const { sources } = await serverJson(request, SETTINGS_URL);
+    expect([sources.configured, sources.auto_detected]).toEqual([[], true]);
+});
+
+test('a configured source that does not exist says why and can be removed', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/missing-source')).toBeOK();
+    await openSources(page);
+    // The fixture's unmounted drive is not inside a ComfyUI folder, so the server says that (it never probes outside).
+    expect((await rowsOf(page)).at(-1)).toEqual(['unmounted-drive', `unmounted-drive · ${OUTSIDE_REASON}`, ['Remove']]);
+    await sourceRow(page, 'unmounted-drive').getByRole('button', { name: 'Remove', exact: true }).click();
+    await expect(sourceList(page).locator('.operation')).toHaveCount(2);
+    await saveButton(page).click();
+    await expect(statusOf(page)).toHaveText('Saved to the server configuration.');
+    expect((await serverJson(request, SETTINGS_URL)).sources.configured.map(source => source.path)).toEqual(['output', 'input']);
+});
+
+test('watching only with a live observer; restart pending otherwise', async ({ page, request }) => {
+    // No image monitor in this process: every source is scanned by hand.
+    await openSources(page);
+    await expect(sourceList(page).locator('.operation p')).toHaveText(['output · manual scan', 'input · manual scan']);
+    // A live observer that scheduled output: output is watched; input was added since it started.
+    await expect(await request.post('/__test__/system/monitor', { data: { watching: ['output'] } })).toBeOK();
+    await page.reload();
+    await expect(sourceList(page).locator('.operation p')).toHaveText(['output · watching', 'input · restart pending']);
+    await expect(sourceList(page).locator('.operation .row-actions > button:first-child')).toHaveText(['Scan changes', 'Scan folder']);
+    // An observer that died watches nothing.
+    await expect(await request.post('/__test__/system/monitor', { data: { watching: ['output', 'input'], alive: false } })).toBeOK();
+    await page.reload();
+    await expect(sourceList(page).locator('.operation p')).toHaveText(['output · restart pending', 'input · restart pending']);
+});
+
+test('Watch for new outputs saves monitoring_enabled; a restart applies it', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/monitor', { data: { watching: ['output', 'input'] } })).toBeOK();
+    const layout = await openSources(page);
+    const monitoring = layout.getByRole('switch', { name: 'Watch for new outputs', exact: true });
+    await expect(monitoring).toBeChecked();
+    await expect(layout.locator('.setting-row').filter({ has: page.locator('#monitoring') }).locator('p'))
+        .toHaveText('New files enter the same library. Existing scans do not count as new runs.');
+    await monitoring.uncheck();
+    await expect(statusOf(page)).toHaveText('Unsaved changes.');
+    const saved = page.waitForResponse(response => response.request().method() === 'POST' && response.url().endsWith(SETTINGS_URL));
+    await saveButton(page).click();
+    const answer = await (await saved).json();
+    expect(answer.restart_required_fields).toEqual(['monitoring_enabled']);
+    // D128: saved for the next start, and the status says a restart applies it.
+    await expect(statusOf(page)).toHaveText('Saved to the server configuration. Restart ComfyUI to apply: Watch for new outputs.');
+    // The running observer keeps watching until ComfyUI restarts, and the list says so.
+    const { settings, monitor } = await serverJson(request, SETTINGS_URL);
+    expect([settings.monitoring_enabled, monitor.observer_alive]).toEqual([false, true]);
+    await expect(sourceList(page).locator('.operation p')).toHaveText(['output · watching until restart', 'input · watching until restart']);
+    await expect(sourceList(page).locator('.operation .row-actions > button:first-child')).toHaveText(['Scan changes', 'Scan changes']);
+    // Switched back on before the restart: the observer still runs, so nothing waits for one.
+    await monitoring.check();
+    await saveButton(page).click();
+    await expect(statusOf(page)).toHaveText('Saved to the server configuration.');
+    await expect(sourceList(page).locator('.operation p')).toHaveText(['output · watching', 'input · watching']);
+});
+
+test('worker range max is cpu_count', async ({ page, request }) => {
+    const { settings } = await serverJson(request, SETTINGS_URL);
+    const layout = await openSources(page);
+    const workers = layout.locator('#workers');
+    await expect(layout.locator('label[for="workers"]')).toHaveText('Worker threads');
+    await expect(workers).toHaveAttribute('type', 'range');
+    await expect(workers).toHaveAttribute('min', '1');
+    await expect(workers).toHaveAttribute('max', String(settings.cpu_count));
+    await expect(workers).toHaveValue(String(settings.worker_threads));
+    const next = settings.worker_threads === 1 ? settings.cpu_count : 1;
+    await workers.fill(String(next));
+    await expect(statusOf(page)).toHaveText(next === settings.worker_threads ? 'No unsaved changes.' : 'Unsaved changes.');
+    test.skip(next === settings.worker_threads, 'One core: the range has a single value');
+    const saved = page.waitForRequest(item => item.method() === 'POST' && item.url().endsWith(SETTINGS_URL));
+    await saveButton(page).click();
+    expect((await saved).postDataJSON().worker_threads).toBe(next);
+    await expect(statusOf(page)).toHaveText('Saved to the server configuration.');
+    expect((await serverJson(request, SETTINGS_URL)).settings.worker_threads).toBe(next);
+});
+
+test('Refresh files calls /gallery/rescan and toasts its counts', async ({ page }) => {
+    const layout = await openSources(page);
+    const refresh = layout.locator('.operation').filter({ has: page.getByRole('heading', { name: 'Refresh files', exact: true }) });
+    await expect(refresh.locator('p')).toHaveText('Read every source again to find files added or removed outside ComfyUI.');
+    const answered = page.waitForResponse(response => response.url().endsWith('/prompt_manager/gallery/rescan'));
+    await refresh.getByRole('button', { name: 'Refresh', exact: true }).click();
+    const { total, roots } = await (await answered).json();
+    expect(roots).toBe(2);
+    await expect(toast(page)).toHaveText(`Files refreshed. ${total.toLocaleString('en-US')} files in 2 output folders.`);
+    // A failed refresh says so.
+    await page.route('**/prompt_manager/gallery/rescan', route => route.fulfill({ status: 500, json: { success: false, error: 'busy disk' } }));
+    await refresh.getByRole('button', { name: 'Refresh', exact: true }).click();
+    await expect(toast(page)).toHaveText('Files could not be refreshed. Try again.');
+});
+
+const THUMBNAIL_PLAN_URL = '/prompt_manager/images/thumbnails/plan';
+const THUMBNAIL_JOB_URL = '/prompt_manager/jobs/thumbnails';
+const planCount = value => value.toLocaleString('en-US');
+
+/** Open "Thumbnail maintenance" from Sources' Thumbnail generation → Review options. */
+async function openThumbnailReview(page) {
+    const layout = await openSources(page);
+    const thumbnails = layout.locator('.operation').filter({ has: page.getByRole('heading', { name: 'Thumbnail generation', exact: true }) });
+    await expect(thumbnails.locator('p')).toHaveText('Generate missing previews; rebuilding all is a separate explicit option.');
+    await thumbnails.getByRole('button', { name: 'Review options', exact: true }).click();
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Thumbnail maintenance');
+    return dialog(page);
+}
+
+/** The thumbnail requests this page sends: plan reads (their query) and job starts (their body). */
+function thumbnailRequests(page) {
+    const seen = { plans: [], starts: [] };
+    page.on('request', item => {
+        const url = new URL(item.url());
+        if (url.pathname === THUMBNAIL_PLAN_URL) seen.plans.push(Object.fromEntries(url.searchParams));
+        if (item.method() === 'POST' && url.pathname === THUMBNAIL_JOB_URL) seen.starts.push(item.postDataJSON());
+    });
+    return seen;
+}
+
+const missingLine = plan => `${planCount(plan.targets)} ${plan.targets === 1 ? 'preview' : 'previews'} to generate · ` +
+    `${planCount(plan.fresh)} already up to date.`;
+
+const SETTINGS_LINE = 'Previews are written as WebP · quality 80 · 512 px. Change this in System › Appearance.';
+
+test('Review options shows the plan counts for the chosen scope and the server settings before Start', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/unthumbnailed', { data: { count: 3 } })).toBeOK();
+    const seen = thumbnailRequests(page);
+    const plan = await serverJson(request, `${THUMBNAIL_PLAN_URL}?mode=missing`);
+    expect(plan.targets).toBe(3);
+    const review = await openThumbnailReview(page);
+    // D131: Scope, the plan line, the server's settings line, the actions (no quality or size field of its own).
+    await expect(review.locator('#modal-body > *')).toHaveCount(4);
+    await expect(review.locator('.field > label')).toHaveText(['Scope']);
+    await expect(review.locator('#thumb-mode option')).toHaveText(['Missing thumbnails only', 'Rebuild all (explicit opt-in)',
+        'Convert outdated (removes older formats)']);
+    await expect(review.locator('#thumb-mode')).toHaveValue('missing');
+    const [line, settings] = [review.locator('#modal-body > p.small').first(), review.locator('#modal-body > p.small').last()];
+    await expect(line).toHaveAttribute('role', 'status');
+    await expect(line).toHaveText(missingLine(plan));
+    await expect(settings).toHaveText(SETTINGS_LINE);
+    expect(seen.plans).toEqual([{ mode: 'missing' }]);
+    await expect(review.locator('.dialog-actions > button')).toHaveText(['Cancel', 'Start']);
+    // Reviewing starts nothing; Cancel closes.
+    await review.getByRole('button', { name: 'Cancel', exact: true }).click();
+    await expect(dialog(page)).toHaveCount(0);
+    expect(seen.starts).toEqual([]);
+    expect((await serverJson(request, '/prompt_manager/jobs')).jobs).toEqual([]);
+});
+
+test('Convert outdated replaces older-format previews from their originals and removes the old files (#317)', async ({ page, request }) => {
+    const { files } = await (await request.post('/__test__/system/legacy-previews', { data: { count: 3 } })).json();
+    const before = await serverJson(request, '/prompt_manager/images/thumbnails/status');
+    expect(before.outdated).toBe(3);
+    const seen = thumbnailRequests(page);
+    const review = await openThumbnailReview(page);
+    const line = review.locator('#modal-body > p.small').first();
+    await expect(line).toHaveText(/ already up to date\.$/);
+    await review.locator('#thumb-mode').selectOption('convert');
+    await expect(line).toHaveText('3 previews in an older format to convert.');
+    // Choosing the scope converts nothing: only Start does.
+    expect(seen.starts).toEqual([]);
+    await review.getByRole('button', { name: 'Start', exact: true }).click();
+    await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+    expect(seen.starts).toEqual([{ mode: 'convert' }]);
+    const id = page.url().split('/').pop();
+    await expect.poll(async () => (await serverJson(request, `/prompt_manager/jobs/${id}`)).job.state).toBe('finished');
+    const { job } = await serverJson(request, `/prompt_manager/jobs/${id}`);
+    expect(job).toMatchObject({ kind: 'thumbnails', title: 'Convert outdated thumbnails', scope: { mode: 'convert', format: 'webp' } });
+    expect(job.status_line).toMatch(/^3 converted · 0 failed · .+ → .+$/);
+    await expect(page.locator('#workspace-main h1')).toHaveText('Convert outdated thumbnails');
+    const after = await serverJson(request, '/prompt_manager/images/thumbnails/status');
+    expect(after.outdated).toBe(0);
+    // The listing now names the WebP previews; the old PNG previews are gone.
+    for (const file of files) {
+        const name = file.replace(/\.png$/, '');
+        expect((await request.get(`/prompt_manager/images/serve/thumbnails/${name}_thumb.webp?root=0`)).headers()['content-type']).toBe('image/webp');
+        expect((await request.get(`/prompt_manager/images/serve/${file}?root=0`)).ok()).toBe(true);
+    }
+});
+
+test('Start closes the dialog, toasts, and opens the job in Activity', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/unthumbnailed', { data: { count: 2 } })).toBeOK();
+    const seen = thumbnailRequests(page);
+    const review = await openThumbnailReview(page);
+    await review.getByRole('button', { name: 'Start', exact: true }).click();
+    await expect(dialog(page)).toHaveCount(0);
+    await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+    // The toast says it started (or, for a run this quick, that it already finished); Activity shows its progress.
+    await expect(toast(page)).toHaveText(/^(Thumbnail generation started\.|Thumbnails finished · 2 generated · 0 errors)$/);
+    expect(seen.starts).toEqual([{ mode: 'missing' }]);
+    const id = page.url().split('/').pop();
+    const { job } = await serverJson(request, `/prompt_manager/jobs/${id}`);
+    expect(job).toMatchObject({ kind: 'thumbnails', title: 'Thumbnail generation',
+        scope: { mode: 'missing', format: 'webp', size: 512, quality: 80 } });
+    await expect(page.locator('#workspace-main h1')).toHaveText('Thumbnail generation');
+    await expect.poll(async () => (await serverJson(request, `/prompt_manager/jobs/${id}`)).job.state).toBe('finished');
+});
+
+test('Rebuild all is explicit and the plan line says every preview is regenerated', async ({ page, request }) => {
+    const seen = thumbnailRequests(page);
+    const rebuild = await serverJson(request, `${THUMBNAIL_PLAN_URL}?mode=rebuild`);
+    expect(rebuild.targets).toBeGreaterThan(0);
+    const review = await openThumbnailReview(page);
+    // Missing thumbnails only is the default; rebuilding is the explicit second option.
+    await expect(review.locator('#thumb-mode')).toHaveValue('missing');
+    const line = review.locator('#modal-body > p.small').first();
+    await expect(line).toHaveText(/ already up to date\.$/);
+    await review.locator('#thumb-mode').selectOption('rebuild');
+    await expect(line).toHaveText(`Every preview is regenerated: ${planCount(rebuild.targets)} files.`);
+    expect(seen.plans).toEqual([{ mode: 'missing' }, { mode: 'rebuild' }]);
+    // Back and forth reads each scope once.
+    await review.locator('#thumb-mode').selectOption('missing');
+    await expect(line).toHaveText(/ already up to date\.$/);
+    await review.locator('#thumb-mode').selectOption('rebuild');
+    await expect(line).toHaveText(`Every preview is regenerated: ${planCount(rebuild.targets)} files.`);
+    expect(seen.plans).toHaveLength(2);
+    await review.getByRole('button', { name: 'Start', exact: true }).click();
+    await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+    expect(seen.starts).toEqual([{ mode: 'rebuild' }]);
+    const id = page.url().split('/').pop();
+    await expect.poll(async () => (await serverJson(request, `/prompt_manager/jobs/${id}`)).job.state).toBe('finished');
+});
+
+test('a plan that cannot be read says so; Start still starts', async ({ page }) => {
+    await page.route(`**${THUMBNAIL_PLAN_URL}?*`, route => route.fulfill({ status: 500, json: { success: false, error: 'disk' } }));
+    const review = await openThumbnailReview(page);
+    await expect(review.locator('#modal-body > p.small').first()).toHaveText('The previews could not be counted.');
+    await expect(review.getByRole('button', { name: 'Start', exact: true })).not.toHaveAttribute('aria-disabled');
+    await review.getByRole('button', { name: 'Cancel', exact: true }).click();
+});
+
+test('a refused start shows the busy link toast', async ({ page, request }) => {
+    const running = await (await request.post('/__test__/jobs/start', { data: { title: 'Scan for metadata' } })).json();
+    const review = await openThumbnailReview(page);
+    await review.getByRole('button', { name: 'Start', exact: true }).click();
+    await expect(dialog(page)).toHaveCount(0);
+    await expect(toast(page)).toHaveText('Another job is running: Scan for metadata.');
+    await expect(toast(page).getByRole('link', { name: 'Scan for metadata', exact: true })).toHaveAttribute('href', `#/activity/${running.job.id}`);
+    await expect(page).toHaveURL(`${workspace}#/system/sources`);
+    expect((await serverJson(request, '/prompt_manager/jobs')).jobs.map(job => job.kind)).toEqual(['scan']);
+    await request.post(`/__test__/jobs/${running.job.id}/finish`, { data: { state: 'finished' } });
+});
+
+test('a save refused by a running scan shows the busy link toast', async ({ page, request }) => {
+    const running = await (await request.post('/__test__/jobs/start', { data: { title: 'Scan for metadata' } })).json();
+    await openSources(page);
+    await sourceRow(page, 'ComfyUI input').getByRole('button', { name: 'Remove', exact: true }).click();
+    await saveButton(page).click();
+    await expect(toast(page)).toHaveText('Another job is running: Scan for metadata.');
+    await expect(toast(page).getByRole('link', { name: 'Scan for metadata', exact: true })).toHaveAttribute('href', `#/activity/${running.job.id}`);
+    await expect(statusOf(page)).toHaveText('Some changes were not saved. Review the highlighted settings.');
+    // The draft is kept for the next Save, and the server still has both sources.
+    await expect(sourceList(page).locator('.operation')).toHaveCount(1);
+    expect((await serverJson(request, SETTINGS_URL)).sources.configured).toHaveLength(2);
+    // An answer that does not name its job (an older server): the toast names the running one from the job list.
+    await page.route(`**${SETTINGS_URL}`, route => (route.request().method() === 'POST'
+        ? route.fulfill({ status: 409, json: { success: false, code: 'busy', error: 'Scan for metadata already running' } })
+        : route.continue()));
+    await page.locator('#workspace-toast').evaluate(node => { node.textContent = ''; });
+    await saveButton(page).click();
+    await expect(toast(page)).toHaveText('Another job is running: Scan for metadata.');
+    await expect(toast(page).getByRole('link', { name: 'Scan for metadata', exact: true })).toHaveAttribute('href', `#/activity/${running.job.id}`);
+    await page.unroute(`**${SETTINGS_URL}`);
+    await request.post(`/__test__/jobs/${running.job.id}/finish`, { data: { state: 'finished' } });
+});
+
+test('a source list that cannot be read says so and retries', async ({ page }) => {
+    await page.addInitScript(key => { if (location.protocol.startsWith('http')) localStorage.setItem(key, '3.2.0'); }, NOTICE_KEY);
+    let failing = true;
+    await page.route(`**${SETTINGS_URL}`, route => (failing && route.request().method() === 'GET'
+        ? route.fulfill({ status: 500, json: { success: false, error: 'Injected failure' } }) : route.continue()));
+    await page.goto(`${workspace}#/system/sources`);
+    await expect(sourceList(page).getByRole('alert')).toHaveText('Sources could not be loaded. Your saved data has not changed.');
+    await expect(sourceList(page).locator('.operation')).toHaveCount(0);
+    // The server settings rows say so too, and stay disabled.
+    await expect(layoutOf(page).locator('#workers')).toBeDisabled();
+    failing = false;
+    await sourceList(page).getByRole('button', { name: 'Retry', exact: true }).click();
+    await expect(sourceList(page).locator('.operation')).toHaveCount(2);
+});
+
+test('a scan from a list that changed since it was read starts nothing, says why and reads the list again', async ({ page, request }) => {
+    await openSources(page);
+    // The legacy page (or another tab) removes ComfyUI output: the page's "input" is index 1, now past the end.
+    await expect(await request.post(SETTINGS_URL, { data: { gallery_root_paths: ['input'] } })).toBeOK();
+    const refused = page.waitForResponse(response => response.url().endsWith('/prompt_manager/jobs/scan'));
+    await sourceRow(page, 'ComfyUI input').getByRole('button', { name: 'Scan folder', exact: true }).click();
+    await dialog(page).getByRole('button', { name: 'Start scan', exact: true }).click();
+    const answer = await refused;
+    expect([answer.status(), (await answer.json()).code]).toEqual([409, 'sources-changed']);
+    await expect(toast(page)).toHaveText('The sources changed since they were loaded. Reload them.');
+    // No scan started (the other save ran as its own source-change hold).
+    expect((await serverJson(request, '/prompt_manager/jobs')).jobs.map(job => job.kind)).toEqual(['source_change']);
+    // Read again: the one source is index 0 now, and its scan starts.
+    await expect.poll(rowsOf.bind(null, page)).toEqual([['ComfyUI input', 'input · manual scan', ['Scan folder', 'Remove']]]);
+    await expect(statusOf(page)).toHaveText('No unsaved changes.');
+    const started = page.waitForRequest(item => item.method() === 'POST' && item.url().endsWith('/prompt_manager/jobs/scan'));
+    await sourceRow(page, 'ComfyUI input').getByRole('button', { name: 'Scan folder', exact: true }).click();
+    await dialog(page).getByRole('button', { name: 'Start scan', exact: true }).click();
+    expect((await started).postDataJSON()).toEqual({ scope: 'new', roots: [0], paths: ['input'] });
+    await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+});
+
+test('a save refused for one unusable source names it and marks its row', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/missing-source', { data: { inside: true } })).toBeOK();
+    await openSources(page);
+    await expect(sourceRow(page, 'unplugged').locator('p')).toHaveText('output/unplugged · manual scan');
+    // The drive is unplugged after the page read the list; removing another source resends the whole list.
+    await expect(await request.post('/__test__/system/unplug')).toBeOK();
+    await sourceRow(page, 'ComfyUI input').getByRole('button', { name: 'Remove', exact: true }).click();
+    const saved = page.waitForResponse(response => response.request().method() === 'POST' && response.url().endsWith(SETTINGS_URL));
+    await saveButton(page).click();
+    const answer = await saved;
+    expect(answer.status()).toBe(400);
+    expect(await answer.json()).toMatchObject({ code: 'invalid-source', source: 'output/unplugged', index: 1 });
+    await expect(statusOf(page)).toHaveText("output/unplugged can't be used: Gallery root does not exist. Remove it or reconnect it, then save.");
+    await expect(sourceRow(page, 'unplugged')).toHaveAttribute('aria-invalid', 'true');
+    await expect(sourceList(page).locator('.operation[aria-invalid="true"]')).toHaveCount(1);
+    expect((await serverJson(request, SETTINGS_URL)).sources.configured).toHaveLength(3);
+    // Removed, the list saves.
+    await sourceRow(page, 'unplugged').getByRole('button', { name: 'Remove', exact: true }).click();
+    await expect(sourceList(page).locator('.operation[aria-invalid="true"]')).toHaveCount(0);
+    await saveButton(page).click();
+    await expect(statusOf(page)).toHaveText('Saved to the server configuration.');
+    expect((await serverJson(request, SETTINGS_URL)).sources.configured.map(source => source.path)).toEqual(['output']);
+});

tests/browser/workspace-system.spec.mjs

@@ -11,7 +11,7 @@ const number = value => value.toLocaleString('en-US');
 
 test.beforeEach(async ({ page, request, browserName }) => {
     await startCoverage(page, browserName);
-    await seedConcept(request);
+    page.manifest = await seedConcept(request);
     await expect(await request.post('/__test__/system/reset')).toBeOK();
     await expect(await request.post('/__test__/jobs/restart')).toBeOK();
     page.systemErrors = [];
@@ -36,6 +36,9 @@ const layoutOf = page => page.locator('#workspace-main .settings-layout');
 async function openOverview(page) {
     await page.goto(`${workspace}#/system/overview`);
     await expect(layoutOf(page).locator(':scope > .summary-metrics')).toBeVisible();
+    // The Backup status row is its own read of /backup/status (S9): compare once it answered.
+    await expect(layoutOf(page).locator('.operation').filter({ has: page.locator('h3', { hasText: 'Backup status' }) })
+        .locator('p')).not.toHaveText('Checking backups…');
     return layoutOf(page);
 }
 
@@ -55,6 +58,8 @@ test('overview shows real counts and Not checked', async ({ page, request }) =>
     expect([overview.library.positive_prompts, overview.images.indexed, thumbnails.pending]).toEqual([6, 24, 0]);
     // I2: the Overview never walks the sources for thumbnails; the row reads the status route itself.
     expect(overview).not.toHaveProperty('thumbnails');
+    // The fixture records no ambiguous file: the Needs review queue is empty.
+    expect(overview.needs_review).toEqual({ pending: 0 });
     const layout = await openOverview(page);
     expect(await layout.locator('.summary-metrics > .metric').evaluateAll(items => items.map(item =>
         [item.querySelector('strong').textContent, item.querySelector('span').textContent]))).toEqual([
@@ -64,8 +69,10 @@ test('overview shows real counts and Not checked', async ({ page, request }) =>
         ['Not checked', 'Database integrity'],
     ]);
     expect(await rowsOf(layout, 'Library health')).toEqual([
-        ['Ambiguous image links', 'Not available yet.', 'Review metadata'],
-        ['Backup status', 'No retained backup record.', 'View backups'],
+        ['0 ambiguous image links', 'Review metadata before assigning a positive / negative pair.', 'Review metadata'],
+        ['Backup status', 'No backup recorded.', 'View backups'],
+        // D129: the fixture's database is configured explicitly, so it reads as config.json's choice and does not move.
+        ['Library location', 'browser.db · The database path set in config.json.', 'Details'],
         ['No missing thumbnails', 'Generate only missing previews when necessary.', 'Review thumbnails'],
     ]);
     expect(await rowsOf(layout, 'Workspace preferences')).toEqual([
@@ -76,12 +83,101 @@ test('overview shows real counts and Not checked', async ({ page, request }) =>
     expect(writes).toEqual([]);
 });
 
+// D129 (#249 S6b): where the library lives. The hook makes the fixture's database read as a node-folder library; its
+// Move library is a stand-in that touches no file (workspace_system_fixture.py).
+const banner = page => page.locator('#library-banner');
+const LIBRARY_URL = '/prompt_manager/system/library';
+
+test('a node-folder library is offered a move above every page; Keep it here stops the offer', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/library', { data: { state: 'node_folder' } })).toBeOK();
+    await page.goto(`${workspace}#/images`);
+    await expect(banner(page).locator('.notice h2')).toHaveText('Your library is inside the node folder');
+    await expect(banner(page).locator('.notice p')).toHaveText(/^Your library is stored inside the node folder, where an update or reinstall can delete it\./);
+    await expect(banner(page).locator('.notice .row-actions button')).toHaveText(['Keep it here', 'Move library']);
+    await expect(banner(page).getByRole('button', { name: 'Move library', exact: true })).toHaveClass(/ca-primary/);
+    await page.goto(`${workspace}#/library`);
+    await expect(banner(page).locator('.notice')).toBeVisible();
+    await banner(page).getByRole('button', { name: 'Keep it here', exact: true }).click();
+    await expect(banner(page)).toBeHidden();
+    const { location } = await serverJson(request, LIBRARY_URL);
+    expect([location.keep, location.offer, location.movable]).toEqual([true, false, true]);
+    await page.reload();
+    const layout = await openOverview(page);
+    await expect(banner(page)).toBeHidden();
+    const row = layout.locator('.operation').filter({ hasText: 'Library location' });
+    await expect(row.locator('p')).toHaveText('browser.db · The node folder, where an update or reinstall can delete it. '
+        + 'You chose to keep it here.');
+    // The row stays: the move is still one press away.
+    await expect(row.locator('.row-actions button')).toHaveText('Move library');
+});
+
+test('Move library is reviewed, runs as an Activity job and ends the offer', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/library', { data: { state: 'node_folder' } })).toBeOK();
+    const layout = await openOverview(page);
+    const row = layout.locator('.operation').filter({ hasText: 'Library location' });
+    await expect(row.locator('p')).toHaveText('browser.db · The node folder, where an update or reinstall can delete it.');
+    const move = banner(page).getByRole('button', { name: 'Move library', exact: true });
+    await move.click();
+    const dialog = page.locator('dialog#modal[open]');
+    await expect(dialog.locator('#modal-title')).toHaveText('Move library');
+    expect(await dialog.locator('dl.meta-grid > div').evaluateAll(items => items.map(item =>
+        [item.querySelector('dt').textContent, item.querySelector('dd').textContent]))).toEqual([
+        ['From', 'browser.db'], ['To', 'user/__promptmanager/prompts.db'], ['Size', expect.stringMatching(/ (KB|MB)$/)],
+        ['Moves with it', 'config.json and the database backups'], ['Old files', 'Renamed *.moved-to-…, never deleted'],
+    ]);
+    await expect(dialog.locator('.dialog-actions button')).toHaveText(['Cancel', 'Move library']);
+    await dialog.getByRole('button', { name: 'Cancel', exact: true }).click();
+    await expect(page.locator('dialog#modal[open]')).toHaveCount(0);
+    await expect(move).toBeFocused();
+    await row.getByRole('button', { name: 'Move library', exact: true }).click();
+    await dialog.getByRole('button', { name: 'Move library', exact: true }).click();
+    await expect(page).toHaveURL(/#\/activity\/[^/]+$/);
+    await expect(page.locator('#workspace-main')).toContainText(
+        /Moved the library to user\/__promptmanager: \d+ prompts? and 0 images verified\. The old files were renamed browser\.db\.moved-to-__promptmanager; nothing was deleted\./);
+    // The offer ends with the job; the Overview says where the library lives now.
+    await expect(banner(page)).toBeHidden();
+    const after = await openOverview(page);
+    await expect(after.locator('.operation').filter({ hasText: 'Library location' }).locator('p'))
+        .toHaveText('browser.db · ComfyUI\'s user folder, which updates and reinstalls of the node leave alone.');
+});
+
+test('a move that fails says so and keeps the offer; a refused start says why', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/library', { data: { state: 'failing' } })).toBeOK();
+    await page.goto(`${workspace}#/images`);
+    await banner(page).getByRole('button', { name: 'Move library', exact: true }).click();
+    await page.locator('dialog#modal[open]').getByRole('button', { name: 'Move library', exact: true }).click();
+    await expect(page).toHaveURL(/#\/activity\/[^/]+$/);
+    await expect(page.locator('#workspace-main')).toContainText(
+        'The copy did not pass verification. Nothing was moved. The library is still in the node folder, unchanged.');
+    await expect(banner(page).locator('.notice')).toBeVisible();
+    await expect(await request.post('/__test__/system/fail', { data: { path: `${LIBRARY_URL}/move` } })).toBeOK();
+    await banner(page).getByRole('button', { name: 'Move library', exact: true }).click();
+    await page.locator('dialog#modal[open]').getByRole('button', { name: 'Move library', exact: true }).click();
+    await expect(page.locator('#workspace-toast')).toHaveText('Move library could not start. Try again.');
+});
+
+test('a library that does not move shows its details', async ({ page }) => {
+    const layout = await openOverview(page);
+    await expect(banner(page)).toBeHidden();
+    const details = layout.locator('.operation').filter({ hasText: 'Library location' }).getByRole('button', { name: 'Details', exact: true });
+    await details.click();
+    const dialog = page.locator('dialog#modal[open]');
+    await expect(dialog.locator('#modal-title')).toHaveText('Library location');
+    expect(await dialog.locator('dl.meta-grid > div').evaluateAll(items => items.map(item =>
+        [item.querySelector('dt').textContent, item.querySelector('dd').textContent.replace(/[\d.,]+ (KB|MB)$/, 'N')]))).toEqual([
+        ['Database', 'browser.db'], ['Why here', 'The database path set in config.json'],
+        ['Beside it', 'config.json, the database backups and the logs'], ['Size', 'N'],
+    ]);
+    await dialog.getByRole('button', { name: 'Close', exact: true }).click();
+    await expect(details).toBeFocused();
+});
+
 test('Run health checks opens Health report and updates metric 4', async ({ page, request }) => {
     await page.goto(`${workspace}#/system/maintenance`);
     const layout = layoutOf(page);
     await expect(layout.locator(':scope > .notice h2')).toHaveText('Check first. Review changes. Then apply.');
-    // The rest of Maintenance is still the existing tools' (D94).
-    await expect(layout.locator(':scope > section.handoff h2')).toHaveText('Your current tools are ready');
+    // Maintenance is native (S7): its two surfaces follow the notice.
+    await expect(layout.locator(':scope > section.surface > h2')).toHaveText(['Database', 'Images & cache']);
     const run = layout.getByRole('button', { name: 'Run health checks', exact: true });
     await run.click();
     const dialog = page.locator('dialog#modal[open]');
@@ -111,8 +207,11 @@ test('Run health checks opens Health report and updates metric 4', async ({ page
         .toHaveText(['1 link needs review', 'Passed', 'Not available']);
     await expect(dialog.locator('.operation h3').filter({ hasText: 'Missing files' }))
         .toHaveText(['Missing files · output', 'Missing files · input', 'Missing files · unmounted-drive']);
-    // Review missing links goes to Maintenance, where the cleanup's existing tool is linked.
+    // Review missing links reviews a fresh Missing-file links plan (S7); nothing is cleaned up.
     await dialog.getByRole('button', { name: 'Review missing links', exact: true }).click();
+    await expect(dialog.locator('#modal-title')).toHaveText('Review maintenance plan');
+    await expect(dialog.locator('#modal-body > h3')).toHaveText('Missing-file links');
+    await dialog.getByRole('button', { name: 'Cancel', exact: true }).click();
     await expect(page.locator('dialog#modal[open]')).toHaveCount(0);
     await expect(page).toHaveURL(`${workspace}#/system/maintenance`);
     await page.locator('#workspace-main .section-nav').getByRole('button', { name: 'Overview', exact: true }).click();
@@ -138,9 +237,82 @@ test('thumbnail row reflects the status endpoint', async ({ page, request }) =>
     const layout = await openOverview(page);
     const row = layout.locator('.operation').filter({ has: page.getByRole('button', { name: 'Review thumbnails', exact: true }) });
     await expect(row.locator('h3')).toHaveText('3 missing thumbnails');
-    // Until the thumbnail review dialog (S5), Review thumbnails opens Sources.
+});
+
+test('Overview Review thumbnails opens the same dialog', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/unthumbnailed', { data: { count: 2 } })).toBeOK();
+    const plan = await serverJson(request, '/prompt_manager/images/thumbnails/plan?mode=missing');
+    const starts = [];
+    page.on('request', item => { if (item.method() === 'POST' && item.url().endsWith('/prompt_manager/jobs/thumbnails')) starts.push(item.postDataJSON()); });
+    const layout = await openOverview(page);
+    const row = layout.locator('.operation').filter({ has: page.getByRole('button', { name: 'Review thumbnails', exact: true }) });
+    await expect(row.locator('h3')).toHaveText('2 missing thumbnails');
     await row.getByRole('button', { name: 'Review thumbnails', exact: true }).click();
-    await expect(page).toHaveURL(`${workspace}#/system/sources`);
+    const review = page.locator('dialog#modal[open]');
+    await expect(review.locator('#modal-title')).toHaveText('Thumbnail maintenance');
+    await expect(page).toHaveURL(`${workspace}#/system/overview`);
+    await expect(review.locator('.field > label')).toHaveText(['Scope']);
+    await expect(review.locator('#modal-body > p.small').first()).toHaveText(`2 previews to generate · ${number(plan.fresh)} already up to date.`);
+    // Escape closes it and focus returns to the row's button.
+    await page.keyboard.press('Escape');
+    await expect(review).toHaveCount(0);
+    await expect(row.getByRole('button', { name: 'Review thumbnails', exact: true })).toBeFocused();
+    await row.getByRole('button', { name: 'Review thumbnails', exact: true }).click();
+    await review.getByRole('button', { name: 'Start', exact: true }).click();
+    await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+    expect(starts).toEqual([{ mode: 'missing' }]);
+    const id = page.url().split('/').pop();
+    await expect.poll(async () => (await serverJson(request, `/prompt_manager/jobs/${id}`)).job.state).toBe('finished');
+});
+
+test('the thumbnail row counts outdated previews and offers Convert outdated (#317)', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/legacy-previews', { data: { count: 2 } })).toBeOK();
+    const layout = await openOverview(page);
+    const row = layout.locator('.operation').filter({ has: page.getByRole('button', { name: 'Review thumbnails', exact: true }) });
+    await expect(row.locator('h3')).toHaveText('No missing thumbnails · 2 outdated');
+    await expect(row.locator('.row-actions > button')).toHaveText(['Review thumbnails', 'Convert outdated']);
+    await row.getByRole('button', { name: 'Convert outdated', exact: true }).click();
+    const review = page.locator('dialog#modal[open]');
+    await expect(review.locator('#modal-title')).toHaveText('Thumbnail maintenance');
+    // It opens on the Convert outdated scope; nothing starts until Start.
+    await expect(review.locator('#thumb-mode')).toHaveValue('convert');
+    await expect(review.locator('#modal-body > p.small').first()).toHaveText('2 previews in an older format to convert.');
+    expect((await serverJson(request, '/prompt_manager/jobs')).jobs).toEqual([]);
+    await page.keyboard.press('Escape');
+    await expect(row.getByRole('button', { name: 'Convert outdated', exact: true })).toBeFocused();
+});
+
+test('Appearance › Thumbnails saves the server thumbnail settings and never converts by itself (#317)', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/jxl-encoder', { data: { available: false } })).toBeOK();
+    await expect(await request.post('/__test__/system/legacy-previews', { data: { count: 1 } })).toBeOK();
+    await page.goto(`${workspace}#/system/appearance`);
+    const surface = page.locator('#workspace-main .settings-layout > section.surface').nth(1);
+    await expect(surface.locator(':scope > h2')).toHaveText('Thumbnails');
+    await expect(surface.locator('.setting-row label')).toHaveText(['Thumbnail format', 'Thumbnail quality', 'Thumbnail size limit']);
+    const format = surface.locator('#thumbnail-format');
+    await expect(format).toBeEnabled();
+    await expect(format).toHaveValue('webp');
+    await expect(surface.locator('#thumbnail-quality')).toHaveValue('80');
+    await expect(surface.locator('#thumbnail-edge')).toHaveValue('512');
+    // D130: JPEG XL is offered only with an encoder; without one the row says why, in the server's words.
+    await expect(format.locator('option[value="jxl"]')).toBeDisabled();
+    await expect(surface.locator('.setting-row').first().locator('p.small').first()).toContainText('No JPEG XL encoder found.');
+    await format.selectOption('jpeg');
+    await surface.locator('#thumbnail-quality').fill('65');
+    await surface.locator('#thumbnail-quality').dispatchEvent('change');
+    await page.getByRole('button', { name: 'Save preferences', exact: true }).click();
+    await expect(page.locator('#settings-status')).toHaveText('Saved to the server configuration.');
+    const { settings } = await serverJson(request, '/prompt_manager/settings');
+    expect([settings.thumbnail_format, settings.thumbnail_quality, settings.thumbnail_edge]).toEqual(['jpeg', 65, 512]);
+    // Changing the format converts nothing: the row says so and the old preview is still listed.
+    await expect(surface.locator('.operation p')).toHaveText('Format saved. Existing previews keep their old format until you convert them.');
+    expect((await serverJson(request, '/prompt_manager/jobs')).jobs).toEqual([]);
+    expect((await serverJson(request, '/prompt_manager/images/thumbnails/status')).outdated).toBeGreaterThan(0);
+    // With an encoder JPEG XL can be chosen.
+    await expect(await request.post('/__test__/system/jxl-encoder', { data: { available: true } })).toBeOK();
+    await page.reload();
+    await expect(page.locator('#workspace-main #thumbnail-format option[value="jxl"]')).toBeEnabled();
+    await expect(page.locator('#workspace-main #thumbnail-format')).toHaveValue('jpeg');
 });
 
 test('the thumbnail row paints when its own status read answers', async ({ page, request }) => {
@@ -166,14 +338,17 @@ test('a failed thumbnail read is unavailable, never zero', async ({ page }) => {
     await expect(layout.locator('.metric').nth(2).locator('strong')).toHaveText('24');
 });
 
-test('ambiguous row reads Not available yet (Q6)', async ({ page }) => {
+test('ambiguous row reads the pending count and Review metadata opens Needs review', async ({ page }) => {
     const layout = await openOverview(page);
-    const row = layout.locator('.operation').filter({ hasText: 'Ambiguous image links' });
-    await expect(row.locator('p')).toHaveText('Not available yet.');
+    const row = layout.locator('.operation').filter({ hasText: 'ambiguous image links' });
+    await expect(row.locator('h3')).toHaveText('0 ambiguous image links');
+    await expect(row.locator('p')).toHaveText('Review metadata before assigning a positive / negative pair.');
     const review = row.getByRole('button', { name: 'Review metadata', exact: true });
-    await expect(review).toHaveAttribute('aria-disabled', 'true');
-    await review.click({ force: true });
-    await expect(page).toHaveURL(`${workspace}#/system/overview`);
+    await expect(review).not.toHaveAttribute('aria-disabled');
+    await review.click();
+    // The concept's go-review: the Needs review page.
+    await expect(page).toHaveURL(`${workspace}#/review`);
+    await expect(page.getByRole('heading', { name: 'Metadata review', exact: true })).toBeVisible();
 });
 
 test('View backups / Appearance / Manage sources switch sections', async ({ page }) => {
@@ -237,10 +412,11 @@ test('out-of-order overview responses never repaint a newer section', async ({ p
     await nav.getByRole('button', { name: 'Appearance', exact: true }).click();
     await nav.getByRole('button', { name: 'Overview', exact: true }).click();
     await expect.poll(held).toBe(2);
-    await nav.getByRole('button', { name: 'Sources & scans', exact: true }).click();
+    // Auto-tagging still hands off (S11), so its body is one known panel.
+    await nav.getByRole('button', { name: 'Auto-tagging', exact: true }).click();
     await expect(await request.post('/__test__/release')).toBeOK();
     await expect.poll(held).toBe(0);
-    // Both late answers reached a section that had left: Sources keeps its own body.
+    // Both late answers reached a section that had left: Auto-tagging keeps its own body.
     await expect(layout.locator(':scope > section.handoff')).toBeVisible();
     await page.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))));
     await expect(layout.locator('.summary-metrics')).toHaveCount(0);
@@ -250,3 +426,370 @@ test('out-of-order overview responses never repaint a newer section', async ({ p
     await expect(layout.locator('.summary-metrics')).toHaveCount(1);
     await expect(layout.locator('.two-col')).toHaveCount(1);
 });
+
+// System › Appearance (#249 System S3 Task 8): the browser display defaults (`gallerySettings`, preferences.mjs) and the
+// two host fields behind the one Save row, and the consumers that read them on their next visit.
+const SETTINGS_URL = '/prompt_manager/settings';
+const INSPECT_PATH = '/prompt_manager/images/inspect/';
+const statusOf = page => page.locator('#workspace-main #settings-status');
+const saveOf = page => page.locator('#workspace-main .save-row > button');
+const storedSettings = page => page.evaluate(() => JSON.parse(localStorage.getItem('gallerySettings') || 'null'));
+const imageCards = page => page.locator('#workspace-main article.media-card');
+const panel = page => page.getByRole('complementary', { name: 'Selected image details', exact: true });
+
+async function openAppearance(page) {
+    await page.goto(`${workspace}#/system/appearance`);
+    await expect(page.locator('#workspace-main .settings-layout > section.surface > h2').first()).toHaveText('Browsing & display');
+    // The host rows are enabled once the server settings answered.
+    await expect(page.locator('#timeout')).toBeEnabled();
+}
+
+async function saveAppearance(page, text) {
+    await expect(saveOf(page)).not.toHaveAttribute('aria-disabled', 'true');
+    await saveOf(page).click();
+    await expect(statusOf(page)).toHaveText(text);
+}
+
+/** Set toggles (by row id) through their Toolkit switches. */
+async function toggle(page, values) {
+    for (const [id, checked] of Object.entries(values)) await page.locator(`#${id}`).setChecked(checked, { force: true });
+}
+
+/**
+ * A request barrier: one request issued and answered after everything the page has asked for so far, so a read the
+ * last action started has been seen (Playwright reports a page's requests in order).
+ */
+async function requestBarrier(page) {
+    expect(await page.evaluate(url => fetch(url, { cache: 'no-store' }).then(response => response.ok), SETTINGS_URL)).toBe(true);
+}
+
+async function openImages(page) {
+    await page.goto(`${workspace}#/images`);
+    await expect(imageCards(page).first()).toBeVisible();
+}
+
+test('defaults apply to a new visit but not to the current view or a saved view', async ({ page, request }) => {
+    const created = await request.post('/prompt_manager/saved-views', { data: { page: 'images', name: 'Everything',
+        state: { q: '', category: '', sort: 'newest', source: 'all', folder: '', media: 'all', tags: [], favorites: false } } });
+    expect(created.status()).toBe(201);
+    const view = (await created.json()).view;
+    try {
+        await openImages(page);
+        // The current view: the toolbar sets List.
+        await page.getByRole('group', { name: 'Image layout' }).getByRole('button', { name: 'List', exact: true }).click();
+        await expect(page.locator('.image-grid')).toHaveAttribute('data-layout', 'list');
+        await openAppearance(page);
+        await expect(page.locator('#default-view')).toHaveValue('grid');
+        await page.locator('#default-view').selectOption('masonry');
+        await page.locator('#density').selectOption('compact');
+        await expect(statusOf(page)).toHaveText('Unsaved changes.');
+        await saveAppearance(page, 'Saved in this browser.');
+        const stored = await storedSettings(page);
+        expect([stored.workspaceLayout, stored.workspaceDensity]).toEqual(['masonry', 'compact']);
+        // Back in Images (the page session's last visit): the current view keeps its own layout and size.
+        await page.locator('#primary-nav a[data-route="images"]').click();
+        await expect(page.locator('.image-grid')).toHaveAttribute('data-layout', 'list');
+        await expect(page.locator('.image-grid')).toHaveAttribute('data-density', 'comfortable');
+        // The saved view opens as before.
+        await page.goto(`${workspace}#/saved/${view.id}`);
+        await expect(imageCards(page).first()).toBeVisible();
+        await expect(page.locator('.image-grid')).toHaveAttribute('data-layout', 'grid');
+        await expect(page.locator('.image-grid')).toHaveAttribute('data-density', 'comfortable');
+        // A new visit starts from the defaults.
+        await openImages(page);
+        await page.reload();
+        await expect(imageCards(page).first()).toBeVisible();
+        await expect(page.locator('.image-grid')).toHaveAttribute('data-layout', 'masonry');
+        await expect(page.locator('.image-grid')).toHaveAttribute('data-density', 'compact');
+        await expect(page.getByRole('group', { name: 'Image layout' }).getByRole('button', { name: 'Masonry', exact: true }))
+            .toHaveAttribute('aria-pressed', 'true');
+    } finally {
+        await request.delete(`/prompt_manager/saved-views/${view.id}`);
+    }
+});
+
+test('the defaults reach the Images page only; embedded galleries keep their own presentation', async ({ page }) => {
+    await openAppearance(page);
+    await page.locator('#default-view').selectOption('list');
+    await page.locator('#density').selectOption('compact');
+    await saveAppearance(page, 'Saved in this browser.');
+    // The prompt history's shared gallery has no toolbar to change them, so it opens as it always did.
+    await page.goto(`${workspace}#/library/${page.manifest.prompts[0].positive_id}`);
+    await expect(imageCards(page).first()).toBeVisible();
+    await expect(page.locator('#workspace-main .image-grid')).toHaveAttribute('data-layout', 'grid');
+    await expect(page.locator('#workspace-main .image-grid')).toHaveAttribute('data-density', 'comfortable');
+    // The Images page starts from them.
+    await page.locator('#primary-nav a[data-route="images"]').click();
+    await expect(imageCards(page).first()).toBeVisible();
+    await expect(page.locator('.image-grid')).toHaveAttribute('data-layout', 'list');
+    await expect(page.locator('.image-grid')).toHaveAttribute('data-density', 'compact');
+});
+
+test('metadata off shows an explicit load and loads once on request', async ({ page }) => {
+    await openAppearance(page);
+    await toggle(page, { 'metadata-auto': false });
+    await saveAppearance(page, 'Saved in this browser.');
+    const reads = [];
+    page.on('request', item => { if (new URL(item.url()).pathname.startsWith(INSPECT_PATH)) reads.push(item.url()); });
+    await openImages(page);
+    const first = imageCards(page).first();
+    await first.locator('.image-card-actions button').first().click();
+    await expect(panel(page).getByRole('status')).toHaveText('Metadata loads when you ask for it.');
+    const load = panel(page).getByRole('button', { name: 'Load metadata', exact: true });
+    await expect(load).toBeVisible();
+    expect(reads).toEqual([]);
+    await load.click();
+    await expect(panel(page).locator('.panel-heading h2')).toBeVisible();
+    expect(reads).toHaveLength(1);
+    // The same file again reads nothing more (the cache is on).
+    await first.locator('.image-card-actions button').first().click();
+    await expect(panel(page).locator('.panel-heading h2')).toBeVisible();
+    await requestBarrier(page);
+    expect(reads).toHaveLength(1);
+    // The viewer's details use the same inspector: another file waits there too, and loads on request.
+    await imageCards(page).nth(1).locator('.image-open').click();
+    const viewerDetails = page.locator('#viewer-details');
+    await expect(viewerDetails.getByRole('status')).toHaveText('Metadata loads when you ask for it.');
+    expect(reads).toHaveLength(1);
+    await viewerDetails.getByRole('button', { name: 'Load metadata', exact: true }).click();
+    await expect(viewerDetails.locator('.panel-heading h2')).toBeVisible();
+    expect(reads).toHaveLength(2);
+});
+
+test('cache off rereads the current selection; on reuses the one current record', async ({ page }) => {
+    const reads = [];
+    page.on('request', item => { if (new URL(item.url()).pathname.startsWith(INSPECT_PATH)) reads.push(item.url()); });
+    for (const cache of [true, false]) {
+        if (!cache) {
+            await openAppearance(page);
+            await toggle(page, { 'metadata-cache': false });
+            await saveAppearance(page, 'Saved in this browser.');
+            await page.reload();
+        }
+        await openImages(page);
+        const info = imageCards(page).first().locator('.image-card-actions button').first();
+        await info.click();
+        await expect(panel(page).locator('.panel-heading h2')).toBeVisible();
+        await expect.poll(() => reads.length).toBeGreaterThan(0);
+        await requestBarrier(page);
+        reads.length = 0;
+        // Inspect the selected file twice more.
+        for (const _ of [1, 2]) {
+            const answered = cache ? null : page.waitForResponse(response => new URL(response.url()).pathname.startsWith(INSPECT_PATH));
+            await info.click();
+            if (answered) await answered;
+            await expect(panel(page).locator('.panel-heading h2')).toBeVisible();
+        }
+        await requestBarrier(page);
+        expect(reads, `cache ${cache}`).toHaveLength(cache ? 0 : 2);
+    }
+});
+
+test('paths hidden only changes display', async ({ page }) => {
+    const rows = async () => page.locator('#viewer-details details').filter({ hasText: 'File & provenance' }).locator('dt')
+        .evaluateAll(terms => terms.map(term => term.textContent));
+    const openViewer = async () => {
+        await openImages(page);
+        await imageCards(page).first().locator('.image-open').click();
+        const provenance = page.locator('#viewer-details details').filter({ hasText: 'File & provenance' });
+        await provenance.locator('summary').click();
+        await expect(provenance.locator('dl')).toBeVisible();
+        return provenance;
+    };
+    let provenance = await openViewer();
+    expect(await rows()).toContain('Path');
+    const before = { show: await provenance.getByRole('button', { name: /^Show .* in folder$/ }).count(),
+        download: await provenance.getByRole('link', { name: 'Download original', exact: true }).getAttribute('href') };
+    await page.keyboard.press('Escape');
+    await openAppearance(page);
+    await toggle(page, { paths: false });
+    await saveAppearance(page, 'Saved in this browser.');
+    provenance = await openViewer();
+    const shown = await rows();
+    expect(shown).not.toContain('Path');
+    expect(shown).toEqual(expect.arrayContaining(['Source', 'Size']));
+    // Everything else is as it was: the folder action and the original download stay.
+    expect(await provenance.getByRole('button', { name: /^Show .* in folder$/ }).count()).toBe(before.show);
+    await expect(provenance.getByRole('link', { name: 'Download original', exact: true })).toHaveAttribute('href', before.download);
+});
+
+test('video defaults reach the viewer', async ({ page }) => {
+    await openAppearance(page);
+    await toggle(page, { 'video-auto': true, 'video-muted': false, 'video-loop': false });
+    await saveAppearance(page, 'Saved in this browser.');
+    expect(await page.evaluate(async () => (await import('/prompt_manager/js/workspace/media-viewer.mjs')).readViewerPreferences()))
+        .toEqual({ videoAutoplay: true, videoMute: false, videoLoop: false });
+    const stored = await storedSettings(page);
+    expect([stored.videoAutoplay, stored.videoMute, stored.videoLoop]).toEqual([true, false, false]);
+});
+
+test('host fields round-trip through /settings with revision', async ({ page, request }) => {
+    const posts = [];
+    page.on('request', item => { if (item.method() === 'POST' && new URL(item.url()).pathname === SETTINGS_URL) posts.push(item.postDataJSON()); });
+    const before = await serverJson(request, SETTINGS_URL);
+    await openAppearance(page);
+    await expect(page.locator('#open-mode')).toHaveValue(before.settings.webui_display_mode);
+    await expect(page.locator('#timeout')).toHaveValue(String(before.settings.result_timeout));
+    // Only whole seconds from 0 to 300: anything else is highlighted and never sent.
+    for (const bad of ['301', '-1', '2.5']) {
+        await page.locator('#timeout').fill(bad);
+        await page.locator('#timeout').press('Tab');
+        await expect(page.locator('#timeout')).toHaveAttribute('aria-invalid', 'true');
+        await expect(statusOf(page)).toHaveText('Some changes were not saved. Review the highlighted settings.');
+        await expect(saveOf(page)).toHaveAttribute('aria-disabled', 'true');
+    }
+    await page.locator('#timeout').fill('0');
+    await page.locator('#timeout').press('Tab');
+    await expect(page.locator('#timeout')).not.toHaveAttribute('aria-invalid');
+    await page.locator('#open-mode').selectOption('popup');
+    await saveAppearance(page, 'Saved to the server configuration.');
+    expect(posts).toEqual([{ webui_display_mode: 'popup', result_timeout: 0, expected_revision: before.revision }]);
+    const after = await serverJson(request, SETTINGS_URL);
+    expect([after.settings.webui_display_mode, after.settings.result_timeout]).toEqual(['popup', 0]);
+    expect(after.revision).not.toBe(before.revision);
+    // No browser key was written for a host field.
+    expect(await storedSettings(page)).toBeNull();
+});
+
+test('server settings that cannot be read say so in their rows', async ({ page }) => {
+    await page.route(url => url.pathname === SETTINGS_URL, route => (route.request().method() === 'GET'
+        ? route.fulfill({ status: 500, contentType: 'application/json', body: JSON.stringify({ success: false, error: 'Injected failure' }) })
+        : route.continue()));
+    await page.goto(`${workspace}#/system/appearance`);
+    // #317: the Thumbnails rows are server settings too.
+    for (const id of ['open-mode', 'timeout', 'thumbnail-format', 'thumbnail-quality', 'thumbnail-edge']) {
+        const row = page.locator('#workspace-main .setting-row').filter({ has: page.locator(`#${id}`) });
+        await expect(row.locator('p.small').first()).toHaveText('Server settings could not be read.');
+        await expect(page.locator(`#${id}`)).toBeDisabled();
+    }
+    // The browser rows are this browser's, and work as before.
+    await expect(page.locator('#default-view')).toBeEnabled();
+    await expect(page.locator('#workspace-main .setting-row p.small', { hasText: 'Server settings could not be read.' })).toHaveCount(5);
+    await expect(page.locator('#workspace-main section.surface').first().locator('.setting-row p.small')).toHaveCount(2);
+});
+
+test('stale revision shows the conflict status', async ({ page, request }) => {
+    await openAppearance(page);
+    // Another page saves after this one read the settings.
+    const current = await serverJson(request, SETTINGS_URL);
+    await expect(await request.post(SETTINGS_URL, { data: { result_timeout: 42, expected_revision: current.revision } })).toBeOK();
+    await page.locator('#open-mode').selectOption('popup');
+    await saveAppearance(page, 'Settings changed elsewhere. Reload this section to see them.');
+    await expect(page.locator('#open-mode')).toHaveAttribute('aria-invalid', 'true');
+    // The draft is kept and the section now shows the other page's value.
+    await expect(page.locator('#open-mode')).toHaveValue('popup');
+    await expect(page.locator('#timeout')).toHaveValue('42');
+    expect((await serverJson(request, SETTINGS_URL)).settings.webui_display_mode).toBe('newtab');
+    // With the reloaded revision, Save succeeds.
+    await saveAppearance(page, 'Saved to the server configuration.');
+    expect((await serverJson(request, SETTINGS_URL)).settings.webui_display_mode).toBe('popup');
+});
+
+test('reload keeps saved values; a new tab reads them', async ({ page, context }) => {
+    await openAppearance(page);
+    await page.locator('#image-quality').selectOption('high');
+    await toggle(page, { 'card-details': false });
+    await page.locator('#open-mode').selectOption('popup');
+    await saveAppearance(page, 'Saved in this browser. Saved to the server configuration.');
+    await page.reload();
+    await expect(page.locator('#timeout')).toBeEnabled();
+    await expect(page.locator('#image-quality')).toHaveValue('high');
+    await expect(page.locator('#card-details')).not.toBeChecked();
+    await expect(page.locator('#open-mode')).toHaveValue('popup');
+    const other = await context.newPage();
+    await openAppearance(other);
+    await expect(other.locator('#image-quality')).toHaveValue('high');
+    await expect(other.locator('#card-details')).not.toBeChecked();
+    // A change saved in one tab reaches the other's clean controls; a draft it overtakes is flagged and kept.
+    await other.locator('#density').selectOption('large');
+    await page.locator('#density').selectOption('compact');
+    await saveAppearance(page, 'Saved in this browser.');
+    await expect(other.locator('#density')).toHaveValue('large');
+    await expect(other.locator('#settings-status')).toHaveText('Settings changed elsewhere. Reload this section to see them.');
+    await expect(other.locator('#density')).toHaveAttribute('aria-invalid', 'true');
+    await page.locator('#image-quality').selectOption('low');
+    await saveAppearance(page, 'Saved in this browser.');
+    await expect(other.locator('#image-quality')).toHaveValue('low');
+    await other.close();
+});
+
+test('a change another tab saved while System was closed is a conflict on return, never saved over silently', async ({ page, context }) => {
+    await openAppearance(page);
+    await page.locator('#density').selectOption('compact');
+    await expect(statusOf(page)).toHaveText('Unsaved changes.');
+    // Leave System for Images: the draft stays for the page session, but System no longer listens.
+    await page.locator('#primary-nav a[data-route="images"]').click();
+    await expect(imageCards(page).first()).toBeVisible();
+    const other = await context.newPage();
+    await openAppearance(other);
+    await other.locator('#density').selectOption('large');
+    await saveAppearance(other, 'Saved in this browser.');
+    await other.close();
+    // Back in System: the draft is kept and flagged, and nothing was written over the other tab's value.
+    await page.evaluate(() => { location.hash = '#/system/appearance'; });
+    await expect(page.locator('#workspace-main .settings-layout > section.surface > h2').first()).toHaveText('Browsing & display');
+    await expect(statusOf(page)).toHaveText('Settings changed elsewhere. Reload this section to see them.');
+    await expect(page.locator('#density')).toHaveAttribute('aria-invalid', 'true');
+    await expect(page.locator('#density')).toHaveValue('compact');
+    expect((await storedSettings(page)).workspaceDensity).toBe('large');
+    // Saving after the conflict was shown is an explicit choice: it wins.
+    await saveAppearance(page, 'Saved in this browser.');
+    expect((await storedSettings(page)).workspaceDensity).toBe('compact');
+    await expect(page.locator('#density')).not.toHaveAttribute('aria-invalid');
+});
+
+test('a browser that refuses storage is saved for this tab only, never "Saved"', async ({ page }) => {
+    await openAppearance(page);
+    await page.evaluate(() => {
+        Storage.prototype.setItem = function setItem() { throw new DOMException('Quota exceeded', 'QuotaExceededError'); };
+    });
+    await page.locator('#default-view').selectOption('list');
+    await saveAppearance(page, 'Saved for this tab only; browser storage is unavailable.');
+    expect(await storedSettings(page)).toBeNull();
+    // This tab's next Images visit still uses it.
+    await page.locator('#primary-nav a[data-route="images"]').click();
+    await expect(imageCards(page).first()).toBeVisible();
+    await expect(page.locator('.image-grid')).toHaveAttribute('data-layout', 'list');
+});
+
+test('added rows reach their consumers', async ({ page }) => {
+    await openImages(page);
+    await expect(imageCards(page).first().locator('.media-info h3')).toBeVisible();
+    await openAppearance(page);
+    await toggle(page, { 'card-details': false, 'viewer-details': true });
+    await saveAppearance(page, 'Saved in this browser.');
+    await page.reload();
+    await openImages(page);
+    // Show image details on cards off: no title or file line; Info and Tag stay.
+    const card = imageCards(page).first();
+    await expect(card.locator('.media-info h3')).toBeHidden();
+    await expect(card.locator('.image-card-actions button')).toHaveCount(2);
+    // Collapse viewer details by default: the viewer opens with its details hidden behind one toggle.
+    await card.locator('.image-open').click();
+    const details = page.locator('#viewer-details');
+    await expect(page.locator('#viewer-dialog')).toBeVisible();
+    await expect(details).toBeHidden();
+    const show = page.locator('#viewer-toolbar').getByRole('button', { name: 'Show details', exact: true });
+    await expect(show).toHaveAttribute('aria-expanded', 'false');
+    await show.click();
+    await expect(details).toBeVisible();
+    await expect(page.locator('#viewer-toolbar').getByRole('button', { name: 'Hide details', exact: true })).toHaveAttribute('aria-expanded', 'true');
+});
+
+test('reset restores defaults without touching other keys', async ({ page }) => {
+    await page.goto(`${workspace}#/system/appearance`);
+    await page.evaluate(() => localStorage.setItem('gallerySettings', JSON.stringify({ gridColumns: 5, defaultLimit: 200,
+        thumbnailPromptDismissed: 'kept', workspaceLayout: 'list', videoMute: false, showImageInfo: false })));
+    await page.reload();
+    await expect(page.locator('#timeout')).toBeEnabled();
+    await expect(page.locator('#default-view')).toHaveValue('list');
+    const reset = page.locator('#workspace-main .operation').filter({ hasText: 'Reset display defaults' }).getByRole('button', { name: 'Reset', exact: true });
+    await reset.click();
+    await expect(page.locator('#default-view')).toHaveValue('grid');
+    await expect(page.locator('#video-muted')).toBeChecked();
+    await expect(statusOf(page)).toHaveText('Unsaved changes.');
+    await saveAppearance(page, 'Saved in this browser.');
+    const stored = await storedSettings(page);
+    expect(stored).toEqual({ gridColumns: 5, defaultLimit: 200, thumbnailPromptDismissed: 'kept', workspaceLayout: 'grid',
+        videoMute: true, showImageInfo: true });
+});

tests/browser/workspace-tagging.spec.mjs

@@ -602,6 +602,10 @@ test('a save under a Tags filter re-reads the listing: the selection stays while
 
 test('a save under a search keeps the scroll position and the loaded range', async ({ page, request }) => {
     await expect(await request.post('/__test__/tagging/reset', { data: { extra_images: 140 } })).toBeOK();
+    // Listing pages still in flight: one that lands after the scroll below would grow the loaded range.
+    const inFlight = new Set();
+    page.on('request', item => { if (item.url().includes('/images/output?')) inFlight.add(item); });
+    for (const done of ['requestfinished', 'requestfailed']) page.on(done, item => inFlight.delete(item));
     await page.goto(images);
     const searched = listingOf(page, query => query.get('q') === 'bulk');
     await page.getByRole('searchbox', { name: 'Search workspace', exact: true }).fill('bulk');
@@ -615,6 +619,9 @@ test('a save under a search keeps the scroll position and the loaded range', asy
     await expect.poll(async () => { await continuation.scrollIntoViewIfNeeded(); return loadedCount(); }).toBeGreaterThanOrEqual(80);
     await page.evaluate(() => window.scrollTo(0, Math.round(document.documentElement.scrollHeight / 3)));
     await expect(continuation).not.toBeInViewport();
+    // A load the continuation scheduled for the next frame has started by now; wait for every page to land.
+    await page.evaluate(() => new Promise(done => requestAnimationFrame(() => requestAnimationFrame(done))));
+    await expect.poll(() => inFlight.size).toBe(0);
     const loaded = await continuation.textContent();
     await expect.poll(() => continuation.textContent()).toBe(loaded);
     const y = await page.evaluate(() => window.scrollY);

tests/browser/workspace-thumbnails.spec.mjs

@@ -0,0 +1,170 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+
+/**
+ * #249: cards and strips load previews, never the full file. The approved mock has no repeated thumbnail prompt
+ * (docs/concepts/workspace/README.md), so a preview that was not made yet is made by the server on first view:
+ * the listing still names the `_thumb` URL. Only the media viewer's main image (and downloads) load the original.
+ */
+const images = '/prompt_manager/workspace#/images';
+const library = '/prompt_manager/workspace#/library';
+const cards = page => page.locator('article[data-image-key]');
+const details = page => page.getByRole('complementary', { name: 'Selected image details', exact: true });
+const SERVE = '/prompt_manager/images/serve/';
+
+/** Every media file the page asks the server for, as `{path, preview}` (path relative to its root). */
+function recordMedia(page) {
+    const seen = [];
+    page.on('request', request => {
+        const url = new URL(request.url());
+        if (!url.pathname.startsWith(SERVE)) return;
+        const path = decodeURIComponent(url.pathname.slice(SERVE.length));
+        seen.push({ path, preview: /^thumbnails\/.+_thumb\.[a-z0-9]+$/.test(path) });
+    });
+    return seen;
+}
+/** Every card image has loaded (or failed): what it asked for is all in `seen`. */
+const settled = page => page.evaluate(() => Promise.all([...document.querySelectorAll('article img')].map(image => image.decode().catch(() => {}))));
+const originals = seen => seen.filter(item => !item.preview).map(item => item.path);
+
+test.beforeEach(async ({ page, browserName }) => {
+    await startCoverage(page, browserName);
+    page.thumbErrors = [];
+    page.on('pageerror', error => page.thumbErrors.push(error.message));
+});
+test.afterEach(async ({ page, browserName }) => {
+    await saveCoverage(page, browserName);
+    expect(page.thumbErrors).toEqual([]);
+});
+
+test('a page of the Images grid requests previews, never originals, in every layout and size', async ({ page, request }) => {
+    await expect(await request.post('/__test__/reset')).toBeOK();
+    // Newest outputs with no preview yet: the live finding (844 such files listed with a null thumbnail).
+    await expect(await request.post('/__test__/system/unthumbnailed', { data: { count: 6 } })).toBeOK();
+    const listing = await (await request.get('/prompt_manager/images/output?limit=40')).json();
+    const fresh = listing.images.filter(image => image.path.startsWith('unthumbnailed/'));
+    expect(fresh).toHaveLength(6);
+    for (const image of fresh) expect(image.thumbnail_url).toMatch(/\/thumbnails\/unthumbnailed\/plain_\d{3}_thumb\.webp\?root=0/);
+    const seen = recordMedia(page);
+    await page.goto(images);
+    await expect(cards(page)).toHaveCount(8);
+    await settled(page);
+    expect(originals(seen)).toEqual([]);
+    expect(seen.filter(item => item.path.startsWith('thumbnails/unthumbnailed/'))).toHaveLength(6);
+    // The server made them on that first view.
+    await expect.poll(async () => (await (await request.get('/prompt_manager/images/thumbnails/status')).json()).pending).toBe(0);
+    for (const layout of ['List', 'Masonry', 'Grid']) {
+        await page.getByRole('button', { name: layout, exact: true }).click();
+        await expect(page.getByRole('button', { name: layout, exact: true })).toHaveAttribute('aria-pressed', 'true');
+        for (const density of ['large', 'compact', 'comfortable']) {
+            await page.getByRole('combobox', { name: 'Thumbnail size', exact: true }).selectOption(density);
+            await expect(cards(page)).toHaveCount(8);
+            await settled(page);
+        }
+    }
+    expect(originals(seen)).toEqual([]);
+});
+
+test('the inspector cover is the preview and only the media viewer loads the original', async ({ page, request }) => {
+    await expect(await request.post('/__test__/reset')).toBeOK();
+    await expect(await request.post('/__test__/system/unthumbnailed', { data: { count: 1 } })).toBeOK();
+    const seen = recordMedia(page);
+    await page.goto(images);
+    const card = cards(page).filter({ hasText: 'plain_001.png' });
+    await card.getByRole('button', { name: 'Inspect plain_001.png', exact: true }).click();
+    const cover = details(page).locator('img.detail-cover');
+    await expect(cover).toHaveAttribute('src', /\/thumbnails\/unthumbnailed\/plain_001_thumb\.webp\?/);
+    await settled(page);
+    await cover.evaluate(image => image.decode().catch(() => {}));
+    expect(originals(seen)).toEqual([]);
+    await card.getByRole('button', { name: 'Open plain_001.png', exact: true }).click();
+    await expect(page.locator('dialog#viewer-dialog')).toBeVisible();
+    await expect.poll(() => originals(seen)).toEqual(['unthumbnailed/plain_001.png']);
+    await page.getByRole('button', { name: 'Close image viewer', exact: true }).click();
+});
+
+test('a video card shows its preview frame instead of loading the video', async ({ page, request }) => {
+    await expect(await request.post('/__test__/reset', { data: { include_video: true } })).toBeOK();
+    const seen = recordMedia(page);
+    await page.goto(images);
+    const card = cards(page).filter({ hasText: 'clip.webm' });
+    await expect(card.locator('.media-art > .image-open > img')).toHaveAttribute('src', /\/thumbnails\/clip_thumb\.webp\?/);
+    await expect(card.locator('video')).toHaveCount(0);
+    await settled(page);
+    expect(originals(seen)).toEqual([]);
+});
+
+test('Library cards and the shared gallery request previews only', async ({ page, request }) => {
+    await expect(await request.post('/__test__/reset', { data: { native_library: true } })).toBeOK();
+    const seen = recordMedia(page);
+    await page.goto(library);
+    const cat = page.locator('article[data-prompt-id]').filter({ has: page.getByText('Cat portrait', { exact: true }) });
+    await expect(cat.locator('.card-art img')).not.toHaveCount(0);
+    await settled(page);
+    expect(seen.length).toBeGreaterThan(0);
+    expect(originals(seen)).toEqual([]);
+});
+
+test('a video whose preview cannot be loaded swaps back to its own element', async ({ page, request }) => {
+    await expect(await request.post('/__test__/reset', { data: { include_video: true } })).toBeOK();
+    await page.route(url => url.pathname.endsWith('/thumbnails/clip_thumb.webp'), route => route.fulfill({ status: 404, body: '' }));
+    await page.goto(images);
+    const card = cards(page).filter({ hasText: 'clip.webm' });
+    await expect(card.locator('.media-art > .image-open > video')).toHaveCount(1);
+    await expect(card.locator('.media-art > .image-open > img')).toHaveCount(0);
+    await card.getByRole('button', { name: 'Inspect clip.webm', exact: true }).click();
+    await expect(details(page).locator('video.detail-cover')).toHaveCount(1);
+    await expect(details(page).locator('img.detail-cover')).toHaveCount(0);
+});
+
+test('an image listed without a preview (a nested thumbnails folder) shows its original', async ({ page, request }) => {
+    await expect(await request.post('/__test__/reset')).toBeOK();
+    // M10: such files are listed with a null thumbnail_url; the card falls back to the original as before.
+    await page.route(url => url.pathname === '/prompt_manager/images/output', async route => {
+        const response = await route.fetch();
+        const body = await response.json();
+        if (Array.isArray(body.images)) body.images = body.images.map(image => ({ ...image, thumbnail_url: null }));
+        await route.fulfill({ response, json: body });
+    });
+    const seen = recordMedia(page);
+    await page.goto(images);
+    await expect(cards(page)).toHaveCount(2);
+    await settled(page);
+    expect(seen.length).toBeGreaterThan(0);
+    expect(seen.every(item => !item.preview)).toBe(true);
+});
+
+test('a JPEG XL thumbnail this browser cannot show loads the original; one it can show is used (#317)', async ({ page, request }) => {
+    await expect(await request.post('/__test__/reset')).toBeOK();
+    await expect(await request.post('/__test__/system/reset')).toBeOK();
+    try {
+        await expect(await request.post('/__test__/system/jxl-encoder', { data: { available: true } })).toBeOK();
+        const saved = await request.post('/prompt_manager/settings', { data: { thumbnail_format: 'jxl' } });
+        await expect(saved).toBeOK();
+        await expect(await request.post('/__test__/system/unthumbnailed', { data: { count: 1 } })).toBeOK();
+        const listing = await (await request.get('/prompt_manager/images/output?limit=40')).json();
+        const fresh = listing.images.find(image => image.path === 'unthumbnailed/plain_001.png');
+        expect(fresh.thumbnail_url).toMatch(/\/thumbnails\/unthumbnailed\/plain_001_thumb\.jxl\?root=0/);
+        await page.goto(images);
+        // What this browser does with JPEG XL, decided the way the workspace decides it (an embedded probe).
+        const decodes = await page.evaluate(() => new Promise(resolve => {
+            const probe = new Image();
+            probe.onload = () => resolve(true);
+            probe.onerror = () => resolve(false);
+            probe.src = 'data:image/jxl;base64,/woAkAEAE4gCALQAtZ8gAAAVKqOMG7yc6/nyQ4fFtI3rDG21bWEJY7O9MEhIOGwY4s3xwRCTShIA';
+        }));
+        const card = cards(page).filter({ hasText: 'plain_001.png' });
+        const media = card.locator('.media-art > .image-open > img');
+        // A browser without JPEG XL shows the original; one with it shows the preview, or the original when the
+        // preview cannot be made here (no real encoder in the test server): never a broken image.
+        if (!decodes) await expect(media).toHaveAttribute('src', /\/unthumbnailed\/plain_001\.png\?root=0/);
+        await expect.poll(() => media.evaluate(image => image.complete && image.naturalWidth > 0)).toBe(true);
+        // The inspector cover follows the same rule.
+        await card.getByRole('button', { name: 'Inspect plain_001.png', exact: true }).click();
+        const cover = details(page).locator('img.detail-cover');
+        if (!decodes) await expect(cover).toHaveAttribute('src', /\/unthumbnailed\/plain_001\.png\?/);
+        await expect.poll(() => cover.evaluate(image => image.complete && image.naturalWidth > 0)).toBe(true);
+    } finally {
+        await request.post('/__test__/system/reset');
+    }
+});

tests/browser/workspace-visual.spec.mjs

@@ -173,7 +173,8 @@ test('visual fixture exposes real stable media and library records', async ({ re
     await expect(await request.get(image.url)).toBeOK();
     const thumbnail = await request.get(image.thumbnail_url);
     await expect(thumbnail).toBeOK();
-    expect(thumbnail.headers()['content-type']).toBe('image/png');
+    // #317: previews are written as WebP by default.
+    expect(thumbnail.headers()['content-type']).toBe('image/webp');
     const inspection = await (await request.get(`/prompt_manager/images/inspect/${encodeURIComponent(image.path)}?root=${image.root_index}`)).json();
     expect(inspection.success).toBe(true);
     expect(inspection.image.path).toBe(image.path);

tests/browser/workspace.spec.mjs

@@ -22,6 +22,8 @@ const routes = [
     ['system', 'System', null],
     // #249 D51: SAVED VIEWS' Favorites, Images filtered to favorites.
     ['favorites', 'Favorites', null],
+    // #249 PR F (ruling R5): SAVED VIEWS' Needs review, the concept's Metadata review page (its own heading).
+    ['review', 'Needs review', null, 'Metadata review'],
     // #249 Activity-1: the concept's Activity page in the tools-and-system group.
     ['activity', 'Activity', null],
 ];
@@ -77,10 +79,10 @@ test('workspace starts with real persisted statistics without mutating data', as
 });
 
 test('all shell destinations deep-link, reload and expose working existing applications', async ({ page, request }) => {
-    for (const [route, label, legacy] of routes) {
+    for (const [route, label, legacy, title = label] of routes) {
         await page.goto(`${workspace}#/${route}`);
         const main = page.locator('#workspace-main');
-        await expect(main.getByRole('heading', { level: 1, name: label, exact: true })).toBeVisible();
+        await expect(main.getByRole('heading', { level: 1, name: title, exact: true })).toBeVisible();
         await expect(sidebarLink(page, label)).toHaveAttribute('aria-current', 'page');
         if (route === 'tags' || route === 'inspect') await expect(main.locator('.handoff')).toHaveCount(0);
         if (route === 'inspect') await expect(main.locator('#local-file')).toBeAttached();
@@ -89,7 +91,7 @@ test('all shell destinations deep-link, reload and expose working existing appli
             await expect(await request.get(legacy.split('#')[0])).toBeOK();
         }
         await page.reload();
-        await expect(main.getByRole('heading', { level: 1, name: label, exact: true })).toBeVisible();
+        await expect(main.getByRole('heading', { level: 1, name: title, exact: true })).toBeVisible();
     }
     // D29 and #249 E3: the legacy gallery and Library are reached from Overview's tool cards, not from their pages.
     await page.goto(`${workspace}#/overview`);
@@ -309,9 +311,9 @@ test('overview reports loading, offers retry after failure and renders real empt
 test('small screens keep navigation and the theme accessible without horizontal page overflow', async ({ page }) => {
     await page.setViewportSize({ width: 375, height: 812 });
     await page.goto(`${workspace}#/overview`);
-    for (const [, label] of routes) {
+    for (const [, label, , title = label] of routes) {
         await sidebarLink(page, label).click();
-        await expect(page.locator('#workspace-main h1')).toHaveText(label);
+        await expect(page.locator('#workspace-main h1')).toHaveText(title);
     }
     await expect(page.getByRole('combobox', { name: 'Theme', exact: true })).toBeVisible();
     expect(await page.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth)).toBe(true);
@@ -411,7 +413,7 @@ for (const width of [1600, 390]) test(`overview and handoff render with concept
 
     await sidebarLink(page, 'System').click();
     // System's Overview is native (S2 Task 6); a section not delivered yet still hands off (D94).
-    await main.locator('.section-nav').getByRole('button', { name: 'Integrations', exact: true }).click();
+    await main.locator('.section-nav').getByRole('button', { name: 'Auto-tagging', exact: true }).click();
     const handoff = main.locator('section.handoff');
     await expect(handoff).toHaveClass(/\bsurface\b/);
     expect(await handoff.evaluate(surfaceStyle)).toMatchObject(SURFACE);
@@ -425,8 +427,6 @@ for (const width of [1600, 390]) test(`overview and handoff render with concept
 const SYSTEM_SECTION_LABELS = ['Overview', 'Appearance', 'Sources & scans', 'Integrations', 'Auto-tagging', 'Maintenance',
     'Backup & export', 'Diagnostics & logs'];
 const SYSTEM_HASHES = ['overview', 'appearance', 'sources', 'integrations', 'tagging', 'maintenance', 'backups', 'diagnostics'];
-const SYSTEM_HANDOFFS = { appearance: ['/prompt_manager/gallery', '/prompt_manager/admin'], sources: ['/prompt_manager/admin', '/prompt_manager/gallery'],
-    maintenance: ['/prompt_manager/admin', '/prompt_manager/gallery'] };
 
 test('System is native: the concept shell, section navigation, sections, hand-offs and the Save row', async ({ page }) => {
     const mutations = [];
@@ -462,18 +462,25 @@ test('System is native: the concept shell, section navigation, sections, hand-of
         await expect(nav.locator('[aria-pressed="true"]')).toHaveCount(1);
         // The section changes in place: focus stays on the pressed section, not the page title.
         await expect(button).toBeFocused();
-        // S2 Task 6: Overview is native (workspace-system.spec.mjs); Maintenance shows its health-check notice above
-        // the hand-off (D123); every other section hands off.
+        // S2 Task 6: Overview is native (workspace-system.spec.mjs), and so are Appearance (S3 Task 8) and Sources & scans
+        // (S4 Task 11, workspace-system-sources.spec.mjs, its update notice shown in a fresh browser), Integrations (S10
+        // Task 27, workspace-system-integrations.spec.mjs), Maintenance (S7 Task 19,
+        // workspace-system-maintenance.spec.mjs) and Backup & export (S9 Task 24, workspace-system-backups.spec.mjs);
+        // every other section hands off.
         if (hash === 'overview') await expect(layout.locator(':scope > .summary-metrics')).toBeVisible();
+        if (hash === 'sources') await expect(layout.locator('#source-list .operation')).toHaveCount(2);
         expect(await layout.evaluate(node => [...node.children].map(child => `${child.localName}.${child.className}`)))
-            .toEqual({ overview: ['div.summary-metrics', 'div.two-col', 'div.save-row'],
-                maintenance: ['div.notice', 'section.surface handoff', 'div.save-row'] }[hash]
+            .toEqual({ overview: ['div.summary-metrics', 'div.two-col', 'div.save-row'], appearance: ['section.surface', 'section.surface', 'div.save-row'],
+                sources: ['div.notice', 'section.surface', 'div.save-row'],
+                integrations: ['section.surface', 'section.surface', 'div.save-row'],
+                maintenance: ['div.notice', 'section.surface', 'section.surface', 'div.save-row'],
+                backups: ['div.two-col', 'section.surface', 'div.save-row'] }[hash]
                 ?? ['section.surface handoff', 'div.save-row']);
-        if (hash === 'overview') continue;
+        if (['overview', 'appearance', 'sources', 'integrations', 'maintenance', 'backups'].includes(hash)) continue;
         const handoff = layout.locator('section.handoff');
         await expect(handoff.locator('h2')).toHaveText('Your current tools are ready');
         expect(await handoff.locator('a.workspace-link').evaluateAll(links => links.map(link => link.getAttribute('href'))))
-            .toEqual(SYSTEM_HANDOFFS[hash] ?? ['/prompt_manager/admin']);
+            .toEqual(['/prompt_manager/admin']);
         await expect(layout.locator('#settings-status')).toHaveText('No unsaved changes.');
         await expect(page.locator('aside.sidebar a[href="#/system"]')).toHaveAttribute('aria-current', 'page');
     }

tests/browser/workspace_activity_fixture.py

@@ -5,18 +5,23 @@ reading files, so a test sets its progress and counters exactly:
 
 - ``POST /__test__/jobs/start`` starts one (``kind``, ``title``, ``total``,
   ``output_folders``; for ``kind: "image-tags"`` the image tagging job's
-  groups and its ``{mode, images}`` scope instead) and returns its summary,
-  or 409 while one runs;
+  groups and its ``{mode, images}`` scope instead; for ``kind:
+  "thumbnails"`` the thumbnail job's groups, ``guarded`` admission and its
+  ``{mode, size, quality, output_folders}`` scope; for ``kind: "health"`` the
+  health check's: no groups, ``read``, not cancellable, with its status
+  line) and returns its summary, or 409 while one runs;
 - ``POST /__test__/jobs/{id}/step`` records ``records`` (``{group, path,
   root, root_index, detail}`` file outcomes, counted, listed and logged as the scan
   records them) and ``bulk`` (``{group, count, root}``: ``count`` numbered
   rows), sets ``processed`` (and ``total``) and ``counters``, then publishes
   the progress to every subscriber;
 - ``POST /__test__/jobs/{id}/finish`` ends it as ``finished``, ``cancelled``
-  or ``failed``; a cancel through the real route ends it ``cancelled``;
-- ``POST /__test__/jobs/hold`` opens a legacy-page hold (``kind``, ``title``):
-  a running, non-cancellable ``records`` job, as a legacy restore or
-  maintenance request takes, until ``finish`` ends it;
+  or ``failed``, with the runner's final ``status_line`` when given; a cancel
+  through the real route ends it ``cancelled``;
+- ``POST /__test__/jobs/hold`` opens a legacy-page hold (``kind``, ``title``,
+  ``admission``, default ``records``): a running, non-cancellable job with no
+  outcome groups, as a legacy restore, maintenance or thumbnail clear request
+  takes, until ``finish`` ends it;
 - ``POST /__test__/jobs/restart`` acts out a ComfyUI restart: the open job
   streams drop without a final event and the registry starts empty.
 """
@@ -35,6 +40,9 @@ PREFIXES = {"added": "+", "known": "=", "review": "?", "errors": "!"}
 PREFIXES["no_metadata"] = "-"
 # The image tagging job's groups (#249 PR D), logged with the runner's prefixes.
 PREFIXES.update({"tagged": "+", "unchanged": "=", "skipped": "-"})
+# The thumbnail job's (#249 System S5).
+PREFIXES["generated"] = "+"
+HEALTH_STATUS_LINE = "Checking the database and image links"
 ROOT_INDEXES = {"output": 0, "input": 1}
 
 
@@ -80,9 +88,12 @@ def outcome_records(data):
 
 def register_activity_commands(app, routes, api):
     from py.api.jobs import (
+        HEALTH_JOB_KIND,
         IMAGE_TAG_GROUP_NAMES,
         IMAGE_TAG_JOB_KIND,
         SCAN_GROUP_NAMES,
+        THUMBNAIL_GROUP_NAMES,
+        THUMBNAILS_JOB_KIND,
         JobBusy,
         JobRegistry,
     )
@@ -138,7 +149,21 @@ def register_activity_commands(app, routes, api):
         data = await body(request)
         ending = asyncio.get_running_loop().create_future()
         kind = str(data.get("kind", "scan"))
-        if kind == IMAGE_TAG_JOB_KIND:
+        admission, cancellable = "records", True
+        if kind == THUMBNAILS_JOB_KIND:
+            title = "Thumbnail generation"
+            scope = {
+                "mode": str(data.get("mode", "missing")),
+                "size": count(data.get("size"), 512),
+                "quality": str(data.get("quality", "medium")),
+                "output_folders": count(data.get("output_folders"), 2),
+            }
+            groups = THUMBNAIL_GROUP_NAMES
+            admission = "guarded"
+        elif kind == HEALTH_JOB_KIND:
+            title, scope, groups = "Health check", {}, ()
+            admission, cancellable = "read", False
+        elif kind == IMAGE_TAG_JOB_KIND:
             title = "Add tags to images"
             scope = {
                 "mode": str(data.get("mode", "add")),
@@ -150,13 +175,20 @@ def register_activity_commands(app, routes, api):
             scope = {
                 "files": str(data.get("files", "new")),
                 "output_folders": count(data.get("output_folders"), 2),
+                # A real scan's count of its files in the Needs review queue.
+                **(
+                    {"review_items": count(data["review_items"])}
+                    if "review_items" in data
+                    else {}
+                ),
             }
             groups = SCAN_GROUP_NAMES
         try:
             job = api._jobs.start(
                 kind,
                 str(data.get("title", title)),
-                record_changing=True,
+                admission=admission,
+                cancellable=cancellable,
                 scope=scope,
                 runner=fake_runner(ending),
                 groups=groups,
@@ -164,6 +196,8 @@ def register_activity_commands(app, routes, api):
         except JobBusy:
             raise web.HTTPConflict()
         job.update(total=count(data.get("total")))
+        if kind == HEALTH_JOB_KIND:
+            job.update(status_line=HEALTH_STATUS_LINE)
         endings[job.id] = ending
         return web.json_response({"success": True, "job": job.summary()})
 
@@ -178,7 +212,7 @@ def register_activity_commands(app, routes, api):
             async with api._jobs.hold(
                 str(data.get("kind", "restore")),
                 str(data.get("title", "Database restore (admin page)")),
-                admission="records",
+                admission=str(data.get("admission", "records")),
             ) as job:
                 entered.set_result(job)
                 state = await ending
@@ -226,9 +260,12 @@ def register_activity_commands(app, routes, api):
     @routes.post("/__test__/jobs/{job_id}/finish")
     async def finish_job(request):
         job = job_or_404(request)
-        state = (await body(request)).get("state", "finished")
+        data = await body(request)
+        state = data.get("state", "finished")
         if state not in FINAL_STATES:
             raise web.HTTPBadRequest()
+        if isinstance(data.get("status_line"), str):  # the runner's final line
+            job.update(status_line=data["status_line"])
         ending = endings[job.id]
         if not ending.done():
             ending.set_result(state)

tests/browser/workspace_concept_fixture.py

@@ -176,6 +176,8 @@ _TABLES = (
     "execution_context_texts",
     "saved_views",
     "image_favorites",
+    "media_review_decisions",
+    "media_review_items",
     "media_image_tags",
     "media_annotation_bytes",
     "media_annotation_files",
@@ -511,7 +513,12 @@ def seed_workspace_concept(
         tags = [row[0] for row in conn.execute("SELECT name FROM tags ORDER BY id")]
     if tuple(counts) != (len(CONCEPT_PROMPTS), CONCEPT_RUN_COUNT, CONCEPT_RUN_COUNT):
         raise RuntimeError(f"Concept fixture run counts are not real: {tuple(counts)}")
-    api._generate_gallery_thumbnails_sync(api._get_all_output_dirs(), (150, 150))
+    from py.api.thumbnail_settings import ThumbnailSettings
+
+    # 150 px previews in the default format (#317 thumbnail settings).
+    api._generate_gallery_thumbnails_sync(
+        api._get_all_output_dirs(), ThumbnailSettings("webp", 80, 150)
+    )
     api.invalidate_gallery_cache()
     return {
         "epoch": epoch,

tests/browser/workspace_integrations_fixture.py

@@ -0,0 +1,198 @@
+"""System › Integrations test hooks for the browser tests (#249 System S10).
+
+A fake LoraManager install lives under this server's temp root; nothing ever
+reaches a real LoraManager, ComfyUI install or the network:
+
+- ``POST /__test__/integrations/reset`` turns the integration off (no path,
+  no key, no trigger words), removes the fake install, its LoRA folder and
+  the image cache, forgets every LoRA import and injected failure, and opens
+  the download gate;
+- ``POST /__test__/integrations/lora-manager`` ``{loras, civitai, previous}``
+  writes ``custom_nodes/ComfyUI-Lora-Manager`` (detected through the
+  ``folder_paths`` stub's base path) and ``loras`` metadata files under
+  ``models/loras``, each with a local preview PNG; ``civitai`` adds one
+  CivitAI example image per LoRA (served by the stub opener below);
+  ``previous`` saves that many earlier ``lora-manager`` imports with tags and
+  image links;
+- ``POST /__test__/integrations/gate`` ``{hold}`` holds every CivitAI
+  download until it is released (``{"hold": false}``), so a test sees the job
+  while it downloads;
+- ``POST /__test__/integrations/fail-import`` makes the next collection
+  replacement fail (a database error after staging);
+- ``POST /__test__/integrations/pair`` saves a pair whose positive is the first
+  imported prompt (a saved pair that blocks the replacement);
+- ``GET /__test__/integrations/state`` answers the imported prompt texts,
+  whether a CivitAI key is saved and the downloads served.
+
+CivitAI downloads are always answered by a stub opener (a small PNG), so no
+test ever opens a network connection.
+"""
+
+import io
+import json
+import shutil
+import threading
+from pathlib import Path
+
+from aiohttp import web
+from PIL import Image
+
+MAX_LORAS = 20
+CATEGORY = "lora-manager"
+
+
+def _png():
+    buffer = io.BytesIO()
+    Image.new("RGB", (8, 8), "#3a6ea5").save(buffer, "PNG")
+    return buffer.getvalue()
+
+
+class _Response:
+    def __init__(self, body):
+        self._body = io.BytesIO(body)
+        self.headers = {"Content-Length": str(len(body))}
+
+    def read(self, amount=-1):
+        return self._body.read(amount)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+def register_integrations_commands(app, routes, api, root: Path):
+    from py import lora_utils
+    from py.config import IntegrationConfig
+    from utils.hashing import generate_prompt_hash
+
+    lora_manager = root / "custom_nodes" / "ComfyUI-Lora-Manager"
+    loras = root / "models" / "loras"
+    gate = threading.Event()
+    gate.set()
+    served = []
+    failures = {"replace": 0}
+    pairs = []  # the blocking pairs this fixture saved
+    real_replace = type(api.db).replace_category_prompts
+
+    def stub_open(request, timeout=10):
+        served.append(request.full_url)
+        gate.wait(30)
+        return _Response(_png())
+
+    lora_utils._open_url = stub_open
+
+    def replace(db, *args, **kwargs):
+        if failures["replace"] > 0:
+            failures["replace"] -= 1
+            raise RuntimeError("Injected replacement failure")
+        return real_replace(db, *args, **kwargs)
+
+    type(api.db).replace_category_prompts = replace
+
+    def reset():
+        IntegrationConfig.LORA_MANAGER_ENABLED = False
+        IntegrationConfig.LORA_MANAGER_PATH = ""
+        IntegrationConfig.LORA_TRIGGER_WORDS_ENABLED = False
+        IntegrationConfig.CIVITAI_API_KEY = ""
+        lora_utils.get_trigger_cache().clear()
+        gate.set()
+        served.clear()
+        failures["replace"] = 0
+        cache = Path(lora_utils.get_lora_image_cache_dir(create=False))
+        for folder in (lora_manager, loras, cache):
+            shutil.rmtree(folder, ignore_errors=True)
+        for pair_id in pairs:
+            api.db.delete_prompt_pair(pair_id)
+        pairs.clear()
+        real_replace(api.db, CATEGORY, [], allow_empty=True)
+
+    @routes.post("/__test__/integrations/reset")
+    async def integrations_reset(request):
+        reset()
+        return web.json_response({"success": True})
+
+    @routes.post("/__test__/integrations/lora-manager")
+    async def make_lora_manager(request):
+        data = await request.json() if request.can_read_body else {}
+        count = data.get("loras", 2)
+        previous = data.get("previous", 0)
+        for value in (count, previous):
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise web.HTTPBadRequest()
+        if not 0 <= count <= MAX_LORAS or not 0 <= previous <= MAX_LORAS:
+            raise web.HTTPBadRequest()
+        (lora_manager / "py").mkdir(parents=True, exist_ok=True)
+        (lora_manager / "__init__.py").write_text("")
+        loras.mkdir(parents=True, exist_ok=True)
+        for number in range(count):
+            stem = f"style_{number + 1:02}"
+            civitai = {"trainedWords": [f"trigger{number + 1}"]}
+            if data.get("civitai") is True:
+                civitai["images"] = [
+                    {
+                        "url": f"https://image.civitai.com/x/{stem}.jpeg",
+                        "meta": {"prompt": f"{stem} example prompt"},
+                    }
+                ]
+            meta = {
+                "file_name": f"{stem}.safetensors",
+                "model_name": f"Style {number + 1:02}",
+                "civitai": civitai,
+            }
+            (loras / f"{stem}.metadata.json").write_text(json.dumps(meta))
+            (loras / f"{stem}.png").write_bytes(_png())
+        for number in range(previous):
+            text = f"previous lora import {number + 1}"
+            prompt_id = api.db.save_prompt(
+                text=text,
+                category=CATEGORY,
+                tags=[CATEGORY, f"lora:previous-{number + 1}"],
+                prompt_hash=generate_prompt_hash(text),
+            )
+            api.db.link_image_to_prompt(str(prompt_id), str(loras / "old.png"))
+        return web.json_response({"success": True})
+
+    @routes.post("/__test__/integrations/gate")
+    async def download_gate(request):
+        data = await request.json()
+        if not isinstance(data.get("hold"), bool):
+            raise web.HTTPBadRequest()
+        if data["hold"]:
+            gate.clear()
+        else:
+            gate.set()
+        return web.json_response({"success": True})
+
+    @routes.post("/__test__/integrations/fail-import")
+    async def fail_import(request):
+        failures["replace"] = 1
+        return web.json_response({"success": True})
+
+    @routes.post("/__test__/integrations/pair")
+    async def pair(request):
+        with api.db.model.get_connection() as conn:
+            row = conn.execute(
+                "SELECT text FROM prompts WHERE category = ? ORDER BY id LIMIT 1",
+                (CATEGORY,),
+            ).fetchone()
+        if row is None:
+            raise web.HTTPConflict()
+        pairs.append(api.db.save_prompt_pair(row[0], "blurry"))
+        return web.json_response({"success": True})
+
+    @routes.get("/__test__/integrations/state")
+    async def state(request):
+        imports = api.db.search_prompts(category=CATEGORY, limit=MAX_LORAS * 2)
+        return web.json_response(
+            {
+                "imports": sorted(prompt["text"] for prompt in imports),
+                "key_saved": bool(IntegrationConfig.CIVITAI_API_KEY),
+                "enabled": IntegrationConfig.LORA_MANAGER_ENABLED,
+                "trigger_words": IntegrationConfig.LORA_TRIGGER_WORDS_ENABLED,
+                "downloads": len(served),
+            }
+        )
+
+    return reset

tests/browser/workspace_library_editor_fixture.py

@@ -28,6 +28,8 @@ EDITOR_METADATA = {
 _TABLES = (
     "saved_views",
     "image_favorites",
+    "media_review_decisions",
+    "media_review_items",
     "media_image_tags",
     "media_annotation_bytes",
     "media_annotation_files",

tests/browser/workspace_review_fixture.py

@@ -0,0 +1,388 @@
+"""Owned, deterministic Needs review items for the workspace page (#249 PR F).
+
+Each file is a PNG whose workflow has two samplers with their own positive
+encoders and one shared negative, so the resolver finds it ``ambiguous``. Its
+loader node carries ComfyUI's ``Infinity`` stamp, which the legacy pages'
+parser (the scan's fallback) cannot read, so nothing links the file and it is
+a Needs review case (#284: only ambiguous, unlinked files are queued). It is
+recorded through the scan's recorder (``_record_review_sync`` with
+``inspection=True``; only scans add items). No path or SQL comes from a
+request.
+
+``POST /__test__/review/reset`` also takes the special items F2 needs, queued
+after the plain ones in this order:
+
+- ``conflict``: an item whose file was linked to another prompt ("Misty
+  forest path") after it was queued (the next scan or monitor pass would
+  remove the item); applying a sampler path then conflicts with that link.
+- ``limited``: a graph of 17 samplers, each with its own prompt, which the
+  recorder stores ``limited`` (more than 16 candidates, so none are stored).
+  An A1111 block with two negative lines is not queued any more: it offers
+  no candidate to choose (#284).
+- ``unavailable``: a file recorded under the ``temp`` directory while it was a
+  gallery root; the root is then removed again, so no current root lists it.
+
+``concept: true`` (F3, the concept comparison) names and sizes the plain
+files as the concept's first three images (app.js ``images``) and gives
+their first sampler the concept's first prompt (``alpine``: its positive and
+its first negative, the one the concept's panel shows), so the panel's text
+wraps as the concept's does.
+
+``POST /__test__/review/add {kind}`` adds one file while a page is open:
+``scan`` records a new ambiguous, unlinked output from a worker thread
+through the scan's recorder (as a running scan's batch does; the monitor
+never adds items), ``file`` only writes one (a metadata scan records it). ``GET
+/__test__/review/links`` answers each review file's prompt and pair links, and
+``GET /__test__/review/streams`` the open change streams and captures.
+``POST /__test__/review/notify`` sends one queue change notice without
+changing the queue: each open stream writes a ``change``, and a stream whose
+page closed is dropped at such a write.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from pathlib import Path
+import shutil
+import time
+from typing import TYPE_CHECKING
+
+from aiohttp import web
+from PIL import Image
+from PIL.PngImagePlugin import PngInfo
+
+if TYPE_CHECKING:
+    from py.api import PromptManagerAPI
+
+POSITIVES = ("Golden dunes at dusk", "Harbor lights at night")
+NEGATIVE = "Soft negative, blur"
+# The prompt the conflict item's file is linked to after it was queued.
+FALLBACK = "Misty forest path"
+SPECIAL = ("conflict", "limited", "unavailable")
+# The concept's first three images (concept app.js `images`) and first prompt.
+CONCEPT_IMAGES = (
+    ("alpine_00001.png", (1536, 1152)),
+    ("dunes_00001.png", (1024, 1536)),
+    ("forest_00001.png", (1280, 1280)),
+)
+CONCEPT_POSITIVE = (
+    "A remote alpine observatory at blue hour, warm light through glass, dramatic "
+    "mountain peaks, cinematic composition, atmospheric mist, fine detail"
+)
+CONCEPT_NEGATIVE = "blurry, low quality, low resolution"
+# More candidates than an item stores (16): the ``limited`` item.
+LIMITED_SAMPLERS = 17
+# More than one queue page (40), so Load more has a second page.
+MAX_ITEMS = 45
+_TABLES = (
+    "saved_views",
+    "image_favorites",
+    "media_review_decisions",
+    "media_review_items",
+    "media_image_tags",
+    "media_annotation_bytes",
+    "media_annotation_files",
+    "image_prompt_pairs",
+    "prompt_pair_tags",
+    "prompt_pairs",
+    "generated_images",
+    "prompt_tags",
+    "tags",
+    "prompt_library_state",
+    "prompts",
+)
+
+
+def _graph(
+    encoder_class: str = "CLIPTextEncode",
+    positives: tuple = POSITIVES,
+    negative: str = NEGATIVE,
+) -> dict:
+    graph = {
+        # ``Infinity`` (as ComfyUI writes it): the legacy parser cannot read the
+        # graph, so the scan's fallback links nothing and the file is queued.
+        "1": {
+            "class_type": "CheckpointLoaderSimple",
+            "inputs": {"ckpt_name": "m"},
+            "is_changed": [float("inf")],
+        },
+        "2": {"class_type": "CLIPTextEncode", "inputs": {"text": negative}},
+    }
+    for index, text in enumerate(positives):
+        encoder, sampler = str(10 + 2 * index), str(11 + 2 * index)
+        graph[encoder] = {"class_type": encoder_class, "inputs": {"text": text}}
+        graph[sampler] = {
+            "class_type": "KSampler",
+            "inputs": {
+                "model": ["1", 0],
+                "positive": [encoder, 0],
+                "negative": ["2", 0],
+            },
+        }
+    return graph
+
+
+def _png(
+    path: Path,
+    colour: tuple[int, int, int],
+    *,
+    graph: dict | None = None,
+    parameters: str | None = None,
+    size: tuple[int, int] = (96, 64),
+) -> None:
+    info = PngInfo()
+    if parameters is not None:
+        info.add_text("parameters", parameters)
+    else:
+        info.add_text("prompt", json.dumps(graph or _graph()))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with Image.new("RGB", size, colour) as image:
+        image.save(path, pnginfo=info)
+
+
+def _scan_record(api: PromptManagerAPI, path: Path) -> str:
+    """Record ``path`` as the scan's recorder does."""
+    from py.api.admin import _scan_roots
+
+    roots = _scan_roots(api._get_all_output_dirs())
+    return api._record_review_sync(Path(str(path)), roots, inspection=True)
+
+
+def _record(api: PromptManagerAPI, path: Path, expected: str) -> None:
+    outcome = _scan_record(api, path)
+    if outcome != expected:
+        raise RuntimeError(f"{path.name} was {outcome}, not {expected}")
+
+
+def _stamp(path: Path, age: float) -> None:
+    stamp = time.time() - age
+    os.utime(path, (stamp, stamp))
+
+
+class _ScanRecorder:
+    """The scan's recorder over this server's database (one per server)."""
+
+    def __init__(self, api: PromptManagerAPI) -> None:
+        self.api = api
+        self.lock = threading.Lock()
+
+    def new_output(self, path: Path) -> None:
+        """The scan's Needs review recording of a new output, from a worker thread."""
+        outcome = []
+        with self.lock:
+            worker = threading.Thread(
+                target=lambda: outcome.append(_scan_record(self.api, path))
+            )
+            worker.start()
+            worker.join()
+        if outcome != ["recorded"]:
+            raise RuntimeError(f"{path.name} was {outcome}, not recorded")
+
+
+def _scanned_output(api: PromptManagerAPI, recorder: _ScanRecorder, path: Path) -> None:
+    _png(path, (150, 60, 40))
+    recorder.new_output(path)
+
+
+def _linked_after_queueing(api: PromptManagerAPI, path: Path) -> None:
+    from utils.hashing import generate_prompt_hash
+
+    _png(path, (150, 60, 40))
+    _record(api, path, "recorded")
+    prompt = api.db.get_prompt_by_hash(generate_prompt_hash(FALLBACK))
+    prompt_id = (
+        prompt["id"]
+        if prompt is not None
+        else api.db.save_prompt(FALLBACK, prompt_hash=generate_prompt_hash(FALLBACK))
+    )
+    api.db.link_image_to_prompt(prompt_id, str(path))
+
+
+def _unavailable(api: PromptManagerAPI, root: Path, path: Path) -> None:
+    from py.config import GalleryConfig
+
+    roots = list(GalleryConfig.MONITORING_DIRECTORIES)
+    GalleryConfig.MONITORING_DIRECTORIES = [*roots, str(root / "temp")]
+    try:
+        _record(api, path, "recorded")
+    finally:
+        GalleryConfig.MONITORING_DIRECTORIES = roots
+
+
+def seed_review(
+    api: PromptManagerAPI,
+    root: Path,
+    items: int,
+    special: tuple = (),
+    recorder: _ScanRecorder | None = None,
+    concept: bool = False,
+) -> dict:
+    """Replace this server's disposable rows and files with ``items`` queued files."""
+    with api.db.model.get_connection() as conn:
+        for table in _TABLES:
+            conn.execute(f"DELETE FROM {table}")
+    api.close_annotation_captures()
+    for name in ("output", "input"):
+        shutil.rmtree(root / name)
+        (root / name).mkdir()
+    shutil.rmtree(root / "temp" / "review", ignore_errors=True)
+    output = root / "output"
+    files = []
+    for number in range(items):
+        relative = f"review/review_{number:04}.png"
+        options = {}
+        if concept:
+            name, size = CONCEPT_IMAGES[number % len(CONCEPT_IMAGES)]
+            relative = f"review/{name}" if number < len(CONCEPT_IMAGES) else relative
+            graph = _graph(
+                positives=(CONCEPT_POSITIVE, POSITIVES[1]), negative=CONCEPT_NEGATIVE
+            )
+            options = {"graph": graph, "size": size}
+        _png(output / relative, (40 + number * 4, 90, 140), **options)
+        _stamp(output / relative, 60 + number)
+        _record(api, output / relative, "recorded")
+        files.append({"path": relative, "filename": Path(relative).name})
+    for kind in SPECIAL:
+        if kind not in special:
+            continue
+        relative = f"review/{kind}.png"
+        path = (root / "temp" if kind == "unavailable" else output) / relative
+        if kind == "conflict":
+            _linked_after_queueing(api, path)
+        elif kind == "limited":
+            many = tuple(f"{POSITIVES[0]} {n}" for n in range(LIMITED_SAMPLERS))
+            _png(path, (90, 90, 90), graph=_graph(positives=many))
+            _record(api, path, "limited")
+        else:
+            _png(path, (20, 140, 90))
+            _unavailable(api, root, path)
+        files.append({"path": relative, "filename": path.name, "kind": kind})
+    api.invalidate_gallery_cache()
+    return {
+        "files": files,
+        "positives": list(POSITIVES),
+        "negative": NEGATIVE,
+        "fallback": FALLBACK,
+    }
+
+
+def add_review_file(
+    api: PromptManagerAPI, root: Path, kind: str, recorder: _ScanRecorder
+) -> dict:
+    """One more ambiguous output: recorded as a scan does, or only written."""
+    output = root / "output"
+    number = (
+        len(list((output / "added").glob("*.png")))
+        if (output / "added").exists()
+        else 0
+    )
+    relative = f"added/added_{number:04}.png"
+    if kind == "scan":
+        _scanned_output(api, recorder, output / relative)
+    else:
+        _png(output / relative, (200, 200, 40))
+    api.invalidate_gallery_cache()
+    return {"path": relative, "filename": Path(relative).name}
+
+
+_LINKS = (
+    "SELECT gi.filename, p.text AS prompt, pp.id AS pair_id, pos.text AS positive, "
+    "neg.text AS negative FROM generated_images gi "
+    "JOIN prompts p ON p.id = gi.prompt_id "
+    "LEFT JOIN image_prompt_pairs ipp ON ipp.image_id = gi.id "
+    "LEFT JOIN prompt_pairs pp ON pp.id = ipp.pair_id "
+    "LEFT JOIN prompts pos ON pos.id = pp.positive_prompt_id "
+    "LEFT JOIN prompts neg ON neg.id = pp.negative_prompt_id "
+    "ORDER BY gi.filename, gi.id, pp.id"
+)
+
+
+def review_links(api: PromptManagerAPI) -> list:
+    """Every file's prompt link and pair links, as plain rows."""
+    conn = api.db.model.get_connection()
+    return [dict(row) for row in conn.execute(_LINKS)]
+
+
+def register_review_commands(
+    routes: web.RouteTableDef, api: PromptManagerAPI, root: Path
+) -> None:
+    """Register the review fixture's commands; no path or SQL comes from a request."""
+    recorders = []
+
+    def recorder() -> _ScanRecorder:
+        if not recorders:
+            recorders.append(_ScanRecorder(api))
+        return recorders[0]
+
+    @routes.post("/__test__/review/reset")
+    async def reset(request: web.Request) -> web.Response:
+        data = await request.json() if request.can_read_body else {}
+        if (
+            request.query
+            or not isinstance(data, dict)
+            or set(data) - {"items", "concept", *SPECIAL}
+        ):
+            raise web.HTTPBadRequest()
+        items = data.get("items", 3)
+        if isinstance(items, bool) or not isinstance(items, int):
+            raise web.HTTPBadRequest()
+        if not 0 <= items <= MAX_ITEMS:
+            raise web.HTTPBadRequest()
+        if any(
+            not isinstance(data.get(kind, False), bool)
+            for kind in (*SPECIAL, "concept")
+        ):
+            raise web.HTTPBadRequest()
+        special = tuple(kind for kind in SPECIAL if data.get(kind))
+        manifest = await api._run_in_executor(
+            seed_review,
+            api,
+            root,
+            items,
+            special,
+            recorder(),
+            data.get("concept", False),
+        )
+        return web.json_response({"success": True, **manifest})
+
+    @routes.post("/__test__/review/add")
+    async def add(request: web.Request) -> web.Response:
+        data = await request.json() if request.can_read_body else None
+        if request.query or not isinstance(data, dict) or set(data) != {"kind"}:
+            raise web.HTTPBadRequest()
+        if data["kind"] not in ("scan", "file"):
+            raise web.HTTPBadRequest()
+        added = await api._run_in_executor(
+            add_review_file, api, root, data["kind"], recorder()
+        )
+        return web.json_response({"success": True, **added})
+
+    @routes.post("/__test__/review/notify")
+    async def notify(request: web.Request) -> web.Response:
+        if request.query or request.can_read_body:
+            raise web.HTTPBadRequest()
+        from database.review_changes import notify_review_change
+
+        notify_review_change(api.db.model.db_path)
+        return web.json_response({"success": True})
+
+    @routes.get("/__test__/review/links")
+    async def links(request: web.Request) -> web.Response:
+        if request.query:
+            raise web.HTTPBadRequest()
+        return web.json_response(
+            {"links": await api._run_in_executor(review_links, api)}
+        )
+
+    @routes.get("/__test__/review/streams")
+    async def streams(request: web.Request) -> web.Response:
+        """Open review change streams and held captures (teardown checks)."""
+        if request.query:
+            raise web.HTTPBadRequest()
+        store = api._captures
+        captures = store.stats()["captures"] if store is not None else 0
+        return web.json_response(
+            {"streams": api.review_stream_count(), "captures": captures}
+        )

tests/browser/workspace_system_fixture.py

@@ -11,16 +11,59 @@ read. These per-server hooks only change what a System test needs on top:
   requests for ``path`` (a ``/prompt_manager/system/`` route) with the routes'
   500 error envelope;
 - ``POST /__test__/system/missing-source`` configures one more source that
-  does not exist (an unmounted drive);
+  does not exist (an unmounted drive); with ``{"inside": true}`` it is an
+  existing folder inside the output folder (``output/unplugged``), which
+  ``POST /__test__/system/unplug`` then removes (a drive unplugged while the
+  page shows it);
 - ``POST /__test__/system/missing-file`` deletes the newest linked image's
   file from disk, leaving its database row (a missing-file link);
 - ``POST /__test__/system/unthumbnailed`` ``{count}`` writes ``count`` plain
-  PNGs with no thumbnail into the output folder.
+  PNGs with no thumbnail into the output folder;
+- ``POST /__test__/system/monitor`` ``{watching, alive}`` stands in a fake
+  image monitor whose observer is ``alive`` (default true) and schedules the
+  named folders of this server's root (``["output"]``), so Sources reads
+  watching, manual scan and restart pending states (S4).
+- ``POST /__test__/system/library`` ``{state}`` (S6b): ``node_folder`` makes
+  the live database read as a node-folder library that can move to
+  ``user/__promptmanager``; Move library then runs a stand-in move that
+  touches no file and ends with the library in the default folder.
+  ``failing`` is the same library whose move fails verification. Reset
+  restores the real resolver, the real move and "Keep it here".
+- ``POST /__test__/system/legacy-previews`` ``{count}`` (#317) writes ``count``
+  PNGs into ``output/legacy`` with an older release's preview beside each
+  (``thumbnails/legacy/<name>_thumb.png``, newer than its file): outdated
+  previews for Convert outdated;
+- ``POST /__test__/system/jxl-encoder`` ``{available}`` (#317) makes the
+  server read as having (``cjxl``) or lacking a JPEG XL encoder without
+  probing; reset restores the thumbnail settings and the real detection.
+
+- ``POST /__test__/system/duplicate-prompts`` (S7) adds two prompts whose
+  text differs only in case and spacing (a duplicate prompt text group);
+  ``{"again": true}`` adds a third, so a reviewed plan no longer matches;
+- ``POST /__test__/system/duplicate-files`` (S7) writes one PNG's bytes three
+  times: ``output/s7-dupes/same.png``, ``input/s7-dupes/same.png`` (the same
+  relative path in the other source) and ``output/s7-dupes/copy.png``;
+  ``{"groups": n}`` adds ``n`` more groups of two copies each, and
+  ``{"trio": false}`` leaves the three ``same.png``/``copy.png`` copies out,
+  and ``{"long": true}`` adds a group under long names with no spaces;
+- ``GET /__test__/system/digest`` (S7) answers the sha256 of the database's
+  rows (a read-only dump) and of every media file under ``output`` and
+  ``input`` (not the automatic previews in ``thumbnails``), so a test proves
+  a Cancel wrote nothing.
+- ``POST /__test__/system/safety-backup`` (S9) writes one verified safety
+  backup beside the database, as a maintenance apply does;
+  ``GET /__test__/system/backups`` answers ``{safety: [names], stages: n}``:
+  the ``<db>.backup_*`` files and the held ``.pm-restore-*`` stage folders.
+  Reset drops every held restore review, removes the safety backups and
+  forgets the session's last download.
 
 Delays use the shared request holds (``request_hold.py``).
 """
 
+import hashlib
 import os
+import shutil
+import sqlite3
 from pathlib import Path
 
 from aiohttp import web
@@ -31,9 +74,41 @@ MAX_UNTHUMBNAILED = 50
 
 
 def register_system_commands(app, routes, api, root: Path):
-    from py.config import GalleryConfig
+    # System › Appearance saves the host fields to this server's config.json (S3);
+    # reset restores both. The file is this server's own, inside its temp root:
+    # reset rewrites or deletes it, so a server whose configuration points
+    # anywhere else (a real config.json) refuses to register these hooks.
+    config_path = root / "config.json"
+    configured_path = os.environ.get("PROMPT_MANAGER_CONFIG_PATH")
+    if (
+        configured_path is None
+        or Path(configured_path).resolve() != config_path.resolve()
+    ):
+        raise RuntimeError(
+            f"PROMPT_MANAGER_CONFIG_PATH must be {config_path}, not {configured_path!r}"
+        )
+    from py.config import GalleryConfig, PromptManagerConfig
+    from utils import image_monitor
+
+    from database import library_move
+    from utils import library_location
 
     configured = list(GalleryConfig.MONITORING_DIRECTORIES)
+    real_move = library_move.move_library
+    keep = PromptManagerConfig.KEEP_LIBRARY_IN_NODE_FOLDER
+    config_bytes = config_path.read_bytes() if config_path.exists() else None
+    host_values = (
+        PromptManagerConfig.RESULT_TIMEOUT,
+        PromptManagerConfig.WEBUI_DISPLAY_MODE,
+        PromptManagerConfig.WORKER_THREADS,
+        GalleryConfig.MONITORING_ENABLED,
+        PromptManagerConfig.THUMBNAIL_FORMAT,
+        PromptManagerConfig.THUMBNAIL_QUALITY,
+        PromptManagerConfig.THUMBNAIL_EDGE,
+    )
+    from py.api import thumbnail_encode
+
+    monitor = getattr(image_monitor, "_monitor_instance", None)
     failures: dict[str, int] = {}
 
     @web.middleware
@@ -48,16 +123,79 @@ def register_system_commands(app, routes, api, root: Path):
 
     app.middlewares.append(inject_failures)
 
+    unplugged = root / "output" / "unplugged"
+
+    dupes = [root / "output" / "s7-dupes", root / "input" / "s7-dupes"]
+
     def reset():
         failures.clear()
+        for folder in dupes:
+            shutil.rmtree(folder, ignore_errors=True)
+        if unplugged.is_dir():
+            unplugged.rmdir()
         GalleryConfig.MONITORING_DIRECTORIES = list(configured)
         api._health_report = None
+        (
+            PromptManagerConfig.RESULT_TIMEOUT,
+            PromptManagerConfig.WEBUI_DISPLAY_MODE,
+            PromptManagerConfig.WORKER_THREADS,
+            GalleryConfig.MONITORING_ENABLED,
+            PromptManagerConfig.THUMBNAIL_FORMAT,
+            PromptManagerConfig.THUMBNAIL_QUALITY,
+            PromptManagerConfig.THUMBNAIL_EDGE,
+        ) = host_values
+        thumbnail_encode.reset_encoders()
+        image_monitor._monitor_instance = monitor
+        api.__dict__.pop("_library_resolver", None)
+        library_move.move_library = real_move
+        PromptManagerConfig.KEEP_LIBRARY_IN_NODE_FOLDER = keep
+        if config_bytes is None:
+            config_path.unlink(missing_ok=True)
+        else:
+            # Replace in one step, as the server writes it (Windows preflight).
+            staged = config_path.with_name(config_path.name + ".reset")
+            staged.write_bytes(config_bytes)
+            os.replace(staged, config_path)
+
+    def backup_files():
+        db_path = Path(api.db.model.db_path)
+        safety = sorted(
+            path.name
+            for path in db_path.parent.glob(db_path.name + ".backup_*")
+            if path.is_file()
+        )
+        stages = [
+            path
+            for path in db_path.parent.glob(".pm-restore-*")
+            if path.is_dir() and not path.name.startswith(".pm-restore-upload-")
+        ]
+        return db_path, safety, stages
+
+    async def reset_backups():
+        await api._discard_held(api._restore_plans.pop_all())
+        db_path, safety, _stages = backup_files()
+        for name in safety:
+            (db_path.parent / name).unlink(missing_ok=True)
+        api._last_backup_download = None
 
     @routes.post("/__test__/system/reset")
     async def system_reset(request):
         reset()
+        await reset_backups()
         return web.json_response({"success": True})
 
+    @routes.post("/__test__/system/safety-backup")
+    async def safety_backup(request):
+        from py.api.maintenance import take_safety_backup
+
+        name = await api._run_in_executor(take_safety_backup, api.db.model)
+        return web.json_response({"success": True, "name": name})
+
+    @routes.get("/__test__/system/backups")
+    async def backups(request):
+        _db_path, safety, stages = backup_files()
+        return web.json_response({"safety": safety, "stages": len(stages)})
+
     @routes.post("/__test__/system/fail")
     async def system_fail(request):
         data = await request.json()
@@ -75,14 +213,26 @@ def register_system_commands(app, routes, api, root: Path):
 
     @routes.post("/__test__/system/missing-source")
     async def missing_source(request):
-        absent = str(root / "unmounted-drive")
-        if os.path.exists(absent):
-            raise web.HTTPConflict()
+        data = await request.json() if request.can_read_body else {}
+        if data.get("inside") is True:
+            unplugged.mkdir(exist_ok=True)
+            absent = str(unplugged)
+        else:
+            absent = str(root / "unmounted-drive")
+            if os.path.exists(absent):
+                raise web.HTTPConflict()
         GalleryConfig.MONITORING_DIRECTORIES = [*configured, absent]
         return web.json_response(
             {"success": True, "configured": len(GalleryConfig.MONITORING_DIRECTORIES)}
         )
 
+    @routes.post("/__test__/system/unplug")
+    async def unplug(request):
+        if not unplugged.is_dir():
+            raise web.HTTPConflict()
+        unplugged.rmdir()
+        return web.json_response({"success": True})
+
     @routes.post("/__test__/system/missing-file")
     async def missing_file(request):
         with api.db.model.get_connection() as conn:
@@ -113,4 +263,178 @@ def register_system_commands(app, routes, api, root: Path):
         api.invalidate_gallery_cache()
         return web.json_response({"success": True})
 
+    @routes.post("/__test__/system/legacy-previews")
+    async def legacy_previews(request):
+        data = await request.json()
+        count = data.get("count")
+        if (
+            isinstance(count, bool)
+            or not isinstance(count, int)
+            or not 1 <= count <= MAX_UNTHUMBNAILED
+        ):
+            raise web.HTTPBadRequest()
+        folder = root / "output" / "legacy"
+        previews = root / "output" / "thumbnails" / "legacy"
+        folder.mkdir(exist_ok=True)
+        previews.mkdir(parents=True, exist_ok=True)
+        names = []
+        for number in range(count):
+            name = f"old_{number + 1:03}"
+            with Image.effect_noise((256, 256), 50) as noise:
+                noise.convert("RGB").save(folder / f"{name}.png")
+                noise.convert("RGB").save(previews / f"{name}_thumb.png")
+            later = (folder / f"{name}.png").stat().st_mtime + 5
+            os.utime(previews / f"{name}_thumb.png", (later, later))
+            names.append(f"legacy/{name}.png")
+        api.invalidate_gallery_cache()
+        return web.json_response({"success": True, "files": names})
+
+    @routes.post("/__test__/system/jxl-encoder")
+    async def jxl_encoder(request):
+        data = await request.json()
+        available = data.get("available")
+        if not isinstance(available, bool):
+            raise web.HTTPBadRequest()
+        # Test-only: stand in the cached detection (no probe).
+        with thumbnail_encode._detect_lock:
+            thumbnail_encode._detected = "cjxl" if available else None
+        return web.json_response({"success": True})
+
+    @routes.post("/__test__/system/monitor")
+    async def fake_monitor(request):
+        data = await request.json()
+        watching, alive = data.get("watching", []), data.get("alive", True)
+        if (
+            not isinstance(watching, list)
+            or not all(name in ("output", "input") for name in watching)
+            or not isinstance(alive, bool)
+        ):
+            raise web.HTTPBadRequest()
+        image_monitor._monitor_instance = _FakeMonitor(
+            [str(root / name) for name in watching], alive
+        )
+        return web.json_response({"success": True})
+
+    @routes.post("/__test__/system/duplicate-prompts")
+    async def duplicate_prompts(request):
+        data = await request.json() if request.can_read_body else {}
+        texts = [("S7 duplicate prompt", "2001-01-01 00:00:00")]
+        texts.append(("  s7 DUPLICATE prompt", "2002-01-01 00:00:00"))
+        if data.get("again") is True:
+            texts = [("S7 Duplicate Prompt  ", "2003-01-01 00:00:00")]
+        with api.db.model.get_connection() as conn:
+            conn.executemany(
+                "INSERT INTO prompts(text, created_at) VALUES(?, ?)", texts
+            )
+            conn.commit()
+        return web.json_response({"success": True})
+
+    @routes.post("/__test__/system/duplicate-files")
+    async def duplicate_files(request):
+        body = await request.json() if request.can_read_body else {}
+        for folder in dupes:
+            folder.mkdir(exist_ok=True)
+        extra = body.get("groups", 0)
+        if (
+            isinstance(extra, bool)
+            or not isinstance(extra, int)
+            or not 0 <= extra <= 20
+        ):
+            raise web.HTTPBadRequest()
+        for number in range(extra):
+            # One more group each: two copies of a picture no other file has.
+            with Image.new("RGB", (16, 16), (number * 9, 40, 90)) as image:
+                image.save(dupes[0] / f"group_{number:02}_a.png")
+            copy = (dupes[0] / f"group_{number:02}_a.png").read_bytes()
+            (dupes[0] / f"group_{number:02}_b.png").write_bytes(copy)
+        if body.get("long") is True:
+            # One group whose copies sit under long folder and file names with
+            # no space to break at, as real dataset folders do.
+            deep = dupes[0] / ("mabes9sans_DATASET_ideogram_v1_" * 3).rstrip("_")
+            deep.mkdir(exist_ok=True)
+            with Image.new("RGB", (16, 16), "#204060") as image:
+                image.save(deep / ("mabes9sans_DATASET072_" * 4 + "a.png"))
+            copy = (deep / ("mabes9sans_DATASET072_" * 4 + "a.png")).read_bytes()
+            (deep / ("mabes9sans_DATASET072_" * 4 + "b.png")).write_bytes(copy)
+        if body.get("trio", True) is not False:
+            with Image.new("RGB", (48, 48), "#7a3b2e") as image:
+                image.save(dupes[0] / "same.png")
+            data = (dupes[0] / "same.png").read_bytes()
+            (dupes[1] / "same.png").write_bytes(data)
+            (dupes[0] / "copy.png").write_bytes(data)
+        api.invalidate_gallery_cache()
+        return web.json_response({"success": True})
+
+    @routes.get("/__test__/system/digest")
+    async def digest(request):
+        uri = Path(api.db.model.db_path).as_uri() + "?mode=ro"
+        rows = hashlib.sha256()
+        conn = sqlite3.connect(uri, uri=True)
+        try:
+            for line in conn.iterdump():
+                rows.update(line.encode("utf-8") + b"\n")
+        finally:
+            conn.close()
+        media = hashlib.sha256()
+        for name in ("output", "input"):
+            for path in sorted((root / name).rglob("*")):
+                # Automatic previews are written in the background (#316): media only.
+                if path.is_file() and "thumbnails" not in path.relative_to(root).parts:
+                    media.update(str(path.relative_to(root)).encode("utf-8"))
+                    media.update(hashlib.sha256(path.read_bytes()).digest())
+        return web.json_response({"rows": rows.hexdigest(), "media": media.hexdigest()})
+
+    @routes.post("/__test__/system/library")
+    async def library_state(request):
+        data = await request.json()
+        state = data.get("state")
+        if state not in ("node_folder", "failing"):
+            raise web.HTTPBadRequest()
+        target = str(root / "user" / "__promptmanager")
+
+        def located(source):
+            return library_location.LibraryLocation(
+                source,
+                api.db.model.db_path,
+                str(config_path),
+                str(root),
+                target if source == library_location.SOURCE_NODE_FOLDER else None,
+                target_source=library_location.SOURCE_DEFAULT,
+            )
+
+        current = {"source": library_location.SOURCE_NODE_FOLDER}
+        api._library_resolver = lambda: located(current["source"])
+
+        def stand_in_move(plan, *, progress, **_kwargs):
+            if state == "failing":
+                raise library_move.MoveFailed("verify-failed")
+            progress("Copying the database")
+            counts = api.db.library_counts()
+            current["source"] = library_location.SOURCE_DEFAULT
+            return library_move.MoveResult(
+                located(library_location.SOURCE_DEFAULT),
+                {"prompts": counts["positive_prompts"], "generated_images": 0},
+                ["prompts.db"],
+                ["browser.db.moved-to-__promptmanager"],
+            )
+
+        library_move.move_library = stand_in_move
+        return web.json_response({"success": True})
+
     return reset
+
+
+class _FakeMonitor:
+    """The image monitor's status surface (``get_status``) with no observer thread."""
+
+    def __init__(self, directories, alive):
+        self.monitored_directories = directories
+        self._alive = alive
+
+    def get_status(self):
+        return {
+            "running": True,
+            "monitored_directories": list(self.monitored_directories),
+            "handler_active": True,
+            "observer_alive": self._alive,
+        }

tests/browser/workspace_tagging_fixture.py

@@ -44,6 +44,8 @@ MAX_EXTRA_IMAGES = 160
 _TABLES = (
     "saved_views",
     "image_favorites",
+    "media_review_decisions",
+    "media_review_items",
     "media_image_tags",
     "media_annotation_bytes",
     "media_annotation_files",
@@ -146,7 +148,12 @@ def seed_tagging(api: PromptManagerAPI, root: Path, extra_images: int = 0) -> di
             image_id = db.link_image_to_prompt(positive_id, str(output / relative))
             if kind == "linked":
                 db.link_image_to_pair(pair_id, image_id, {"source": "fixture"})
-    api._generate_gallery_thumbnails_sync(api._get_all_output_dirs(), (150, 150))
+    from py.api.thumbnail_settings import ThumbnailSettings
+
+    # 150 px previews in the default format (#317 thumbnail settings).
+    api._generate_gallery_thumbnails_sync(
+        api._get_all_output_dirs(), ThumbnailSettings("webp", 80, 150)
+    )
     api.invalidate_gallery_cache()
     return {
         "positive_id": positive_id,