fix(system): say which source is the default and where a symlinked library lives

Sources & scans: with no source configured, ComfyUI's output folder now
reads "ComfyUI/output · watching · default" on its own row instead of a
separate note line. GET /settings marks each effective source with
in_comfyui (its public path is relative to the ComfyUI base) so only
those get the "ComfyUI/" prefix; the scan still sends the server's
public path.

Library location: a library in the node folder reads through the node
folder's unresolved place in custom_nodes, so a node folder symlinked to
a checkout outside ComfyUI shows custom_nodes/promptmanager/prompts.db
instead of prompts.db (System library row, Move review, admin Library
line). Never absolute or "..", else the shared _public_path, which
sources and jobs keep using unchanged.

.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-*

README.md

@@ -751,9 +751,34 @@ 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.
+
 ### 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
 {
@@ -970,6 +995,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

@@ -91,6 +91,9 @@ try:
     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 +125,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/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/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,768 @@
+"""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 closes them
+    (``PromptModel.close_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
+
+    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).
+    """
+    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
+            try:
+                PromptModel.close_detached(
+                    move.unswitch(plan.db_path, location.db_path), logger
+                )
+            except Exception:
+                logger.exception("Library move: undoing the switch failed")
+            # The old file's connections a partial switch detached: the
+            # models reopen it on next use, so close them now, not at GC.
+            PromptModel.close_detached(detached, logger)
+            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):
+    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 fails when its connection closes (and runs again on
+                # the new library) instead of landing in the old file.
+                PromptModel.close_detached(detached, logger)
+            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/models.py

@@ -18,7 +18,19 @@ from typing import Optional, Set, Tuple
 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,
@@ -45,6 +57,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 +328,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")
@@ -575,19 +609,37 @@ 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 can clean up other
+            # threads' connections; each connection is still used by one thread.
+            conn = sqlite3.connect(
+                path, check_same_thread=False, timeout=BUSY_TIMEOUT_SECONDS
+            )
+            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 +648,59 @@ 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
+        closes them once nothing can block on the new file any more. Closing
+        a connection another thread is using waits for its statement; a write
+        waiting on the mover's lock then 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 close_detached(connections, logger=None) -> None:
+        """Close connections ``repoint_instances`` detached."""
+        for conn in connections:
+            try:
+                conn.close()
+            except sqlite3.Error as e:
+                if logger is not None:
+                    logger.warning(f"Error closing database connection: {e}")
+
     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.
@@ -699,6 +788,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 +954,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 +1020,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 +1031,7 @@ class PromptModel:
                 conn.commit()
         except Exception as e:
             self.logger.error(f"Error vacuuming database: {e}")
+            raise
 
     def get_database_info(self) -> dict:
         """
@@ -1023,9 +1119,9 @@ 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.
 
         Returns:
             (ok, reason): reason is "ok" when the file is acceptable, otherwise
@@ -1095,6 +1191,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=True
+            )
+            if documents_error:
+                return False, documents_error
             return True, "ok"
         except sqlite3.Error as e:
             return False, f"Invalid SQLite database: {e}"

database/operations.py

@@ -4,28 +4,49 @@ 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 .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 +54,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 +101,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 +200,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 +359,13 @@ class PromptDatabase(
     HistoryReadOperations,
     ImageFavoriteOperations,
     AnnotationOperations,
+    ReviewOperations,
+    ReviewDecisionOperations,
     SavedViewOperations,
     HealthOperations,
+    MaintenanceOperations,
+    DuplicateCopyOperations,
+    WorkflowStorageOperations,
 ):
     """Database operations class for managing prompts."""
 
@@ -361,6 +383,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()
@@ -781,10 +822,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 +851,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 +1579,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 +1617,118 @@ 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
+            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"],
+                    ),
+                )
+            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
+
     def get_prompt_images(self, prompt_id: str) -> List[Dict[str, Any]]:
         """
         Get all images associated with a prompt.
@@ -1735,7 +1748,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 +1775,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 +1810,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 +1851,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 +1869,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 +1882,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 +1943,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 +2019,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 +2061,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 +2102,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 +2220,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 +2300,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 +2381,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 +2629,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 +2645,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,16 +1,26 @@
 """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 ingest_resolved_pair(
@@ -19,118 +29,168 @@ def ingest_resolved_pair(
     state = resolution.get("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/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,507 @@
+"""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."""
+    for evidence_hash, text in conn.execute(
+        f"SELECT evidence_hash, evidence FROM {ITEMS_TABLE}"  # nosec B608
+    ):
+        if not _is_canonical(text) or evidence_digest(text) != evidence_hash:
+            return f"Review queue table {ITEMS_TABLE} contains invalid evidence"
+    for (text,) in conn.execute(
+        f"SELECT evidence FROM {DECISIONS_TABLE}"  # nosec B608
+    ):
+        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/workflow_documents.py

@@ -0,0 +1,477 @@
+"""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

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."
+)

py/api/__init__.py

@@ -8,7 +8,16 @@ 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
+- 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
 """
 
 import asyncio
@@ -16,6 +25,7 @@ import datetime
 import functools
 import gzip as gzip_module
 import json
+import math
 import ntpath
 import os
 import re
@@ -29,6 +39,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,7 +49,14 @@ 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_auto import AutoThumbnailMixin
 from .system import SystemRoutesMixin
+from .library_location import LibraryLocationRoutesMixin
+from .maintenance import MaintenanceRoutesMixin
+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
@@ -263,6 +283,9 @@ class PromptManagerAPI(
     LibraryRoutesMixin,
     VocabularyRoutesMixin,
     AnnotationRoutesMixin,
+    ReviewRoutesMixin,
+    ReviewRecordingMixin,
+    ReviewEventsMixin,
     SavedViewRoutesMixin,
     HistoryRoutesMixin,
     PromptRoutesMixin,
@@ -271,7 +294,13 @@ class PromptManagerAPI(
     SettingsRoutesMixin,
     JobRoutesMixin,
     ImageTagJobsMixin,
+    ThumbnailJobsMixin,
+    AutoThumbnailMixin,
     SystemRoutesMixin,
+    LibraryLocationRoutesMixin,
+    MaintenanceRoutesMixin,
+    WorkflowStorageRoutesMixin,
+    DuplicateFilesMixin,
     LoggingRoutesMixin,
     AutotagRoutesMixin,
     LoraIntegrationMixin,
@@ -303,6 +332,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 +357,31 @@ 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
+
+            swept = sweep_safety_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 +532,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,6 +542,9 @@ 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_duplicate_routes(routes)
         self._register_logging_routes(routes)
         self._register_autotag_routes(routes)
         self._register_lora_routes(routes)
@@ -609,12 +663,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/admin.py

@@ -4,6 +4,7 @@ import asyncio
 import contextlib
 from contextlib import closing
 import datetime
+import functools
 import hashlib
 import json
 import math
@@ -23,9 +24,9 @@ from .jobs import (
     SCAN_GROUPS,
     SCAN_SCOPES,
     DUPLICATE_CLEANUP_JOB_KIND,
+    DUPLICATES_JOB_KIND,
     MAINTENANCE_JOB_KIND,
     RESTORE_JOB_KIND,
-    Job,
     JobBusy,
 )
 
@@ -44,6 +45,7 @@ try:
         parse_page_json,
     )
     from ...utils.prompt_pair_resolver import resolve_prompt_pair
+    from ...utils.review_capture import reviewable
 except ImportError:
     from database.operations import PromptDatabase
     from database.pair_ingestion import ingest_resolved_pair
@@ -54,6 +56,7 @@ except ImportError:
         parse_page_json,
     )
     from utils.prompt_pair_resolver import resolve_prompt_pair
+    from utils.review_capture import reviewable
 
 
 try:
@@ -66,7 +69,9 @@ except ImportError:
 IMAGE_EXTENSIONS = (".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff")
 VIDEO_EXTENSIONS = (".mp4", ".avi", ".mov", ".mkv", ".webm", ".m4v", ".wmv")
 SCAN_BATCH_SIZE = 50  # Files per executor call during the output scan
-MAX_SAFETY_BACKUPS = 10  # '<db>.backup_*' files kept next to the live database
+# '<db>.backup_*' files kept next to the live database: one pool for the
+# restore backups and the maintenance safety backups (py/api/maintenance.py).
+MAX_SAFETY_BACKUPS = 10
 MAX_SCAN_FILES = 50_000  # Upper bound on media files one scan will look at
 SCAN_COUNT_KEYS = (
     "processed",
@@ -87,6 +92,7 @@ MAX_SCAN_DEPTH = 12  # Directory levels below an output root that are scanned
 # the common single-f TIFF spelling. Anything else inside the output
 # directory (databases, scripts, notes) is never a "duplicate image".
 DELETABLE_MEDIA_EXTENSIONS = frozenset(IMAGE_EXTENSIONS + VIDEO_EXTENSIONS + (".tif",))
+DUPLICATE_FIND_LEGACY_TITLE = "Find duplicate image files (gallery page)"
 
 
 def _collect_media_files(output_dirs, extensions):
@@ -129,11 +135,52 @@ def _collect_media_files(output_dirs, extensions):
     return found
 
 
+def _physical_file_key(path, stat):
+    """What tells two physical files apart: ``(st_dev, st_ino)``.
+
+    A filesystem that reports no inode (``st_ino`` 0, some network or FAT
+    volumes on Windows) falls back to the resolved, case-folded path.
+    """
+    if stat.st_ino:
+        return ("inode", stat.st_dev, stat.st_ino)
+    return ("path", os.path.normcase(os.path.realpath(str(path))))
+
+
 def _thumbnail_rel_path(rel_path, thumbnail_ext):
     """Relative path of the thumbnail the gallery would generate for ``rel_path``."""
     return f"thumbnails/{rel_path.with_suffix('').as_posix()}_thumb{thumbnail_ext}"
 
 
+def _media_thumbnail_rel_path(rel_path):
+    """The thumbnail of a media file: a video's preview is a ``.jpg``."""
+    extension = rel_path.suffix.lower()
+    return _thumbnail_rel_path(
+        rel_path, ".jpg" if extension in VIDEO_EXTENSIONS else rel_path.suffix
+    )
+
+
+def _remove_thumbnail(output_path, rel_path, logger=None):
+    """Remove the thumbnail of ``rel_path`` under ``output_path``, if any.
+
+    Shared by the legacy duplicate delete and the reviewed removal job. A
+    thumbnail that is a link, or one that cannot be removed, is left alone
+    (a stale preview never fails a removal). Returns whether one was removed.
+    """
+    output_path = Path(output_path)
+    thumbnail_path = output_path / _media_thumbnail_rel_path(Path(rel_path))
+    try:
+        if thumbnail_path.is_symlink() or not thumbnail_path.is_file():
+            return False
+        os.remove(thumbnail_path)
+    except OSError as e:
+        if logger is not None:
+            logger.warning(f"Could not delete thumbnail for {rel_path}: {e}")
+        return False
+    if logger is not None:
+        logger.debug(f"Deleted associated thumbnail: {thumbnail_path}")
+    return True
+
+
 async def _read_json(request):
     """Parse a JSON object body through the package's capped reader.
 
@@ -211,6 +258,30 @@ def _time_left(done, total, batches, elapsed):
     return f" · about {minutes} min left"
 
 
+def new_review_counts():
+    """The scan's Needs review tally: ``added`` new items, ``queued`` files
+    in the queue after this scan (new or already there), ``settled`` items
+    removed because their file is linked now, ``untraced`` items removed
+    because they offer nothing to choose, and ``errors``."""
+    return {"added": 0, "queued": 0, "settled": 0, "untraced": 0, "errors": 0}
+
+
+def _review_scope(review):
+    """The scan job's ``scope`` keys for its Needs review tally.
+
+    ``review_items`` is the number of this scan's files that are in the
+    pending queue after it: the review group's ambiguous files, less those a
+    capture could not read or a decision already settled.
+    """
+    return {
+        "review_items": review["queued"],
+        "review_added": review["added"],
+        "review_settled": review["settled"],
+        "review_untraced": review["untraced"],
+        "review_errors": review["errors"],
+    }
+
+
 def _scan_status_line(done, total, batches, elapsed):
     """ "Processing file N of M", with an estimate once enough batches ran."""
     line = f"Processing file {done:,} of {total:,}"
@@ -534,12 +605,21 @@ class AdminRoutesMixin:
     LONG_JOB_DUPLICATES = "duplicates"
 
     async def scan_duplicates_endpoint(self, request):
-        """Scan for duplicate images without removing them (single flight)."""
-        job = self._acquire_long_job(self.LONG_JOB_DUPLICATES)
-        if job is None:
-            return self._long_job_busy_response("Duplicate scan")
-        async with job:
-            return await self._scan_duplicates(request)
+        """Scan for duplicate images without removing them.
+
+        Holds the ``duplicates`` kind on the registry (a ``read`` hold, so it
+        is listed in Activity), so it is single flight with every duplicate
+        find, and it is refused while a duplicate removal runs.
+        """
+        cleanup = self._jobs.active(DUPLICATE_CLEANUP_JOB_KIND)
+        if cleanup is not None:
+            return self._long_job_busy_response(cleanup.title)
+        return await self._run_held(
+            DUPLICATES_JOB_KIND,
+            DUPLICATE_FIND_LEGACY_TITLE,
+            "read",
+            functools.partial(self._scan_duplicates, request),
+        )
 
     async def _scan_duplicates(self, request):
         try:
@@ -561,24 +641,29 @@ class AdminRoutesMixin:
             )
 
     async def scan_duplicates_stream(self, request):
-        """Run the duplicate scan as a background job and stream its progress.
+        """Stream a duplicate find to the legacy gallery (its event shapes).
 
-        A request while a scan is running attaches to it. The job holds the
-        duplicates lock, so a delete is refused (409) until it finishes.
+        Starts the registry's ``duplicates`` job over the gallery's output
+        folder, or attaches to the running one when it covers that folder
+        (one started in the workspace, for instance). A held legacy scan, a
+        find that does not cover the folder or a running removal answers the
+        legacy 409. The job outlives the request.
         """
-        job = self._duplicate_job
-        if job is None or job.finished:
-            guard = self._acquire_long_job(self.LONG_JOB_DUPLICATES)
-            if guard is None:
-                return self._long_job_busy_response("Duplicate scan or delete")
-            job = Job("duplicates", "Duplicate scan")
-            self._duplicate_job = job
-            job.task = asyncio.ensure_future(self._run_duplicate_job(job, guard))
+        job = self._jobs.active(DUPLICATES_JOB_KIND)
+        if job is None:
+            try:
+                job = self._start_duplicate_find(origin="gallery")
+            except JobBusy as busy:
+                return self._long_job_busy_response(busy.running.title)
+        else:
+            legacy_dir = await self._run_in_executor(self._find_comfyui_output_dir)
+            if not self._find_covers(job, legacy_dir):
+                return self._long_job_busy_response(job.title)
         return await self._stream_scan_job(request, job)
 
     async def scan_duplicates_status(self, request):
-        """Whether a duplicate scan is running, and its latest event."""
-        job = self._duplicate_job
+        """Whether a duplicate find is running, and its latest legacy event."""
+        job = self._latest_duplicate_find()
         return web.json_response(
             {
                 "success": True,
@@ -587,62 +672,6 @@ class AdminRoutesMixin:
             }
         )
 
-    async def _run_duplicate_job(self, job, guard):
-        loop = asyncio.get_running_loop()
-        counts = {"processed": 0}
-
-        def report(done, total):
-            # Called from worker threads; hand the event to the loop.
-            counts["processed"] = done
-            pct = int(done / total * 100) if total else 100
-            loop.call_soon_threadsafe(
-                job.publish,
-                {
-                    "type": "progress",
-                    "progress": pct,
-                    "status": f"Hashing file {done}/{total}...",
-                    "processed": done,
-                    "found": 0,
-                },
-            )
-
-        try:
-            async with guard:
-                job.publish(
-                    {
-                        "type": "progress",
-                        "progress": 0,
-                        "status": "Collecting media files...",
-                        "processed": 0,
-                        "found": 0,
-                    }
-                )
-                output_dir = await self._run_in_executor(self._find_comfyui_output_dir)
-                groups = await self._run_in_executor(
-                    self._find_duplicate_images_sync, output_dir, report
-                )
-                job.publish(
-                    {
-                        "type": "complete",
-                        "processed": counts["processed"],
-                        "found": len(groups),
-                        "duplicates": groups,
-                        "message": f"Found {len(groups)} groups of duplicate images",
-                    }
-                )
-        except Exception:
-            self.logger.exception("Duplicate scan error")
-            job.publish(
-                {
-                    "type": "error",
-                    "message": (
-                        "An internal error occurred. Check server logs for details."
-                    ),
-                }
-            )
-        finally:
-            job.finish()
-
     async def cleanup_duplicates_endpoint(self, request):
         """Cleanup duplicate prompts endpoint (holds the registry: records)."""
         return await self._run_held(
@@ -679,31 +708,109 @@ class AdminRoutesMixin:
     def _find_duplicate_images_sync(self, output_dir, progress=None):
         """Group media files under ``output_dir`` by content hash (blocking).
 
-        Files are hashed on ``PromptManagerConfig.WORKER_THREADS`` threads.
-        ``progress(done, total)`` is called from those threads about every
-        percent and once at the end.
+        The legacy response shape over ``_hash_media_groups``, which the
+        workspace's duplicate find shares.
         """
-        from ..config import PromptManagerConfig
-
         if not output_dir or not os.path.isdir(output_dir):
             self.logger.warning("ComfyUI output directory not found")
             return []
+        groups = self._hash_media_groups([os.path.abspath(output_dir)], progress)
+        duplicates = self._legacy_duplicate_groups(groups, output_dir)
+        self.logger.info(f"Found {len(duplicates)} groups of duplicate images")
+        return duplicates
+
+    def _legacy_duplicate_groups(self, groups, output_dir):
+        """``_hash_media_groups`` groups as the legacy gallery reads them.
+
+        Only the files under ``output_dir`` count (paths are relative to it);
+        a group needs two of them. A file that vanished since it was hashed
+        is left out.
+        """
+        output_path = Path(os.path.abspath(output_dir))
+        base = os.path.normcase(str(output_path)).rstrip("\\/") + os.sep
+        duplicates = []
+        for group in groups:
+            images = []
+            for record in group["files"]:
+                if not os.path.normcase(record["abs"]).startswith(base):
+                    continue
+                try:
+                    images.append(
+                        self._describe_media_file(
+                            Path(record["abs"]), output_path, file_hash=group["hash"]
+                        )
+                    )
+                except (OSError, ValueError) as e:
+                    self.logger.error(
+                        f"Error describing {Path(record['abs']).name}: {e}"
+                    )
+            if len(images) > 1:
+                duplicates.append(
+                    {"hash": group["hash"], "images": images, "count": len(images)}
+                )
+        return duplicates
+
+    def _hash_media_groups(self, roots, progress=None, stop=None):
+        """Content-identical media files under ``roots`` (blocking).
+
+        Each root is walked as ``_collect_media_files`` walks (no symlinks,
+        no ``thumbnails``, bounded). A physical file is listed once, under
+        the first root that holds it: files are told apart by ``(st_dev,
+        st_ino)``, so a source listed twice under two spellings (a symlink, a
+        bind mount, a case variant), a source inside another one or a
+        hardlink is one file, never a copy of itself. At most MAX_SCAN_FILES
+        files are read. Files
+        are hashed on ``PromptManagerConfig.WORKER_THREADS`` threads;
+        ``progress(done, total)`` is called from those threads about every
+        percent and once at the end, and ``stop()`` true skips the files not
+        yet read. Returns ``[{hash, size, files:[{slot, abs, rel, size,
+        mtime, mtime_ns, inode}]}]`` for every hash shared by two or more
+        files (``inode`` is ``[st_dev, st_ino]``), ``slot``
+        being the root's place in ``roots`` and the files oldest first.
+        """
+        from ..config import PromptManagerConfig
 
-        output_path = Path(output_dir)
         extensions = IMAGE_EXTENSIONS + VIDEO_EXTENSIONS
-        media_files = _collect_media_files([output_path], extensions)
+        media_files = []
+        seen = set()
+        for slot, root in enumerate(roots):
+            for path in _collect_media_files([root], extensions):
+                try:
+                    # os.stat, not Path.stat: one stat call for every check
+                    # (Python 3.10's Path.stat bypasses a patched os.stat).
+                    stat = os.stat(path)
+                except OSError:
+                    continue
+                key = _physical_file_key(path, stat)
+                if key not in seen:
+                    seen.add(key)
+                    media_files.append((slot, root, path, stat))
+                if len(media_files) >= MAX_SCAN_FILES:
+                    break
+        media_files = media_files[:MAX_SCAN_FILES]
         total = len(media_files)
         self.logger.info(f"Found {total} media files to analyze")
         step = max(1, total // 100)
         counter = {"done": 0}
         lock = threading.Lock()
 
-        def describe(media_path):
-            try:
-                info = self._describe_media_file(media_path, output_path)
-            except Exception as e:
-                self.logger.error(f"Error processing file {media_path.name}: {e}")
-                info = None
+        def describe(item):
+            slot, root, media_path, stat = item
+            info = None
+            if stop is None or not stop():
+                try:
+                    info = {
+                        "slot": slot,
+                        "abs": str(media_path),
+                        "rel": Path(os.path.relpath(str(media_path), root)).as_posix(),
+                        "size": stat.st_size,
+                        "mtime": stat.st_mtime,
+                        "mtime_ns": stat.st_mtime_ns,
+                        "inode": [stat.st_dev, stat.st_ino],
+                        "hash": self._calculate_file_hash(media_path),
+                    }
+                except Exception as e:
+                    self.logger.error(f"Error processing file {media_path.name}: {e}")
             with lock:
                 counter["done"] += 1
                 done = counter["done"]
@@ -717,24 +824,22 @@ class AdminRoutesMixin:
 
         infos = map_parallel(describe, media_files, PromptManagerConfig.WORKER_THREADS)
 
-        file_hashes = {}
+        by_hash = {}
         for info in infos:
             if info is not None:
-                file_hashes.setdefault(info["hash"], []).append(info)
-
-        duplicates = []
-        for file_hash, images in file_hashes.items():
-            if len(images) > 1:
-                images.sort(key=lambda x: x["modified_time"])
-                duplicates.append(
-                    {"hash": file_hash, "images": images, "count": len(images)}
+                by_hash.setdefault(info.pop("hash"), []).append(info)
+        groups = []
+        for file_hash, files in by_hash.items():
+            if len(files) > 1:
+                files.sort(key=lambda record: (record["mtime"], record["abs"]))
+                groups.append(
+                    {"hash": file_hash, "size": files[0]["size"], "files": files}
                 )
+        return groups
 
-        self.logger.info(f"Found {len(duplicates)} groups of duplicate images")
-        return duplicates
-
-    def _describe_media_file(self, media_path, output_path):
-        """Hash one media file and describe it for the duplicates response."""
+    def _describe_media_file(self, media_path, output_path, file_hash=None):
+        """Describe one media file for the duplicates response (hashing it
+        unless ``file_hash`` is given)."""
         stat = media_path.stat()
         rel_path = media_path.relative_to(output_path)
         extension = media_path.suffix.lower()
@@ -755,7 +860,7 @@ class AdminRoutesMixin:
             "extension": extension,
             "media_type": "video" if is_video else "image",
             "is_video": is_video,
-            "hash": self._calculate_file_hash(media_path),
+            "hash": file_hash or self._calculate_file_hash(media_path),
         }
 
     def _calculate_file_hash(self, file_path):
@@ -769,9 +874,9 @@ class AdminRoutesMixin:
     async def delete_duplicate_images_endpoint(self, request):
         """Delete duplicate image files from disk.
 
-        Single flight with the duplicate scan, and a records hold on the
-        registry, so no scan, restore or tagging job runs meanwhile. A body
-        without paths is refused before the hold (it is no job).
+        Refused while a duplicate find runs, and a records hold on the
+        registry, so no scan, restore, removal or tagging job runs meanwhile.
+        A body without paths is refused before the hold (it is no job).
         """
         data, error_response = await _read_json(request)
         if error_response is not None:
@@ -782,20 +887,14 @@ class AdminRoutesMixin:
                 {"success": False, "error": "No image paths provided"},
                 status=400,
             )
-        guard = self._acquire_long_job(self.LONG_JOB_DUPLICATES)
-        if guard is None:
-            return self._long_job_busy_response("Duplicate scan or delete")
-
-        async def delete():
-            # No await since the check above: the lock is still free.
-            async with guard:
-                return await self._delete_duplicate_images(image_paths)
-
+        find = self._jobs.active(DUPLICATES_JOB_KIND)
+        if find is not None:
+            return self._long_job_busy_response(find.title)
         return await self._run_held(
             DUPLICATE_CLEANUP_JOB_KIND,
             "Duplicate image delete (gallery page)",
             "records",
-            delete,
+            functools.partial(self._delete_duplicate_images, image_paths),
         )
 
     async def _delete_duplicate_images(self, image_paths):
@@ -875,14 +974,7 @@ class AdminRoutesMixin:
 
         os.remove(file_path)
         self.logger.info(f"Deleted duplicate image: {image_path}")
-
-        thumbnail_path = output_path / _thumbnail_rel_path(rel_path, file_path.suffix)
-        try:
-            if thumbnail_path.exists():
-                os.remove(thumbnail_path)
-                self.logger.debug(f"Deleted associated thumbnail: {thumbnail_path}")
-        except OSError as e:
-            self.logger.warning(f"Could not delete thumbnail for {image_path}: {e}")
+        _remove_thumbnail(output_path.resolve(), rel_path, self.logger)
         return None
 
     async def get_statistics(self, request):
@@ -1085,8 +1177,10 @@ class AdminRoutesMixin:
                 db.cleanup_duplicates(), "duplicate prompts"
             ),
             "vacuum": vacuum,
+            # Only under sources that can be read now (never an unmounted drive).
             "cleanup_orphaned_images": lambda: count_result(
-                db.cleanup_missing_images(), "orphaned image records"
+                db.cleanup_missing_images(self._health_roots()),
+                "orphaned image records",
             ),
             "check_hash_duplicates": lambda: self._hash_duplicates_result(
                 db.check_hash_duplicates()
@@ -1180,7 +1274,11 @@ class AdminRoutesMixin:
     async def restore_database(self, request):
         """Restore the prompts database from an uploaded SQLite file.
 
-        The upload is streamed to a temp file (capped at restore_max_bytes),
+        The upload is streamed to a temp file. 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
         verified with PromptModel.verify_database_file and only then copied
         over the live database, which is backed up first. The whole request
         holds the registry (records): it is refused while a scan or another
@@ -1193,10 +1291,44 @@ class AdminRoutesMixin:
             lambda: self._restore_database(request),
         )
 
+    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 _restore_database(self, request):
-        max_bytes = getattr(self, "restore_max_bytes", 100 * 1024 * 1024)
+        from .maintenance import RESTORE_MAX_BYTES, restore_room
+
+        ceiling = getattr(self, "restore_max_bytes", RESTORE_MAX_BYTES)
         temp_path = None
         try:
+            # 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, self.db.model.db_path)
+            max_bytes = min(ceiling, room)
+            length = request.content_length
+            if length is not None and length > max_bytes:
+                return self._restore_refusal(length, ceiling, room, known=True)
             reader = await request.multipart()
             field = await reader.next()
 
@@ -1222,16 +1354,7 @@ class AdminRoutesMixin:
                         break
                     size += len(chunk)
                     if size > max_bytes:
-                        return web.json_response(
-                            {
-                                "success": False,
-                                "error": (
-                                    "File too large. Maximum size is "
-                                    f"{max_bytes // (1024 * 1024)}MB"
-                                ),
-                            },
-                            status=400,
-                        )
+                        return self._restore_refusal(size, ceiling, room, known=False)
                     out.write(chunk)
 
             if size == 0:
@@ -1344,28 +1467,34 @@ class AdminRoutesMixin:
             }
         )
 
-    def _start_scan_job(self, files=DEFAULT_SCAN_SCOPE):
+    def _start_scan_job(self, files=DEFAULT_SCAN_SCOPE, roots=None, output_dirs=None):
         """Register the scan job synchronously; its runner starts on the loop.
 
-        ``files`` is the scope (``SCAN_SCOPES``). Raises JobBusy while another
-        record-changing job runs.
+        ``files`` is the scope (``SCAN_SCOPES``). ``roots`` selects sources by
+        their index in ``output_dirs`` (the effective sources the caller
+        resolved); None scans every source, resolved when the job starts.
+        Raises JobBusy while another record-changing job runs.
         """
         if files not in SCAN_SCOPES:
             raise ValueError(f"Unknown scan scope: {files!r}")
+        if roots is not None and (
+            output_dirs is None or not roots or max(roots) >= len(output_dirs)
+        ):
+            raise ValueError("A scoped scan needs the sources its roots index")
         job = self._jobs.start(
             SCAN_JOB_KIND,
             SCAN_JOB_TITLE,
             record_changing=True,
-            scope={"files": files},
-            runner=self._run_scan_job,
+            scope={"files": files, "roots": None if roots is None else list(roots)},
+            runner=functools.partial(self._run_scan_job, output_dirs=output_dirs),
             groups=SCAN_GROUP_NAMES,
         )
         self._scan_job = job
         return job
 
-    async def _run_scan_job(self, job):
+    async def _run_scan_job(self, job, output_dirs=None):
         final = None
-        async for payload in self._scan_images_events(job):
+        async for payload in self._scan_images_events(job, output_dirs):
             job.publish(payload)
             final = payload.get("type")
         state = SCAN_FINAL_STATES.get(final, "finished")
@@ -1375,6 +1504,9 @@ class AdminRoutesMixin:
             verb = "cancelled" if state == "cancelled" else "finished"
             job.log_line(f"Scan {verb} · {_plural(job.processed, 'file')} processed")
         job.finish(state)
+        if state == "finished":
+            # After the scan, so the guarded thumbnail job is admitted (#249).
+            await self._hand_off_scan_thumbnails(job, output_dirs)
 
     async def _stream_scan_job(self, request, job):
         """Stream ``job`` as SSE; stop quietly if the client goes away."""
@@ -1400,16 +1532,25 @@ class AdminRoutesMixin:
             )
         return response
 
-    async def _scan_images_events(self, job):
-        """Yield progress payloads while scanning every configured output directory.
+    async def _scan_images_events(self, job, output_dirs=None):
+        """Yield progress payloads while scanning the output directories.
 
-        The payloads are the legacy SSE events, unchanged; ``job`` also gets
-        its status line, totals and one outcome per processed file.
+        Every effective source is walked, or only those ``job.scope["roots"]``
+        selects (indexes into ``output_dirs``). The payloads are the legacy SSE
+        events, unchanged; ``job`` also gets its status line, totals and one
+        outcome per processed file. Rows keep each source's listing index.
         """
         try:
             self.logger.info("Starting image scan operation")
-            output_dirs = self._get_all_output_dirs()
-            if not output_dirs:
+            if output_dirs is None:
+                output_dirs = self._get_all_output_dirs()
+            selected = job.scope.get("roots")
+            walked = (
+                output_dirs
+                if selected is None
+                else [output_dirs[index] for index in selected]
+            )
+            if not walked:
                 self.logger.error("No output directories found")
                 message = (
                     "No output directories found. "
@@ -1419,18 +1560,18 @@ class AdminRoutesMixin:
                 yield {"type": "error", "message": message}
                 return
 
-            dir_names = [self._public_path(d) for d in output_dirs]
-            folders = _plural(len(output_dirs), "output folder")
-            job.scope["output_folders"] = len(output_dirs)
+            dir_names = [self._public_path(d) for d in walked]
+            folders = _plural(len(walked), "output folder")
+            job.scope["output_folders"] = len(walked)
             scope = SCAN_SCOPE_LOG[job.scope.get("files", "all")]
             job.log_line(f"Scan started · {folders} · {scope}")
             job.update(status_line=f"Looking for media files in {folders}")
             yield self._scan_progress(
-                0, f"Scanning {len(output_dirs)} directory(ies) for media files..."
+                0, f"Scanning {len(walked)} directory(ies) for media files..."
             )
 
             media_files = await self._run_in_executor(
-                self._collect_output_media_sync, output_dirs
+                self._collect_output_media_sync, walked
             )
             counts = dict.fromkeys(SCAN_COUNT_KEYS, 0)
             job.update(
@@ -1445,10 +1586,13 @@ class AdminRoutesMixin:
             known = set()
             if media_files and job.scope.get("files") != "all":
                 known = await self._known_scan_files(job, media_files)
+            review = new_review_counts()
+            job.scope.update(_review_scope(review))
             async for event in self._scan_batches(
-                media_files, counts, job, roots, known
+                media_files, counts, job, roots, known, review
             ):
                 yield event
+            self._log_review_items(job, review)
 
             self.logger.info(
                 f"Scan completed: processed={counts['processed']}, "
@@ -1485,12 +1629,16 @@ class AdminRoutesMixin:
         sizes = {str(media_file): _file_size(media_file) for media_file in media_files}
         return self.db.get_known_resolved_paths(sizes)
 
-    async def _scan_batches(self, media_files, counts, job, roots=(), known=()):
+    async def _scan_batches(
+        self, media_files, counts, job, roots=(), known=(), review=None
+    ):
         """Process ``media_files`` in executor batches, updating ``counts`` in place.
 
         Records each file's outcome in ``job`` and yields one progress event
         per batch. Files in ``known`` (path strings) are not read: they count
-        as processed and unchanged and are recorded as skipped.
+        as processed and unchanged and are recorded as skipped. ``review``
+        counts the Needs review items the batches record (``job.scope``
+        ``review_items`` / ``review_errors`` follow it after every batch).
         """
         total = len(media_files)
         started = time.monotonic()
@@ -1513,9 +1661,16 @@ class AdminRoutesMixin:
                     batch_results,
                     roots=roots,
                     outcomes=outcomes,
+                    review=review,
                 )
                 for key in counts:
                     counts[key] += batch_counts[key]
+            if review is not None:
+                # After the batch's links: a file linked now leaves the queue.
+                await self._run_in_executor(
+                    self._settle_scanned_reviews, batch, roots, review
+                )
+                job.scope.update(_review_scope(review))
             for group, row, log_line in outcomes:
                 job.record(group, row, log_line)
 
@@ -1565,12 +1720,20 @@ class AdminRoutesMixin:
 
         return map_parallel(extract, file_batch, PromptManagerConfig.WORKER_THREADS)
 
-    def _ingest_scan_batch_sync(self, batch_results, roots=(), outcomes=None):
+    def _ingest_scan_batch_sync(
+        self, batch_results, roots=(), outcomes=None, review=None
+    ):
         """Store the prompts found in a metadata batch (blocking DB work).
 
         Returns the legacy counts. When ``outcomes`` is a list, every processed
         file appends its ``(group, row, log_line)`` for the scan job, with the
-        path relative to its root in ``roots`` (see ``_scan_roots``).
+        path relative to its root in ``roots`` (see ``_scan_roots``). A file
+        whose final outcome is ambiguous and unlinked (the resolver found it
+        ambiguous and the fallback did not link it) is recorded for Needs
+        review (best effort, counted in ``review`` when given); one a saved
+        row already links is reported ``unchanged`` and never queued. An
+        ambiguous file with nothing to choose is reported ``unresolved`` and
+        its pending items without a choice leave the queue.
         """
         counts = dict.fromkeys(SCAN_COUNT_KEYS, 0)
 
@@ -1582,13 +1745,32 @@ class AdminRoutesMixin:
             if self._scan_job and self._scan_job.cancelled:
                 break
             counts["processed"] += 1
+            ambiguous, untraced, records = [], [], {}
             try:
-                outcome = self._ingest_scanned_file(media_file, metadata, detailed=True)
+                outcome = self._ingest_scanned_file(
+                    media_file,
+                    metadata,
+                    detailed=True,
+                    ambiguous=ambiguous,
+                    untraced=untraced,
+                    records=records,
+                )
             except Exception as e:
                 self.logger.error(f"Error processing {media_file.name}: {e}")
                 counts["failed"] += 1
                 note(media_file, "error")
                 continue
+            if ambiguous and outcome == "ambiguous":
+                if self._review_file_linked(media_file, roots):
+                    outcome = "unchanged"  # already linked: not a review case
+                else:
+                    self._record_scanned_review(media_file, roots, review)
+            elif untraced and outcome == "unresolved":
+                # Untraced by the default profile: the inspection profile may
+                # still offer a choice (queued for review, never linked).
+                outcome = self._untraced_scan_outcome(
+                    media_file, roots, records.get("canonical"), review
+                )
             if outcome is None:
                 note(media_file, None)
                 continue
@@ -1622,13 +1804,29 @@ class AdminRoutesMixin:
             return None
         return positive.strip() or None
 
-    def _ingest_scanned_file(self, media_file, metadata, detailed=False):
+    def _ingest_scanned_file(
+        self,
+        media_file,
+        metadata,
+        detailed=False,
+        ambiguous=None,
+        untraced=None,
+        records=None,
+    ):
         """Enrich exact pairs; retain legacy positive-only import for absent pairs.
 
         Returns the file's scan status, or None without prompt metadata. With
         ``detailed``, a stored or linked file returns a dict instead: its
         ``status``, the prompt's display ``title`` and, for a resolved pair,
-        the pair counts.
+        the pair counts. When the resolver finds the file ambiguous (whether
+        or not the browser parser then links it) and ``ambiguous`` is a list,
+        ``media_file`` is appended to it; only a file that then returns
+        ``"ambiguous"`` (nothing linked it) is a Needs review case. An
+        ambiguous result with nothing to choose (``reviewable`` is False: fewer
+        than two candidates carry a prompt) that nothing links returns
+        ``"unresolved"`` instead, and ``media_file`` goes to ``untraced``;
+        its parsed records go to ``records["canonical"]`` when ``records`` is
+        a dict.
         """
         if not metadata:
             return None
@@ -1644,6 +1842,15 @@ class AdminRoutesMixin:
             return None
         _with_file_size(canonical, media_file)
         resolution = resolve_prompt_pair(canonical)
+        # Ambiguous without a choice: unresolved unless something links it.
+        unchoosable = resolution["state"] == "ambiguous" and not reviewable(resolution)
+        if unchoosable:
+            if untraced is not None:
+                untraced.append(media_file)
+            if records is not None:
+                records["canonical"] = canonical
+        elif resolution["state"] == "ambiguous" and ambiguous is not None:
+            ambiguous.append(media_file)
         if resolution["state"] == "resolved":
             result = ingest_resolved_pair(
                 self.db, str(media_file), canonical, resolution
@@ -1663,9 +1870,9 @@ class AdminRoutesMixin:
             # Graphs without a recognized sampler keep the legacy extractor below.
             prompt_text = self._graph_prompt_text(metadata)
             if not prompt_text:
-                return resolution["state"]
+                return "unresolved" if unchoosable else resolution["state"]
         elif resolution["state"] == "ambiguous":
-            return "ambiguous"
+            return "unresolved" if unchoosable else "ambiguous"
         elif resolution["state"] == "unresolved" and not isinstance(
             canonical.get("parameters"), str
         ):

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/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

@@ -734,7 +734,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 +764,44 @@ 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(),
+            }
+        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
@@ -309,17 +310,35 @@ class _OpenedCurrentMedia:
         self.handle.close()
 
 
+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 _prepare_current_media(
-    resolved: ResolvedCurrentCandidate, scope: CurrentOutputScope, *, thumbnail: bool
+    resolved: ResolvedCurrentCandidate,
+    scope: CurrentOutputScope,
+    *,
+    thumbnail: bool,
+    ensure_preview=None,
+    placeholder: bytes | None = None,
 ) -> _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>``.
+    """
     target = resolved.canonical_target
     if thumbnail:
         relative = target.relative_to(resolved.gallery_root)
-        extension = (
-            ".jpg"
-            if target.suffix.lower() in VIDEO_EXTENSIONS
-            else target.suffix.lower()
-        )
+        is_video = target.suffix.lower() in VIDEO_EXTENSIONS
+        extension = ".jpg" if is_video else target.suffix.lower()
         preview = (
             resolved.gallery_root
             / "thumbnails"
@@ -328,7 +347,14 @@ def _prepare_current_media(
         try:
             preview.stat()
         except FileNotFoundError:
-            pass
+            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 _OpenedCurrentMedia(
+                    io.BytesIO(placeholder), len(placeholder), "image/jpeg"
+                )
         else:
             target = _canonical(preview)
     handle = _open_current_target(target, resolved.namespace, scope)

py/api/images.py

@@ -3,6 +3,7 @@
 import asyncio
 import base64
 import binascii
+import functools
 import hashlib
 import hmac
 import json
@@ -19,7 +20,7 @@ from typing import Callable, NamedTuple
 from aiohttp import web
 from PIL import Image, UnidentifiedImageError
 
-from .jobs import THUMBNAILS_JOB_KIND
+from .jobs import MAX_OUTCOME_ROWS, THUMBNAILS_JOB_KIND
 from .prompts import bad_request, parse_page_params, publish_image_paths
 from .prompts import thumbnail_url_for
 from .prompts import safe_error_message as _safe_error
@@ -37,6 +38,7 @@ try:
     from ...database.models import normalize_image_path
     from ...utils.card_seed import card_seed, header_params, parsed_positive
     from ...utils.parallel import map_parallel
+    from ...utils.json_strict import dumps_strict
     from ...utils.inspection_response import (
         encode_inspection_response,
         library_metadata,
@@ -56,6 +58,7 @@ except ImportError:
     from database.models import normalize_image_path
     from utils.card_seed import card_seed, header_params, parsed_positive
     from utils.parallel import map_parallel
+    from utils.json_strict import dumps_strict
     from utils.inspection_response import (
         encode_inspection_response,
         library_metadata,
@@ -107,6 +110,8 @@ def _card_header(path: Path) -> tuple:
 
 # The legacy gallery page's thumbnail generation, as Activity lists it (D80).
 THUMBNAIL_GENERATION_TITLE = "Thumbnail generation (gallery page)"
+# Its clear: automatic previews are not written while it runs.
+THUMBNAIL_CLEAR_TITLE = "Thumbnail clear (gallery page)"
 
 
 class _CardFacts(NamedTuple):
@@ -232,6 +237,8 @@ MEDIA_EXTENSIONS = GALLERY_IMAGE_EXTENSIONS | VIDEO_EXTENSIONS
 # Caps on request-triggered filesystem work.
 MAX_SCAN_DEPTH = 12
 MAX_THUMBNAIL_FILES = 10_000
+# Already-fresh files a thumbnail job lists under Skipped (its counter stays exact).
+MAX_FRESH_LISTED = MAX_OUTCOME_ROWS
 
 
 def _worker_threads():
@@ -256,28 +263,127 @@ def _temp_sibling(dst):
     return dst.with_name(f".{dst.stem}.part-{token}{dst.suffix}")
 
 
-def _atomic_save(img, dst, fmt=None, **save_kwargs):
+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"
+
+
+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)
+
+
+def _atomic_save(img, dst, fmt=None, *, guard=None, **save_kwargs):
     """Save a PIL image to *dst* without a partially written file ever being
-    visible at that path: write a temp sibling, then rename over it."""
+    visible at that path: write a temp sibling, then rename over it.
+
+    ``guard()`` (automatic previews) is asked again just before the rename;
+    false leaves *dst* untouched and raises PreviewWriteHeld.
+    """
     tmp = _temp_sibling(dst)
     try:
         img.save(tmp, fmt, **save_kwargs)
-        os.replace(tmp, dst)
+        _replace_unless_held(tmp, dst, guard)
     finally:
         if tmp.exists():
             tmp.unlink()
 
 
-def _write_image_thumbnail(src, dst, thumbnail_size):
-    """Resize *src* into *dst* (blocking PIL work), atomically."""
+# Encoder settings per thumbnail quality (the System thumbnail dialog's
+# "Medium · optimized", "High · original", "Low · fastest"). The legacy
+# routes always encode as "medium", which is what they always wrote.
+THUMBNAIL_ENCODINGS = {
+    "low": {"quality": 70, "optimize": False},
+    "medium": {"quality": 85, "optimize": True},
+    "high": {"quality": 95, "optimize": True},
+}
+DEFAULT_THUMBNAIL_ENCODING = THUMBNAIL_ENCODINGS["medium"]
+# ffmpeg's JPEG scale (-q:v, 2 best to 31 worst) for each encoding's quality.
+_FFMPEG_QSCALE = {95: 2, 85: 4, 70: 8}
+
+# A preview that could not be replaced (#249 S5 M6). Windows refuses to rename
+# over a file another process has open (WinError 5 or 32), such as a preview
+# the gallery is serving; the old preview stays and the file counts as an error.
+PREVIEW_IN_USE = "Preview in use by another program; the old one was kept"
+PREVIEW_NOT_WRITABLE = "Permission denied writing the preview"
+_WINDOWS_LOCKED = (5, 32)  # ERROR_ACCESS_DENIED, ERROR_SHARING_VIOLATION
+
+
+def _preview_write_error(exc):
+    """The readable error for a PermissionError while writing a preview."""
+    if getattr(exc, "winerror", None) in _WINDOWS_LOCKED:
+        return PREVIEW_IN_USE
+    return PREVIEW_NOT_WRITABLE
+
+
+def _ffmpeg_qscale(encoding):
+    """ffmpeg's ``-q:v`` for a THUMBNAIL_ENCODINGS entry."""
+    return str(_FFMPEG_QSCALE.get(encoding["quality"], 4))
+
+
+def _write_image_thumbnail(src, dst, thumbnail_size, encoding=None, guard=None):
+    """Resize *src* into *dst* (blocking PIL work), atomically.
+
+    ``encoding`` is one of THUMBNAIL_ENCODINGS (medium when None); a PNG
+    preview keeps only its ``optimize`` flag. ``guard`` see _atomic_save.
+    """
+    encoding = encoding or DEFAULT_THUMBNAIL_ENCODING
     with Image.open(src) as img:
         if img.mode in ("RGBA", "LA", "P"):
             img = img.convert("RGB")
         img.thumbnail(thumbnail_size, Image.Resampling.LANCZOS)
-        save_kwargs = {"quality": 85, "optimize": True}
+        save_kwargs = dict(encoding)
         if dst.suffix.lower() == ".png":
-            save_kwargs = {"optimize": True}
-        _atomic_save(img, dst, **save_kwargs)
+            save_kwargs = {"optimize": encoding["optimize"]}
+        _atomic_save(img, dst, guard=guard, **save_kwargs)
+
+
+def _video_placeholder_image(thumbnail_size):
+    """The placeholder frame for a video no decoder could read: a play mark."""
+    from PIL import ImageDraw, ImageFont
+
+    img = Image.new("RGB", thumbnail_size, color=(50, 50, 50))
+    draw = ImageDraw.Draw(img)
+    center_x, center_y = thumbnail_size[0] // 2, thumbnail_size[1] // 2
+    triangle_size = min(thumbnail_size) // 4
+    points = [
+        (center_x - triangle_size // 2, center_y - triangle_size // 2),
+        (center_x - triangle_size // 2, center_y + triangle_size // 2),
+        (center_x + triangle_size // 2, center_y),
+    ]
+    draw.polygon(points, fill=(255, 255, 255))
+    try:
+        font = ImageFont.load_default()
+        text = "VIDEO"
+        bbox = draw.textbbox((0, 0), text, font=font)
+        text_width = bbox[2] - bbox[0]
+        draw.text(
+            (center_x - text_width // 2, center_y + triangle_size // 2 + 10),
+            text,
+            fill=(255, 255, 255),
+            font=font,
+        )
+    except (OSError, AttributeError):
+        pass
+    return img
+
+
+def _is_decode_error(exc):
+    """True when *exc* says the file itself cannot be decoded (#249 M4).
+
+    Pillow's decoder errors are OSErrors without an errno; a real I/O error
+    (disk full, a share gone) carries one and is worth another try.
+    """
+    if isinstance(exc, (UnidentifiedImageError, Image.DecompressionBombError)):
+        return True
+    if isinstance(exc, SyntaxError):
+        return True
+    return isinstance(exc, OSError) and exc.errno is None
 
 
 def _new_thumbnail_stats():
@@ -668,6 +774,53 @@ def _iter_media_files(output_path, max_files):
             yield root_path / name
 
 
+def media_thumbnail_rel(rel_path):
+    """``thumbnails/<rel>_thumb<ext>`` (POSIX) for the media file *rel_path*.
+
+    The extension is lower case, and a video's preview is a ``.jpg``: the
+    name every thumbnail writer (the plan, the job, automatic previews) uses.
+    """
+    rel_path = Path(rel_path)
+    extension = rel_path.suffix.lower()
+    return (
+        f"thumbnails/{rel_path.with_suffix('').as_posix()}_thumb"
+        f"{'.jpg' if extension in VIDEO_EXTENSIONS else extension}"
+    )
+
+
+def media_thumbnail(output_path, rel_path, root_index, *, root_scope=None):
+    """``(thumbnail_url, ready)`` for *rel_path* under *output_path* (one
+    blocking stat). The Images listing, the Needs review queue cards and the
+    Library use the same URL (#249 F, M10).
+
+    An existing preview's URL carries its mtime as ``v=`` and ``ready`` is
+    True. A missing one is still listed (without ``v=``): the serve route
+    makes it on first view and falls back when it cannot
+    (py/api/thumbnail_auto.py), so no card loads the full file because its
+    preview was not made yet. Media inside a nested ``thumbnails`` folder is
+    never previewed: ``(None, False)``, and its card shows the original.
+    """
+    rel_path = Path(rel_path)
+    if "thumbnails" in rel_path.parts[:-1]:
+        return None, False
+    thumb_rel = media_thumbnail_rel(rel_path)
+    thumbnail_url = thumbnail_url_for(thumb_rel, Path(output_path) / thumb_rel)
+    ready = thumbnail_url is not None
+    if thumbnail_url is None:
+        quoted = urllib.parse.quote(thumb_rel, safe="/")
+        thumbnail_url = f"/prompt_manager/images/serve/{quoted}?root={root_index}"
+    else:
+        thumbnail_url += f"&root={root_index}"
+    if root_scope is not None:
+        thumbnail_url += f"&root_scope={root_scope}"
+    return thumbnail_url, ready
+
+
+def media_thumbnail_url(output_path, rel_path, root_index, *, root_scope=None):
+    """The thumbnail URL of ``media_thumbnail`` (None for nested previews)."""
+    return media_thumbnail(output_path, rel_path, root_index, root_scope=root_scope)[0]
+
+
 def _output_image_entry(
     media_path, output_path, root_index, public_root=None, *, root_scope=None
 ):
@@ -683,19 +836,13 @@ def _output_image_entry(
     extension = media_path.suffix.lower()
     is_video = extension in VIDEO_EXTENSIONS
 
-    thumb_rel = (
-        f"thumbnails/{rel_path.with_suffix('').as_posix()}_thumb"
-        f"{'.jpg' if is_video else extension}"
+    thumbnail_url, thumbnail_ready = media_thumbnail(
+        output_path, rel_path, root_index, root_scope=root_scope
     )
-    thumbnail_url = thumbnail_url_for(thumb_rel, output_path / thumb_rel)
-    if thumbnail_url is not None:
-        thumbnail_url += f"&root={root_index}"
     encoded_path = urllib.parse.quote(rel_path.as_posix(), safe="/")
     url = f"/prompt_manager/images/serve/{encoded_path}?root={root_index}"
     if root_scope is not None:
         url += f"&root_scope={root_scope}"
-        if thumbnail_url is not None:
-            thumbnail_url += f"&root_scope={root_scope}"
 
     entry = {
         "id": hashlib.sha1(
@@ -708,6 +855,8 @@ def _output_image_entry(
         "root_index": root_index,
         "url": url,
         "thumbnail_url": thumbnail_url,
+        # Whether the preview file exists yet (the legacy gallery's dot, #249).
+        "thumbnail_ready": thumbnail_ready,
         "size": stat.st_size,
         "modified_time": stat.st_mtime,
         "extension": extension,
@@ -929,6 +1078,10 @@ class ImageRoutesMixin:
         async def thumbnail_status_route(request):
             return await self.get_thumbnail_status(request)
 
+        @routes.get("/prompt_manager/images/thumbnails/plan")
+        async def thumbnail_plan_route(request):
+            return await self.get_thumbnail_plan(request)
+
         @routes.post("/prompt_manager/images/generate-thumbnails")
         async def generate_thumbnails_route(request):
             return await self.generate_thumbnails(request)
@@ -982,27 +1135,12 @@ class ImageRoutesMixin:
             # Add url and thumbnail_url so the frontend can serve them
             cleaned_images = self._present_images(cleaned_images)
 
-            # Additional fallback: convert to JSON string and clean NaN values manually
-            try:
-                response_data = {"success": True, "images": cleaned_images}
-                # Convert to JSON string
-                json_str = json.dumps(response_data, default=str)
-
-                # Clean any remaining NaN values with regex
-                json_str = re.sub(r":\s*NaN", ": null", json_str)
-                json_str = re.sub(r"\[\s*NaN\s*\]", "[null]", json_str)
-                json_str = re.sub(r",\s*NaN\s*,", ", null,", json_str)
-                json_str = re.sub(r",\s*NaN\s*\]", ", null]", json_str)
-                json_str = re.sub(r"\[\s*NaN\s*,", "[null,", json_str)
-
-                # Parse back to verify it's valid JSON
-                cleaned_data = json.loads(json_str)
-
-                return web.json_response(cleaned_data)
-            except Exception as json_error:
-                self.logger.error(f"JSON cleaning error: {json_error}")
-                # Fallback to original response
-                return web.json_response({"success": True, "images": cleaned_images})
+            # Rows an older version stored may still hold NaN/Infinity: answer
+            # strict JSON, and leave prompt text that spells "NaN" untouched.
+            return web.json_response(
+                {"success": True, "images": cleaned_images},
+                dumps=functools.partial(dumps_strict, default=str),
+            )
 
         except Exception as e:
             self.logger.error(f"Get prompt images error: {e}")
@@ -1638,6 +1776,11 @@ class ImageRoutesMixin:
                 if image_path.is_file():
                     return self._file_response(image_path)
 
+            # A listed preview that was not made yet is made now (#249).
+            preview = await self._serve_missing_thumbnail(output_dirs, filepath)
+            if preview is not None:
+                return preview
+
             # ComfyUI's cache middleware would otherwise let browsers cache this
             # miss for an hour, hiding a thumbnail generated a moment later.
             return web.json_response(
@@ -1816,15 +1959,35 @@ class ImageRoutesMixin:
         self.logger.info(payload["message"])
         return payload
 
-    def _plan_gallery_thumbnails(self, output_dirs: list[Path]) -> dict:
-        """Plan every gallery root with one shared per-run generation cap."""
-        combined = {"targets": [], "skipped": 0, "remaining": 0}
+    def _plan_gallery_thumbnails(
+        self, output_dirs: list[Path], rebuild: bool = False, stop=None
+    ) -> dict:
+        """Plan every gallery root with one shared per-run generation cap.
+
+        See ``_plan_thumbnails``; ``fresh_files`` keeps at most
+        MAX_FRESH_LISTED files across the roots. ``stop()`` true ends the walk
+        at the next file (a cancelled job); the partial plan is returned.
+        """
+        combined = {
+            "targets": [],
+            "skipped": 0,
+            "remaining": 0,
+            "fresh": 0,
+            "fresh_files": [],
+        }
         for root in output_dirs:
+            if stop is not None and stop():
+                break
             root = Path(root)
-            plan = self._plan_thumbnails(root, root / "thumbnails")
+            plan = self._plan_thumbnails(
+                root, root / "thumbnails", rebuild=rebuild, stop=stop
+            )
             available = max(0, MAX_THUMBNAIL_FILES - len(combined["targets"]))
             combined["targets"].extend(plan["targets"][:available])
             combined["skipped"] += plan["skipped"]
+            combined["fresh"] += plan["fresh"]
+            room = max(0, MAX_FRESH_LISTED - len(combined["fresh_files"]))
+            combined["fresh_files"].extend(plan["fresh_files"][:room])
             combined["remaining"] += plan["remaining"] + max(
                 0, len(plan["targets"]) - available
             )
@@ -1845,6 +2008,8 @@ class ImageRoutesMixin:
                     "total_images": pending + plan["skipped"],
                     "pending": pending,
                     "ready": plan["skipped"],
+                    # Files whose automatic preview failed this session (#249).
+                    "failed": self._auto_thumbnail_failures(),
                     "collection_id": hashlib.sha256(collection.encode()).hexdigest()[
                         :16
                     ],
@@ -1857,22 +2022,30 @@ class ImageRoutesMixin:
                 {"success": False, "error": _safe_error(exc)}, status=500
             )
 
-    def _plan_thumbnails(self, output_path, thumbnails_dir):
+    def _plan_thumbnails(self, output_path, thumbnails_dir, rebuild=False, stop=None):
         """Decide which media files need a thumbnail (blocking walk).
 
-        Returns ``{"targets": [(src, dst, is_video)], "skipped": n, "remaining": n}``.
-        Files whose thumbnail is already newer than the source are counted as
-        skipped and never queued, so a large library that is mostly done only
-        pays for the files that changed. The walk is bounded like the gallery
-        listing (MAX_SCAN_DEPTH, MAX_GALLERY_FILES, no symlinks) and at most
-        MAX_THUMBNAIL_FILES pending files are queued per run; ``remaining``
-        counts the pending files beyond that cap.
+        Returns ``{"targets": [(src, dst, is_video)], "skipped": n,
+        "remaining": n, "fresh": n, "fresh_files": [src]}``. Files whose
+        thumbnail is already newer than the source are ``fresh``. Without
+        ``rebuild`` they are counted as skipped and never queued, so a large
+        library that is mostly done only pays for the files that changed;
+        ``fresh_files`` lists the first MAX_FRESH_LISTED of them. With
+        ``rebuild`` every file is a target (nothing is skipped). The walk is
+        bounded like the gallery listing (MAX_SCAN_DEPTH, MAX_GALLERY_FILES,
+        no symlinks) and at most MAX_THUMBNAIL_FILES targets are queued per
+        run; ``remaining`` counts the targets beyond that cap. ``stop()`` true
+        ends the walk before the next file.
         """
         output_path = Path(output_path)
         targets = []
         skipped = 0
         remaining = 0
+        fresh = 0
+        fresh_files = []
         for src in _iter_media_files(output_path, MAX_GALLERY_FILES):
+            if stop is not None and stop():
+                break
             suffix = src.suffix.lower()
             is_video = suffix in VIDEO_EXTENSIONS
             rel_no_ext = src.relative_to(output_path).with_suffix("")
@@ -1882,8 +2055,12 @@ class ImageRoutesMixin:
                 self.logger.warning(f"Skipping thumbnail outside safe dir: {src.name}")
                 continue
             if _thumbnail_is_fresh(src, dst):
-                skipped += 1
-                continue
+                fresh += 1
+                if not rebuild:
+                    skipped += 1
+                    if len(fresh_files) < MAX_FRESH_LISTED:
+                        fresh_files.append(src)
+                    continue
             if len(targets) >= MAX_THUMBNAIL_FILES:
                 remaining += 1
                 continue
@@ -1893,189 +2070,107 @@ class ImageRoutesMixin:
                 f"Thumbnail run capped at {MAX_THUMBNAIL_FILES} new files; "
                 f"{remaining} more will be generated on the next run"
             )
-        return {"targets": targets, "skipped": skipped, "remaining": remaining}
+        return {
+            "targets": targets,
+            "skipped": skipped,
+            "remaining": remaining,
+            "fresh": fresh,
+            "fresh_files": fresh_files,
+        }
 
     def _thumbnail_targets(self, output_path, thumbnails_dir):
         """Pending (src, dst, is_video) triples; see _plan_thumbnails."""
         return self._plan_thumbnails(output_path, thumbnails_dir)["targets"]
 
-    def _generate_batch(self, targets, thumbnail_size):
+    def _generate_batch(self, targets, thumbnail_size, **options):
         """Create thumbnails for ``targets`` on the configured worker threads.
 
-        Blocking; returns one result dict per target, in order.
+        Blocking; returns one result dict per target, in order. ``options``
+        go to ``_generate_one`` (``encoding``, ``rebuild``, ``stop``).
         """
 
         def one(target):
             src, dst, is_video = target
-            return self._generate_one(src, dst, thumbnail_size, is_video)
+            return self._generate_one(src, dst, thumbnail_size, is_video, **options)
 
         return map_parallel(one, targets, _worker_threads())
 
-    def _generate_one(self, src, dst, thumbnail_size, is_video):
-        """Create one thumbnail (blocking). Never raises; returns a result dict."""
+    def _generate_one(
+        self,
+        src,
+        dst,
+        thumbnail_size,
+        is_video,
+        encoding=None,
+        rebuild=False,
+        stop=None,
+        guard=None,
+        track=None,
+    ):
+        """Create one thumbnail (blocking). Never raises; returns a result dict.
+
+        ``stop()`` true before the file starts gives ``action: "cancelled"``
+        and touches nothing (a job's file boundary). ``rebuild`` writes a
+        fresh preview again and never replaces an existing video preview with
+        the placeholder. Every write is atomic, so a failure keeps the old
+        preview. ``guard()`` false just before the rename gives ``action:
+        "error"`` with ``held: True`` and writes nothing; ``track(process)``
+        is handed the ffmpeg process (both for automatic previews, #249). An
+        error result carries ``decode: True`` when the file itself cannot be
+        decoded (an I/O error does not).
+        """
         result = {
             "file": src.name,
             "dir": src.parent.name,
             "type": "video" if is_video else "image",
         }
         try:
+            if stop is not None and stop():
+                return {**result, "action": "cancelled"}
             if not src.is_file():
                 return {**result, "action": "error", "error": "File no longer exists"}
-            if _thumbnail_is_fresh(src, dst):
+            if not rebuild and _thumbnail_is_fresh(src, dst):
                 return {**result, "action": "skipped"}
             dst.parent.mkdir(parents=True, exist_ok=True)
             if is_video:
-                if not self._generate_video_thumbnail(src, dst, thumbnail_size):
-                    return {**result, "action": "error", "error": "Video decode failed"}
+                made = self._generate_video_thumbnail(
+                    src,
+                    dst,
+                    thumbnail_size,
+                    encoding,
+                    keep_existing=rebuild,
+                    guard=guard,
+                    track=track,
+                )
+                if not made:
+                    return {
+                        **result,
+                        "action": "error",
+                        "error": "Video decode failed",
+                        "decode": True,
+                    }
             else:
-                _write_image_thumbnail(src, dst, thumbnail_size)
+                _write_image_thumbnail(src, dst, thumbnail_size, encoding, guard)
             return {**result, "action": "generated"}
+        except PreviewWriteHeld:
+            return {**result, "action": "error", "error": PREVIEW_HELD, "held": True}
         except UnidentifiedImageError:
-            return {**result, "action": "error", "error": "Not a valid image file"}
+            return {
+                **result,
+                "action": "error",
+                "error": "Not a valid image file",
+                "decode": True,
+            }
+        except PermissionError as e:
+            message = _preview_write_error(e)
+            self.logger.warning(f"Thumbnail failed for {src.name}: {message}")
+            return {**result, "action": "error", "error": message}
         except Exception as e:
             self.logger.warning(f"Thumbnail failed for {src.name}", exc_info=True)
-            return {**result, "action": "error", "error": _safe_error(e)}
-
-    async def generate_thumbnails_with_progress(self, request):
-        """Generate thumbnails with Server-Sent Events progress updates (POST).
-
-        ``quality`` is read from the query string so a POST-capable SSE
-        client can keep using the same URL shape. Every blocking step (scan,
-        PIL/ffmpeg) runs in the executor; the event loop only writes SSE
-        frames between files.
-        """
-        thumbnail_size = self._thumbnail_size(request.query.get("quality", "medium"))
-        response = web.StreamResponse(
-            status=200,
-            headers={
-                "Content-Type": "text/event-stream",
-                "Cache-Control": "no-cache",
-                "Connection": "keep-alive",
-            },
-        )
-        busy = self._jobs.blocker(THUMBNAILS_JOB_KIND, admission="guarded")
-        if busy is not None:
-            # The gallery reads this stream: refuse with its error event.
-            await response.prepare(request)
-            message = f"{busy.title} already running"
-            await self._emit_sse(
-                response, "error", {"error": message, "message": message}
-            )
-            return response
-        async with self._jobs.hold(
-            THUMBNAILS_JOB_KIND, THUMBNAIL_GENERATION_TITLE, admission="guarded"
-        ) as job:
-            await response.prepare(request)
-            if not await self._thumbnail_progress_stream(response, thumbnail_size):
-                job.finish("failed")  # an error event ended the stream
-        return response
-
-    async def _thumbnail_progress_stream(self, response, thumbnail_size) -> bool:
-        """Stream one generation run; False when it ended with an error event."""
-        try:
-            output_dirs = self._get_all_output_dirs()
-            if not output_dirs:
-                await self._emit_sse(
-                    response, "error", {"error": "ComfyUI output directory not found"}
-                )
-                return False
-
-            await self._emit_sse(
-                response,
-                "status",
-                {"phase": "scanning", "message": "Scanning for images and videos..."},
-            )
-            plan = await self._run_in_executor(
-                self._plan_gallery_thumbnails, output_dirs
-            )
-            await self._stream_thumbnails(
-                response,
-                plan["targets"],
-                thumbnail_size,
-                skipped=plan["skipped"],
-                remaining=plan["remaining"],
-            )
-            self.invalidate_gallery_cache()
-            return True
-        except Exception:
-            self.logger.exception("Thumbnail generation failed")
-            await self._emit_sse(
-                response,
-                "error",
-                {
-                    "error": "An internal error occurred",
-                    "message": "Thumbnail generation failed. Check server logs.",
-                },
-            )
-            return False
-
-    async def _stream_thumbnails(
-        self, response, targets, thumbnail_size, skipped=0, remaining=0
-    ):
-        """Process pending *targets* in worker-thread batches, emitting SSE per file.
-
-        ``skipped`` files already had fresh thumbnails and ``remaining`` were
-        left for the next run; both only feed the start/complete payloads.
-        """
-        total = len(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 skipped:
-            message += f" ({skipped} already have thumbnails)"
-        connected = await self._emit_sse(
-            response,
-            "start",
-            {
-                "total_images": total,
-                "skipped": skipped,
-                "remaining": remaining,
-                "phase": "processing",
-                "image_count": total - video_count,
-                "video_count": video_count,
-                "message": message,
-            },
-        )
-        if not connected:
-            return
-        stats = _new_thumbnail_stats()
-        stats["skipped"] = skipped
-        start = _time.monotonic()
-        batch_size = _thumbnail_batch_size(_worker_threads())
-        index = 0
-        for batch_start in range(0, total, batch_size):
-            batch = targets[batch_start : batch_start + batch_size]
-            results = await self._run_in_executor(
-                self._generate_batch, batch, thumbnail_size
-            )
-            for result in results:
-                index += 1
-                _record_thumbnail_result(stats, result)
-                if result["action"] == "error":
-                    await self._emit_sse(
-                        response,
-                        "file_error",
-                        {"file": result["file"], "error": result["error"]},
-                    )
-                connected = await self._emit_sse(
-                    response,
-                    "progress",
-                    _thumbnail_progress_payload(index, total, stats, result, start),
-                )
-                if not connected:
-                    self.logger.info("Thumbnail client disconnected; stopping early")
-                    return
-            await asyncio.sleep(0)  # let other requests run between batches
-        payload = _thumbnail_complete_payload(
-            total + skipped + remaining,
-            stats,
-            start,
-            remaining=remaining,
-            processed=total,
-        )
-        await self._emit_sse(response, "complete", payload)
-        self.logger.info(payload["message"])
+            failed = {**result, "action": "error", "error": _safe_error(e)}
+            if _is_decode_error(e):
+                failed["decode"] = True
+            return failed
 
     async def _emit_sse(self, response, event, data) -> bool:
         """Write one SSE frame. Returns False once the client has gone away."""
@@ -2087,131 +2182,155 @@ class ImageRoutesMixin:
             self.logger.warning(f"Failed to send SSE message: {e}")
             return False
 
-    def _generate_video_thumbnail(self, video_path, thumbnail_path, thumbnail_size):
-        """Generate thumbnail from video file. Returns True if successful."""
+    def _generate_video_thumbnail(
+        self,
+        video_path,
+        thumbnail_path,
+        thumbnail_size,
+        encoding=None,
+        keep_existing=False,
+        *,
+        guard=None,
+        track=None,
+    ):
+        """Generate thumbnail from video file. Returns True if successful.
+
+        Tries OpenCV, then ffmpeg, then writes the placeholder frame: a
+        decoder that cannot open or read the clip (an AV1 file OpenCV was
+        built without) falls through to the next one (#249 I1). ``encoding``
+        is one of THUMBNAIL_ENCODINGS (medium when None); it encodes the
+        OpenCV frame, ffmpeg's frame (as ``-q:v``) and the placeholder alike.
+        Both decoders fit the frame inside ``thumbnail_size`` keeping its
+        aspect ratio. With ``keep_existing`` an existing preview is kept, and
+        the run fails, when no frame could be decoded, rather than replaced
+        by the placeholder. A PermissionError while replacing the preview
+        propagates (``_generate_one`` names it), as does PreviewWriteHeld
+        when ``guard()`` refuses the rename. ``track(process)`` is handed the
+        ffmpeg process so a shutdown can kill it.
+        """
+        encoding = encoding or DEFAULT_THUMBNAIL_ENCODING
         try:
-            # Try using OpenCV first (most reliable)
-            try:
-                import cv2
-
-                cap = cv2.VideoCapture(str(video_path))
-                if not cap.isOpened():
-                    return False
-
-                frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
-                target_frame = max(1, int(frame_count * 0.1))
-                cap.set(cv2.CAP_PROP_POS_FRAMES, target_frame)
-
-                ret, frame = cap.read()
-                cap.release()
-
-                if not ret or frame is None:
-                    return False
-
-                frame_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
-
-                img = Image.fromarray(frame_rgb)
-                img.thumbnail(thumbnail_size, Image.Resampling.LANCZOS)
-                _atomic_save(img, thumbnail_path, "JPEG", quality=85, optimize=True)
+            frame = self._opencv_frame(video_path, thumbnail_size)
+            if frame is not None:
+                _atomic_save(frame, thumbnail_path, "JPEG", guard=guard, **encoding)
                 self.logger.debug(
                     f"Generated video thumbnail using OpenCV: {thumbnail_path}"
                 )
                 return True
-
-            except ImportError:
-                pass
-
-            # Fallback to ffmpeg
+            if self._ffmpeg_frame(
+                video_path, thumbnail_path, thumbnail_size, encoding, guard, track
+            ):
+                return True
+            if keep_existing and thumbnail_path.exists():
+                self.logger.warning(
+                    f"No frame decoded for {video_path.name}; keeping its preview"
+                )
+                return False
+            # Last resort: the placeholder frame.
             try:
-                import subprocess
-
-                tmp_path = _temp_sibling(thumbnail_path)
-                cmd = [
-                    "ffmpeg",
-                    "-i",
-                    str(video_path),
-                    "-ss",
-                    "00:00:01",
-                    "-vframes",
-                    "1",
-                    "-s",
-                    f"{thumbnail_size[0]}x{thumbnail_size[1]}",
-                    "-y",
-                    str(tmp_path),
-                ]
-
-                result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
-                if result.returncode == 0 and tmp_path.exists():
-                    os.replace(tmp_path, thumbnail_path)
-                    self.logger.debug(
-                        f"Generated video thumbnail using ffmpeg: {thumbnail_path}"
-                    )
-                    return True
-                else:
-                    self.logger.warning(
-                        f"ffmpeg failed for {video_path}: {result.stderr}"
-                    )
-
-            except (ImportError, subprocess.TimeoutExpired, FileNotFoundError):
-                pass
-            finally:
-                try:
-                    tmp_path.unlink()
-                except (NameError, OSError):
-                    pass
-
-            # Last resort: create a placeholder thumbnail
-            try:
-                from PIL import ImageDraw, ImageFont
-
-                img = Image.new("RGB", thumbnail_size, color=(50, 50, 50))
-                draw = ImageDraw.Draw(img)
-
-                center_x, center_y = thumbnail_size[0] // 2, thumbnail_size[1] // 2
-                triangle_size = min(thumbnail_size) // 4
-
-                points = [
-                    (center_x - triangle_size // 2, center_y - triangle_size // 2),
-                    (center_x - triangle_size // 2, center_y + triangle_size // 2),
-                    (center_x + triangle_size // 2, center_y),
-                ]
-                draw.polygon(points, fill=(255, 255, 255))
-
-                try:
-                    font = ImageFont.load_default()
-                    text = "VIDEO"
-                    bbox = draw.textbbox((0, 0), text, font=font)
-                    text_width = bbox[2] - bbox[0]
-                    draw.text(
-                        (
-                            center_x - text_width // 2,
-                            center_y + triangle_size // 2 + 10,
-                        ),
-                        text,
-                        fill=(255, 255, 255),
-                        font=font,
-                    )
-                except (OSError, AttributeError):
-                    pass
-
-                _atomic_save(img, thumbnail_path, "JPEG", quality=85)
+                img = _video_placeholder_image(thumbnail_size)
+                _atomic_save(img, thumbnail_path, "JPEG", guard=guard, **encoding)
                 self.logger.debug(
                     f"Generated placeholder video thumbnail: {thumbnail_path}"
                 )
                 return True
-
+            except (PermissionError, PreviewWriteHeld):
+                raise
             except Exception as e:
                 self.logger.warning(
                     f"Failed to create placeholder thumbnail for {video_path}: {e}"
                 )
                 return False
-
+        except (PermissionError, PreviewWriteHeld):
+            raise
         except Exception as e:
             self.logger.error(
                 f"Video thumbnail generation failed for {video_path}: {e}"
             )
             return False
 
+    def _opencv_frame(self, video_path, thumbnail_size):
+        """A frame about 10% in, fitted to *thumbnail_size*, or None (no
+        OpenCV, or it could not open or read the clip)."""
+        try:
+            import cv2
+        except ImportError:
+            return None
+        try:
+            cap = cv2.VideoCapture(str(video_path))
+            try:
+                if not cap.isOpened():
+                    return None
+                frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+                cap.set(cv2.CAP_PROP_POS_FRAMES, max(1, int(frame_count * 0.1)))
+                ret, frame = cap.read()
+            finally:
+                cap.release()
+            if not ret or frame is None:
+                return None
+            img = Image.fromarray(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))
+            img.thumbnail(thumbnail_size, Image.Resampling.LANCZOS)
+            return img
+        except Exception as e:
+            self.logger.debug(f"OpenCV could not read {video_path}: {e}")
+            return None
+
+    def _ffmpeg_frame(
+        self, video_path, thumbnail_path, thumbnail_size, encoding, guard, track
+    ):
+        """Write ffmpeg's frame at 1 s into *thumbnail_path*; True on success."""
+        import subprocess  # nosec B404 - fixed argv, no shell
+
+        tmp_path = _temp_sibling(thumbnail_path)
+        cmd = [
+            "ffmpeg",
+            "-i",
+            str(video_path),
+            "-ss",
+            "00:00:01",
+            "-vframes",
+            "1",
+            "-vf",
+            f"scale={thumbnail_size[0]}:{thumbnail_size[1]}"
+            ":force_original_aspect_ratio=decrease",
+            "-q:v",
+            _ffmpeg_qscale(encoding),
+            "-y",
+            str(tmp_path),
+        ]
+        try:
+            process = subprocess.Popen(  # nosec B603 B607 - fixed argv
+                cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+            )
+            if track is not None:
+                track(process)
+            try:
+                _out, stderr = process.communicate(timeout=30)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.communicate()
+                return False
+            if process.returncode == 0 and tmp_path.exists():
+                _replace_unless_held(tmp_path, thumbnail_path, guard)
+                self.logger.debug(
+                    f"Generated video thumbnail using ffmpeg: {thumbnail_path}"
+                )
+                return True
+            self.logger.warning(f"ffmpeg failed for {video_path}: {stderr}")
+            return False
+        except (FileNotFoundError, OSError) as e:
+            if isinstance(e, PermissionError) and tmp_path.exists():
+                raise
+            return False
+        finally:
+            try:
+                tmp_path.unlink()
+            except OSError:
+                pass
+
     async def clear_thumbnails(self, request: web.Request) -> web.Response:
         """Clear generated thumbnails across gallery roots, preserving originals.
 
@@ -2221,7 +2340,7 @@ class ImageRoutesMixin:
         """
         return await self._run_held(
             THUMBNAILS_JOB_KIND,
-            "Thumbnail clear (gallery page)",
+            THUMBNAIL_CLEAR_TITLE,
             "guarded",
             self._clear_thumbnails,
         )

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,7 +19,11 @@ 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
@@ -72,12 +76,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 +97,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 +261,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 +303,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()
@@ -425,20 +471,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 +515,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

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/maintenance.py

@@ -0,0 +1,815 @@
+"""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),
+``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
+import tempfile
+from contextlib import closing
+
+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.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.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
+# 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"
+_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 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 _now():
+    return datetime.datetime.now()
+
+
+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 disks have room for (blocking).
+
+    The upload is written to a temp file and staged once more in the
+    temporary folder (2x), then copied over the live database beside it,
+    whose current contents are first kept as a safety backup (1x the upload
+    for the WAL, plus the current database). Needs on one device add up,
+    each with ``DISK_MARGIN_BYTES``.
+    """
+    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
+    devices = {}
+    for path, per_upload, fixed in (
+        (tempfile.gettempdir(), 2, 0),
+        (folder, 1, current),
+    ):
+        entry = devices.setdefault(_device(path), {"path": path, "per": 0, "fixed": 0})
+        entry["per"] += per_upload
+        entry["fixed"] += fixed
+    room = min(
+        (_free_bytes(e["path"]) - e["fixed"] - DISK_MARGIN_BYTES) // e["per"]
+        for e in devices.values()
+    )
+    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 _remove_quietly(*paths):
+    for path in paths:
+        try:
+            if path and os.path.exists(path):
+                os.remove(path)
+        except OSError:
+            pass
+
+
+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 _backup_names(db_path, label="backup"):
+    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 _place_backup(temp, db_path, label="backup"):
+    """Give the verified ``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
+
+
+SAFETY_TEMP_PREFIX = ".pm-safety-"
+
+
+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 _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(path):
+    with open(path, "rb+") as handle:
+        os.fsync(handle.fileno())
+
+
+def take_safety_backup(model, label="backup"):
+    """Write and verify a safety backup; return its file name (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 verified,
+    so a backup file on disk is always a verified 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)
+    fd, temp = tempfile.mkstemp(
+        dir=os.path.dirname(db_path), prefix=SAFETY_TEMP_PREFIX, suffix=".tmp"
+    )
+    os.close(fd)
+    final = None
+    try:
+        if not model.backup_database(temp):
+            raise SafetyBackupFailed("The backup could not be written")
+        _standalone(temp)
+        ok, reason = model.verify_database_file(temp)
+        if not ok:
+            raise SafetyBackupFailed("The backup did not verify", reason)
+        _fsync(temp)
+        if os.name != "nt":
+            os.chmod(temp, 0o600)
+        final = _place_backup(temp, db_path, label)
+        return os.path.basename(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")
+
+
+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):
+        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")
+            return _failure(APPLY_FAILED, 500)
+        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."""
+    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/review.py

@@ -0,0 +1,713 @@
+"""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 .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
+
+
+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."""
+        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,15 @@ 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 os
 
 from aiohttp import web
@@ -15,7 +22,10 @@ from ..config_store import (
     RevisionConflict,
     get_config_store,
 )
+from . import sources
 from .admin import _current_image_monitor
+from .job_routes import busy_response
+from .jobs import JobBusy
 
 try:
     from ...utils.validators import validate_result_timeout, validate_worker_threads
@@ -23,13 +33,76 @@ 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"),
 }
+# 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 +120,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 +133,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 +162,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 +175,20 @@ 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)
             return web.json_response(
                 {
                     "success": True,
                     **revision,
+                    "sources": source_status,
+                    "monitor": monitor,
                     "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,
                         "cpu_count": PromptManagerConfig.max_worker_threads(),
                         "gallery_root_paths": root_paths,
                         "gallery_root_path": root_paths[0] if root_paths else "",
@@ -115,6 +205,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
@@ -151,9 +296,15 @@ class SettingsRoutesMixin:
                     {"success": False, "error": str(ve)}, status=400
                 )
 
-            new_roots, error = self._parse_gallery_roots(data)
+            # 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 +313,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(
                 {
@@ -196,10 +362,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 +379,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,6 +479,14 @@ 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()
@@ -295,15 +499,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 +522,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,843 @@
+"""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 thumbnail job's default
+size and quality (``DEFAULT_THUMBNAIL_EDGE``, medium), into a temp sibling
+renamed over the old one, so a reader never sees a partial file.
+
+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 .images import (
+    GALLERY_IMAGE_EXTENSIONS,
+    MEDIA_EXTENSIONS,
+    THUMBNAIL_CLEAR_TITLE,
+    THUMBNAIL_ENCODINGS,
+    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_jobs import DEFAULT_THUMBNAIL_EDGE, ThumbnailOptions
+
+try:
+    from ...utils.parallel import map_parallel
+except ImportError:  # tests import the package top-level
+    from utils.parallel import map_parallel
+
+AUTO_THUMBNAIL_EDGE = DEFAULT_THUMBNAIL_EDGE
+AUTO_THUMBNAIL_SIZE = (AUTO_THUMBNAIL_EDGE, AUTO_THUMBNAIL_EDGE)
+AUTO_THUMBNAIL_ENCODING = THUMBNAIL_ENCODINGS["medium"]
+# 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(AUTO_THUMBNAIL_SIZE).save(
+        buffer, "JPEG", **AUTO_THUMBNAIL_ENCODING
+    )
+    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 GALLERY_IMAGE_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, extensions)`` of a checked preview request."""
+    stem, extension = os.path.splitext(parts[-1])
+    wanted = [extension] + (sorted(VIDEO_EXTENSIONS) if extension == ".jpg" else [])
+    return parts[1:-1], stem[: -len("_thumb")], wanted
+
+
+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 previews as the requested one
+    (any case: exact names first, then one listing of the folder); a ``.jpg``
+    may also be a video's. It must be a regular file inside *root*. ``dst``
+    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 != root.joinpath(*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)
+
+    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,
+            AUTO_THUMBNAIL_SIZE,
+            is_video,
+            encoding=AUTO_THUMBNAIL_ENCODING,
+            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 = root.joinpath(*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", AUTO_THUMBNAIL_EDGE, "medium")
+            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_jobs.py

@@ -0,0 +1,494 @@
+"""Thumbnail generation as an Activity job (#249 System S5, Task 12).
+
+- ``GET /prompt_manager/images/thumbnails/plan?mode=&size=&quality=`` counts
+  what a run would do over every gallery root and writes nothing:
+  ``{success, targets, fresh, remaining, roots, mode, size, quality}``.
+- ``POST /prompt_manager/jobs/thumbnails {mode, size, quality}`` 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)
+or ``rebuild`` (every preview again, fresh ones too). ``size`` is the
+preview's longest edge, 128 to 2048 pixels. ``quality`` picks the encoder
+settings (``THUMBNAIL_ENCODINGS``). Every preview is written next to the old
+one 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 (its quality preset still sizes the previews) 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 (
+    THUMBNAIL_ENCODINGS,
+    _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
+
+THUMBNAIL_JOB_TITLE = "Thumbnail generation"
+THUMBNAIL_MODES = ("missing", "rebuild")
+THUMBNAIL_QUALITIES = tuple(THUMBNAIL_ENCODINGS)
+MIN_THUMBNAIL_EDGE = 128
+MAX_THUMBNAIL_EDGE = 2048
+# The concept's "Preview size limit" default.
+DEFAULT_THUMBNAIL_EDGE = 512
+DEFAULT_THUMBNAIL_OPTIONS = {
+    "mode": "missing",
+    "size": DEFAULT_THUMBNAIL_EDGE,
+    "quality": "medium",
+}
+_OPTIONS_ERROR = (
+    'mode must be "missing" or "rebuild", quality "low", "medium" or "high", '
+    f"and size a whole number of pixels from {MIN_THUMBNAIL_EDGE} "
+    f"to {MAX_THUMBNAIL_EDGE}"
+)
+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, the preview's longest edge and quality."""
+
+    mode: str
+    edge: int
+    quality: str
+
+    @property
+    def size(self):
+        return (self.edge, self.edge)
+
+    @property
+    def encoding(self):
+        return THUMBNAIL_ENCODINGS[self.quality]
+
+    @property
+    def rebuild(self):
+        return self.mode == "rebuild"
+
+    def scope(self):
+        return {"mode": self.mode, "size": self.edge, "quality": self.quality}
+
+
+def _edge(value, *, from_query):
+    """The preview edge as an int, or None when it is not one in range."""
+    if from_query and isinstance(value, str):
+        if not value.isascii() or not value.isdigit() or len(value) > 5:
+            return None
+        value = int(value)
+    if isinstance(value, bool) or not isinstance(value, int):
+        return None
+    return value if MIN_THUMBNAIL_EDGE <= value <= MAX_THUMBNAIL_EDGE else None
+
+
+def thumbnail_options(raw, *, from_query=False):
+    """``(ThumbnailOptions, None)`` from a body or query, or ``(None, message)``.
+
+    Absent fields take ``DEFAULT_THUMBNAIL_OPTIONS``. Query values are
+    strings, so a query ``size`` may be decimal digits; a JSON ``size`` must
+    be an int.
+    """
+    if not isinstance(raw, dict) and not hasattr(raw, "get"):
+        return None, _OPTIONS_ERROR
+    mode = raw.get("mode", DEFAULT_THUMBNAIL_OPTIONS["mode"])
+    quality = raw.get("quality", DEFAULT_THUMBNAIL_OPTIONS["quality"])
+    edge = _edge(raw.get("size", DEFAULT_THUMBNAIL_EDGE), from_query=from_query)
+    if mode not in THUMBNAIL_MODES or quality not in THUMBNAIL_QUALITIES:
+        return None, _OPTIONS_ERROR
+    if edge is None:
+        return None, _OPTIONS_ERROR
+    return ThumbnailOptions(mode, edge, quality), 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, rebuild=options.rebuild
+            )
+        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"],
+                "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."""
+        return self._jobs.start(
+            THUMBNAILS_JOB_KIND,
+            THUMBNAIL_JOB_TITLE,
+            admission="guarded",
+            cancellable=True,
+            scope=options.scope(),
+            runner=functools.partial(self._run_thumbnail_job, 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.edge} px · {options.quality}"
+        )
+        job.publish(
+            _frame(
+                "status",
+                {"phase": "scanning", "message": "Scanning for images and videos..."},
+            )
+        )
+        plan = await self._run_in_executor(
+            self._plan_gallery_thumbnails,
+            output_dirs,
+            rebuild=options.rebuild,
+            stop=lambda: job.cancelled,
+        )
+        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 = await self._generate_thumbnail_targets(job, options, plan, roots)
+        self.invalidate_gallery_cache()
+        generated = _plural(stats["generated"], "preview")
+        if job.cancelled:
+            return self._end_cancelled(
+                job, stats["generated"], f"Cancelled · {generated} written"
+            )
+        payload = _thumbnail_complete_payload(
+            len(plan["targets"]) + plan["skipped"] + plan["remaining"],
+            stats,
+            start,
+            remaining=plan["remaining"],
+            processed=len(plan["targets"]),
+        )
+        job.update(progress=100, status_line=_finished_line(plan, stats))
+        if plan["remaining"]:
+            job.log_line(
+                f"{plan['remaining']:,} 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"
+
+    @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")
+
+    async def _generate_thumbnail_targets(self, job, options, plan, roots):
+        """Generate ``plan``'s targets in worker batches, publishing each file."""
+        targets = plan["targets"]
+        total = len(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": plan["remaining"],
+                    "phase": "processing",
+                    "image_count": total - video_count,
+                    "video_count": video_count,
+                    "message": message,
+                },
+            )
+        )
+        stats = _new_thumbnail_stats()
+        stats["skipped"] = plan["skipped"]
+        start = time.monotonic()
+        batch_size = _thumbnail_batch_size(_worker_threads())
+        generate = {
+            "encoding": options.encoding,
+            "rebuild": options.rebuild,
+            "stop": lambda: job.cancelled,
+        }
+        index = 0
+        batches = 0
+        for batch_start in range(0, total, 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.size, **generate
+            )
+            for (src, _dst, _video), result in zip(batch, results):
+                if result["action"] == "cancelled":
+                    continue
+                index += 1
+                _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),
+                    )
+                )
+            batches += 1
+            job.update(
+                status_line=_scan_status_line(
+                    index, total, batches, time.monotonic() - start
+                )
+            )
+            await asyncio.sleep(0)  # let other requests run between batches
+        return stats, start
+
+    @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 with the gallery's quality preset as the
+        preview size (missing previews, medium encoding, as before), 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.
+        """
+        thumbnail_size = self._thumbnail_size(request.query.get("quality", "medium"))
+        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(thumbnail_size)
+        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, thumbnail_size):
+        """``(job, started, busy)`` for the legacy stream, synchronously.
+
+        Attaches to the running cancellable thumbnail job, or starts one with
+        the gallery's preset as the size (missing previews, medium encoding,
+        as the gallery always wrote), or names the job in the way.
+        """
+        running = self._jobs.active(THUMBNAILS_JOB_KIND)
+        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", thumbnail_size[0], "medium")
+        return self._start_thumbnail_job(options), True, None

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
@@ -268,7 +300,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:
@@ -337,31 +374,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 +461,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 +661,14 @@ 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
+
     @classmethod
     def max_worker_threads(cls) -> int:
         """Largest accepted worker-thread count: the detected core count."""
@@ -617,6 +723,8 @@ 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},
             "gallery": GalleryConfig.get_config(),
             "integrations": IntegrationConfig.get_config(),
             "autotag": AutotagConfig.get_config(),
@@ -626,14 +734,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 +858,18 @@ 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"]
+
         # Update gallery config
         if "gallery" in new_config:
             GalleryConfig.update_config(new_config["gallery"])

py/lora_utils.py

@@ -567,10 +567,21 @@ def download_civitai_images(
 
 
 def get_lora_image_cache_dir() -> Path:
-    """Get the directory used to cache downloaded LoRA example images."""
-    # Store in the extension's own directory
+    """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``.
+    """
+    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 = Path(
+        library_location.cache_dir("lora_images", extension_root=str(ext_root))
+    )
     cache.mkdir(parents=True, exist_ok=True)
     return cache
 

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/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
@@ -40,6 +41,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,6 +199,7 @@ 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)
@@ -226,6 +229,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",
@@ -382,6 +387,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 +598,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 +657,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 +693,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-concept.spec.mjs

@@ -169,9 +169,9 @@ 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: 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: no backup has been recorded (verified backups arrive with S8).
         'Backup status': row => ({ ...row, description: 'No retained backup record.' }),
         // D93: there is no paging, so the shared settings are grid and density.
@@ -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.' },
@@ -230,16 +240,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 +425,581 @@ 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,
+        // 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(['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").
+ */
+function mapThumbnailConcept(reference, plan) {
+    const [cancel, start] = reference.actions.buttons;
+    const tree = [...reference.tree];
+    tree.splice(tree.indexOf('div.dialog-actions'), 0, 'p.small');
+    return { ...reference, tree,
+        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')).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&size=512&quality=medium');
+
+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 is recorded.
+    expect(diffInventory(concept, production).map(item => item.path).sort())
+        .toEqual(['actions.buttons.1.text', 'plan.role', 'plan.text', 'tree.3', 'tree.4', 'tree.length']);
+    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-quality option').textContent = 'Medium'; });
+    expect(await paths()).toEqual(['fields.1.control.options.0']);
+    await page.evaluate(() => { document.querySelector('#thumb-quality option').textContent = 'Medium · optimized'; });
+    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.prepend(select.lastElementChild); 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-limit { border-color: rgb(255, 0, 0); } dialog#modal #modal-body > p.small { color: rgb(255, 0, 0); }' });
+    expect(await paths()).toEqual(expect.arrayContaining(['fields.2.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/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();

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\.jpg\?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\.jpg\?/);
+    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 }) => {

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-sources.spec.mjs

@@ -0,0 +1,535 @@
+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.`;
+
+test('Review options shows the plan counts for the chosen scope/quality/size before Start', async ({ page, request }) => {
+    await expect(await request.post('/__test__/system/unthumbnailed', { data: { count: 3 } })).toBeOK();
+    // Image loading quality (Appearance, Q3) preselects the dialog's quality.
+    await page.addInitScript(() => { if (location.protocol.startsWith('http')) localStorage.setItem('gallerySettings', JSON.stringify({ imageQuality: 'high' })); });
+    const seen = thumbnailRequests(page);
+    const plan = await serverJson(request, `${THUMBNAIL_PLAN_URL}?mode=missing&size=512&quality=high`);
+    expect(plan.targets).toBe(3);
+    const review = await openThumbnailReview(page);
+    await expect(review.locator('#modal-body > *')).toHaveCount(5);
+    await expect(review.locator('.field > label')).toHaveText(['Scope', 'Quality', 'Preview size limit']);
+    await expect(review.locator('#thumb-mode option')).toHaveText(['Missing thumbnails only', 'Rebuild all (explicit opt-in)']);
+    await expect(review.locator('#thumb-quality option')).toHaveText(['Medium · optimized', 'High · original', 'Low · fastest']);
+    await expect(review.locator('#thumb-mode')).toHaveValue('missing');
+    await expect(review.locator('#thumb-quality')).toHaveValue('high');
+    await expect(review.locator('#thumb-limit')).toHaveValue('512');
+    await expect(review.locator('#thumb-limit')).toHaveAttribute('min', '128');
+    await expect(review.locator('#thumb-limit')).toHaveAttribute('max', '2048');
+    const line = review.locator('#modal-body > p.small');
+    await expect(line).toHaveAttribute('role', 'status');
+    await expect(line).toHaveText(missingLine(plan));
+    expect(seen.plans).toEqual([{ mode: 'missing', size: '512', quality: 'high' }]);
+    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('size outside 128–2048 reports validity and requests nothing', async ({ page, request }) => {
+    const seen = thumbnailRequests(page);
+    const review = await openThumbnailReview(page);
+    const line = review.locator('#modal-body > p.small');
+    await expect(line).toHaveText(/ already up to date\.$/);
+    const size = review.locator('#thumb-limit');
+    for (const value of ['4096', '64', '']) {
+        await size.fill(value);
+        await expect(size).toHaveAttribute('aria-invalid', 'true');
+        await expect(line).toHaveText('Enter a size from 128 to 2048 pixels.');
+        expect(await size.evaluate(input => input.validity.valid)).toBe(false);
+        // Start keeps the dialog open and sends nothing; neither does a scope change.
+        await review.getByRole('button', { name: 'Start', exact: true }).click();
+        await expect(dialog(page).locator('#modal-title')).toHaveText('Thumbnail maintenance');
+        await review.locator('#thumb-mode').selectOption('rebuild');
+        await expect(line).toHaveText('Enter a size from 128 to 2048 pixels.');
+        await review.locator('#thumb-mode').selectOption('missing');
+    }
+    expect(seen.starts).toEqual([]);
+    expect(seen.plans).toEqual([{ mode: 'missing', size: '512', quality: 'medium' }]);
+    await size.fill('1024');
+    await expect(size).not.toHaveAttribute('aria-invalid');
+    await expect(line).toHaveText(/ already up to date\.$/);
+    expect((await serverJson(request, '/prompt_manager/jobs')).jobs).toEqual([]);
+});
+
+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.locator('#thumb-quality').selectOption('low');
+    await review.locator('#thumb-limit').fill('256');
+    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', size: 256, quality: 'low' }]);
+    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', size: 256, quality: 'low' } });
+    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&size=512&quality=medium`);
+    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');
+    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', size: '512', quality: 'medium' }, { mode: 'rebuild', size: '512', quality: 'medium' }]);
+    // 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', size: 512, quality: 'medium' }]);
+    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')).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 = [];
@@ -55,6 +55,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 +66,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'],
+        ['0 ambiguous image links', 'Review metadata before assigning a positive / negative pair.', 'Review metadata'],
         ['Backup status', 'No retained backup record.', '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,6 +80,95 @@ 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);
@@ -138,9 +231,32 @@ 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&size=512&quality=medium');
+    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', 'Quality', 'Preview size limit']);
+    await expect(review.locator('#modal-body > p.small')).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', size: 512, quality: 'medium' }]);
+    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 paints when its own status read answers', async ({ page, request }) => {
@@ -166,14 +282,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 +356,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();
+    // Integrations still hands off (S10), so its body is one known panel.
+    await nav.getByRole('button', { name: 'Integrations', 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: Integrations 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 +370,368 @@ 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')).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`);
+    for (const id of ['open-mode', 'timeout']) {
+        const row = page.locator('#workspace-main .setting-row').filter({ has: page.locator(`#${id}`) });
+        await expect(row.locator('p.small')).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')).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')).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-thumbnails.spec.mjs

@@ -0,0 +1,135 @@
+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\.png\?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\.png\?/);
+    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\.jpg\?/);
+    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.jpg'), 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);
+});

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);
@@ -425,8 +427,7 @@ 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'] };
+const SYSTEM_HANDOFFS = { 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,14 +463,17 @@ 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); Maintenance shows
+        // its health-check notice above the hand-off (D123); 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'],
+            .toEqual({ overview: ['div.summary-metrics', 'div.two-col', 'div.save-row'], appearance: ['section.surface', 'div.save-row'],
+                sources: ['div.notice', 'section.surface', 'div.save-row'],
                 maintenance: ['div.notice', 'section.surface handoff', 'div.save-row'] }[hash]
                 ?? ['section.surface handoff', 'div.save-row']);
-        if (hash === 'overview') continue;
+        if (['overview', 'appearance', 'sources'].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'))))

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",

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,11 +11,24 @@ 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".
 
 Delays use the shared request holds (``request_hold.py``).
 """
@@ -31,9 +44,36 @@ 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,
+    )
+    monitor = getattr(image_monitor, "_monitor_instance", None)
     failures: dict[str, int] = {}
 
     @web.middleware
@@ -48,10 +88,31 @@ def register_system_commands(app, routes, api, root: Path):
 
     app.middlewares.append(inject_failures)
 
+    unplugged = root / "output" / "unplugged"
+
     def reset():
         failures.clear()
+        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,
+        ) = host_values
+        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)
 
     @routes.post("/__test__/system/reset")
     async def system_reset(request):
@@ -75,14 +136,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 +186,72 @@ def register_system_commands(app, routes, api, root: Path):
         api.invalidate_gallery_cache()
         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/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",

tests/browser/workspace_visual_fixture.py

@@ -114,6 +114,8 @@ def seed_workspace_visual(api: PromptManagerAPI, root: Path) -> None:
         for table in (
             "saved_views",
             "image_favorites",
+            "media_review_decisions",
+            "media_review_items",
             "media_image_tags",
             "media_annotation_bytes",
             "media_annotation_files",

tests/browser/workspace_vocabulary_fixture.py

@@ -81,6 +81,8 @@ MAX_EXTRA_CATEGORIES = 200
 _TABLES = (
     "saved_views",
     "image_favorites",
+    "media_review_decisions",
+    "media_review_items",
     "media_image_tags",
     "media_annotation_bytes",
     "media_annotation_files",

tests/comfyui/host-fixture.mjs

@@ -1,11 +1,20 @@
 import { expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
 import runtime from '../../tools/vendor/comfyui-runtime.json' with { type: 'json' };
+import { hostBaseDirectory } from '../../tools/vendor/comfyui-host.mjs';
 
 export function installHostHooks(test, expectedTypes = ['PromptManager', 'PromptManagerText', 'PromptSearchList']) {
     test.beforeEach(async ({ page, context, request }, testInfo) => {
         const response = await request.get('/system_stats');
         expect(response.ok()).toBe(true);
-        const info = (await response.json()).system;
+        const stats = await response.json();
+        // comfyui.config.mjs's launcher reports the host it owns. The execution suite has no
+        // web server: it starts its own host per worker behind a port refusal.
+        if (testInfo.config.webServer) {
+            const ownedBase = process.env.PM_COMFY_HOST_BASE;
+            expect(ownedBase, 'the launcher reported the host it started').toBeTruthy();
+            expect(hostBaseDirectory(stats), 'the host answering the port is the one this run started').toBe(ownedBase);
+        }
+        const info = stats.system;
         expect(info.comfyui_version).toBe(runtime.serverVersion);
         expect(info.pytorch_version).toBe(`${runtime.torchVersion}+cpu`);
         expect(info.required_frontend_version).toBe(runtime.frontendVersion);

tests/comfyui/library-location.spec.mjs

@@ -0,0 +1,73 @@
+// #249 S6b: a fresh install keeps its library in ComfyUI's system user folder. A pinned CPU ComfyUI starts with Prompt
+// Manager and no configuration at all (no config.json, no PROMPT_MANAGER_* paths): the library must be created in
+// user/__promptmanager, nothing may be written into the node folder, and ComfyUI's /userdata API must not serve it.
+import { execFileSync } from 'node:child_process';
+import { access, readdir } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { test, expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import { launchSharedHost } from '../../tools/vendor/comfyui-host.mjs';
+import runtime from '../../tools/vendor/comfyui-runtime.json' with { type: 'json' };
+
+const repositoryRoot = fileURLToPath(new URL('../../', import.meta.url));
+
+/** An unused loopback port chosen by the OS (this host shares no port with the other suites). */
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const probe = createServer();
+        probe.once('error', reject);
+        probe.listen({ host: '127.0.0.1', port: 0, exclusive: true }, () => {
+            const { port } = probe.address();
+            probe.close(error => error ? reject(error) : resolve(port));
+        });
+    });
+}
+
+test('a fresh host keeps the library in user/__promptmanager and serves none of it', async ({ playwright }, testInfo) => {
+    test.skip(testInfo.project.name !== 'classic-start', 'one fresh host is enough; the renderer does not matter here');
+    test.setTimeout(180000);
+    const port = await freePort();
+    const host = await launchSharedHost({ checkout: process.env.PM_COMFY_ROOT, repository: repositoryRoot,
+        python: process.env.PM_TEST_PYTHON || 'python', port, pins: runtime, forwardOutput: false,
+        logPath: join(repositoryRoot, 'tools/vendor/test-results/executions/fresh-host.log'), pluginName: 'promptmanager',
+        // A fresh install: nothing written, and no inherited path variable may choose the folder.
+        preparePlugin: async () => ({ PROMPT_MANAGER_CONFIG_PATH: '', PROMPT_MANAGER_DATA_DIR: '',
+            PROMPT_MANAGER_EXTRA_GALLERY_ROOTS: '' }) });
+    const request = await playwright.request.newContext({ baseURL: `http://127.0.0.1:${port}/` });
+    try {
+        await expect.poll(async () => {
+            if (host.child.exitCode !== null) throw new Error('The fresh host exited before it answered');
+            try { return (await request.get('/system_stats')).ok(); } catch { return false; }
+        }, { timeout: 120000 }).toBe(true);
+        expect((await (await request.get('/system_stats')).json()).system.comfyui_version).toBe(runtime.serverVersion);
+        await expect(await request.get('/prompt_manager/stats')).toBeOK();
+
+        const dataFolder = join(host.stateDirectory, 'user', '__promptmanager');
+        await access(join(dataFolder, 'prompts.db'));
+        await access(join(dataFolder, 'logs'));
+        const { location } = await (await request.get('/prompt_manager/system/library')).json();
+        expect(location).toMatchObject({ path: 'user/__promptmanager/prompts.db', source: 'default', movable: false,
+            offer: false, problem: null });
+
+        // Nothing but byte code was added to the node folder: no database, config.json, logs or caches.
+        const installed = join(host.stateDirectory, 'custom_nodes', 'promptmanager');
+        const tracked = new Set(execFileSync('git', ['-C', repositoryRoot, 'ls-files', '-z'], { encoding: 'utf8' })
+            .split('\0').filter(Boolean).map(file => file.split('/')[0]));
+        const added = (await readdir(installed)).filter(name => !tracked.has(name) && name !== '__pycache__');
+        expect(added).toEqual([]);
+
+        // ComfyUI's /userdata serves public users only: the system user's folder is out of reach.
+        for (const path of ['/userdata/..%2F__promptmanager%2Fprompts.db', '/api/userdata/..%2F__promptmanager%2Fprompts.db',
+            '/userdata/%2E%2E%2F__promptmanager%2Fconfig.json', '/userdata/prompts.db']) {
+            const response = await request.get(path);
+            expect(response.status(), path).not.toBe(200);
+        }
+        const listing = await request.get('/userdata?dir=..%2F__promptmanager&recurse=true');
+        expect(listing.status()).not.toBe(200);
+        const asSystemUser = await request.get('/userdata/prompts.db', { headers: { 'comfy-user': '__promptmanager' } });
+        expect(asSystemUser.status()).not.toBe(200);
+    } finally {
+        try { await request.dispose(); } finally { await host.stop(); }
+    }
+});

tests/fixtures/inspection_parity/vectors.json

@@ -594,12 +594,12 @@
     "anchor": null,
     "expect": {
       "metadata_status": "available",
-      "state": "ambiguous",
-      "reason": "Multiple sampler branches",
+      "state": "resolved",
+      "reason": "",
       "reason_code": null,
       "selection": null,
-      "positive": null,
-      "negative": null,
+      "positive": "a red fox in snow, detailed fur",
+      "negative": "blurry, lowres",
       "candidate_count": 0,
       "facts": {
         "seed": {

tests/js/api-client.test.js

@@ -355,3 +355,20 @@ test("keepalive is forwarded only when asked, so a request can outlive its page"
     for (const call of fetch.calls) call.resolve(jsonResponse(200, { success: true }));
     await Promise.all(writes);
 });
+
+test("ApiError keeps a validated running job on busy and a validated source on invalid-source", () => {
+    const body = { running: { id: "a".repeat(32), title: "Scan for metadata" }, source: "output/gone" };
+    const busy = new ApiError(409, "busy", "busy", null, body);
+    assert.deepEqual([busy.running, busy.source], [{ id: "a".repeat(32), title: "Scan for metadata" }, null]);
+    assert.notEqual(busy.running, body.running, "server objects must be copied");
+    const invalid = new ApiError(400, "refused", "invalid-source", null, body);
+    assert.deepEqual([invalid.running, invalid.source], [null, "output/gone"]);
+    for (const running of [null, "x", { id: 1, title: "t" }, { id: "a b", title: "t" }, { id: "a", title: "" },
+        { id: "a", title: "x".repeat(201) }, { id: "a".repeat(65), title: "t" }]) {
+        assert.equal(new ApiError(409, "busy", "busy", null, { running }).running, null);
+    }
+    for (const source of [null, 7, "", "x".repeat(4097)]) {
+        assert.equal(new ApiError(400, "refused", "invalid-source", null, { source }).source, null);
+    }
+    assert.deepEqual([new ApiError(409, "old caller").running, new ApiError(409, "old caller").source], [null, null]);
+});

tests/js/gallery-settings.test.js

@@ -61,3 +61,50 @@ test("infinite scrolling is off by default and must be a boolean", () => {
     assert.equal(normalizeGallerySettings({ infiniteScroll: true }).infiniteScroll, true);
     assert.equal(normalizeGallerySettings({ infiniteScroll: "yes" }).infiniteScroll, false);
 });
+
+test("the workspace keys have their own defaults and validation", () => {
+    const { WORKSPACE_LAYOUTS, WORKSPACE_DENSITIES } = require("../../web/js/gallery-settings.js");
+    assert.equal(DEFAULT_SETTINGS.workspaceLayout, "grid");
+    assert.equal(DEFAULT_SETTINGS.workspaceDensity, "comfortable");
+    assert.deepEqual(WORKSPACE_LAYOUTS, ["grid", "list", "masonry"]);
+    assert.deepEqual(WORKSPACE_DENSITIES, ["comfortable", "large", "compact"]);
+    assert.equal(normalizeGallerySettings({ workspaceLayout: "masonry" }).workspaceLayout, "masonry");
+    assert.equal(normalizeGallerySettings({ workspaceLayout: "mosaic" }).workspaceLayout, "grid");
+    assert.equal(normalizeGallerySettings({ workspaceDensity: "large" }).workspaceDensity, "large");
+    assert.equal(normalizeGallerySettings({ workspaceDensity: 3 }).workspaceDensity, "comfortable");
+    // The legacy gallery's own view mode is separate: it has no masonry.
+    assert.equal(normalizeGallerySettings({ defaultViewMode: "masonry" }).defaultViewMode, "grid");
+});
+
+test("a legacy gallery Save keeps the workspace keys and every other stored key", () => {
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const vm = require("node:vm");
+    const settings = require("../../web/js/gallery-settings.js");
+    const storage = new Map([["gallerySettings", JSON.stringify({ workspaceLayout: "masonry", workspaceDensity: "compact", someOtherTool: 1 })]]);
+    const controls = {
+        lazyLoadingToggle: { checked: true }, imageQualitySelect: { value: "high" }, defaultViewModeSelect: { value: "list" },
+        defaultLimitSelect: { value: "200" }, gridColumnsSelect: { value: "6" }, showImageInfoToggle: { checked: false },
+        autoLoadMetadataToggle: { checked: true }, cacheMetadataToggle: { checked: true }, showFilePathsToggle: { checked: false },
+        sidebarCollapsedByDefaultToggle: { checked: true }, infiniteScrollToggle: { checked: false }, debugModeToggle: { checked: false },
+        apiTimeoutInput: { value: "30" }, checkThumbnailsAtStartup: { checked: true }, videoAutoplayToggle: { checked: true },
+        videoMuteToggle: { checked: false }, videoLoopToggle: { checked: true },
+    };
+    const context = vm.createContext({
+        document: { addEventListener() {}, getElementById: id => controls[id] },
+        window: {}, console: { debug() {}, warn() {}, error() {} }, GallerySettings: settings,
+        localStorage: { getItem: key => storage.get(key) ?? null, setItem: (key, value) => storage.set(key, value) },
+    });
+    const file = path.join(__dirname, "../../web/js/gallery.js");
+    const Manager = vm.runInContext(`${fs.readFileSync(file, "utf8")}\nGalleryManager;`, context, { filename: file });
+    const manager = Object.create(Manager.prototype);
+    Object.assign(manager, { showNotification() {}, hideSettings() {}, applySettings() {} });
+    manager.saveSettings();
+    const saved = JSON.parse(storage.get("gallerySettings"));
+    assert.equal(saved.workspaceLayout, "masonry");
+    assert.equal(saved.workspaceDensity, "compact");
+    assert.equal(saved.someOtherTool, 1);
+    assert.equal(saved.defaultViewMode, "list");
+    assert.equal(saved.showImageInfo, false);
+    assert.equal(saved.videoMute, false);
+});

tests/js/gallery-thumbnails.test.js

@@ -110,3 +110,123 @@ test('saving gallery settings retains the remembered thumbnail dismissal', () =>
     f.manager.saveSettings();
     assert.equal(JSON.parse(f.storage.get('gallerySettings')).thumbnailPromptDismissed, 'remembered-state');
 });
+
+// #249 System S5: the stream's work is now an Activity job that outlives the page's connection, so the gallery's
+// Cancel asks the server to stop the job. The stream's first frame, `job {id, started}`, names the job; the gallery
+// cancels by that id, only a job this stream started, and a Cancel before the id waits for it (review I1).
+const JOB = 'b'.repeat(32);
+
+function streamFixture({ modal = false, postFails = false } = {}) {
+    const posts = [];
+    const warnings = [];
+    const gets = [];
+    const listeners = {};
+    const source = { closed: 0, readyState: 1, CLOSED: 2, url: null,
+        addEventListener(type, handler) { (listeners[type] ||= []).push(handler); },
+        close() { this.closed += 1; } };
+    const element = () => ({ classList: { add() {}, remove() {} }, style: {}, textContent: '', handlers: {},
+        addEventListener(type, handler) { this.handlers[type] = handler; },
+        removeEventListener(type, handler) { if (this.handlers[type] === handler) delete this.handlers[type]; },
+        click() { this.handlers.click?.(); } });
+    const elements = {};
+    const document = { addEventListener() {}, getElementById: id => elements[id] ||= element(),
+        createElement: () => element(), body: { appendChild() {}, removeChild() {} } };
+    const context = vm.createContext({ document, window: {},
+        console: { debug() {}, warn: (...args) => warnings.push(args), error() {} },
+        setTimeout() {}, localStorage: { setItem() {} },
+        SseStream: { connect: (url, options) => { source.url = url; source.options = options; return source; } } });
+    const file = path.join(__dirname, '../../web/js/gallery.js');
+    const Manager = vm.runInContext(fs.readFileSync(file, 'utf8') + '\nGalleryManager;', context, { filename: file });
+    const manager = Object.create(Manager.prototype);
+    Object.assign(manager, { getSettings: () => ({}),
+        api: { get: async url => { gets.push(url); return { success: true, jobs: [] }; },
+            post: async (url, body) => {
+                posts.push([url, body]);
+                if (postFails) throw new Error('offline');
+                return { success: true };
+            } } });
+    const emit = (type, data) => (listeners[type] || []).forEach(handler => handler({ data: JSON.stringify(data) }));
+    const ui = { addStatusMessage() {}, progressText: element(), progressPercent: element(), progressBar: element(),
+        progressDetails: element(), progressETA: element(), isCancelled: () => false,
+        onCancel: handler => { ui.cancel = handler; } };
+    const result = modal ? manager.generateThumbnailsWithProgressInModal(ui)
+        : manager.generateThumbnailsWithProgress({ quality: 'medium' });
+    const outcome = result.then(value => ({ value }), error => ({ error: error.message }));
+    const cancel = () => (modal ? ui.cancel() : elements.cancelThumbnailsBtn.click());
+    const settle = () => new Promise(resolve => setImmediate(resolve));
+    return { emit, source, posts, gets, warnings, outcome, cancel, settle };
+}
+
+const cancelUrl = id => `/prompt_manager/jobs/${id}/cancel`;
+
+test('Cancel before the job id arrives cancels that job once it does', async () => {
+    const f = streamFixture();
+    f.cancel();
+    await f.settle();
+    assert.deepEqual(f.posts, []);
+    assert.equal(f.source.closed, 0); // kept open until the stream names its job
+    assert.deepEqual(await f.outcome, { error: 'Thumbnail generation cancelled by user' });
+    f.emit('status', { phase: 'scanning', message: 'Scanning…' });
+    f.emit('job', { id: JOB, started: true });
+    await f.settle();
+    assert.equal(JSON.stringify(f.posts), JSON.stringify([[cancelUrl(JOB), {}]]));
+    assert.equal(f.source.closed, 1);
+    f.emit('job', { id: 'c'.repeat(32), started: true }); // a stray second frame changes nothing
+    await f.settle();
+    assert.equal(f.posts.length, 1);
+    assert.deepEqual(f.gets, []); // never looks a job up by kind
+});
+
+test('Cancel after the id cancels it at once, and a double Cancel posts once', async () => {
+    const f = streamFixture();
+    f.emit('job', { id: JOB, started: true });
+    f.cancel();
+    f.cancel();
+    await f.settle();
+    assert.equal(JSON.stringify(f.posts), JSON.stringify([[cancelUrl(JOB), {}]]));
+    assert.equal(f.source.closed, 1);
+    assert.deepEqual(await f.outcome, { error: 'Thumbnail generation cancelled by user' });
+    assert.deepEqual(f.gets, []);
+});
+
+test("Cancel leaves another tab's or System's job running and only stops following it", async () => {
+    const f = streamFixture();
+    f.emit('job', { id: JOB, started: false });
+    f.cancel();
+    await f.settle();
+    assert.deepEqual(f.posts, []);
+    assert.deepEqual(f.gets, []);
+    assert.equal(f.source.closed, 1);
+    assert.match((await f.outcome).error, /keeps running/);
+});
+
+test('a Cancel the stream never names a job for posts nothing and closes when it ends', async () => {
+    const f = streamFixture();
+    f.cancel();
+    f.emit('error', { error: 'Scan for metadata already running' });
+    await f.settle();
+    assert.deepEqual(f.posts, []);
+    assert.equal(f.source.closed, 1);
+});
+
+test('a cancel post that fails is reported, not thrown', async () => {
+    const f = streamFixture({ postFails: true });
+    f.emit('job', { id: JOB, started: true });
+    f.cancel();
+    await f.settle();
+    assert.equal(f.posts.length, 1);
+    assert.equal(f.warnings.length, 1);
+    assert.deepEqual(await f.outcome, { error: 'Thumbnail generation cancelled by user' });
+});
+
+test('the startup dialog cancels its own job by id too', async () => {
+    const f = streamFixture({ modal: true });
+    f.cancel();
+    await f.settle();
+    assert.deepEqual(f.posts, []);
+    f.emit('job', { id: JOB, started: true });
+    await f.settle();
+    assert.equal(JSON.stringify(f.posts), JSON.stringify([[cancelUrl(JOB), {}]]));
+    assert.equal(f.source.closed, 1);
+    assert.match((await f.outcome).error, /cancelled/);
+});

tests/js/prompt-blocks.test.js

@@ -82,6 +82,32 @@ test('a zeroed conditioning negative shows as an explicit empty negative without
     }finally{scope.dispose();f.restore();}
 });
 
+test('a prompt that left out run-time trigger words says so under its text (D125)',()=>{
+    const f=dom(),scope=createScope(),container=new f.Element('div'),sent=[];
+    const note='Text added at run time, such as trigger words, is not included.';
+    try{
+        module.mountPromptBlocks(container,{parentScope:scope,sender:{open:roles=>sent.push(roles)},prompts:{positive:{status:'resolved',text:'own text',source:'runtime-parts-omitted'},negative:{status:'resolved',text:'blur',source:'graph-inferred'}}});
+        const notes=f.walk(container,node=>node.textContent===note);
+        assert.equal(notes.length,1,'one note, under the positive only');
+        assert.equal(notes[0].parent.attributes['aria-label'],'Positive prompt');
+        container.click(f.walk(container,node=>node.dataset.sendRole==='pair')[0]);
+        assert.deepEqual(sent,[{positive:'own text',negative:'blur'}],'the note is never sent');
+    }finally{scope.dispose();f.restore();}
+});
+
+test('a prompt a later stage added conditioning to says so, and both lines show together (D126)',()=>{
+    const f=dom(),scope=createScope(),container=new f.Element('div');
+    const added='Conditioning added at a later stage is not included.', runtime='Text added at run time, such as trigger words, is not included.';
+    try{
+        const view=module.mountPromptBlocks(container,{parentScope:scope,prompts:{positive:{status:'resolved',text:'base',source:'added-conditioning'}}});
+        assert.deepEqual(f.walk(container,node=>node.className==='small muted').map(node=>node.textContent),[added]);
+        view.update({positive:{status:'resolved',text:'base',source:'runtime-parts-omitted-and-added-conditioning'}});
+        assert.deepEqual(f.walk(container,node=>node.className==='small muted').map(node=>node.textContent),[runtime,added]);
+        view.update({positive:{status:'resolved',text:'base',source:'graph-inferred'}});
+        assert.equal(f.walk(container,node=>node.className==='small muted').length,0);
+    }finally{scope.dispose();f.restore();}
+});
+
 const unresolved=message=>({status:'unresolved',text:null,source:null,...(message===undefined?{}:{message})});
 const statusLines=(f,container)=>f.walk(container,node=>node.tagName==='p'&&node.className==='prompt-text muted').map(node=>node.textContent);
 test('unsupported node status names the class',()=>{

tests/js/workspace-activity-kinds.test.js

@@ -0,0 +1,148 @@
+// Per-kind Activity descriptors (#249 System S5 Task 13, D111): each job kind's pill verb, toasts, line, tiles,
+// outcomes, openable rows and labels, from one table (web/js/workspace/activity-kinds.mjs).
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const source = import('../../web/js/workspace/activity-kinds.mjs');
+const store = import('../../web/js/workspace/activity-store.mjs');
+
+const ID = 'a'.repeat(32);
+
+function job(overrides = {}) {
+    return { id: ID, kind: 'scan', title: 'Scan for metadata', state: 'running', started_at: 1, finished_at: null,
+        progress: 42, status_line: '', processed: 8240, total: 19622,
+        counters: { added: 1, known: 0, review: 0, no_metadata: 0, errors: 1 }, scope: {}, listed: {}, log_length: 0,
+        cancellable: true, ...overrides };
+}
+
+test('scan descriptors are unchanged', async () => {
+    const { kindOf } = await source;
+    const scan = kindOf('scan');
+    assert.equal(scan.pillVerb, 'Scanning');
+    assert.equal(scan.startToast(job()), 'Scan started.');
+    assert.deepEqual(scan.tiles, [['added', 'Added to Library', 'added'], ['known', 'Already known', ''],
+        ['review', 'Needs review', 'warn'], ['no_metadata', 'No usable metadata', ''], ['errors', 'Errors', 'bad']]);
+    assert.deepEqual(scan.outcomes, [['added', 'Added to Library'], ['review', 'Needs review'], ['errors', 'Errors'],
+        ['no_metadata', 'No usable metadata'], ['known', 'Already known']]);
+    assert.deepEqual([...scan.openable].sort(), ['added', 'known']);
+    assert.deepEqual([scan.log, scan.cancelLabel], ['Scan log', 'Cancel scan']);
+    assert.equal(scan.finishToast(job({ state: 'finished' })), 'Scan finished · 1 added · 1 error');
+    assert.equal(scan.finishToast(job({ state: 'cancelled' })), 'Scan cancelled · 1 added');
+    assert.equal(scan.finishToast(job({ state: 'failed' })), 'Scan failed · 1 added · 1 error');
+    assert.equal(scan.line(job()), '1 added · 1 error');
+    assert.equal(scan.kept(job()), '1 added');
+    assert.equal(scan.scope(job({ scope: { output_folders: 2 } })), '2 output folders');
+    // The store keeps answering with the same table.
+    const { jobView, finishToast, startToast, pillParts, outcomeLine } = await store;
+    assert.equal(jobView('scan'), scan);
+    assert.equal(finishToast(job({ state: 'finished' })), 'Scan finished · 1 added · 1 error');
+    assert.equal(startToast(job()), 'Scan started.');
+    assert.equal(pillParts(job()).text, 'Scanning · 42% · 8,240 / 19,622');
+    assert.equal(outcomeLine(job()), '1 added · 1 error');
+});
+
+test('thumbnail job shows its own tiles and toasts', async () => {
+    const { kindOf, viewOf } = await source;
+    const { finishToast, startToast, pillParts, outcomeLine } = await store;
+    const thumbs = job({ kind: 'thumbnails', title: 'Thumbnail generation', processed: 4, total: 10, progress: 40,
+        counters: { generated: 1420, skipped: 3, errors: 1 }, scope: { mode: 'missing', size: 512, quality: 'medium',
+            output_folders: 2 } });
+    const view = kindOf('thumbnails');
+    assert.equal(viewOf(thumbs), view);
+    assert.deepEqual(view.tiles, [['generated', 'Generated', 'added'], ['skipped', 'Skipped', ''], ['errors', 'Errors', 'bad']]);
+    assert.deepEqual(view.outcomes, [['generated', 'Generated'], ['errors', 'Errors'], ['skipped', 'Skipped']]);
+    assert.deepEqual([...view.openable].sort(), ['generated', 'skipped']);
+    assert.deepEqual([view.log, view.cancelLabel], ['Job log', 'Cancel job']);
+    assert.equal(pillParts(thumbs).text, 'Generating thumbnails · 40% · 4 / 10');
+    assert.equal(startToast(thumbs), 'Thumbnail generation started.');
+    assert.equal(finishToast({ ...thumbs, state: 'finished' }), 'Thumbnails finished · 1,420 generated · 1 error');
+    assert.equal(finishToast({ ...thumbs, state: 'failed' }), 'Thumbnails failed · 1,420 generated · 1 error');
+    assert.equal(finishToast({ ...thumbs, state: 'cancelled' }), 'Thumbnails cancelled · 1,420 generated');
+    assert.equal(finishToast({ ...thumbs, counters: { generated: 0, skipped: 0, errors: 2 }, state: 'finished' }),
+        'Thumbnails finished · 0 generated · 2 errors');
+    assert.equal(outcomeLine(thumbs), '1,420 generated · 1 error');
+    assert.equal(view.kept(thumbs), '1,420 generated');
+    assert.equal(view.scope(thumbs), '2 output folders');
+});
+
+test('non-cancellable jobs show no Cancel job', async () => {
+    const { canCancel } = await source;
+    assert.equal(canCancel(job()), true);
+    assert.equal(canCancel(job({ cancellable: false })), false);
+    for (const state of ['finished', 'cancelled', 'failed', 'lost']) assert.equal(canCancel(job({ state })), false);
+    // The health check is a read job the server cannot stop.
+    assert.equal(canCancel(job({ kind: 'health', title: 'Health check', cancellable: false, counters: {} })), false);
+});
+
+test('indeterminate progress has no value attribute', async () => {
+    const { indeterminate, showProgress } = await source;
+    const { pillParts } = await store;
+    function node() {
+        const attributes = new Map();
+        return { attributes, textContent: '', set value(v) { attributes.set('value', String(v)); },
+            get value() { return Number(attributes.get('value') ?? 0); },
+            setAttribute(key, v) { attributes.set(key, String(v)); }, removeAttribute(key) { attributes.delete(key); } };
+    }
+    // Running with no total yet: the server has not said how much there is, so there is no percentage.
+    const health = job({ kind: 'health', title: 'Health check', progress: 0, processed: 0, total: 0, counters: {},
+        cancellable: false, status_line: 'Checking the database and image links' });
+    assert.equal(indeterminate(health), true);
+    const bar = node();
+    bar.value = 37;
+    showProgress(bar, health);
+    assert.equal(bar.attributes.has('value'), false);
+    assert.equal(bar.textContent, '');
+    assert.equal(pillParts(health).text, 'Health check');
+    assert.deepEqual(pillParts(health), { label: 'Health check', files: '', text: 'Health check' });
+    // A known total is determinate, and so is any ended job.
+    const scan = job();
+    assert.equal(indeterminate(scan), false);
+    showProgress(bar, scan);
+    assert.equal(bar.attributes.get('value'), '42');
+    assert.equal(bar.textContent, '42%');
+    assert.equal(indeterminate({ ...health, state: 'finished', progress: 100 }), false);
+    // A scan before its file count is known is indeterminate too, never "0%".
+    assert.equal(pillParts(job({ total: 0, processed: 0, progress: 0 })).text, 'Scanning');
+});
+
+test('held legacy jobs read "(admin page)" with no outcomes', async () => {
+    const { viewOf } = await source;
+    const { jobDetail } = await import('../../web/js/workspace/activity.mjs');
+    const { finishToast, outcomeLine } = await store;
+    // A hold has no outcome groups (counters {}), whatever its kind: thumbnails held by the gallery's clear included.
+    for (const [kind, title] of [['restore', 'Database restore (admin page)'],
+        ['thumbnails', 'Thumbnail clear (gallery page)'], ['maintenance', 'Database maintenance (admin page)']]) {
+        const held = job({ kind, title, counters: {}, cancellable: false, progress: 0, processed: 0, total: 0 });
+        const view = viewOf(held);
+        assert.deepEqual([view.tiles, view.outcomes, [...view.openable]], [[], [], []], kind);
+        assert.equal(outcomeLine(held), '');
+        assert.match(jobDetail(held), /^Started \d\d:\d\d · closing this view does not cancel it$/);
+        const ended = { ...held, state: 'finished', finished_at: 2 };
+        assert.match(jobDetail(ended), /^Finished \d\d:\d\d$/);
+        assert.equal(finishToast(ended), `${title} finished.`);
+        assert.ok(title.endsWith('page)'));
+    }
+});
+
+test('unknown and generic kinds show no tiles of another kind', async () => {
+    const { kindOf, viewOf } = await source;
+    for (const kind of ['maintenance', '', 'constructor', '__proto__', 'health']) {
+        const view = kindOf(kind);
+        assert.deepEqual([view.tiles, view.outcomes, [...view.openable]], [[], [], []], kind);
+        assert.deepEqual([view.log, view.cancelLabel], ['Job log', 'Cancel job']);
+        assert.equal(view.pillVerb, null);
+        assert.equal(view.line(job({ kind })), '');
+        assert.equal(view.kept(job({ kind })), '');
+    }
+    const backup = job({ kind: 'backup', title: 'Backup' });
+    assert.equal(kindOf('backup').startToast(backup), 'Backup started.');
+    assert.equal(kindOf('backup').finishToast({ ...backup, state: 'finished' }), 'Backup finished.');
+    assert.equal(kindOf('backup').finishToast({ ...backup, state: 'cancelled' }), 'Backup was cancelled.');
+    assert.equal(kindOf('backup').finishToast({ ...backup, state: 'failed' }), 'Backup failed.');
+    // A kind's tiles are only the groups its job counts: no zero tile for a group the server never reported.
+    const partial = viewOf(job({ counters: { added: 3, errors: 0 } }));
+    assert.deepEqual(partial.tiles, [['added', 'Added to Library', 'added'], ['errors', 'Errors', 'bad']]);
+    assert.deepEqual(partial.outcomes, [['added', 'Added to Library'], ['errors', 'Errors']]);
+    assert.deepEqual([...partial.openable], ['added']);
+    assert.equal(partial.log, 'Scan log');
+});

tests/js/workspace-activity-store.test.js

@@ -289,8 +289,10 @@ test('summaries are validated and the copy follows the spec', async () => {
 
     const scan = parseJob(summary({ progress: 42, processed: 8240, total: 19622, counters: { added: 1, errors: 1 } }));
     assert.deepEqual(pillParts(scan), { label: 'Scanning · 42%', files: ' · 8,240 / 19,622', text: 'Scanning · 42% · 8,240 / 19,622' });
-    assert.equal(pillParts({ ...scan, total: 0 }).text, 'Scanning · 42%');
-    assert.equal(pillParts({ ...scan, kind: 'thumbnails', title: 'Thumbnails' }).text, 'Thumbnails · 42% · 8,240 / 19,622');
+    // D111: without a total the progress is indeterminate, so the pill shows no percentage.
+    assert.equal(pillParts({ ...scan, total: 0 }).text, 'Scanning');
+    // A kind without a pill verb shows its title (D111: thumbnails have their own, see workspace-activity-kinds.test.js).
+    assert.equal(pillParts({ ...scan, kind: 'backup', title: 'Backup' }).text, 'Backup · 42% · 8,240 / 19,622');
     assert.equal(finishToast({ ...scan, state: 'finished' }), 'Scan finished · 1 added · 1 error');
     assert.equal(finishToast({ ...scan, state: 'cancelled' }), 'Scan cancelled · 1 added');
     assert.equal(finishToast({ ...scan, state: 'failed' }), 'Scan failed · 1 added · 1 error');
@@ -332,7 +334,8 @@ test('image-tags jobs get their own tiles outcomes and pill verb', async () => {
         'Add tags to images finished · 0 tagged · 0 errors');
 });
 
-test('unknown kinds keep the generic view', async () => {
+// D111 (S5): an unknown kind no longer borrows the scan's tiles (S1 review M6, S2 review M3); it has none.
+test('unknown kinds get the generic view without the scan tiles', async () => {
     const { jobView } = await source;
     const scan = jobView('scan');
     assert.deepEqual(scan.tiles, [['added', 'Added to Library', 'added'], ['known', 'Already known', ''],
@@ -343,7 +346,7 @@ test('unknown kinds keep the generic view', async () => {
     assert.deepEqual([scan.log, scan.cancel], ['Scan log', 'Cancel scan']);
     for (const kind of ['maintenance', '', 'constructor', '__proto__']) {
         const view = jobView(kind);
-        assert.deepEqual([view.tiles, view.outcomes, [...view.openable]], [scan.tiles, scan.outcomes, [...scan.openable]]);
+        assert.deepEqual([view.tiles, view.outcomes, [...view.openable]], [[], [], []]);
         assert.deepEqual([view.log, view.cancel], ['Job log', 'Cancel job']);
     }
 });

tests/js/workspace-history-media.test.js

@@ -39,3 +39,4 @@ test('stale inspection echoes use the canonical recovery vocabulary and identity
         });
     }
 });
+test('the recorded output inspector cover is its preview, not the original (#249)',()=>{const a=adapter(),target=media('2',1);const record=a.toRecord(envelope(target),target,extractGenerationFacts);assert.deepEqual(record.preview,{url:target.thumbnail_url});assert.notEqual(record.preview.url,record.download.url);});

tests/js/workspace-images-state.test.js

@@ -478,3 +478,19 @@ test('a refresh deferred behind a page load is dropped when the stream is dispos
     await new Promise(resolve=>setImmediate(resolve));
     assert.equal(requests.length,2,'no refresh runs after dispose');
 });
+
+test('defaults apply to a new visit but not to the current view or a saved view', async () => {
+    const { initialImagesView } = await source;
+    assert.equal(typeof initialImagesView, 'function', 'initialImagesView is exported');
+    const preferences = { workspaceLayout: 'masonry', workspaceDensity: 'compact' };
+    // A new visit starts from System › Appearance.
+    assert.deepEqual(initialImagesView({ preferences }), { layout: 'masonry', density: 'compact' });
+    // The current view (the last visit) keeps its own toolbar choices.
+    assert.deepEqual(initialImagesView({ prior: { layout: 'list', density: 'large' }, preferences }), { layout: 'list', density: 'large' });
+    assert.deepEqual(initialImagesView({ prior: {}, preferences }), { layout: 'grid', density: 'comfortable' });
+    // A saved view opens as it always did.
+    assert.deepEqual(initialImagesView({ saved: { q: '' }, preferences }), { layout: 'grid', density: 'comfortable' });
+    // Without readable preferences nothing changes.
+    assert.deepEqual(initialImagesView({}), { layout: 'grid', density: 'comfortable' });
+    assert.deepEqual(initialImagesView({ preferences: {} }), { layout: 'grid', density: 'comfortable' });
+});

tests/js/workspace-inspection-state.test.js

@@ -825,3 +825,100 @@ test('refresh re-reads the selected file and keeps the shown record until the ne
     assert.equal(controller.state.record.identity.path, 'folder/b.png');
     controller.dispose(); assert.equal(await controller.refresh(), undefined);
 });
+
+test('metadata off shows an explicit load and loads once on request', async () => {
+    const { api, requests } = pendingApi(), updates = [];
+    const controller = contract('createInspectionController')({ api, extractFacts: extractGenerationFacts, autoLoad: false });
+    controller.subscribe(state => updates.push(state));
+    // Selecting reads nothing: the state says the metadata waits for a request.
+    assert.equal(controller.select(image()), undefined);
+    assert.equal(requests.length, 0);
+    assert.equal(controller.state.deferred, true);
+    assert.equal(controller.state.loading, false);
+    assert.equal(controller.state.record, null);
+    // Selecting the same file again still reads nothing.
+    controller.select({ ...image() });
+    assert.equal(requests.length, 0);
+    const load = controller.load();
+    assert.equal(requests.length, 1);
+    assert.equal(controller.state.loading, true);
+    assert.equal(controller.state.deferred, false);
+    // A second press while it reads, and the same file selected again once it loaded, read nothing more.
+    controller.load();
+    assert.equal(requests.length, 1);
+    requests[0].resolve(envelope()); await load;
+    assert.equal(controller.state.record.generation.seed.value, '9007199254740993');
+    controller.load(); controller.select(image());
+    assert.equal(requests.length, 1);
+    // Another file waits for its own request again.
+    controller.select({ ...image(), path: 'folder/b.png', filename: 'b.png', url: image().url.replace('a%20%23%25', 'b') });
+    assert.equal(controller.state.deferred, true);
+    assert.equal(requests.length, 1);
+    // The default controller loads on selection, as before.
+    const eager = contract('createInspectionController')({ api, extractFacts: extractGenerationFacts });
+    eager.select(image());
+    assert.equal(requests.length, 2);
+    assert.equal(eager.state.deferred, false);
+    eager.dispose(); controller.dispose();
+    assert.equal(controller.load(), undefined);
+});
+
+test('cache off rereads the current selection; on reuses the one current record', async () => {
+    for (const cache of [true, false]) {
+        const { api, requests } = pendingApi();
+        const controller = contract('createInspectionController')({ api, extractFacts: extractGenerationFacts, cache });
+        const first = controller.select(image());
+        // A read in flight is shared either way.
+        controller.select(image());
+        assert.equal(requests.length, 1);
+        requests[0].resolve(envelope()); await first;
+        const again = controller.select(image());
+        assert.equal(requests.length, cache ? 1 : 2, `cache ${cache}`);
+        if (!cache) { requests[1].resolve(envelope()); await again; assert.equal(controller.state.record.identity.path, 'folder/a #%.png'); }
+        controller.dispose();
+    }
+});
+
+test('cache off never rereads a selection whose source changed, and refresh never loads a deferred one', async () => {
+    const { api, requests } = pendingApi();
+    const controller = contract('createInspectionController')({ api, extractFacts: extractGenerationFacts, cache: false });
+    const first = controller.select(image());
+    requests[0].reject(new ApiError(409, refreshMessage, 'source-changed')); await first;
+    assert.equal(controller.state.refreshRequired, true);
+    controller.select(image());
+    assert.equal(requests.length, 1);
+    controller.dispose();
+    const deferred = contract('createInspectionController')({ api, extractFacts: extractGenerationFacts, autoLoad: false });
+    deferred.select(image());
+    assert.equal(deferred.refresh(), undefined);
+    assert.equal(requests.length, 1);
+    assert.equal(deferred.state.deferred, true);
+    deferred.dispose();
+});
+
+test('record carries the listing thumbnail as its preview, never another file (#249)', () => {
+    const toRecord = contract('toInspectionRecord'), entry = image();
+    const thumb = `/prompt_manager/images/serve/thumbnails/folder/a%20%23%25_thumb.png?root=0&root_scope=${scopeA}`;
+    assert.deepEqual(toRecord(envelope(entry), { ...entry, thumbnail_url: thumb }, extractGenerationFacts).preview, { url: thumb });
+    const versioned = `/prompt_manager/images/serve/thumbnails/folder/a%20%23%25_thumb.png?v=12&root=0&root_scope=${scopeA}`;
+    assert.deepEqual(toRecord(envelope(entry), { ...entry, thumbnail_url: versioned }, extractGenerationFacts).preview, { url: versioned });
+    // No thumbnail, or one naming another file, root or origin: no preview (the cover keeps the original).
+    for (const thumbnail_url of [undefined, null, '', thumb.replace('a%20%23%25_thumb', 'b_thumb'), thumb.replace('root=0', 'root=1'),
+        thumb.replace(scopeA, scopeB), `https://other.test${thumb}`, thumb.replace('thumbnails/', ''), `${thumb}#x`]) {
+        assert.equal(toRecord(envelope(entry), { ...entry, thumbnail_url }, extractGenerationFacts).preview, null, String(thumbnail_url));
+    }
+    const video = { root_index: 0, path: 'clip.MP4', filename: 'clip.MP4', url: `/prompt_manager/images/serve/clip.MP4?root=0&root_scope=${scopeA}`, root_scope: scopeA,
+        thumbnail_url: `/prompt_manager/images/serve/thumbnails/clip_thumb.jpg?root=0&root_scope=${scopeA}` };
+    const data = envelope(video); data.file = { ...data.file, media_type: 'video', extension: '.mp4', format: 'MP4' };
+    assert.deepEqual(toRecord(data, video, extractGenerationFacts).preview, { url: video.thumbnail_url });
+});
+
+test("names the server quotes (parentheses, '!*') still match their original and preview (#249 M11)", () => {
+    const toRecord = contract('toInspectionRecord');
+    const entry = { root_index: 0, path: "folder/a (1)!'*.png", filename: "a (1)!'*.png", root_scope: scopeA,
+        url: `/prompt_manager/images/serve/folder/a%20%281%29%21%27%2A.png?root=0&root_scope=${scopeA}`,
+        thumbnail_url: `/prompt_manager/images/serve/thumbnails/folder/a%20%281%29%21%27%2A_thumb.png?root=0&root_scope=${scopeA}` };
+    const record = toRecord(envelope(entry), entry, extractGenerationFacts);
+    assert.equal(record.download.url, entry.url);
+    assert.deepEqual(record.preview, { url: entry.thumbnail_url });
+});

tests/js/workspace-library-location.test.js

@@ -0,0 +1,159 @@
+// Where the library lives (#249 System S6b, D129): the Overview row's copy, the Move library review and its start,
+// "Keep it here" and the Move library job's end.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const locationModule = import('../../web/js/workspace/library-location.mjs');
+
+const NODE_FOLDER = Object.freeze({
+    path: 'custom_nodes/ComfyUI_PromptManager/prompts.db', source: 'node_folder', movable: true, keep: false, offer: true,
+    target: 'user/__promptmanager', problem: null, size_bytes: 1_700_000_000,
+    target_source: 'default', config_moves: true,
+});
+
+function scope() {
+    const controller = new AbortController();
+    return { signal: controller.signal, abort: () => controller.abort(), listen() {}, cleanup() {} };
+}
+
+function activityStore({ running = [] } = {}) {
+    const listeners = new Set();
+    let jobs = [];
+    return {
+        tracked: [], loads: 0,
+        track(job) { this.tracked.push(job); jobs = [...jobs, job]; return job; },
+        async load() { this.loads += 1; },
+        running() { return running; },
+        jobs() { return jobs; },
+        set(next) { jobs = next; for (const listener of listeners) listener(); },
+        subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    };
+}
+
+class ApiError extends Error {
+    constructor(status, message, code) { super(message); this.status = status; this.code = code; }
+}
+
+test('the row says where the library is and why, the choice and any problem', async () => {
+    const { locationDescription, SOURCE_TEXT } = await locationModule;
+    assert.equal(locationDescription(NODE_FOLDER),
+        'custom_nodes/ComfyUI_PromptManager/prompts.db · The node folder, where an update or reinstall can delete it.');
+    assert.equal(locationDescription({ ...NODE_FOLDER, keep: true }),
+        `${NODE_FOLDER.path} · ${SOURCE_TEXT.node_folder}. You chose to keep it here.`);
+    assert.equal(locationDescription({ path: 'user/__promptmanager/prompts.db', source: 'default', movable: false, keep: true }),
+        'user/__promptmanager/prompts.db · ComfyUI\'s user folder, which updates and reinstalls of the node leave alone.');
+    assert.match(locationDescription({ ...NODE_FOLDER, problem: 'data-dir-empty' }), /PROMPT_MANAGER_DATA_DIR has no library yet/);
+    assert.match(locationDescription({ path: 'prompts.db', source: 'environment', movable: false }), /PROMPT_MANAGER_DATA_DIR names/);
+    assert.match(locationDescription({ path: 'prompts.db', source: 'config', movable: false }), /config\.json/);
+});
+
+test('the notice and the review name the actual target and what moves', async () => {
+    const { bannerText, reviewGrid, locationDescription } = await locationModule;
+    assert.match(bannerText(NODE_FOLDER), /Move it to ComfyUI's user folder: it is copied/);
+    assert.match(bannerText({ ...NODE_FOLDER, target_source: 'environment' }),
+        /Move it to the folder PROMPT_MANAGER_DATA_DIR names: it is copied/);
+    assert.match(bannerText(null), /ComfyUI's user folder/);
+    assert.equal(reviewGrid({ ...NODE_FOLDER, config_moves: false })[3][1],
+        'The database backups (config.json stays where PROMPT_MANAGER_CONFIG_PATH names it)');
+    assert.equal(reviewGrid({ ...NODE_FOLDER, config_moves: true })[3][1], 'config.json and the database backups');
+    assert.match(locationDescription({ path: 'custom_nodes/pm/data/my.db', source: 'config', movable: false,
+        problem: 'inside-node-folder' }), /inside the node folder, where an update or reinstall deletes it/);
+});
+
+test('only a well-formed location is shown', async () => {
+    const { isLocation } = await locationModule;
+    assert.equal(isLocation(NODE_FOLDER), true);
+    for (const bad of [null, undefined, 'x', {}, { ...NODE_FOLDER, source: 'elsewhere' }, { ...NODE_FOLDER, path: 3 },
+        { ...NODE_FOLDER, movable: 'yes' }]) assert.equal(isLocation(bad), false);
+});
+
+test('sizes read as the server would write them', async () => {
+    const { sizeText } = await locationModule;
+    assert.equal(sizeText(1_700_000_000), '1.6 GB');
+    assert.equal(sizeText(120 * 2 ** 20), '120.0 MB');
+    assert.equal(sizeText(1500), '2 KB');
+    assert.equal(sizeText(-1), 'Unknown');
+    assert.equal(sizeText(undefined), 'Unknown');
+});
+
+test('the review names both folders, the size and what happens to the old files', async () => {
+    const { reviewGrid } = await locationModule;
+    assert.deepEqual(reviewGrid(NODE_FOLDER), [
+        ['From', 'custom_nodes/ComfyUI_PromptManager/prompts.db'],
+        ['To', 'user/__promptmanager/prompts.db'],
+        ['Size', '1.6 GB'],
+        ['Moves with it', 'config.json and the database backups'],
+        ['Old files', 'Renamed *.moved-to-…, never deleted'],
+    ]);
+});
+
+test('Move library starts the job, tracks it and opens its view', async () => {
+    const { startLibraryMove, MOVE_URL } = await locationModule;
+    const posts = [];
+    const api = { post: async (url, body) => { posts.push([url, body]); return { job: { id: 'j1', kind: 'library_move' } }; } };
+    const activity = activityStore();
+    const routes = [];
+    const job = await startLibraryMove({ api, activity, scope: scope(), notify: () => assert.fail('no toast'),
+        navigate: hash => routes.push(hash) });
+    assert.equal(job.id, 'j1');
+    assert.deepEqual(posts, [[MOVE_URL, {}]]);
+    assert.deepEqual(activity.tracked.map(item => item.id), ['j1']);
+    assert.deepEqual(routes, ['#/activity/j1']);
+});
+
+test('a busy server names the running job; another refusal says the server reason', async () => {
+    const { startLibraryMove, START_FAILED } = await locationModule;
+    const running = { id: 'scan1', title: 'Metadata scan' };
+    const activity = activityStore({ running: [running] });
+    const toasts = [];
+    const busy = { post: async () => { throw new ApiError(409, 'busy', 'busy'); } };
+    assert.equal(await startLibraryMove({ api: busy, activity, scope: scope(), notify: t => toasts.push(t),
+        navigate: () => assert.fail('nothing opens') }), null);
+    assert.equal(activity.loads, 1);
+    assert.deepEqual(toasts.at(-1), ['Another job is running: ', { text: 'Metadata scan', href: '#/activity/scan1' }, '.']);
+    const short = { post: async () => { throw new ApiError(507, 'There is not enough free space for the copy.', 'insufficient-space'); } };
+    await startLibraryMove({ api: short, activity, scope: scope(), notify: t => toasts.push(t), navigate: () => {} });
+    assert.equal(toasts.at(-1), 'There is not enough free space for the copy.');
+    const broken = { post: async () => { throw new TypeError('network'); } };
+    await startLibraryMove({ api: broken, activity, scope: scope(), notify: t => toasts.push(t), navigate: () => {} });
+    assert.equal(toasts.at(-1), START_FAILED);
+    const gone = scope();
+    gone.abort();
+    const before = toasts.length;
+    await startLibraryMove({ api: broken, activity, scope: gone, notify: t => toasts.push(t), navigate: () => {} });
+    assert.equal(toasts.length, before);
+});
+
+test('Keep it here posts the choice and resolves the new location, or null with a toast', async () => {
+    const { keepLibrary, KEEP_URL, KEEP_FAILED } = await locationModule;
+    const posts = [];
+    const kept = { ...NODE_FOLDER, keep: true, offer: false };
+    const api = { post: async (url, body) => { posts.push([url, body]); return { location: kept }; } };
+    assert.deepEqual(await keepLibrary({ api, scope: scope() }), kept);
+    assert.deepEqual(posts, [[KEEP_URL, { keep: true }]]);
+    const toasts = [];
+    const failing = { post: async () => { throw new ApiError(500, 'no', 'config-write-failed'); } };
+    assert.equal(await keepLibrary({ api: failing, scope: scope(), notify: t => toasts.push(t) }), null);
+    assert.deepEqual(toasts, [KEEP_FAILED]);
+    const odd = { post: async () => ({ location: { path: 1 } }) };
+    assert.equal(await keepLibrary({ api: odd, scope: scope() }), null);
+});
+
+test('the end of a Move library job is reported once; other jobs are ignored', async () => {
+    const { onMoveEnded } = await locationModule;
+    const activity = activityStore();
+    let ended = 0;
+    const unsubscribe = onMoveEnded(activity, () => { ended += 1; });
+    activity.set([{ id: 'm', kind: 'library_move', state: 'running' }, { id: 's', kind: 'scan', state: 'running' }]);
+    assert.equal(ended, 0);
+    activity.set([{ id: 'm', kind: 'library_move', state: 'running' }, { id: 's', kind: 'scan', state: 'finished' }]);
+    assert.equal(ended, 0);
+    activity.set([{ id: 'm', kind: 'library_move', state: 'failed' }]);
+    assert.equal(ended, 1);
+    activity.set([{ id: 'm', kind: 'library_move', state: 'failed' }]);
+    assert.equal(ended, 1);
+    unsubscribe();
+    activity.set([{ id: 'n', kind: 'library_move', state: 'running' }]);
+    activity.set([{ id: 'n', kind: 'library_move', state: 'finished' }]);
+    assert.equal(ended, 1);
+});

tests/js/workspace-local-resolver.test.js

@@ -136,6 +136,17 @@ test('an unusable semantics table is refused', () => {
     for (const doc of [null, {schema: 2}, {schema: 1, samplers: []}]) assert.throws(() => resolver.compileSemantics(doc), resolver.SemanticsError);
 });
 
+test('the lineage section is compiled, and a bad one refuses the table', () => {
+    const doc = JSON.parse(fs.readFileSync(new URL('../../web/js/inspection-semantics.json', import.meta.url), 'utf8'));
+    assert.deepEqual(semantics.lineage.get('Image Filter\u00001'), { strategy: 'continue', input: 'latents' });
+    // Lineage describes no prompt: its classes are not table classes for the stage walk.
+    assert.equal(semantics.allClasses.has('VAEEncode'), false);
+    const row = { class: 'VAEEncode', slot: 0, strategy: 'continue', input: 'pixels' };
+    for (const lineage of [undefined, {}, [null], [{ ...row, slot: -1 }], [{ ...row, strategy: 'passthrough' }], [{ ...row, input: '' }], [row, row]]) {
+        assert.throws(() => resolver.compileSemantics({ ...doc, lineage }), resolver.SemanticsError, JSON.stringify(lineage));
+    }
+});
+
 // The committed server answers (tests/fixtures/local-inspect/resolver-vectors.json, written by
 // `python3 -m tests.local_resolver_cases --write` and checked current by the Python suite).
 test('committed server answers equal the local evidence', () => {

tests/js/workspace-media-viewer.test.js

@@ -124,18 +124,51 @@ test('real inspection navigation preserves slideshow across two advances and def
     } finally {view.dispose();controller.dispose();parentScope.dispose();globalThis.setTimeout=oldSetTimeout;globalThis.clearTimeout=oldClearTimeout;f.restore();}
 });
 
-test('an inline Viewer still loading its image is destroyed only after it has viewed it', async () => {
+test('Viewer.js is built only on a loaded image and an unbuilt viewer is released at once', async () => {
     const {reportedLocationAdapter:adapter} = await import('../../web/js/workspace/history-media.mjs');
-    const f = mountedDom(), parentScope = createScope(), controller = borrowedController(), items = [occurrenceMedia('1',1,'c')];
+    const f = mountedDom(), parentScope = createScope(), controller = borrowedController(), items = [occurrenceMedia('1',1,'c'),occurrenceMedia('2',0,'d')];
     const instances = [];
-    // Viewer.js's inline destroy() leaves an in-flight view running; its callback then needs a live instance.
-    f.win.Viewer = class { constructor(node,options) { this.node = node; this.options = options; this.destroyed = 0; this.viewed = false; instances.push(this); }
+    // On a loaded image Viewer.js schedules its inline build; until it runs `ready` is false and destroy() cancels it.
+    f.win.Viewer = class { constructor(node,options) { this.node = node; this.options = options; this.destroyed = 0; this.ready = false; this.viewed = false; instances.push(this); }
         destroy() { this.destroyed++; } resize() {} };
     const globals = {ResizeObserver:globalThis.ResizeObserver, requestAnimationFrame:globalThis.requestAnimationFrame, cancelAnimationFrame:globalThis.cancelAnimationFrame};
     Object.assign(globalThis, {ResizeObserver:class { observe() {} disconnect() {} }, requestAnimationFrame:() => 1, cancelAnimationFrame() {}});
     const view = module.createMediaViewer({container:f.container,parentScope,inspectionController:controller,adapter,sender:{open(){}}});
     try {
-        view.open({items,selectedKey:'c'.repeat(64)});
+        const stageImage = () => f.walk(f.container,n => n.tagName === 'img')[0];
+        view.open({items,selectedKey:'d'.repeat(64)});
+        // Viewer.js's own cancel misses an image whose load event is still queued, so none exists before the load.
+        const unloaded = stageImage(), dropped = [];unloaded.removeAttribute = key => dropped.push(key);
+        assert.equal(instances.length, 0, 'no Viewer.js before the image loads');
+        f.walk(f.container,n => n.attributes['aria-label'] === 'Previous media')[0].fire('click');
+        assert.deepEqual(dropped, ['src'], 'an image left before it loads is released at once');
+        unloaded.fire('load');
+        assert.equal(instances.length, 0, 'its late load builds no Viewer.js');
+        stageImage().fire('load');
+        const [loading] = instances, image = loading.node, removed = [];
+        image.removeAttribute = key => removed.push(key);
+        // Next drops the image whose build is pending; a deferred destroy would let that build run there.
+        f.walk(f.container,n => n.attributes['aria-label'] === 'Next media')[0].fire('click');
+        stageImage().fire('load');assert.equal(instances.length, 2, 'the next image builds its own Viewer.js once loaded');
+        assert.equal(loading.destroyed, 1, 'an unbuilt viewer is destroyed at once');
+        assert.deepEqual(removed, ['src'], 'and its image is released at once');
+        loading.options.viewed.call(loading);
+        assert.equal(loading.destroyed, 1, 'never destroyed twice');
+    } finally { view.dispose(); parentScope.dispose(); f.restore(); Object.assign(globalThis, globals); }
+});
+
+test('an inline Viewer still loading its image is destroyed only after it has viewed it', async () => {
+    const {reportedLocationAdapter:adapter} = await import('../../web/js/workspace/history-media.mjs');
+    const f = mountedDom(), parentScope = createScope(), controller = borrowedController(), items = [occurrenceMedia('1',1,'c')];
+    const instances = [];
+    // A built (`ready`) inline Viewer.js's destroy() leaves an in-flight view running; its callback then needs a live instance.
+    f.win.Viewer = class { constructor(node,options) { this.node = node; this.options = options; this.destroyed = 0; this.ready = true; this.viewed = false; instances.push(this); }
+        destroy() { this.destroyed++; } resize() {} };
+    const globals = {ResizeObserver:globalThis.ResizeObserver, requestAnimationFrame:globalThis.requestAnimationFrame, cancelAnimationFrame:globalThis.cancelAnimationFrame};
+    Object.assign(globalThis, {ResizeObserver:class { observe() {} disconnect() {} }, requestAnimationFrame:() => 1, cancelAnimationFrame() {}});
+    const view = module.createMediaViewer({container:f.container,parentScope,inspectionController:controller,adapter,sender:{open(){}}});
+    try {
+        view.open({items,selectedKey:'c'.repeat(64)});f.walk(f.container,n => n.tagName === 'img')[0].fire('load');
         const [loading] = instances, image = loading.node, removed = [];
         image.removeAttribute = key => removed.push(key);
         f.walk(f.container,n => n.attributes['aria-label'] === 'Close image viewer')[0].fire('click');
@@ -148,7 +181,7 @@ test('an inline Viewer still loading its image is destroyed only after it has vi
         loading.options.viewed.call(loading);
         assert.equal(loading.destroyed, 1, 'never destroyed twice');
 
-        view.open({items,selectedKey:'c'.repeat(64)});
+        view.open({items,selectedKey:'c'.repeat(64)});f.walk(f.container,n => n.tagName === 'img')[0].fire('load');
         const shown = instances[1]; shown.viewed = true; shown.options.viewed.call(shown);
         f.walk(f.container,n => n.attributes['aria-label'] === 'Close image viewer')[0].fire('click');
         assert.equal(shown.destroyed, 1, 'a viewed image is destroyed at once');
@@ -236,7 +269,7 @@ test('viewer uses adapter.mediaUrl for image and video', async () => {
         const img = f.walk(f.container,n => n.tagName === 'img')[0];
         assert.equal(img.src, image.url, 'the blob URL is used exactly');
         assert.doesNotMatch(img.src, /\?/);
-        assert.equal(instances[0].node, img, 'Viewer.js shows the blob image');
+        img.fire('load');assert.equal(instances[0].node, img, 'Viewer.js shows the blob image');
         const download = f.walk(f.container,n => n.attributes['aria-label'] === 'Download original')[0];
         assert.equal(download.href, image.url);assert.equal(download.download, 'a.png');
         f.walk(f.container,n => n.attributes['aria-label'] === 'Next media')[0].fire('click');

tests/js/workspace-preferences.test.js

@@ -0,0 +1,193 @@
+// Browser display defaults (#249 System S3 Task 7): the workspace reads and writes the legacy gallery's own
+// `gallerySettings` object (Q3, "One display configuration"), writes only the keys it changed, never consumes the
+// legacy paging keys, and says when this browser refused to keep a change.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import gallerySettings from '../../web/js/gallery-settings.js';
+
+const module = await import('../../web/js/workspace/preferences.mjs').catch(error => {
+    if (error.code !== 'ERR_MODULE_NOT_FOUND') throw error;
+    return {};
+});
+globalThis.GallerySettings = gallerySettings;
+const KEY = 'gallerySettings';
+
+/** A localStorage stand-in holding `text` under the settings key; `setItem` can be made to throw. */
+function storage(text = null, { quota = false } = {}) {
+    const writes = [];
+    const store = {
+        text,
+        writes,
+        getItem(key) { assert.equal(key, KEY); return store.text; },
+        setItem(key, value) {
+            assert.equal(key, KEY);
+            writes.push(value);
+            if (quota) { const error = new Error('Quota exceeded'); error.name = 'QuotaExceededError'; throw error; }
+            store.text = value;
+        },
+        removeItem() { assert.fail('Preferences never remove the shared settings'); },
+    };
+    return store;
+}
+const denied = () => { const error = new Error('Denied'); error.name = 'SecurityError'; throw error; };
+
+test('normalizes new workspace keys and keeps legacy keys', () => {
+    assert.equal(typeof module.readPreferences, 'function', 'preferences.mjs exports readPreferences');
+    module.resetTabPreferences();
+    const legacy = { defaultViewMode: 'list', gridColumns: 5, defaultLimit: 200, thumbnailPromptDismissed: 'sig', extra: 1 };
+    const store = storage(JSON.stringify({ ...legacy, workspaceLayout: 'masonry', workspaceDensity: 'compact', showFilePaths: false }));
+    const { values, persisted } = module.readPreferences(() => store);
+    assert.equal(persisted, true);
+    assert.equal(values.workspaceLayout, 'masonry');
+    assert.equal(values.workspaceDensity, 'compact');
+    assert.equal(values.showFilePaths, false);
+    // Invalid workspace values fall back to the defaults, as every legacy key does.
+    store.text = JSON.stringify({ workspaceLayout: 'mosaic', workspaceDensity: 7, videoMute: 'no' });
+    const fallback = module.readPreferences(() => store).values;
+    assert.equal(fallback.workspaceLayout, 'grid');
+    assert.equal(fallback.workspaceDensity, 'comfortable');
+    assert.equal(fallback.videoMute, true);
+    // The legacy normalizer knows the new keys and still keeps unknown ones.
+    const normalized = gallerySettings.normalizeGallerySettings({ ...legacy, workspaceLayout: 'list' });
+    assert.equal(normalized.workspaceLayout, 'list');
+    assert.equal(normalized.workspaceDensity, 'comfortable');
+    assert.equal(normalized.extra, 1);
+    assert.equal(normalized.thumbnailPromptDismissed, 'sig');
+    assert.deepEqual(gallerySettings.WORKSPACE_LAYOUTS, ['grid', 'list', 'masonry']);
+    assert.deepEqual(gallerySettings.WORKSPACE_DENSITIES, ['comfortable', 'large', 'compact']);
+});
+
+test('write touches only dirty keys', () => {
+    module.resetTabPreferences();
+    const stored = { defaultViewMode: 'list', gridColumns: 5, thumbnailsGenerated: true, extra: { kept: true }, videoMute: false };
+    const store = storage(JSON.stringify(stored));
+    const result = module.writePreferences({ workspaceLayout: 'masonry', showImageInfo: false }, () => store);
+    assert.deepEqual(result, { persisted: true, conflicts: [] });
+    assert.equal(store.writes.length, 1);
+    // Every other key, legacy or unknown, is written back exactly as it was stored: no defaults are filled in.
+    assert.deepEqual(JSON.parse(store.text), { ...stored, workspaceLayout: 'masonry', showImageInfo: false });
+    // It re-reads the stored object, so a key another page wrote after this one read is kept.
+    store.text = JSON.stringify({ ...JSON.parse(store.text), gridColumns: 9 });
+    module.writePreferences({ videoLoop: false }, () => store);
+    assert.equal(JSON.parse(store.text).gridColumns, 9);
+    assert.equal(JSON.parse(store.text).workspaceLayout, 'masonry');
+    // An empty or malformed stored value starts from an empty object, never the defaults.
+    for (const text of [null, '{broken', '[]', '42']) {
+        const fresh = storage(text);
+        assert.equal(module.writePreferences({ cacheMetadata: false }, () => fresh).persisted, true);
+        assert.deepEqual(JSON.parse(fresh.text), { cacheMetadata: false });
+    }
+    // Only workspace keys with valid values are accepted; nothing is written for a bad change.
+    for (const bad of [{ gridColumns: 4 }, { defaultLimit: 50 }, { workspaceLayout: 'mosaic' }, { videoMute: 'yes' }, { imageQuality: 'ultra' }]) {
+        const untouched = storage(JSON.stringify(stored));
+        assert.throws(() => module.writePreferences(bad, () => untouched), TypeError);
+        assert.equal(untouched.writes.length, 0);
+    }
+    // A key changed elsewhere since this tab read it (its baseline) is reported, and the explicit save still wins.
+    const elsewhere = storage(JSON.stringify({ videoLoop: false }));
+    const outcome = module.writePreferences({ videoLoop: true, videoMute: false }, () => elsewhere, { baseline: { videoLoop: true, videoMute: true } });
+    assert.deepEqual(outcome, { persisted: true, conflicts: ['videoLoop'] });
+    assert.equal(JSON.parse(elsewhere.text).videoLoop, true);
+});
+
+test('denied storage reports tab-only', () => {
+    module.resetTabPreferences();
+    const read = module.readPreferences(denied);
+    assert.equal(read.persisted, false);
+    assert.equal(read.values.workspaceLayout, 'grid');
+    const result = module.writePreferences({ workspaceLayout: 'list', videoAutoplay: true }, denied);
+    assert.deepEqual(result, { persisted: false, conflicts: [] });
+    // The change is kept for this tab: every reader in it (a new Images visit, the viewer) sees it.
+    const tab = module.readPreferences(denied);
+    assert.equal(tab.persisted, false);
+    assert.equal(tab.values.workspaceLayout, 'list');
+    assert.equal(tab.values.videoAutoplay, true);
+    // A getItem that throws is denied storage too.
+    const throwing = { getItem: denied, setItem: denied };
+    assert.equal(module.readPreferences(() => throwing).values.workspaceLayout, 'list');
+    assert.equal(module.writePreferences({ workspaceDensity: 'large' }, () => throwing).persisted, false);
+    // Once storage accepts a write, the tab copy of that key gives way to the stored value.
+    const working = storage(JSON.stringify({ workspaceLayout: 'masonry' }));
+    assert.equal(module.writePreferences({ workspaceLayout: 'masonry' }, () => working).persisted, true);
+    assert.equal(module.readPreferences(() => working).values.workspaceLayout, 'masonry');
+    module.resetTabPreferences();
+    assert.equal(module.readPreferences(denied).values.videoAutoplay, false);
+});
+
+test('quota error keeps previous bytes', () => {
+    module.resetTabPreferences();
+    const before = JSON.stringify({ gridColumns: 6, workspaceDensity: 'large' });
+    const store = storage(before, { quota: true });
+    const result = module.writePreferences({ workspaceDensity: 'compact' }, () => store);
+    assert.deepEqual(result, { persisted: false, conflicts: [] });
+    assert.equal(store.writes.length, 1);
+    assert.equal(store.text, before);
+    // This tab keeps the change it could not store.
+    assert.equal(module.readPreferences(() => store).values.workspaceDensity, 'compact');
+    module.resetTabPreferences();
+    assert.equal(module.readPreferences(() => store).values.workspaceDensity, 'large');
+});
+
+/** A window stand-in that records its storage listeners. */
+function fakeWindow() {
+    const listeners = new Set();
+    return {
+        listeners,
+        addEventListener(type, listener) { assert.equal(type, 'storage'); listeners.add(listener); },
+        removeEventListener(type, listener) { assert.equal(type, 'storage'); listeners.delete(listener); },
+        fire(event) { for (const listener of [...listeners]) listener(event); },
+    };
+}
+
+test('storage event updates clean values and flags dirty conflicts', () => {
+    module.resetTabPreferences();
+    const store = storage(JSON.stringify({ workspaceLayout: 'list', videoMute: false }));
+    const win = fakeWindow();
+    const seen = [];
+    const unsubscribe = module.subscribePreferences(win, next => seen.push(next), () => store);
+    assert.equal(win.listeners.size, 1);
+    // Another key, or another storage area's event, is not ours.
+    win.fire({ key: 'pm_update_notice_dismissed', storageArea: store });
+    win.fire({ key: KEY, storageArea: { other: true } });
+    assert.equal(seen.length, 0);
+    win.fire({ key: KEY, storageArea: store });
+    win.fire({ key: null, storageArea: store }); // localStorage.clear() elsewhere
+    assert.equal(seen.length, 2);
+    assert.equal(seen[0].values.workspaceLayout, 'list');
+    unsubscribe();
+    assert.equal(win.listeners.size, 0);
+    // The reconciliation of the System drafts: clean values follow the other page; a key this tab has a draft for and
+    // the other page changed is a conflict, and the draft stays.
+    const baseline = { workspaceLayout: 'grid', videoMute: true, videoLoop: true };
+    const next = { workspaceLayout: 'list', videoMute: true, videoLoop: false };
+    assert.deepEqual(module.reconcilePreferences({ baseline, drafts: { videoMute: false, videoLoop: false }, next }), { conflicts: [] });
+    assert.deepEqual(module.reconcilePreferences({ baseline, drafts: { workspaceLayout: 'masonry' }, next }), { conflicts: ['workspaceLayout'] });
+    assert.deepEqual(module.reconcilePreferences({ baseline, drafts: { workspaceLayout: 'list' }, next }), { conflicts: [] });
+});
+
+test('legacy paging keys are never consumed by the workspace', () => {
+    module.resetTabPreferences();
+    const store = storage(JSON.stringify({ defaultLimit: 500, gridColumns: 12, infiniteScroll: true, lazyLoading: false,
+        defaultViewMode: 'list', debugMode: true, apiTimeout: 9, thumbnailsGenerated: true, checkThumbnailsAtStartup: false }));
+    const { values } = module.readPreferences(() => store);
+    assert.deepEqual(Object.keys(values).sort(), [...module.WORKSPACE_PREFERENCE_KEYS].sort());
+    for (const key of ['defaultLimit', 'gridColumns', 'infiniteScroll', 'lazyLoading', 'defaultViewMode', 'debugMode', 'apiTimeout',
+        'thumbnailsGenerated', 'checkThumbnailsAtStartup', 'thumbnailPromptDismissed']) assert.equal(Object.hasOwn(values, key), false, key);
+    // The display defaults are the gallery's own defaults for these keys.
+    const defaults = module.preferenceDefaults();
+    for (const key of module.WORKSPACE_PREFERENCE_KEYS) assert.equal(defaults[key], gallerySettings.DEFAULT_SETTINGS[key], key);
+});
+
+test('a later save flushes the changes kept for this tab only', () => {
+    module.resetTabPreferences();
+    const store = storage(JSON.stringify({ gridColumns: 4 }), { quota: true });
+    assert.equal(module.writePreferences({ workspaceLayout: 'list' }, () => store).persisted, false);
+    // Storage accepts writes again: saving another key stores the tab-only change with it, so "Saved" is true for both.
+    const working = storage(store.text);
+    assert.deepEqual(module.writePreferences({ videoLoop: false }, () => working), { persisted: true, conflicts: [] });
+    assert.deepEqual(JSON.parse(working.text), { gridColumns: 4, workspaceLayout: 'list', videoLoop: false });
+    // Nothing is overlaid any more: another page's later change reads through.
+    working.text = JSON.stringify({ ...JSON.parse(working.text), workspaceLayout: 'masonry' });
+    assert.equal(module.readPreferences(() => working).values.workspaceLayout, 'masonry');
+    module.resetTabPreferences();
+});

tests/js/workspace-review-state.test.js

@@ -0,0 +1,788 @@
+// Run with: node --test tests/js/workspace-review-state.test.js
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createApiClient } = require('../../web/js/api-client.js');
+
+// Only an absent module is tolerated, so RED is an assertion failure, not a crash.
+const source = import('../../web/js/workspace/review-state.mjs').catch(error => {
+    if (error.code !== 'ERR_MODULE_NOT_FOUND') throw error;
+    return {};
+});
+async function load() {
+    const module = await source;
+    assert.equal(typeof module.createReviewController, 'function', 'review-state.mjs is not implemented');
+    return module;
+}
+
+const EPOCH = '11111111-1111-4111-8111-111111111111';
+const SCOPE = 'c'.repeat(64);
+const SHA = 'd'.repeat(64);
+const PRINT = 'e'.repeat(64);
+const HASH_A = 'a'.repeat(64);
+const HASH_B = 'b'.repeat(64);
+const HASH_C = 'f'.repeat(64);
+const ITEMS = '/prompt_manager/review/items';
+const OBSERVE = '/prompt_manager/image-annotations/observe';
+const CAPTURE = '/prompt_manager/image-annotations/capture/';
+
+const flush = () => new Promise(resolve => setImmediate(resolve));
+async function settle(times = 8) { for (let i = 0; i < times; i++) await flush(); }
+function response(status, body) {
+    return { ok: status >= 200 && status < 300, status, statusText: `Status ${status}`, json: async () => body };
+}
+const fail = (status, code, error = `failure ${code}`, extra = {}) => response(status, { success: false, code, error, ...extra });
+
+function item(id, overrides = {}) {
+    const path = `dunes/${id}.png`;
+    return {
+        id, state: 'pending', revision: 0, created_at: `2026-10-22T10:00:0${id.length}+00:00`, filename: `${id}.png`,
+        target: { root_index: 0, root_scope: SCOPE, path }, unavailable: false, candidate_count: 3, limited: false,
+        url: `/prompt_manager/images/serve/${path}?root=0&root_scope=${SCOPE}`, is_video: false, ...overrides,
+    };
+}
+const candidate = (hash, sampler, label, positive, negative, state = 'resolved') => ({
+    hash, sampler_id: sampler, state, reason: '', label,
+    positive: positive === null ? null : { text: positive }, negative: negative === null ? null : { text: negative },
+});
+function detailOf(entry, overrides = {}) {
+    return {
+        success: true, library_epoch: EPOCH, ...entry, total: 2, sha256: SHA, dependency_fingerprint: PRINT,
+        candidates: [
+            candidate(HASH_C, '9', 'No positive / Soft negative', null, 'blur', 'unresolved'),
+            candidate(HASH_A, '12', 'Dunes / Soft negative', 'golden dunes', 'blur'),
+            candidate(HASH_B, '28', 'Dunes / Harsh negative', 'golden dunes', 'noise'),
+        ],
+        ...overrides,
+    };
+}
+const page = (items, overrides = {}) => ({ success: true, library_epoch: EPOCH, total: items.length, items, next_cursor: null, ...overrides });
+const observed = (token = 'capture-1') => ({
+    success: true, library_epoch: EPOCH, target: item('one').target, filename: 'one.png', title: 'one.png', tags: [], tag_revision: 0,
+    capture: { token, sha256: SHA, preview_url: CAPTURE + token, size: 10, width: 8, height: 8, media_type: 'image',
+        expires_at: '2026-10-22T12:00:00+00:00', generate: { supported: true, reason: null } },
+});
+
+/** Real createApiClient over a fetch whose answers come from routes['METHOD path'](call). */
+function harness(routes = {}) {
+    const calls = [];
+    const fetch = (url, init = {}) => {
+        const call = { url, method: init.method, body: init.body === undefined ? undefined : JSON.parse(init.body) };
+        calls.push(call);
+        const path = url.startsWith(CAPTURE) ? CAPTURE : url.split('?')[0];
+        const route = routes[`${call.method} ${path}`];
+        return new Promise((resolve, reject) => {
+            init.signal?.addEventListener('abort', () => reject(new DOMException('Aborted', 'AbortError')));
+            Promise.resolve().then(() => (route ? route(call) : response(200, { success: true }))).then(resolve, reject);
+        });
+    };
+    return {
+        api: createApiClient(fetch), calls,
+        of: (method, prefix) => calls.filter(call => call.method === method && call.url.startsWith(prefix)),
+    };
+}
+const QUEUE = [item('one'), item('two')];
+function routes(extra = {}) {
+    return {
+        [`GET ${ITEMS}`]: () => response(200, page(QUEUE)),
+        [`GET ${ITEMS}/one`]: () => response(200, detailOf(QUEUE[0])),
+        [`GET ${ITEMS}/two`]: () => response(200, detailOf(QUEUE[1], { candidates: [], limited: true, candidate_count: 0 })),
+        [`POST ${OBSERVE}`]: () => response(200, observed()),
+        [`POST ${ITEMS}/one/decision`]: call => response(200, { success: true, library_epoch: EPOCH, total: 1,
+            item: { ...QUEUE[0], state: call.body.choice === 'unresolved' ? 'unresolved' : 'selected', revision: 1 } }),
+        ...extra,
+    };
+}
+async function loaded(extra) {
+    const { createReviewController } = await load();
+    const h = harness(routes(extra));
+    const c = createReviewController({ api: h.api });
+    await c.load();
+    await settle();
+    return { c, h };
+}
+
+test('notice titles for 0, 1 and 3', async () => {
+    const { noticeTitle } = await load();
+    assert.equal(noticeTitle(0), 'No images need a decision');
+    assert.equal(noticeTitle(1), '1 image needs a decision');
+    assert.equal(noticeTitle(3), '3 images need a decision');
+    assert.equal(noticeTitle(1234), '1,234 images need a decision');
+});
+
+test('loads pending items and the exact count', async () => {
+    const { c, h } = await loaded();
+    assert.equal(c.state.status, 'ready');
+    assert.equal(c.state.total, 2);
+    assert.deepEqual(c.state.items.map(entry => entry.id), ['one', 'two']);
+    const [list] = h.of('GET', ITEMS);
+    assert.equal(list.url, `${ITEMS}?limit=40`);
+    // The first item is selected, as the concept selects its first queue image.
+    assert.equal(c.state.selectedId, 'one');
+    assert.ok(Object.isFrozen(c.state));
+});
+
+test('selecting a card loads detail and option labels, first workable preselected, unusable disabled', async () => {
+    const { c } = await loaded();
+    assert.equal(c.state.detailStatus, 'ready');
+    assert.deepEqual(c.state.options.map(option => [option.label, option.disabled]), [
+        ['Sampler 9 · No positive / Soft negative', true],
+        ['Sampler 12 · Dunes / Soft negative', false],
+        ['Sampler 28 · Dunes / Harsh negative', false],
+        ['Leave unresolved', false],
+    ]);
+    assert.equal(c.state.options.at(-1).value, 'unresolved');
+    assert.equal(c.state.choice, HASH_A);
+    assert.deepEqual(c.state.prompts, { positive: { status: 'resolved', text: 'golden dunes' }, negative: { status: 'resolved', text: 'blur' } });
+    c.choose(HASH_C);
+    assert.equal(c.state.choice, HASH_A, 'a disabled option cannot be chosen');
+    c.choose(HASH_B);
+    assert.equal(c.state.prompts.negative.text, 'noise');
+    c.choose('unresolved');
+    assert.equal(c.state.prompts.positive.status, 'ambiguous');
+    await c.select('two');
+    await settle();
+    assert.equal(c.state.selectedId, 'two');
+    assert.deepEqual(c.state.options.map(option => option.label), ['Leave unresolved']);
+    assert.equal(c.state.choice, 'unresolved');
+    assert.match(c.state.warning, /too many sampler paths/i);
+});
+
+test('apply sends the selected candidate hash or unresolved with a fresh capture', async () => {
+    const { c, h } = await loaded();
+    c.choose(HASH_B);
+    const done = await c.apply();
+    assert.equal(done, true);
+    const [observe] = h.of('POST', OBSERVE);
+    assert.deepEqual(observe.body, { target: QUEUE[0].target });
+    const [decision] = h.of('POST', `${ITEMS}/one/decision`);
+    assert.deepEqual(decision.body, { expected_epoch: EPOCH, expected_revision: 0, capture_token: 'capture-1', sha256: SHA,
+        dependency_fingerprint: PRINT, choice: HASH_B });
+    assert.equal(c.state.phase, 'done');
+    assert.equal(c.state.total, 1);
+    assert.equal(c.state.toast, 'Association accepted.');
+    // The server releases a used capture itself.
+    assert.equal(h.of('DELETE', CAPTURE).length, 0);
+
+    const again = await loaded();
+    again.c.choose('unresolved');
+    assert.equal(await again.c.apply(), true);
+    const [unresolved] = again.h.of('POST', `${ITEMS}/one/decision`);
+    assert.equal(unresolved.body.choice, 'unresolved');
+    assert.equal(unresolved.body.capture_token, 'capture-1');
+    assert.equal(again.c.state.toast, 'Left unresolved.');
+});
+
+test('an unavailable file can only be left unresolved, without a capture', async () => {
+    const gone = item('one', { target: null, unavailable: true, url: null });
+    const { c, h } = await loaded({
+        [`GET ${ITEMS}`]: () => response(200, page([gone])),
+        [`GET ${ITEMS}/one`]: () => response(200, detailOf(gone)),
+    });
+    assert.ok(c.state.options.slice(0, -1).every(option => option.disabled));
+    assert.equal(c.state.choice, 'unresolved');
+    assert.match(c.state.warning, /not under a current image source/i);
+    assert.equal(await c.apply(), true);
+    assert.equal(h.of('POST', OBSERVE).length, 0);
+    const [decision] = h.of('POST', `${ITEMS}/one/decision`);
+    assert.equal(decision.body.capture_token, null);
+    assert.equal(decision.body.sha256, SHA);
+});
+
+test('association conflict keeps the selection and shows the inline warning', async () => {
+    const message = 'This image is already linked to another prompt or negative, so this sampler path cannot be attached safely.';
+    const { c, h } = await loaded({ [`POST ${ITEMS}/one/decision`]: () => fail(409, 'association-conflict', message) });
+    assert.equal(await c.apply(), false);
+    assert.equal(c.state.selectedId, 'one');
+    assert.equal(c.state.choice, HASH_A);
+    assert.equal(c.state.phase, 'idle');
+    assert.equal(c.state.warning, message);
+    // The refused decision's capture is released.
+    assert.equal(h.of('DELETE', CAPTURE).length, 1);
+    assert.equal(h.of('GET', `${ITEMS}?`).length, 1, 'no reload');
+});
+
+test('storage-changed requires reload', async () => {
+    let lists = 0;
+    const { c, h } = await loaded({
+        [`GET ${ITEMS}`]: () => { lists += 1; return response(200, page(QUEUE)); },
+        [`POST ${ITEMS}/one/decision`]: () => fail(409, 'storage-changed', 'Prompt storage was restored; reload the review queue.'),
+    });
+    assert.equal(await c.apply(), false);
+    await settle();
+    assert.equal(lists, 2, 'the queue is read again under the new epoch');
+    assert.equal(c.state.warning, 'Prompt storage was restored; reload the review queue.');
+    assert.equal(c.state.canRetry, false);
+    assert.equal(h.of('DELETE', CAPTURE).length, 1);
+});
+
+test('lost response keeps the selection and retry resends once', async () => {
+    let attempts = 0;
+    const { c, h } = await loaded({
+        [`POST ${ITEMS}/one/decision`]: call => {
+            attempts += 1;
+            if (attempts === 1) return Promise.reject(new TypeError('Failed to fetch'));
+            return response(200, { success: true, library_epoch: EPOCH, total: 1, item: { ...QUEUE[0], state: 'selected', revision: 1 } });
+        },
+    });
+    assert.equal(await c.apply(), false);
+    assert.equal(c.state.selectedId, 'one');
+    assert.equal(c.state.canRetry, true);
+    assert.match(c.state.warning, /may not have been saved/i);
+    assert.equal(h.of('DELETE', CAPTURE).length, 0, 'the capture is kept for the retry');
+    const [first] = h.of('POST', `${ITEMS}/one/decision`);
+    assert.equal(await c.retry(), true);
+    const sent = h.of('POST', `${ITEMS}/one/decision`);
+    assert.equal(sent.length, 2);
+    assert.deepEqual(sent[1].body, first.body, 'the identical decision is resent');
+    assert.equal(h.of('POST', OBSERVE).length, 1, 'no second capture');
+    assert.equal(await c.retry(), false, 'nothing left to resend');
+    assert.equal(h.of('POST', `${ITEMS}/one/decision`).length, 2);
+});
+
+test('a retry answered by review-conflict reloads the queue', async () => {
+    let attempts = 0, lists = 0;
+    const { c } = await loaded({
+        [`GET ${ITEMS}`]: () => { lists += 1; return response(200, page(lists === 1 ? QUEUE : [QUEUE[1]])); },
+        [`POST ${ITEMS}/one/decision`]: () => {
+            attempts += 1;
+            if (attempts === 1) return Promise.reject(new TypeError('Failed to fetch'));
+            return fail(409, 'review-conflict', 'This item was decided or changed since it was opened. Reload the queue.');
+        },
+    });
+    await c.apply();
+    assert.equal(await c.retry(), false);
+    await settle();
+    assert.equal(lists, 2);
+    assert.equal(c.state.selectedId, 'two');
+});
+
+test('a review-conflict on a still pending item reads its detail again', async () => {
+    let details = 0, decisions = 0;
+    const { c, h } = await loaded({
+        [`GET ${ITEMS}/one`]: () => { details += 1; return response(200, detailOf({ ...QUEUE[0], revision: details - 1 })); },
+        [`POST ${ITEMS}/one/decision`]: () => {
+            decisions += 1;
+            return decisions === 1 ? fail(409, 'review-conflict', 'This item was decided or changed since it was opened. Reload the queue.')
+                : response(200, { success: true, library_epoch: EPOCH, total: 1, item: { ...QUEUE[0], state: 'selected', revision: 2 } });
+        },
+    });
+    assert.equal(await c.apply(), false);
+    await settle();
+    assert.equal(details, 2, 'the item is read again');
+    assert.equal(c.state.detail.revision, 1);
+    assert.equal(c.state.warning, 'This item was decided or changed since it was opened. Reload the queue.');
+    assert.equal(await c.apply(), true);
+    assert.equal(h.of('POST', `${ITEMS}/one/decision`).at(-1).body.expected_revision, 1);
+});
+
+test('leave for later writes nothing', async () => {
+    const { c, h } = await loaded();
+    c.leave();
+    assert.equal(c.state.phase, 'done');
+    assert.equal(c.state.toast, null);
+    assert.equal(h.of('POST', '/').length, 0);
+    assert.equal(h.of('DELETE', '/').length, 0);
+});
+
+test('load more pages with the cursor and keeps the selection', async () => {
+    const more = [item('three')];
+    const { c, h } = await loaded({
+        [`GET ${ITEMS}`]: call => response(200, call.url.includes('cursor=')
+            ? page(more, { total: 3 }) : page(QUEUE, { total: 3, next_cursor: 'abc_-1' })),
+    });
+    assert.equal(c.state.nextCursor, 'abc_-1');
+    await c.loadMore();
+    assert.equal(h.of('GET', ITEMS).at(-1).url, `${ITEMS}?limit=40&cursor=abc_-1`);
+    assert.deepEqual(c.state.items.map(entry => entry.id), ['one', 'two', 'three']);
+    assert.equal(c.state.nextCursor, null);
+    assert.equal(c.state.selectedId, 'one');
+});
+
+test('a failed queue read is an error state and load retries', async () => {
+    let lists = 0;
+    const { c } = await loaded({ [`GET ${ITEMS}`]: () => { lists += 1; return lists === 1 ? fail(500, 'review-failed') : response(200, page(QUEUE)); } });
+    assert.equal(c.state.status, 'error');
+    await c.load();
+    await settle();
+    assert.equal(c.state.status, 'ready');
+});
+
+test('tag save toast carries the review suffix and the item stays pending', async () => {
+    const { c, h } = await loaded({
+        ['GET /prompt_manager/autotag/models']: () => response(200, { success: true, models: {}, default_prompt: 'x',
+            wd14_general_threshold: 0.35, wd14_character_threshold: 0.85, suggestion_limit: 10 }),
+        ['PUT /prompt_manager/image-annotations/tags']: call => response(200, { success: true, library_epoch: EPOCH, sha256: SHA,
+            tags: call.body.tags, tag_revision: 1, replayed: false }),
+    });
+    const { createImageTaggingController } = await import('../../web/js/workspace/image-tagging-state.mjs');
+    const before = h.calls.filter(call => call.url.startsWith(ITEMS)).length;
+    // The Tag dialog opened from Needs review is the shared controller with the review source.
+    const tagging = createImageTaggingController({ api: h.api, target: QUEUE[0].target, source: 'review' });
+    assert.equal(tagging.state.showScopeNote, true);
+    await tagging.open();
+    await settle();
+    tagging.setManual('dunes');
+    await tagging.save();
+    await settle();
+    assert.equal(tagging.state.toast, '1 tags saved for one.png. Prompt association still awaits review.');
+    tagging.dispose();
+    assert.equal(h.calls.filter(call => call.url.startsWith(ITEMS)).length, before, 'a tag save neither decides nor re-reads the queue');
+    assert.deepEqual(c.state.items.map(entry => [entry.id, entry.state]), [['one', 'pending'], ['two', 'pending']]);
+    assert.equal(c.state.phase, 'idle');
+});
+
+test('dispose releases a kept capture and stops reads', async () => {
+    const { c, h } = await loaded({ [`POST ${ITEMS}/one/decision`]: () => Promise.reject(new TypeError('Failed to fetch')) });
+    await c.apply();
+    c.dispose();
+    await settle();
+    const released = h.of('DELETE', CAPTURE);
+    assert.equal(released.length, 1);
+    assert.equal(released[0].url, CAPTURE + 'capture-1');
+    assert.equal(await c.retry(), false);
+});
+
+// F2: an open page re-reads its queue when the server says it changed (the review change stream).
+function refreshOf(c) {
+    assert.equal(typeof c.refresh, 'function', 'refresh is not implemented');
+    return c.refresh();
+}
+test('refresh re-reads the queue quietly and keeps the selection and choice', async () => {
+    let queue = QUEUE;
+    const { c, h } = await loaded({ [`GET ${ITEMS}`]: () => response(200, page(queue)) });
+    c.choose(HASH_B);
+    const statuses = [];
+    c.subscribe(state => statuses.push(state.status));
+    queue = [...QUEUE, item('three')];
+    await refreshOf(c);
+    await settle();
+    assert.deepEqual(c.state.items.map(entry => entry.id), ['one', 'two', 'three']);
+    assert.equal(c.state.total, 3);
+    assert.equal(c.state.selectedId, 'one');
+    assert.equal(c.state.choice, HASH_B);
+    assert.equal(c.state.warning, '');
+    assert.ok(statuses.every(status => status === 'ready'), `no loading state: ${statuses}`);
+    assert.equal(h.of('GET', `${ITEMS}/one`).length, 1, 'the open item is not read again');
+});
+
+test('refreshes asked for during a refresh collapse into one more read', async () => {
+    let release;
+    const held = new Promise(resolve => { release = resolve; });
+    let lists = 0;
+    const { c, h } = await loaded({ [`GET ${ITEMS}`]: async () => {
+        lists += 1;
+        if (lists === 2) await held;
+        return response(200, page(QUEUE));
+    } });
+    const first = refreshOf(c);
+    await settle();
+    refreshOf(c);
+    refreshOf(c);
+    release();
+    await first;
+    await settle();
+    assert.equal(h.of('GET', `${ITEMS}?`).length, 3, 'the load, the refresh and one collapsed re-read');
+    assert.equal(c.state.status, 'ready');
+});
+
+test('a refresh after the open item was decided elsewhere opens the next one and says so', async () => {
+    let queue = QUEUE;
+    const { c, h } = await loaded({
+        [`GET ${ITEMS}`]: () => response(200, page(queue)),
+        [`GET ${ITEMS}/three`]: () => response(200, detailOf(item('three'))),
+    });
+    queue = [item('three')];
+    await refreshOf(c);
+    await settle();
+    assert.equal(c.state.selectedId, 'three');
+    assert.equal(c.state.detailStatus, 'ready');
+    assert.equal(c.state.warning, 'one.png was decided elsewhere, so the next image is open.');
+    assert.equal(h.of('GET', `${ITEMS}/three`).length, 1);
+});
+
+test('a refresh to an empty queue clears the selection', async () => {
+    let queue = QUEUE;
+    const { c } = await loaded({ [`GET ${ITEMS}`]: () => response(200, page(queue)) });
+    queue = [];
+    await refreshOf(c);
+    await settle();
+    assert.equal(c.state.total, 0);
+    assert.deepEqual(c.state.items, []);
+    assert.equal(c.state.selectedId, null);
+    assert.equal(c.state.status, 'ready');
+});
+
+test('a failed refresh keeps the queue and says so', async () => {
+    let lists = 0;
+    const { c } = await loaded({ [`GET ${ITEMS}`]: () => { lists += 1; return lists === 1 ? response(200, page(QUEUE)) : fail(500, 'review-failed'); } });
+    await refreshOf(c);
+    await settle();
+    assert.equal(c.state.status, 'ready');
+    assert.deepEqual(c.state.items.map(entry => entry.id), ['one', 'two']);
+    assert.equal(c.state.warning, 'The review queue could not be read again. Reload the page to see the latest images.');
+});
+
+test('dispose during a decision releases its capture', async () => {
+    const { c, h } = await loaded({ [`POST ${ITEMS}/one/decision`]: () => new Promise(() => {}) });
+    const applying = c.apply();
+    await settle();
+    assert.equal(c.state.phase, 'applying');
+    c.dispose();
+    assert.equal(await applying, false);
+    await settle();
+    assert.deepEqual(h.of('DELETE', CAPTURE).map(call => call.url), [CAPTURE + 'capture-1']);
+    await refreshOf(c);
+    assert.equal(h.of('GET', `${ITEMS}?`).length, 1, 'a disposed controller reads nothing');
+});
+
+test('a change heard during the first read re-reads once after it, and a failed first read stays an error', async () => {
+    const { createReviewController } = await load();
+    let release;
+    let lists = 0;
+    const h = harness(routes({ [`GET ${ITEMS}`]: async () => {
+        lists += 1;
+        if (lists === 1) await new Promise(resolve => { release = resolve; });
+        return response(200, page(QUEUE));
+    } }));
+    const c = createReviewController({ api: h.api });
+    const first = c.load();
+    await settle();
+    refreshOf(c);
+    assert.equal(lists, 1, 'the first read is not interrupted');
+    release();
+    await first;
+    await settle();
+    assert.equal(lists, 2, 'one re-read after the first read');
+    assert.equal(c.state.status, 'ready');
+
+    const failing = harness(routes({ [`GET ${ITEMS}`]: () => fail(500, 'review-failed') }));
+    const broken = createReviewController({ api: failing.api });
+    const reading = broken.load();
+    refreshOf(broken);
+    await reading;
+    await settle();
+    assert.equal(broken.state.status, 'error');
+    assert.equal(failing.of('GET', `${ITEMS}?`).length, 1, 'Retry is the way back, not a re-read');
+});
+
+// F3 rulings: a live re-read keeps the loaded depth, and the stream's `ready` reads nothing when the first read is current.
+
+/** A keyset pager over `source()`: pages of 40 with an index cursor, each answering `version()`. */
+function pager(source, version = () => 0, { onPage } = {}) {
+    return call => {
+        const query = new URL(call.url, 'http://x').searchParams;
+        const cursor = query.get('cursor');
+        const all = source();
+        const from = cursor ? Number(cursor.slice(1)) : 0;
+        const answer = onPage?.(cursor);
+        if (answer) return answer;
+        const items = all.slice(from, from + 40);
+        const next = from + 40 < all.length ? `c${from + 40}` : null;
+        return response(200, page(items, { total: all.length, next_cursor: next, review_revision: version() }));
+    };
+}
+const many = (count, prefix = 'i') => Array.from({ length: count }, (_, index) => item(`${prefix}${String(index).padStart(3, '0')}`));
+function syncOf(c, version) {
+    assert.equal(typeof c.sync, 'function', 'sync is not implemented');
+    return c.sync(version);
+}
+const version = revision => ({ library_epoch: EPOCH, review_revision: revision });
+
+test('a refresh keeps the loaded depth: it re-reads as many items as were loaded', async () => {
+    let queue = many(100);
+    const { c, h } = await loaded({ [`GET ${ITEMS}`]: pager(() => queue) });
+    await c.loadMore();
+    assert.equal(c.state.items.length, 80);
+    const before = h.of('GET', `${ITEMS}?`).length;
+    queue = [...queue, item('late')];
+    await refreshOf(c);
+    await settle();
+    assert.equal(c.state.items.length, 80, 'the Load more page is kept');
+    assert.deepEqual(c.state.items.map(entry => entry.id), queue.slice(0, 80).map(entry => entry.id));
+    assert.equal(c.state.total, 101);
+    assert.equal(c.state.nextCursor, 'c80', 'Load more continues after the kept depth');
+    assert.deepEqual(h.of('GET', `${ITEMS}?`).slice(before).map(call => call.url),
+        [`${ITEMS}?limit=40`, `${ITEMS}?limit=40&cursor=c40`]);
+    assert.equal(c.state.selectedId, 'i000');
+});
+
+test('a refresh after decisions elsewhere fills the loaded depth from what is left', async () => {
+    let queue = many(85);
+    const { c } = await loaded({ [`GET ${ITEMS}`]: pager(() => queue) });
+    await c.loadMore();
+    await c.loadMore();
+    assert.equal(c.state.items.length, 85);
+    queue = queue.filter((_, index) => index % 10 !== 5);
+    await refreshOf(c);
+    await settle();
+    assert.equal(c.state.items.length, queue.length);
+    assert.equal(c.state.nextCursor, null);
+});
+
+test('a deep refresh whose next page meets a restore reads again from the first page', async () => {
+    let restored = false;
+    let queue = many(60);
+    const { c, h } = await loaded({ [`GET ${ITEMS}`]: pager(() => queue, () => 0, {
+        onPage: cursor => {
+            if (cursor && restored) { restored = false; return fail(409, 'storage-changed', 'The library was restored.'); }
+            return null;
+        },
+    }) });
+    await c.loadMore();
+    const before = h.of('GET', `${ITEMS}?`).length;
+    restored = true;
+    queue = many(60, 'r');
+    await refreshOf(c);
+    await settle();
+    assert.deepEqual(h.of('GET', `${ITEMS}?`).slice(before).map(call => call.url),
+        [`${ITEMS}?limit=40`, `${ITEMS}?limit=40&cursor=c40`, `${ITEMS}?limit=40`, `${ITEMS}?limit=40&cursor=c40`]);
+    assert.equal(c.state.items.length, 60);
+    assert.equal(c.state.items[0].id, 'r000');
+    assert.notEqual(c.state.warning, 'The review queue could not be read again. Reload the page to see the latest images.',
+        'a restore met mid-read is not a failed re-read');
+    assert.equal(c.state.status, 'ready');
+});
+
+test('ready naming the version the first read answered reads nothing more', async () => {
+    const { c, h } = await loaded({ [`GET ${ITEMS}`]: pager(() => QUEUE, () => 4) });
+    await syncOf(c, version(4));
+    await settle();
+    assert.equal(h.of('GET', `${ITEMS}?`).length, 1, 'one list read per visit');
+    assert.equal(h.of('GET', `${ITEMS}/one`).length, 1);
+});
+
+test('ready naming a newer version, another epoch or no version re-reads once', async () => {
+    const { c, h } = await loaded({ [`GET ${ITEMS}`]: pager(() => QUEUE, () => 4) });
+    await syncOf(c, version(5));
+    await settle();
+    assert.equal(h.of('GET', `${ITEMS}?`).length, 2);
+    await syncOf(c, { library_epoch: '22222222-2222-4222-8222-222222222222', review_revision: 4 });
+    await settle();
+    assert.equal(h.of('GET', `${ITEMS}?`).length, 3);
+    await syncOf(c, {});
+    await settle();
+    assert.equal(h.of('GET', `${ITEMS}?`).length, 4, 'an unknown version is read, as before versions existed');
+});
+
+test('ready heard during the first read re-reads only when that read is older', async () => {
+    const { createReviewController } = await load();
+    for (const [readRevision, readyRevision, reads] of [[4, 4, 1], [5, 4, 1], [4, 5, 2]]) {
+        let release;
+        let lists = 0;
+        const answer = pager(() => QUEUE, () => (lists === 1 ? readRevision : readyRevision));
+        const h = harness(routes({ [`GET ${ITEMS}`]: async call => {
+            lists += 1;
+            if (lists === 1) await new Promise(resolve => { release = resolve; });
+            return answer(call);
+        } }));
+        const c = createReviewController({ api: h.api });
+        const first = c.load();
+        await settle();
+        syncOf(c, version(readyRevision));
+        release();
+        await first;
+        await settle();
+        assert.equal(lists, reads, `first read r${readRevision}, ready r${readyRevision}`);
+        c.dispose();
+    }
+});
+
+test('a change heard during the first read still re-reads after a current ready', async () => {
+    const { createReviewController } = await load();
+    let release;
+    let lists = 0;
+    const h = harness(routes({ [`GET ${ITEMS}`]: async call => {
+        lists += 1;
+        if (lists === 1) await new Promise(resolve => { release = resolve; });
+        return pager(() => QUEUE, () => 4)(call);
+    } }));
+    const c = createReviewController({ api: h.api });
+    const first = c.load();
+    await settle();
+    syncOf(c, version(4));
+    refreshOf(c);
+    release();
+    await first;
+    await settle();
+    assert.equal(lists, 2);
+});
+
+// Final review round (I1, I2, M3–M5, M7).
+test('I1: a change heard during a refused Apply is re-read once the phase is idle again', async () => {
+    let queue = [item('one')], releaseDecision;
+    const { c, h } = await loaded({
+        [`GET ${ITEMS}`]: () => response(200, page(queue, { review_revision: queue.length })),
+        [`POST ${ITEMS}/one/decision`]: () => new Promise(resolve => {
+            releaseDecision = () => resolve(fail(409, 'association-conflict', 'conflict'));
+        }),
+    });
+    const applying = c.apply();
+    await settle();
+    assert.equal(c.state.phase, 'applying');
+    queue = [item('one'), item('two')]; // the monitor records an item while the decision is in flight
+    c.refresh();
+    await settle();
+    assert.equal(h.of('GET', `${ITEMS}?`).length, 1, 'no read while the decision is in flight');
+    releaseDecision();
+    await applying;
+    await settle();
+    assert.equal(c.state.phase, 'idle');
+    assert.deepEqual(c.state.items.map(entry => entry.id), ['one', 'two']);
+    assert.equal(c.state.total, 2);
+    assert.equal(c.state.warning, 'conflict', 'the refusal stays the warning');
+    assert.equal(h.of('GET', `${ITEMS}?`).length, 2, 'exactly one owed re-read');
+});
+
+test('I1: a change heard during an Apply whose observe is refused is re-read too', async () => {
+    let queue = [item('one')], releaseObserve;
+    const { c } = await loaded({
+        [`GET ${ITEMS}`]: () => response(200, page(queue)),
+        [`POST ${OBSERVE}`]: () => new Promise(resolve => {
+            releaseObserve = () => resolve(fail(409, 'capture-capacity', 'busy'));
+        }),
+    });
+    const applying = c.apply();
+    await settle();
+    queue = [item('one'), item('two')];
+    c.refresh();
+    releaseObserve();
+    await applying;
+    await settle();
+    assert.deepEqual(c.state.items.map(entry => entry.id), ['one', 'two']);
+});
+
+const forty = Array.from({ length: 41 }, (_, i) => item(`i${String(i).padStart(2, '0')}`));
+function deepRoutes(state) {
+    return {
+        [`GET ${ITEMS}`]: call => {
+            const cursor = new URL(call.url, 'http://x').searchParams.get('cursor');
+            if (cursor) {
+                if (state.moreGate) return state.moreGate.then(() => state.more ?? response(200, page([forty[40]], { total: 41 })));
+                return state.more ?? response(200, page([forty[40]], { total: 41 }));
+            }
+            const body = response(200, page(state.first, { total: state.first.length + 1, review_revision: state.revision ?? 1, next_cursor: 'cur' }));
+            return state.gate ? state.gate.then(() => state.fail ?? body) : body;
+        },
+        [`GET ${ITEMS}/i00`]: () => response(200, detailOf(forty[0])),
+    };
+}
+
+test('I2: Load more during a re-read waits for it and continues from the re-read queue', async () => {
+    const state = { first: forty.slice(0, 40) };
+    const { c } = await loaded(deepRoutes(state));
+    // Another tab decides i05; the re-read is slow and the user clicks Load more meanwhile.
+    let open;
+    state.first = forty.slice(0, 40).filter(entry => entry.id !== 'i05');
+    state.gate = new Promise(resolve => { open = resolve; });
+    const refreshing = c.refresh();
+    await settle();
+    const more = c.loadMore();
+    await settle();
+    assert.equal(c.state.more, 'loading', 'the click shows as loading while the re-read runs');
+    open();
+    await Promise.all([refreshing, more]);
+    await settle();
+    const ids = c.state.items.map(entry => entry.id);
+    assert.ok(!ids.includes('i05'), 'the re-read was applied');
+    assert.equal(ids.at(-1), 'i40', 'Load more appended the next page after the re-read');
+    assert.equal(c.state.more, 'idle');
+});
+
+test('I2: a re-read started during Load more takes over the click and reads one page deeper', async () => {
+    const state = { first: forty.slice(0, 40) };
+    const { c, h } = await loaded(deepRoutes(state));
+    let openMore;
+    state.moreGate = new Promise(resolve => { openMore = resolve; });
+    const more = c.loadMore();
+    await settle();
+    state.moreGate = null;
+    state.first = forty.slice(0, 40).filter(entry => entry.id !== 'i05');
+    await c.refresh();
+    openMore();
+    await more;
+    await settle();
+    const ids = c.state.items.map(entry => entry.id);
+    assert.ok(!ids.includes('i05'));
+    assert.equal(ids.at(-1), 'i40', 'the aborted Load more page is part of the re-read');
+    assert.equal(c.state.more, 'idle');
+    assert.equal(h.of('GET', `${ITEMS}?`).length, 4, 'load, the aborted more, and the re-read of two pages');
+});
+
+test('M7: a failed re-read that took over Load more clears its loading state', async () => {
+    const state = { first: forty.slice(0, 40) };
+    const { c } = await loaded(deepRoutes(state));
+    state.moreGate = new Promise(() => {});
+    c.loadMore();
+    await settle();
+    assert.equal(c.state.more, 'loading');
+    state.moreGate = null;
+    state.gate = Promise.resolve();
+    state.fail = fail(500, 'review-failed');
+    await c.refresh();
+    await settle();
+    assert.equal(c.state.more, 'idle', 'Load more can be clicked again');
+    assert.equal(c.state.warning, COPY_REFRESH_FAILED);
+});
+const COPY_REFRESH_FAILED = 'The review queue could not be read again. Reload the page to see the latest images.';
+
+test('M3: Apply fences on the epoch of the detail it decides', async () => {
+    const OTHER = '22222222-2222-4222-8222-222222222222';
+    const { c, h } = await loaded({ [`POST ${OBSERVE}`]: () => response(200, { ...observed(), library_epoch: OTHER }) });
+    assert.equal(await c.apply(), false);
+    await settle();
+    assert.equal(h.of('POST', `${ITEMS}/one/decision`).length, 0, 'a restored storage sends no decision');
+    assert.deepEqual(h.of('DELETE', CAPTURE).map(call => call.url), [CAPTURE + 'capture-1']);
+    assert.equal(h.of('GET', `${ITEMS}?`).length, 2, 'the queue is read again');
+    assert.equal(h.of('GET', `${ITEMS}/one`).length, 2, 'the open item is read again under the new storage');
+    assert.equal(c.state.phase, 'idle');
+});
+
+test('M3: the decision carries the detail epoch', async () => {
+    const { c, h } = await loaded();
+    assert.equal(await c.apply(), true);
+    assert.equal(h.of('POST', `${ITEMS}/one/decision`)[0].body.expected_epoch, EPOCH);
+});
+
+test('M3: a quiet re-read under another epoch reads the open item again', async () => {
+    const OTHER = '22222222-2222-4222-8222-222222222222';
+    let epoch = EPOCH;
+    const { c, h } = await loaded({
+        [`GET ${ITEMS}`]: () => response(200, page(QUEUE, { library_epoch: epoch })),
+        [`GET ${ITEMS}/one`]: () => response(200, detailOf(QUEUE[0], { library_epoch: epoch })),
+    });
+    epoch = OTHER;
+    await c.refresh();
+    await settle();
+    assert.equal(h.of('GET', `${ITEMS}/one`).length, 2);
+    assert.equal(c.state.detail.library_epoch, OTHER);
+});
+
+test('M4: leaving during the observe releases the capture it then answers', async () => {
+    let answer;
+    const { c, h } = await loaded({ [`POST ${OBSERVE}`]: () => new Promise(resolve => { answer = resolve; }) });
+    const applying = c.apply();
+    await settle();
+    c.dispose();
+    answer(response(200, observed('late')));
+    assert.equal(await applying, false);
+    await settle();
+    assert.deepEqual(h.of('DELETE', CAPTURE).map(call => call.url), [CAPTURE + 'late']);
+    assert.equal(h.of('POST', `${ITEMS}/one/decision`).length, 0);
+});
+
+test('M5: an unanswered decision that landed finishes as recorded, not as decided elsewhere', async () => {
+    let queue = QUEUE;
+    const { c, h } = await loaded({
+        [`GET ${ITEMS}`]: () => response(200, page(queue)),
+        [`POST ${ITEMS}/one/decision`]: () => Promise.reject(new TypeError('Failed to fetch')),
+    });
+    await c.apply();
+    assert.equal(c.state.canRetry, true);
+    queue = [QUEUE[1]]; // the server did record it: its change arrives
+    await c.refresh();
+    await settle();
+    assert.equal(c.state.phase, 'done');
+    assert.equal(c.state.toast, 'Association accepted.');
+    assert.doesNotMatch(c.state.warning, /decided elsewhere/);
+    assert.equal(h.of('DELETE', CAPTURE).length, 0, 'the server used the capture');
+});

tests/js/workspace-state.test.js

@@ -4,7 +4,7 @@ const source = import('../../web/js/workspace/state.mjs');
 
 test('workspace routes resolve only supported deep links', async () => {
     const { resolveRoute } = await source;
-    for (const route of ['overview', 'images', 'library', 'tags', 'inspect', 'system', 'activity']) {
+    for (const route of ['overview', 'images', 'library', 'tags', 'inspect', 'system', 'activity', 'review']) {
         assert.equal(resolveRoute(`#/${route}`).id, route);
     }
     for (const hash of ['', '#', '#/unknown', '#/images/other', '#/<script>', '#/activity/abc', `#/activity/${'A'.repeat(32)}`]) {
@@ -24,7 +24,7 @@ test('tags is a native route titled Tags; only unbuilt routes hand off to legacy
     }
     assert.equal(routeTitle(resolveRoute('#/library/7')), 'Prompt library');
     // System is native from S2 (#249 System): its undelivered sections hand off per section (D94), not the route.
-    for (const id of ['images', 'library', 'tags', 'inspect', 'overview', 'activity', 'system']) assert.equal(isHandoff(resolveRoute(`#/${id}`)), false, id);
+    for (const id of ['images', 'library', 'tags', 'inspect', 'overview', 'activity', 'review', 'system']) assert.equal(isHandoff(resolveRoute(`#/${id}`)), false, id);
 });
 
 test('system resolves its sections; #/overview stays the production hub', async () => {
@@ -157,9 +157,10 @@ test('positive library deep links preserve the selected identity without duplica
 
 test('nav counts reject negative, non-integer and missing totals', async () => {
     const { summarizeNavCounts } = await source;
-    const counts = summarizeNavCounts({images: {total: 24}, favorites: {total: 3}, library: {total: 0}, tags: {total: 7}});
+    const counts = summarizeNavCounts({images: {total: 24}, favorites: {total: 3}, library: {total: 0}, tags: {total: 7},
+        review: {total: 3}});
     assert.ok(counts instanceof Map);
-    assert.deepEqual([...counts], [['images', 24], ['favorites', 3], ['library', 0], ['tags', 7]]);
+    assert.deepEqual([...counts], [['images', 24], ['favorites', 3], ['library', 0], ['tags', 7], ['review', 3]]);
     assert.equal(counts.has('inspect'), false, 'Inspect a file has no count');
     for (const invalid of [undefined, null, {}, {total: -1}, {total: 1.5}, {total: '3'}, {total: NaN},
         {total: Infinity}, {total: Number.MAX_SAFE_INTEGER + 1}, {total: null}, [], 'x']) {
@@ -169,7 +170,8 @@ test('nav counts reject negative, non-integer and missing totals', async () => {
         assert.equal(result.get('library'), 2);
         assert.equal(result.get('tags'), null);
     }
-    assert.deepEqual([...summarizeNavCounts()], [['images', null], ['favorites', null], ['library', null], ['tags', null]]);
+    assert.deepEqual([...summarizeNavCounts()], [['images', null], ['favorites', null], ['library', null], ['tags', null],
+        ['review', null]]);
 });
 
 test('nav counts settle independently so a slow images read never delays the others', async () => {
@@ -185,14 +187,14 @@ test('nav counts settle independently so a slow images read never delays the oth
     const settled = [];
     const done = loadNavCounts(api, new AbortController().signal, (id, count) => settled.push([id, count]));
     await new Promise(resolve => setTimeout(resolve, 0));
-    assert.deepEqual(settled.sort(), [['favorites', 2], ['library', 3], ['tags', null]]);
+    assert.deepEqual(settled.sort(), [['favorites', 2], ['library', 3], ['review', null], ['tags', null]]);
     releaseImages({success: true, total: 40});
     const counts = await done;
     assert.deepEqual(settled.at(-1), ['images', 40]);
-    assert.deepEqual([...counts], [['images', 40], ['favorites', 2], ['library', 3], ['tags', null]]);
+    assert.deepEqual([...counts], [['images', 40], ['favorites', 2], ['library', 3], ['tags', null], ['review', null]]);
 });
 
-test('nav counts issue four bounded requests and drop only the failed count', async () => {
+test('nav counts issue five bounded requests and drop only the failed count', async () => {
     const { loadNavCounts } = await source;
     const calls = [];
     const signal = new AbortController().signal;
@@ -200,13 +202,15 @@ test('nav counts issue four bounded requests and drop only the failed count', as
         calls.push([url, options.signal]);
         if (url.startsWith('/prompt_manager/library')) throw new Error('Unavailable');
         if (url.startsWith('/prompt_manager/vocabulary/tags')) return {success: true, total: 5};
+        if (url.startsWith('/prompt_manager/review/items')) return {success: true, total: 2};
         return {success: true, total: 12};
     }};
     const counts = await loadNavCounts(api, signal);
-    assert.deepEqual([...counts], [['images', 12], ['favorites', 12], ['library', null], ['tags', 5]]);
+    assert.deepEqual([...counts], [['images', 12], ['favorites', 12], ['library', null], ['tags', 5], ['review', 2]]);
     const urls = calls.map(([url]) => new URL(url, 'http://host'));
     assert.deepEqual(urls.map(url => url.pathname),
-        ['/prompt_manager/images/output', '/prompt_manager/images/output', '/prompt_manager/library', '/prompt_manager/vocabulary/tags']);
+        ['/prompt_manager/images/output', '/prompt_manager/images/output', '/prompt_manager/library', '/prompt_manager/vocabulary/tags',
+            '/prompt_manager/review/items']);
     for (const url of urls) assert.equal(url.searchParams.get('limit'), '1');
     assert.equal(urls[0].searchParams.get('mode'), 'workspace');
     assert.equal(urls[0].searchParams.has('favorites'), false);
@@ -288,3 +292,22 @@ test('saved-view links resolve to their id and re-render only when the id change
     assert.deepEqual(seen,[['saved',3],['saved',4],['images',undefined]]);
     dispose();
 });
+
+test('Needs review is a native SAVED VIEWS route titled Review, with its own count', async () => {
+    const { resolveRoute, isHandoff, routeTitle, routes, loadNavCounts, REVIEW_WRITE_COUNTS, NAV_COUNT_ROUTES } = await source;
+    const route = resolveRoute('#/review');
+    assert.equal(route.id, 'review');
+    assert.equal(route.label, 'Needs review');
+    assert.equal(routeTitle(route), 'Review');
+    assert.equal(isHandoff(route), false);
+    // No href: Overview lists no legacy card for it.
+    assert.equal(routes.find(item => item.id === 'review').href, undefined);
+    assert.ok(NAV_COUNT_ROUTES.includes('review'));
+    assert.deepEqual([...REVIEW_WRITE_COUNTS], ['review']);
+    assert.ok(Object.isFrozen(REVIEW_WRITE_COUNTS));
+    const calls = [];
+    const api = {get: async url => { calls.push(url); return {success: true, total: 4}; }};
+    const counts = await loadNavCounts(api, new AbortController().signal, () => {}, REVIEW_WRITE_COUNTS);
+    assert.deepEqual(calls, ['/prompt_manager/review/items?limit=1']);
+    assert.deepEqual([...counts], [['review', 4]]);
+});

tests/js/workspace-system-appearance.test.js

@@ -0,0 +1,188 @@
+// System › Appearance (#249 System S3 Task 8): the concept's "Browsing & display" rows (app.js 676–678) on the drafts
+// of the one Save row, their stored values (Q3 mappings), the host timeout's 0–300 whole seconds and the D97 rows.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const gallerySettings = require('../../web/js/gallery-settings.js');
+
+const appearanceModule = import('../../web/js/workspace/system-appearance.mjs');
+const stateModule = import('../../web/js/workspace/system-state.mjs');
+const coreModule = import('../../web/js/shared/toolkit/core.js');
+globalThis.GallerySettings = gallerySettings;
+
+/** A minimal DOM whose elements count their live listeners (a listener's signal aborts it, as in a browser). */
+function fakeDOM() {
+    const previous = global.document;
+    const elements = [];
+    class Element {
+        constructor(tag) {
+            this.tagName = tag.toUpperCase();
+            this.children = [];
+            this.attributes = {};
+            this.listeners = [];
+            this.dataset = {};
+            this.className = '';
+            this.id = '';
+            this.value = '';
+            this._text = '';
+            elements.push(this);
+        }
+        get textContent() { return this._text + this.children.map(child => child.textContent).join(''); }
+        set textContent(text) { this.children = []; this._text = String(text); }
+        append(...nodes) {
+            for (const node of nodes) {
+                const child = typeof node === 'string' ? Object.assign(new Element('#text'), { _text: node }) : node;
+                child.parentNode = this;
+                this.children.push(child);
+            }
+        }
+        remove() { if (this.parentNode) this.parentNode.children = this.parentNode.children.filter(child => child !== this); this.parentNode = null; }
+        replaceChildren(...nodes) { this.children = []; this._text = ''; this.append(...nodes); }
+        setAttribute(name, value) { this.attributes[name] = String(value); }
+        getAttribute(name) { return Object.hasOwn(this.attributes, name) ? this.attributes[name] : null; }
+        removeAttribute(name) { delete this.attributes[name]; }
+        addEventListener(type, callback, options = {}) {
+            if (options.signal?.aborted) return;
+            const entry = { type, callback };
+            this.listeners.push(entry);
+            options.signal?.addEventListener('abort', () => { this.listeners = this.listeners.filter(item => item !== entry); });
+        }
+        removeEventListener(type, callback) { this.listeners = this.listeners.filter(item => item.type !== type || item.callback !== callback); }
+        dispatch(type) { for (const { callback } of this.listeners.filter(item => item.type === type)) callback({ type, target: this }); }
+        click() { this.dispatch('click'); }
+    }
+    global.document = {
+        createElement: tag => new Element(tag),
+        createTextNode: text => Object.assign(new Element('#text'), { _text: String(text) }),
+    };
+    const walk = (node, found = []) => { found.push(node); node.children.forEach(child => walk(child, found)); return found; };
+    return {
+        listenerCount: () => elements.reduce((sum, element) => sum + element.listeners.length, 0),
+        find: (root, predicate) => walk(root).find(predicate),
+        tags: node => node.children.map(child => child.tagName.toLowerCase()),
+        restore() { global.document = previous; },
+    };
+}
+
+const BROWSER = { workspaceLayout: 'grid', workspaceDensity: 'comfortable', autoLoadMetadata: true, cacheMetadata: true,
+    imageQuality: 'medium', videoAutoplay: false, videoMute: true, videoLoop: true, showFilePaths: true, showImageInfo: true,
+    sidebarCollapsedByDefault: false };
+
+async function mounted({ host = { webui_display_mode: 'newtab', result_timeout: 5 }, browser = BROWSER, hostFails = false } = {}) {
+    const { mountAppearance } = await appearanceModule;
+    const { createSystemDrafts } = await stateModule;
+    const { createScope } = await coreModule;
+    const dom = fakeDOM();
+    let hostValues = null;
+    const drafts = createSystemDrafts({
+        readBrowser: () => ({ ...browser }), readRuntime: () => ({}),
+        readHost: async () => { if (hostFails) throw new Error('offline'); return { values: hostValues, revision: 'sha256:one' }; },
+        writeBrowser: async () => ({ persisted: true }), writeHost: async () => ({ success: true, persisted: true }), writeRuntime: async () => ({}),
+    });
+    await drafts.load('browser');
+    const scope = createScope();
+    const [surface] = mountAppearance(null, { scope, drafts });
+    const byId = id => dom.find(surface, node => node.dataset?.setting === id);
+    return { dom, drafts, scope, surface, byId, loadHost: async () => { hostValues = host; await drafts.load('host'); },
+        fixHost: () => { hostFails = false; } };
+}
+
+test('the surface is the concept section with the concept rows in order, then the D97 rows', async () => {
+    const { APPEARANCE_ROWS } = await appearanceModule;
+    const { dom, surface, scope } = await mounted();
+    try {
+        assert.equal(surface.className, 'surface');
+        assert.equal(surface.children[0].textContent, 'Browsing & display');
+        assert.equal(surface.children[1].textContent, 'One set of defaults; toolbar changes apply to the current view.');
+        const rows = surface.children.slice(2);
+        const titles = rows.map(row => row.children[0].children[0].textContent);
+        assert.deepEqual(titles, ['Default layout', 'Thumbnail size', 'Continuous browsing', 'Load metadata on selection',
+            'Cache metadata in this browser', 'Image loading quality', 'Autoplay videos', 'Mute videos by default', 'Loop videos',
+            'Show file paths', 'Open from ComfyUI', 'Node search auto-hide (seconds)', 'Show image details on cards',
+            'Collapse viewer details by default', 'Reset display defaults']);
+        const continuous = rows[2];
+        assert.deepEqual(dom.tags(continuous.children[0]), ['h3', 'p']);
+        assert.equal(continuous.children[1].className, 'chip blue');
+        assert.equal(continuous.children[1].textContent, 'Infinite scroll');
+        assert.equal(rows.at(-1).className, 'operation');
+        assert.equal(APPEARANCE_ROWS.filter(Array.isArray).length, 13);
+    } finally { scope.dispose(); assert.equal(dom.listenerCount(), 0); dom.restore(); }
+});
+
+test('added rows reach their consumers: each control edits its stored key with the Q3 values', async () => {
+    const { dom, drafts, scope, byId, loadHost } = await mounted();
+    try {
+        // Host rows stay disabled until the server settings answered.
+        assert.equal(byId('open-mode').disabled, true);
+        assert.equal(byId('timeout').disabled, true);
+        await loadHost();
+        assert.equal(byId('open-mode').disabled, false);
+        assert.equal(byId('timeout').value, '5');
+        assert.deepEqual(byId('image-quality').children.map(option => [option.value, option.textContent]),
+            [['medium', 'Optimized'], ['high', 'Original'], ['low', 'Fast']]);
+        assert.deepEqual(byId('open-mode').children.map(option => [option.value, option.textContent]),
+            [['newtab', 'New tab'], ['popup', 'Popup window']]);
+        const edits = [['default-view', 'masonry'], ['density', 'large'], ['image-quality', 'low'], ['open-mode', 'popup']];
+        for (const [id, value] of edits) { byId(id).value = value; byId(id).dispatch('change'); }
+        for (const id of ['metadata-auto', 'metadata-cache', 'video-muted', 'video-loop', 'paths', 'card-details']) {
+            byId(id).checked = false; byId(id).dispatch('change');
+        }
+        for (const id of ['video-auto', 'viewer-details']) { byId(id).checked = true; byId(id).dispatch('change'); }
+        assert.deepEqual(drafts.changes('browser'), { workspaceLayout: 'masonry', workspaceDensity: 'large', imageQuality: 'low',
+            autoLoadMetadata: false, cacheMetadata: false, videoMute: false, videoLoop: false, showFilePaths: false, showImageInfo: false,
+            videoAutoplay: true, sidebarCollapsedByDefault: true });
+        assert.deepEqual(drafts.changes('host'), { webui_display_mode: 'popup' });
+    } finally { scope.dispose(); dom.restore(); }
+});
+
+test('the auto-hide timeout takes whole seconds from 0 to 300 only', async () => {
+    const { resultTimeout } = await appearanceModule;
+    assert.deepEqual(['0', '30', ' 300 ', '301', '-1', '2.5', '', 'abc', '1e2'].map(resultTimeout), [0, 30, 300, null, null, null, null, null, null]);
+    const { dom, drafts, scope, byId, loadHost } = await mounted();
+    try {
+        await loadHost();
+        const timeout = byId('timeout');
+        timeout.value = '45'; timeout.dispatch('change');
+        assert.deepEqual(drafts.changes('host'), { result_timeout: 45 });
+        timeout.value = '301'; timeout.dispatch('change');
+        assert.deepEqual(drafts.changes('host'), {});
+        assert.deepEqual([...drafts.failed('host')], ['result_timeout']);
+        timeout.value = '0'; timeout.dispatch('change');
+        assert.deepEqual(drafts.changes('host'), { result_timeout: 0 });
+        assert.deepEqual([...drafts.failed('host')], []);
+    } finally { scope.dispose(); dom.restore(); }
+});
+
+test('reset restores defaults without touching other keys', async () => {
+    const { DISPLAY_KEYS } = await appearanceModule;
+    const changed = { ...BROWSER, workspaceLayout: 'list', videoMute: false, showImageInfo: false, sidebarCollapsedByDefault: true };
+    const { dom, drafts, scope, surface, loadHost } = await mounted({ browser: changed });
+    try {
+        await loadHost();
+        drafts.set('host', 'result_timeout', 9);
+        const reset = dom.find(surface.children.at(-1), node => node.tagName === 'BUTTON');
+        assert.equal(reset.textContent, 'Reset');
+        reset.click();
+        assert.deepEqual(drafts.changes('browser'), { workspaceLayout: 'grid', videoMute: true, showImageInfo: true, sidebarCollapsedByDefault: false });
+        // The host fields and every key outside the display defaults are left as they are.
+        assert.deepEqual(drafts.changes('host'), { result_timeout: 9 });
+        assert.deepEqual([...DISPLAY_KEYS].sort(), Object.keys(BROWSER).sort());
+    } finally { scope.dispose(); dom.restore(); }
+});
+
+test('host rows that could not be read stay disabled and say so; a later read clears it', async () => {
+    const { HOST_UNAVAILABLE } = await appearanceModule;
+    const { dom, drafts, scope, byId, surface, fixHost } = await mounted({ hostFails: true });
+    const notes = () => surface.children.slice(2).flatMap(row => row.children[0].children.slice(2).map(note => [row.children[0].children[0].textContent, note.className, note.textContent]));
+    try {
+        assert.deepEqual(notes(), []);
+        assert.equal(await drafts.reloadHost(), false);
+        assert.deepEqual(notes(), [['Open from ComfyUI', 'small', HOST_UNAVAILABLE], ['Node search auto-hide (seconds)', 'small', HOST_UNAVAILABLE]]);
+        assert.equal(byId('timeout').disabled, true);
+        // Repaints keep one line per row.
+        drafts.set('browser', 'videoMute', false);
+        assert.equal(notes().length, 2);
+        fixHost();
+        assert.equal(await drafts.reloadHost(), true);
+        assert.deepEqual(notes(), []);
+    } finally { scope.dispose(); assert.equal(dom.listenerCount(), 0); dom.restore(); }
+});

tests/js/workspace-system-overview.test.js

@@ -253,3 +253,11 @@ test('waiting stops when its signal aborts', async () => {
     gone.abort(new Error('already'));
     await assert.rejects(waitForJob(fakeActivity(), JOB, { signal: gone.signal }), { message: 'already' });
 });
+
+test('the thumbnail row counts previews that could not be made (#249)', async () => {
+    const { thumbnailTitle } = await overviewModule;
+    assert.equal(thumbnailTitle({ pending: 12, failed: 2 }), '12 missing thumbnails · 2 failed');
+    assert.equal(thumbnailTitle({ pending: 1, failed: 1 }), '1 missing thumbnail · 1 failed');
+    assert.equal(thumbnailTitle({ pending: 0, failed: 0 }), 'No missing thumbnails');
+    assert.equal(thumbnailTitle({ pending: 3, failed: 'x' }), '3 missing thumbnails');
+});

tests/js/workspace-system-sources.test.js

@@ -0,0 +1,159 @@
+// System › Sources & scans (#249 System S4 Task 11): the concept's "Image sources" list (app.js 679–681) built from the
+// server's configured, effective and watched sources (GET /settings), the host draft of `gallery_root_paths`, the
+// 3.2.0 update notice's dismissal and the Refresh files toast (D98).
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const sourcesModule = import('../../web/js/workspace/system-sources.mjs');
+
+const STATUS = Object.freeze({
+    configured: [
+        { label: 'ComfyUI output', path: 'output', valid: true, code: null, reason: null },
+        { label: 'ComfyUI input', path: 'input', valid: true, code: null, reason: null },
+    ],
+    effective: [
+        { label: 'ComfyUI output', path: 'output', root_index: 0, watch: 'watching' },
+        { label: 'ComfyUI input', path: 'input', root_index: 1, watch: 'manual' },
+    ],
+    auto_detected: false,
+});
+
+test('each effective source is the concept row: label, "<path> · watching|manual scan", Scan changes or Scan folder', async () => {
+    const { sourceRows } = await sourcesModule;
+    const saved = ['output', 'input'];
+    const { rows, note } = sourceRows({ sources: STATUS, saved, current: saved });
+    assert.equal(note, null);
+    assert.deepEqual(rows, [
+        { key: 'output', title: 'ComfyUI output', description: 'output · watching', scan: { label: 'Scan changes', root: 0, path: 'output' },
+            remove: 'output' },
+        { key: 'input', title: 'ComfyUI input', description: 'input · manual scan', scan: { label: 'Scan folder', root: 1, path: 'input' },
+            remove: 'input' },
+    ]);
+});
+
+test('watching only with a live observer; restart pending otherwise (D98)', async () => {
+    const { sourceRows, WATCH_COPY } = await sourcesModule;
+    assert.deepEqual(WATCH_COPY, { watching: 'watching', stopping: 'watching until restart', manual: 'manual scan',
+        restart_pending: 'restart pending' });
+    const sources = { ...STATUS, effective: STATUS.effective.map(source => ({ ...source, watch: 'restart_pending' })) };
+    const { rows } = sourceRows({ sources, saved: ['output', 'input'], current: ['output', 'input'] });
+    assert.deepEqual(rows.map(row => [row.description, row.scan.label]),
+        [['output · restart pending', 'Scan folder'], ['input · restart pending', 'Scan folder']]);
+});
+
+test('a configured source that cannot be used shows the server reason and only Remove', async () => {
+    const { sourceRows } = await sourcesModule;
+    const sources = { ...STATUS, configured: [...STATUS.configured,
+        { label: 'unmounted-drive', path: 'unmounted-drive', valid: false, code: 'not-found', reason: 'Gallery root does not exist' }] };
+    const saved = ['output', 'input', 'unmounted-drive'];
+    const { rows } = sourceRows({ sources, saved, current: saved });
+    assert.deepEqual(rows.at(-1), { key: 'unmounted-drive', title: 'unmounted-drive',
+        description: 'unmounted-drive · Gallery root does not exist', scan: null, remove: 'unmounted-drive' });
+});
+
+test('an added source is listed as not saved yet with its validated label; a removed one leaves the list', async () => {
+    const { sourceRows } = await sourcesModule;
+    const labels = new Map([['output/archive', 'archive']]);
+    const { rows, note } = sourceRows({ sources: STATUS, saved: ['output', 'input'], current: ['input', 'output/archive'], labels });
+    assert.equal(note, null);
+    assert.deepEqual(rows.map(row => [row.title, row.description, row.scan?.label ?? null, row.remove]), [
+        ['ComfyUI input', 'input · manual scan', 'Scan folder', 'input'],
+        ['archive', 'output/archive · not saved yet', null, 'output/archive'],
+    ]);
+    // Without a recorded label (a reload of System), the folder name stands in.
+    assert.equal(sourceRows({ sources: STATUS, saved: [], current: ['output/new-collection'] }).rows[0].title, 'new-collection');
+});
+
+test('removing the last entry states auto-detect (D98)', async () => {
+    const { sourceRows, NOTES } = await sourcesModule;
+    const { rows, note } = sourceRows({ sources: STATUS, saved: ['output', 'input'], current: [] });
+    assert.deepEqual(rows, []);
+    assert.equal(note, NOTES.removedAll);
+    assert.equal(NOTES.removedAll, 'No source is configured. After saving, ComfyUI’s output folder is used.');
+});
+
+test('auto-detected sources are listed without Remove and read as the default: "ComfyUI/<path> · <watch> · default"', async () => {
+    const { sourceRows, NOTES } = await sourcesModule;
+    const auto = { configured: [], auto_detected: true,
+        effective: [{ label: 'ComfyUI output', path: 'output', root_index: 0, watch: 'watching', in_comfyui: true }] };
+    // The row says it is the default, so no line under the list repeats it; the scan keeps the server's public path.
+    assert.deepEqual(sourceRows({ sources: auto, saved: [], current: [] }), { rows: [
+        { key: 'auto:0', title: 'ComfyUI output', description: 'ComfyUI/output · watching · default',
+            scan: { label: 'Scan changes', root: 0, path: 'output' }, remove: null },
+    ], note: null });
+    assert.equal('autoDetected' in NOTES, false);
+    // An output folder outside the ComfyUI base (--output-directory) is shown by its own name.
+    const outside = { ...auto, effective: [{ label: 'Renders', path: 'Renders', root_index: 0, watch: 'manual', in_comfyui: false }] };
+    assert.equal(sourceRows({ sources: outside, saved: [], current: [] }).rows[0].description, 'Renders · manual scan · default');
+    // Every configured source unusable: ComfyUI's output folder is used instead, and the line says why.
+    const fallback = { ...auto, configured: [{ label: 'gone', path: 'gone', valid: false, code: 'not-found', reason: 'Gallery root does not exist' }] };
+    const result = sourceRows({ sources: fallback, saved: ['gone'], current: ['gone'] });
+    assert.deepEqual(result.rows.map(row => [row.title, row.description, row.remove]),
+        [['gone', 'gone · Gallery root does not exist', 'gone'], ['ComfyUI output', 'ComfyUI/output · watching · default', null]]);
+    assert.equal(result.note, NOTES.fallback);
+    assert.equal(sourceRows({ sources: { configured: [], effective: [], auto_detected: false }, saved: [], current: [] }).note, NOTES.none);
+});
+
+test('a configured source keeps its plain public path even inside ComfyUI', async () => {
+    const { sourceRows } = await sourcesModule;
+    const sources = { ...STATUS, effective: STATUS.effective.map(source => ({ ...source, in_comfyui: true })) };
+    const { rows } = sourceRows({ sources, saved: ['output', 'input'], current: ['output', 'input'] });
+    assert.deepEqual(rows.map(row => row.description), ['output · watching', 'input · manual scan']);
+});
+
+test('a path listed twice in the draft is one row', async () => {
+    const { sourceRows } = await sourcesModule;
+    assert.equal(sourceRows({ sources: STATUS, saved: ['output', 'input'], current: ['output', 'output'] }).rows.length, 1);
+});
+
+test('roots equal to the saved list are the saved list itself, so the draft is clean again', async () => {
+    const { draftRoots } = await sourcesModule;
+    const saved = ['output', 'input'];
+    assert.equal(draftRoots(['output', 'input'], saved), saved);
+    assert.deepEqual(draftRoots(['input'], saved), ['input']);
+    assert.notEqual(draftRoots(['input', 'output'], saved), saved);
+    assert.deepEqual(draftRoots([], undefined), []);
+});
+
+test('notice Later persists the 3.2.0 dismissal (pm_update_notice_dismissed); storage that throws keeps it for this view', async () => {
+    const { noticeDismissed, dismissNotice, NOTICE_KEY, NOTICE_VERSION } = await sourcesModule;
+    assert.deepEqual([NOTICE_KEY, NOTICE_VERSION], ['pm_update_notice_dismissed', '3.2.0']);
+    const values = new Map();
+    const storage = { getItem: key => values.get(key) ?? null, setItem: (key, value) => values.set(key, String(value)) };
+    assert.equal(noticeDismissed(() => storage), false);
+    values.set(NOTICE_KEY, '3.1.0');
+    assert.equal(noticeDismissed(() => storage), false);
+    assert.equal(dismissNotice(() => storage), true);
+    assert.equal(values.get(NOTICE_KEY), '3.2.0');
+    assert.equal(noticeDismissed(() => storage), true);
+    const denied = () => { throw new Error('SecurityError'); };
+    assert.equal(noticeDismissed(denied), false);
+    assert.equal(dismissNotice(denied), false);
+    assert.equal(dismissNotice(() => ({ setItem() { throw new Error('QuotaExceededError'); } })), false);
+});
+
+test('Refresh files toasts the rescan counts, or says it finished when they are missing', async () => {
+    const { refreshedText } = await sourcesModule;
+    assert.equal(refreshedText({ total: 1234, roots: 2 }), 'Files refreshed. 1,234 files in 2 output folders.');
+    assert.equal(refreshedText({ total: 1, roots: 1 }), 'Files refreshed. 1 file in 1 output folder.');
+    assert.equal(refreshedText({ total: -1, roots: 1 }), 'Files refreshed.');
+    assert.equal(refreshedText(null), 'Files refreshed.');
+});
+
+test('monitoring switched off: a source still watched says so until the restart (D128)', async () => {
+    const { sourceRows } = await sourcesModule;
+    const sources = { ...STATUS, effective: [{ ...STATUS.effective[0], watch: 'stopping' }, STATUS.effective[1]] };
+    const { rows } = sourceRows({ sources, saved: ['output', 'input'], current: ['output', 'input'] });
+    assert.deepEqual(rows.map(row => [row.description, row.scan.label]),
+        [['output · watching until restart', 'Scan changes'], ['input · manual scan', 'Scan folder']]);
+});
+
+test('a valid configured source missing from the effective list is another spelling of a listed folder (D128)', async () => {
+    const { sourceRows, DUPLICATE_SOURCE } = await sourcesModule;
+    assert.equal(DUPLICATE_SOURCE, 'same folder as another source');
+    const sources = { ...STATUS, configured: [...STATUS.configured,
+        { label: 'output', path: 'output/.', valid: true, code: null, reason: null }] };
+    const saved = ['output', 'input', 'output/.'];
+    assert.deepEqual(sourceRows({ sources, saved, current: saved }).rows.at(-1), { key: 'output/.', title: 'output',
+        description: 'output/. · same folder as another source', scan: null, remove: 'output/.' });
+});

tests/js/workspace-system-state.test.js

@@ -192,6 +192,7 @@ test('status text per outcome', async () => {
         partial: 'Some changes were not saved. Review the highlighted settings.',
         tabOnly: 'Saved for this tab only; browser storage is unavailable.',
         conflict: 'Settings changed elsewhere. Reload this section to see them.',
+        restart: 'Restart ComfyUI to apply:',
     });
     const clean = { browser: 'clean', host: 'clean', runtime: 'clean' };
     assert.equal(statusText(clean), 'No unsaved changes.');
@@ -259,3 +260,107 @@ test('a failed read keeps the store usable and drafts survive a reload (Q10)', a
     assert.equal(failing.dirty(), false);
     assert.throws(() => createSystemDrafts({ ...domains, writeHost: null }), TypeError);
 });
+
+test('a rejected value drops its draft and is highlighted; a conflict elsewhere keeps the drafts', async () => {
+    const domains = adapters({ browser: { videoMute: true, videoLoop: true }, host: { result_timeout: 5 } });
+    const drafts = await loaded(domains);
+    assert.deepEqual(drafts.saved('browser'), { videoMute: true, videoLoop: true });
+    drafts.set('host', 'result_timeout', 12);
+    assert.equal(drafts.dirty('host'), true);
+    drafts.reject('host', 'result_timeout');
+    assert.equal(drafts.dirty('host'), false);
+    assert.deepEqual([...drafts.failed('host')], ['result_timeout']);
+    assert.equal(drafts.get('host', 'result_timeout'), 5);
+    // A valid value clears the highlight.
+    drafts.set('host', 'result_timeout', 7);
+    assert.deepEqual([...drafts.failed('host')], []);
+    drafts.discard();
+    drafts.set('browser', 'videoMute', false);
+    drafts.conflict('browser', []);
+    assert.equal(drafts.statusText(), 'Unsaved changes.');
+    drafts.conflict('browser', ['videoMute']);
+    assert.equal(drafts.statusText(), 'Settings changed elsewhere. Reload this section to see them.');
+    assert.deepEqual([...drafts.failed('browser')], ['videoMute']);
+    assert.equal(drafts.get('browser', 'videoMute'), false);
+    assert.throws(() => drafts.reject('nowhere', 'x'), TypeError);
+});
+
+test('a rejected value says why in the status until the next edit', async () => {
+    const drafts = await loaded(adapters({ host: { result_timeout: 5 } }));
+    drafts.reject('host', 'result_timeout');
+    assert.equal(drafts.statusText(), 'Some changes were not saved. Review the highlighted settings.');
+    drafts.set('host', 'result_timeout', 9);
+    assert.equal(drafts.statusText(), 'Unsaved changes.');
+});
+
+test('a browser write refused as changed elsewhere keeps the draft and reads the browser values again', async () => {
+    const domains = adapters({ browser: { workspaceDensity: 'comfortable' } });
+    const drafts = await loaded(domains);
+    drafts.set('browser', 'workspaceDensity', 'compact');
+    domains.outcome.browser = () => { throw Object.assign(new Error('changed'), { code: 'settings-changed' }); };
+    assert.deepEqual(await drafts.save(), { browser: 'conflict', host: 'clean', runtime: 'clean' });
+    assert.deepEqual(domains.calls.map(([name]) => name), ['writeBrowser', 'readBrowser']);
+    assert.equal(drafts.get('browser', 'workspaceDensity'), 'compact');
+    assert.deepEqual([...drafts.failed('browser')], ['workspaceDensity']);
+    assert.equal(drafts.statusText(), 'Settings changed elsewhere. Reload this section to see them.');
+});
+
+test('host read state says whether the server settings could be read', async () => {
+    const { createSystemDrafts } = await source;
+    const domains = adapters({ host: { result_timeout: 5 } });
+    let fail = true;
+    const drafts = createSystemDrafts({ ...domains, readHost: async () => { if (fail) throw new Error('offline'); return { values: {}, revision: 'r' }; } });
+    assert.equal(drafts.hostState(), 'pending');
+    assert.equal(await drafts.reloadHost(), false);
+    assert.equal(drafts.hostState(), 'failed');
+    fail = false;
+    assert.equal(await drafts.reloadHost(), true);
+    assert.equal(drafts.hostState(), 'loaded');
+});
+
+test('a host save names the settings that apply after a restart (D128)', async () => {
+    const { statusText, RESTART_LABELS } = await source;
+    assert.deepEqual(RESTART_LABELS, { monitoring_enabled: 'Watch for new outputs' });
+    const saved = { browser: 'clean', host: 'saved', runtime: 'clean' };
+    assert.equal(statusText({ ...saved, restart: ['monitoring_enabled'] }),
+        'Saved to the server configuration. Restart ComfyUI to apply: Watch for new outputs.');
+    // A field without a row label (the sources say "restart pending" per row) adds nothing.
+    assert.equal(statusText({ ...saved, restart: ['gallery_root_paths'] }), 'Saved to the server configuration.');
+    assert.equal(statusText({ ...saved, restart: [] }), 'Saved to the server configuration.');
+
+    const domains = adapters({ host: { monitoring_enabled: true } });
+    const drafts = await loaded(domains);
+    domains.outcome.host = () => ({ success: true, persisted: true, revision: 'sha256:two',
+        restart_required_fields: ['monitoring_enabled', 7] });
+    drafts.set('host', 'monitoring_enabled', false);
+    assert.deepEqual(await drafts.save(), { browser: 'clean', host: 'saved', runtime: 'clean', restart: ['monitoring_enabled'] });
+    assert.equal(drafts.statusText(), 'Saved to the server configuration. Restart ComfyUI to apply: Watch for new outputs.');
+    // The next edit is unsaved again.
+    drafts.set('host', 'monitoring_enabled', true);
+    assert.equal(drafts.statusText(), 'Unsaved changes.');
+});
+
+test('a host save refused for one source says the server reason and names it until the next edit', async () => {
+    const domains = adapters({ host: { gallery_root_paths: ['output', 'output/gone'] } });
+    const drafts = await loaded(domains);
+    const message = "output/gone can't be used: Gallery root does not exist. Remove it or reconnect it, then save.";
+    domains.outcome.host = () => { throw Object.assign(new Error(message), { code: 'invalid-source', source: 'output/gone' }); };
+    drafts.set('host', 'gallery_root_paths', ['output/gone']);
+    const outcome = await drafts.save();
+    assert.deepEqual(outcome, { browser: 'clean', host: 'failed', runtime: 'clean',
+        invalid: { source: 'output/gone', message } });
+    assert.equal(drafts.statusText(), message);
+    assert.equal(drafts.invalidSource(), 'output/gone');
+    assert.deepEqual([...drafts.failed('host')], ['gallery_root_paths']);
+    // Any other failure keeps the generic copy and names no source.
+    domains.outcome.host = () => { throw Object.assign(new Error('busy'), { code: 'busy' }); };
+    await drafts.save();
+    assert.equal(drafts.statusText(), 'Some changes were not saved. Review the highlighted settings.');
+    assert.equal(drafts.invalidSource(), null);
+    domains.outcome.host = () => { throw Object.assign(new Error(message), { code: 'invalid-source' }); };
+    await drafts.save();
+    assert.equal(drafts.invalidSource(), null);
+    drafts.set('host', 'gallery_root_paths', ['output']);
+    assert.equal(drafts.invalidSource(), null);
+    assert.equal(drafts.statusText(), 'Unsaved changes.');
+});

tests/js/workspace-thumbnail-review.test.js

@@ -0,0 +1,93 @@
+// System › thumbnail review (#249 System S5 Task 14): the concept's "Thumbnail maintenance" dialog (app.js 1433–1437,
+// `thumbnail-review`) on the thumbnail job (S5 Task 12). Pure parts: the option values the job takes, the preview size
+// check, the Image loading quality preselection (Q3), the D99 plan line and the start outcome.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const reviewModule = import('../../web/js/workspace/thumbnail-review.mjs');
+
+test('the concept options map to the job values in the concept order', async () => {
+    const { SCOPE_OPTIONS, QUALITY_OPTIONS, SIZE_LIMIT } = await reviewModule;
+    assert.deepEqual(SCOPE_OPTIONS, [['missing', 'Missing thumbnails only'], ['rebuild', 'Rebuild all (explicit opt-in)']]);
+    assert.deepEqual(QUALITY_OPTIONS, [['medium', 'Medium · optimized'], ['high', 'High · original'], ['low', 'Low · fastest']]);
+    assert.deepEqual(SIZE_LIMIT, { min: 128, max: 2048, value: 512 });
+});
+
+test('size outside 128–2048 reports validity: only whole pixels in range are a size', async () => {
+    const { previewSize } = await reviewModule;
+    assert.equal(previewSize('512'), 512);
+    assert.equal(previewSize('128'), 128);
+    assert.equal(previewSize('2048'), 2048);
+    for (const text of ['', ' ', '127', '2049', '4096', '512.5', '-512', 'abc', '1e3', '0x200']) {
+        assert.equal(previewSize(text), null, text);
+    }
+});
+
+test('Image loading quality preselects the dialog quality (Q3); anything else is Medium', async () => {
+    const { preselectedQuality } = await reviewModule;
+    assert.equal(preselectedQuality('low'), 'low');
+    assert.equal(preselectedQuality('high'), 'high');
+    assert.equal(preselectedQuality('medium'), 'medium');
+    assert.equal(preselectedQuality(undefined), 'medium');
+    assert.equal(preselectedQuality('original'), 'medium');
+});
+
+test('the plan line counts what a missing-only run generates and what is already up to date (D99)', async () => {
+    const { planText } = await reviewModule;
+    assert.equal(planText({ mode: 'missing', targets: 12, fresh: 30, remaining: 0 }), '12 previews to generate · 30 already up to date.');
+    assert.equal(planText({ mode: 'missing', targets: 1, fresh: 1, remaining: 0 }), '1 preview to generate · 1 already up to date.');
+    assert.equal(planText({ mode: 'missing', targets: 0, fresh: 0, remaining: 0 }), '0 previews to generate · 0 already up to date.');
+    assert.equal(planText({ mode: 'missing', targets: 10000, fresh: 5, remaining: 2500 }),
+        '10,000 previews to generate · 5 already up to date · 2,500 more on the next run.');
+});
+
+test('Rebuild all says every preview is regenerated (D99)', async () => {
+    const { planText } = await reviewModule;
+    assert.equal(planText({ mode: 'rebuild', targets: 42, fresh: 30, remaining: 0 }), 'Every preview is regenerated: 42 files.');
+    assert.equal(planText({ mode: 'rebuild', targets: 1, fresh: 1, remaining: 0 }), 'Every preview is regenerated: 1 file.');
+    assert.equal(planText({ mode: 'rebuild', targets: 10000, fresh: 9000, remaining: 3 }),
+        'Every preview is regenerated: 10,000 files · 3 more on the next run.');
+});
+
+test('an answer without counts is a failed plan, never zeros', async () => {
+    const { planText, PLAN_FAILED } = await reviewModule;
+    assert.equal(planText(null), PLAN_FAILED);
+    assert.equal(planText({ mode: 'missing', targets: 2 }), PLAN_FAILED);
+    assert.equal(planText({ mode: 'missing', targets: -1, fresh: 0, remaining: 0 }), PLAN_FAILED);
+    assert.equal(planText({ mode: 'other', targets: 1, fresh: 0, remaining: 0 }), PLAN_FAILED);
+});
+
+const scopeOf = () => ({ signal: new AbortController().signal });
+
+test('Start starts the thumbnail job with the chosen options and opens it in Activity', async () => {
+    const { startThumbnails } = await reviewModule;
+    const calls = [];
+    const navigated = [];
+    const store = { start: async (kind, body) => { calls.push([kind, body]); return { job: { id: 'a'.repeat(32) } }; } };
+    await startThumbnails({ store, scope: scopeOf(), options: { mode: 'rebuild', size: 1024, quality: 'high' },
+        navigate: hash => navigated.push(hash), notify: () => assert.fail('no toast of its own') });
+    assert.deepEqual(calls, [['thumbnails', { mode: 'rebuild', size: 1024, quality: 'high' }]]);
+    assert.deepEqual(navigated, [`#/activity/${'a'.repeat(32)}`]);
+});
+
+test('a refused start shows the busy link toast and stays', async () => {
+    const { startThumbnails } = await reviewModule;
+    const toasts = [];
+    const store = { start: async () => ({ busy: { id: 'b'.repeat(32), title: 'Scan for metadata' } }) };
+    await startThumbnails({ store, scope: scopeOf(), options: { mode: 'missing', size: 512, quality: 'medium' },
+        navigate: () => assert.fail('stays'), notify: message => toasts.push(message) });
+    assert.deepEqual(toasts, [['Another job is running: ', { text: 'Scan for metadata', href: `#/activity/${'b'.repeat(32)}` }, '.']]);
+});
+
+test('a failed start says so; a start after the section left says nothing', async () => {
+    const { startThumbnails, START_FAILED } = await reviewModule;
+    const toasts = [];
+    const store = { start: async () => { throw new Error('offline'); } };
+    await startThumbnails({ store, scope: scopeOf(), options: { mode: 'missing', size: 512, quality: 'medium' },
+        navigate: () => assert.fail('stays'), notify: message => toasts.push(message) });
+    assert.deepEqual(toasts, [START_FAILED]);
+    const gone = new AbortController();
+    gone.abort();
+    await startThumbnails({ store, scope: { signal: gone.signal }, options: { mode: 'missing', size: 512, quality: 'medium' },
+        navigate: () => assert.fail('stays'), notify: () => assert.fail('silent') });
+});

tests/local_resolver_cases.py

@@ -29,6 +29,7 @@ VECTORS_PATH = (
 # Committed record sets stay small; the large bound cases are built at test time.
 MAX_VECTOR_CHARS = 20_000
 COMMITTED_FUZZ = (0, 60)
+COMMITTED_PASSTHROUGH = (0, 40)
 
 SPACES = ["", " ", "\t", "\n", "\x1c", "\x85", "　", "", "
 "]
 WORDS = ["fox", "snow", "café", "猫", "\U0001f600", "a,", "detailed fur", ""]
@@ -1380,6 +1381,7 @@ def committed_vectors():
     }
     cases.update(fuzz_cases(*COMMITTED_FUZZ))
     cases.update(selection.selection_fuzz_cases(*COMMITTED_FUZZ))
+    cases.update(selection.passthrough_fuzz_cases(*COMMITTED_PASSTHROUGH))
     vectors = [
         {
             "name": name,

tests/local_resolver_selection_cases.py

@@ -12,8 +12,10 @@ import json
 import random
 
 try:
+    from tests import passthrough_graphs as shapes
     from tests.local_resolver_cases import EXECUTION_KEY, SPACES, WORDS, _Builder
 except ImportError:  # pragma: no cover - discover -s tests puts tests/ first
+    import passthrough_graphs as shapes
     from local_resolver_cases import EXECUTION_KEY, SPACES, WORDS, _Builder
 
 
@@ -437,10 +439,213 @@ def _parameters():
     return cases
 
 
+def _passthrough():
+    """Chains joined through lineage nodes, and the floor for added conditioning."""
+    cases = {
+        "hires-fix": shapes.hires_fix(),
+        "hires-fix-differs": shapes.hires_fix(second_positive=shapes.OTHER),
+        "hires-fix-unlisted": shapes.hires_fix(filter_class="MysteryImageEffect"),
+        "hires-fix-generated": shapes.generated_text_chain(),
+        "flux-three-stage": shapes.flux_three_stage(),
+        "flux-concat": shapes.flux_three_stage(composite="ConditioningConcat"),
+        "flux-average": shapes.flux_three_stage(composite="ConditioningAverage"),
+        "edit-batch": shapes.edit_batch(3),
+    }
+    graph = shapes.flux_three_stage(combined=(("37", 0), ("31", 0)))
+    graph["37"] = shapes.encode(shapes.OTHER)
+    cases["flux-without-base"] = graph
+    graph = shapes.flux_three_stage()
+    graph["38"] = shapes.encode("watermark")
+    graph["60"]["inputs"]["negative"] = ["38", 0]
+    cases["flux-other-negative"] = graph
+    graph = shapes.hires_fix()
+    graph["20"]["inputs"]["latent_image"] = ["10", 0]
+    graph["10"]["inputs"]["latent_image"] = ["20", 0]
+    cases["hires-fix-cycle"] = graph
+    graph = shapes.hires_fix()
+    graph["17"]["inputs"]["pixels"] = ["18", 0]
+    graph["18"] = {"class_type": "Reroute", "inputs": {"value": ["16", 0]}}
+    cases["hires-fix-reroute"] = graph
+    graph = shapes.hires_fix()
+    graph["24"] = {"class_type": "SaveImage", "inputs": {"images": ["11", 0]}}
+    cases["hires-fix-both-saved"] = graph
+    graph = shapes.hires_fix()
+    graph["20"]["inputs"]["latent_image"] = ["99", 0]
+    cases["hires-fix-missing-latent"] = graph
+    graph = shapes.flux_three_stage()
+    graph["38"] = {"class_type": "MysteryNegative", "inputs": {"seed": 1}}
+    graph["60"]["inputs"]["negative"] = ["38", 0]
+    cases["flux-negative-unsupported"] = graph
+    graph = shapes.flux_three_stage()
+    graph["39"] = {"class_type": "Reroute", "inputs": {"input": ["35", 0]}}
+    graph["60"]["inputs"]["positive"] = ["39", 0]
+    cases["flux-reroute-input"] = graph
+    graph = shapes.flux_three_stage()
+    graph["39"] = {
+        "class_type": "CLIPTextEncodeSDXL",
+        "inputs": {"text_g": shapes.POSITIVE, "text_l": shapes.STYLE},
+    }
+    graph["60"]["inputs"]["positive"] = ["39", 0]
+    cases["flux-encoder-parts"] = graph
+    cases.update(_passthrough_edges())
+    cases.update(_runtime_parts())
+    return cases
+
+
+def _runtime_parts():
+    """Option A: a PromptManager part fed by a run-time node is left out."""
+    cases = {"trigger-prepend": shapes.hires_fix_with_trigger_words()}
+    graph = shapes.hires_fix_with_trigger_words()
+    graph["2"]["inputs"].update(prepend_text="masterpiece", append_text=["8", 0])
+    graph["20"]["inputs"]["latent_image"] = ["4", 0]
+    cases["trigger-append-single"] = graph
+    graph = shapes.hires_fix_with_trigger_words()
+    graph["8"] = {"class_type": "PrimitiveString", "inputs": {"value": "trig9word"}}
+    cases["traced-prepend"] = graph
+    graph = shapes.hires_fix_with_trigger_words()
+    graph["8"]["class_type"] = "MysteryWords"
+    cases["unknown-prepend"] = graph
+    graph = shapes.hires_fix_with_trigger_words()
+    graph["9"] = {
+        "class_type": "StringConcatenate",
+        "inputs": {"string_a": "kept", "string_b": ["8", 0], "delimiter": ""},
+    }
+    graph["2"]["inputs"]["prepend_text"] = ["9", 0]
+    cases["indirect-prepend"] = graph
+    graph = shapes.hires_fix_with_trigger_words()
+    graph["2"]["inputs"].update(prepend_text="", text=["8", 0])
+    cases["runtime-main-text"] = graph
+    graph = shapes.hires_fix_with_trigger_words()
+    graph["2"]["class_type"] = "PromptManagerPair"
+    graph["2"]["inputs"]["negative_text"] = shapes.NEGATIVE
+    graph["10"]["inputs"]["negative"] = ["2", 1]
+    graph["20"]["inputs"]["negative"] = ["2", 1]
+    cases["trigger-pair"] = graph
+    graph = shapes.hires_fix_with_trigger_words()
+    graph["30"] = {"class_type": "PromptSearchList", "inputs": {"search": "x"}}
+    graph["2"]["inputs"]["append_text"] = ["30", 0]
+    cases["search-list-append"] = graph
+    for shape in ("text-encode", "chained", "concat"):
+        cases[f"through-{shape}"] = shapes.trigger_words_through(shape)
+    cases["branches-with-and-without"] = (
+        shapes.branches_with_and_without_trigger_words()
+    )
+    graph = shapes.hires_fix_with_trigger_words()
+    graph["9"] = shapes.prompt_manager(shapes.POSITIVE)
+    graph["20"]["inputs"]["positive"] = ["9", 0]
+    cases["stage-with-and-without"] = graph
+    graph = shapes.hires_fix()
+    graph["9"] = {
+        "class_type": "JoinStringMulti",
+        "inputs": {
+            "inputcount": 2,
+            "delimiter": " ",
+            "return_list": ["98", 0],
+            "string_1": "static words",
+            "string_2": "more",
+        },
+    }
+    graph["98"] = {"class_type": "PrimitiveBoolean", "inputs": {"value": False}}
+    graph["2"]["inputs"]["prepend_text"] = ["9", 0]
+    cases["join-multi-flag"] = graph
+    graph = shapes.flux_three_stage()
+    graph["31"] = shapes.encode(shapes.OTHER)
+    cases["flux-other-full-prompt"] = graph
+    graph = shapes.flux_three_stage()
+    graph["7"] = {
+        "class_type": "Lora Loader (LoraManager)",
+        "inputs": {"model": ["1", 0], "clip": ["2", 0], "text": "x"},
+    }
+    graph["8"] = shapes.trigger_toggle()
+    graph["30"]["inputs"]["prepend_text"] = ["8", 0]
+    cases["flux-trigger"] = graph
+    graph = shapes.flux_three_stage()
+    graph["60"] = {
+        "class_type": "SamplerCustomAdvanced",
+        "inputs": {"guider": ["63", 0], "latent_image": ["66", 0]},
+    }
+    graph["63"] = {
+        "class_type": "CFGGuider",
+        "inputs": {"positive": ["35", 0], "negative": ["33", 0]},
+    }
+    graph["66"] = {"class_type": "VAEEncode", "inputs": {"pixels": ["51", 0]}}
+    graph["67"] = {"class_type": "VAEDecode", "inputs": {"samples": ["60", 0]}}
+    graph["61"]["inputs"]["images"] = ["67", 0]
+    cases["flux-custom-advanced-chained"] = graph
+    return {f"runtime-{name}": graph for name, graph in cases.items()}
+
+
+def _passthrough_edges():
+    """Lineage and floor edges: branching refiners, other slots, cycles, guiders."""
+    cases = {}
+    graph = shapes.hires_fix()
+    graph["30"] = shapes.ksampler(["2", 0], ["3", 0], ["17", 0], denoise=0.4)
+    graph["31"] = {"class_type": "SaveImage", "inputs": {"images": ["30", 0]}}
+    cases["hires-fix-two-refiners"] = graph
+    graph = shapes.hires_fix()
+    graph["10"]["class_type"] = "SamplerCustom"
+    graph["11"]["inputs"]["samples"] = ["10", 1]
+    cases["hires-fix-denoised-slot"] = graph
+    graph = shapes.hires_fix()
+    graph["30"] = shapes.ksampler(["2", 0], ["3", 0], ["4", 0])
+    graph["31"] = {"class_type": "VAEDecode", "inputs": {"samples": ["30", 0]}}
+    graph["32"] = {"class_type": "VAEEncode", "inputs": {"pixels": ["31", 0]}}
+    graph["30"]["inputs"]["latent_image"] = ["32", 0]
+    cases["hires-fix-self-latent"] = graph
+    graph = shapes.hires_fix()
+    graph["30"] = shapes.ksampler(["2", 0], ["3", 0], ["32", 0])
+    graph["31"] = {"class_type": "VAEDecode", "inputs": {"samples": ["32", 0]}}
+    graph["32"] = {"class_type": "VAEEncode", "inputs": {"pixels": ["31", 0]}}
+    graph["33"] = {"class_type": "SaveImage", "inputs": {"images": ["30", 0]}}
+    cases["hires-fix-lineage-cycle"] = graph
+    graph = shapes.flux_three_stage()
+    graph["39"] = shapes.encode(shapes.OTHER)
+    graph["40"]["inputs"]["positive"] = ["39", 0]
+    cases["flux-base-stages-differ"] = graph
+    graph = shapes.flux_three_stage()
+    del graph["60"]["inputs"]["negative"]
+    cases["flux-no-last-negative"] = graph
+    graph = shapes.flux_three_stage()
+    graph["39"] = {"class_type": "MysteryPrompt", "inputs": {"seed": 1}}
+    graph["40"]["inputs"]["positive"] = ["39", 0]
+    graph["50"]["inputs"]["positive"] = ["39", 0]
+    cases["flux-unreadable-base"] = graph
+    graph = shapes.flux_three_stage()
+    graph["39"] = {
+        "class_type": "MysteryUpscaler",
+        "inputs": {"image": ["51", 0], "model": ["1", 0], "positive": ["34", 0]},
+    }
+    graph["52"]["inputs"]["images"] = ["39", 0]
+    cases["flux-unsupported-ancestry"] = graph
+    graph = shapes.flux_three_stage()
+    graph["60"] = {
+        "class_type": "SamplerCustomAdvanced",
+        "inputs": {
+            "noise": ["62", 0],
+            "guider": ["63", 0],
+            "sampler": ["64", 0],
+            "sigmas": ["65", 0],
+            "latent_image": ["66", 0],
+        },
+    }
+    graph["62"] = {"class_type": "RandomNoise", "inputs": {"noise_seed": 1}}
+    graph["63"] = {
+        "class_type": "CFGGuider",
+        "inputs": {"model": ["1", 0], "positive": ["35", 0], "negative": ["33", 0]},
+    }
+    graph["64"] = {"class_type": "KSamplerSelect", "inputs": {"sampler_name": "euler"}}
+    graph["65"] = {"class_type": "BasicScheduler", "inputs": {"steps": 4}}
+    graph["66"] = {"class_type": "VAEEncode", "inputs": {"pixels": ["52", 0]}}
+    graph["67"] = {"class_type": "VAEDecode", "inputs": {"samples": ["60", 0]}}
+    graph["61"]["inputs"]["images"] = ["67", 0]
+    cases["flux-custom-advanced-last"] = graph
+    return {f"edge-{name}": graph for name, graph in cases.items()}
+
+
 def selection_cases():
     """Named record sets for every Task 9 path, each a ``read_inspection_file`` dict."""
     cases = {}
-    for group in (_samplers(), _previews(), _detailers()):
+    for group in (_samplers(), _previews(), _detailers(), _passthrough()):
         for name, graph in group.items():
             cases[f"select-{name}"] = {"prompt": json.dumps(graph, ensure_ascii=False)}
     cases.update(_parameters())
@@ -572,3 +777,101 @@ def selection_fuzz_cases(seed, count):
         records.update(builder.records)
         cases[f"select-fuzz-{seed}-{index}"] = records
     return cases
+
+
+_LINEAGE_HOPS = (
+    ("VAEDecode", "samples"),
+    ("VAEDecodeTiled", "samples"),
+    ("Image Filter", "images"),
+    ("ImageUpscaleWithModel", "image"),
+    ("ImageScale", "image"),
+    ("ImageScaleBy", "image"),
+    ("VAEEncode", "pixels"),
+    ("LatentUpscaleBy", "samples"),
+    ("Reroute", "value"),
+    ("MysteryImageEffect", "image"),
+)
+
+
+def passthrough_fuzz_cases(seed, count):
+    """Seeded sampler chains joined by random lineage (and unlisted) hops.
+
+    Each later stage reads the earlier one's output through zero to four hops,
+    with a shared, a different, an added-to (combine, concat, average) or a
+    run-time positive, and a shared or different negative, under a saver or a
+    preview. The server is the oracle; nothing states the expected answer.
+    """
+    rng = random.Random(seed)
+    cases = {}
+    for index in range(count):
+        graph = {
+            "1": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": "m"}},
+            "2": shapes.prompt_manager(rng.choice([shapes.POSITIVE, "fox"])),
+            "3": shapes.encode(shapes.NEGATIVE),
+            "4": {"class_type": "EmptyLatentBatch", "inputs": {"batch_size": 2}},
+            "5": shapes.encode(shapes.STYLE),
+            "6": shapes.encode(shapes.OTHER),
+        }
+        previous, next_id = ["4", 0], 10
+        for stage in range(rng.randint(2, 3)):
+            positive = ["2", 0]
+            choice = rng.randrange(8)
+            if stage and choice == 1:
+                positive = ["6", 0]
+            elif stage and choice in (2, 3, 4):
+                name = (
+                    "ConditioningCombine",
+                    "ConditioningConcat",
+                    "ConditioningAverage",
+                )[choice - 2]
+                names = shapes._COMPOSITE_INPUTS[name]
+                parts = [["2", 0], rng.choice([["5", 0], ["6", 0]])]
+                rng.shuffle(parts)
+                graph[str(next_id)] = {
+                    "class_type": name,
+                    "inputs": dict(zip(names, parts)),
+                }
+                positive, next_id = [str(next_id), 0], next_id + 1
+            elif stage and choice == 5:
+                graph[str(next_id)] = {
+                    "class_type": "FluxGuidance",
+                    "inputs": {"guidance": 3.5, "conditioning": ["2", 0]},
+                }
+                positive, next_id = [str(next_id), 0], next_id + 1
+            negative = ["6", 0] if stage and rng.random() < 0.15 else ["3", 0]
+            latent = previous
+            if stage:
+                image = previous
+                for _ in range(rng.randrange(5)):
+                    name, key = rng.choice(_LINEAGE_HOPS)
+                    graph[str(next_id)] = {"class_type": name, "inputs": {key: image}}
+                    image, next_id = [str(next_id), 0], next_id + 1
+                latent = image
+            sampler = shapes.ksampler(positive, negative, latent)
+            if stage and rng.random() < 0.2:
+                sampler = {
+                    "class_type": "UltimateSDUpscale",
+                    "inputs": {
+                        "image": latent,
+                        "model": ["1", 0],
+                        "positive": positive,
+                        "negative": negative,
+                    },
+                }
+            graph[str(next_id)] = sampler
+            previous, next_id = [str(next_id), 0], next_id + 1
+            if rng.random() < 0.3:
+                saver = rng.choice(["SaveImage", "PreviewImage"])
+                graph[str(next_id)] = {
+                    "class_type": saver,
+                    "inputs": {"images": previous},
+                }
+                next_id += 1
+        graph[str(next_id)] = {
+            "class_type": "SaveImage",
+            "inputs": {"images": previous},
+        }
+        cases[f"select-passthrough-fuzz-{seed}-{index}"] = {
+            "prompt": json.dumps(graph, ensure_ascii=False)
+        }
+    return cases

tests/passthrough_graphs.py

@@ -0,0 +1,332 @@
+"""Synthetic multi-stage graphs for the pass-through lineage rule.
+
+Each builder reproduces one graph shape with neutral texts and generic names:
+a hires-fix or refiner chain (sampler, decode, image filter, model upscale,
+scale, encode, sampler), a three-stage Flux run whose last stage combines the
+base prompt with a style trigger, an image-edit batch of samplers with distinct
+prompts, and a chain whose prompt is generated at run time. They are shared by
+the resolver tests and the browser-port parity cases; no user file is involved.
+"""
+
+import copy
+
+POSITIVE = "a lighthouse on a cliff, golden hour"
+NEGATIVE = "blurry, lowres"
+OTHER = "a red bicycle in the rain"
+STYLE = "film grain, analog photo"
+
+
+def encode(text):
+    return {"class_type": "CLIPTextEncode", "inputs": {"text": text, "clip": ["1", 1]}}
+
+
+def prompt_manager(text, prepend=""):
+    return {
+        "class_type": "PromptManager",
+        "inputs": {
+            "text": text,
+            "category": "",
+            "tags": "",
+            "search_text": "",
+            "prepend_text": prepend,
+            "append_text": "",
+            "clip": ["1", 1],
+        },
+    }
+
+
+def ksampler(positive, negative, latent, denoise=1.0):
+    return {
+        "class_type": "KSampler",
+        "inputs": {
+            "seed": 7,
+            "steps": 20,
+            "cfg": 7.0,
+            "sampler_name": "euler",
+            "scheduler": "normal",
+            "denoise": denoise,
+            "model": ["1", 0],
+            "positive": positive,
+            "negative": negative,
+            "latent_image": latent,
+        },
+    }
+
+
+def hires_fix(second_positive=None, filter_class="Image Filter"):
+    """Two KSamplers joined in image space, like a hires-fix or refiner run.
+
+    Sampler 10 runs on a custom batch latent; its output goes through a tiled
+    decode, an interactive image filter, a model upscale and a scale (sized by a
+    resolution node reading the filtered image), then is encoded again for
+    sampler 20 (denoise 0.25), which is decoded and saved.
+    """
+    graph = {
+        "1": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": "m"}},
+        "2": prompt_manager(POSITIVE),
+        "3": encode(NEGATIVE),
+        "4": {
+            "class_type": "EmptyLatentBatch",
+            "inputs": {"width": 1024, "height": 512, "batch_size": 4},
+        },
+        "10": ksampler(["2", 0], ["3", 0], ["4", 0]),
+        "11": {
+            "class_type": "VAEDecodeTiled",
+            "inputs": {"tile_size": 512, "samples": ["10", 0], "vae": ["1", 2]},
+        },
+        "12": {
+            "class_type": filter_class,
+            "inputs": {"timeout": 600, "ontimeout": "send none", "images": ["11", 0]},
+        },
+        "13": {"class_type": "UpscaleModelLoader", "inputs": {"model_name": "x4"}},
+        "14": {
+            "class_type": "ImageUpscaleWithModel",
+            "inputs": {"upscale_model": ["13", 0], "image": ["12", 0]},
+        },
+        "15": {
+            "class_type": "ResolutionCalculator",
+            "inputs": {"scale_factor": 1.5, "image": ["12", 0]},
+        },
+        "16": {
+            "class_type": "ImageScale",
+            "inputs": {
+                "upscale_method": "nearest-exact",
+                "width": ["15", 0],
+                "height": ["15", 1],
+                "crop": "disabled",
+                "image": ["14", 0],
+            },
+        },
+        "17": {
+            "class_type": "VAEEncode",
+            "inputs": {"pixels": ["16", 0], "vae": ["1", 2]},
+        },
+        "20": ksampler(["2", 0], ["3", 0], ["17", 0], denoise=0.25),
+        "21": {
+            "class_type": "VAEDecodeTiled",
+            "inputs": {"tile_size": 512, "samples": ["20", 0], "vae": ["1", 2]},
+        },
+        "22": {
+            "class_type": "SaveImage",
+            "inputs": {"filename_prefix": "hires", "images": ["21", 0]},
+        },
+        "23": {"class_type": "PlaySound|pysssss", "inputs": {"any": ["21", 0]}},
+    }
+    if second_positive is not None:
+        graph["5"] = encode(second_positive)
+        graph["20"]["inputs"]["positive"] = ["5", 0]
+    return graph
+
+
+_COMPOSITE_INPUTS = {
+    "ConditioningCombine": ("conditioning_1", "conditioning_2"),
+    "ConditioningConcat": ("conditioning_to", "conditioning_from"),
+    "ConditioningAverage": ("conditioning_to", "conditioning_from"),
+}
+
+
+def flux_three_stage(combined=(("30", 0), ("31", 0)), composite="ConditioningCombine"):
+    """FluxGuidance base, a refiner through an image filter, then a tiled upscale.
+
+    Samplers 40 and 50 share FluxGuidance(PromptManager 30) and a zeroed empty
+    negative. Sampler 50 refines 40's filtered image (denoise 0.25). The final
+    UltimateSDUpscale 60 reads 50's image, scaled down, and a positive that is
+    ``composite`` of ``combined`` (by default the base PromptManager and a
+    style-trigger encoder 31).
+    """
+    names = _COMPOSITE_INPUTS[composite]
+    graph = {
+        "1": {"class_type": "UNETLoader", "inputs": {"unet_name": "flux"}},
+        "2": {"class_type": "DualCLIPLoader", "inputs": {"type": "flux"}},
+        "3": {"class_type": "VAELoader", "inputs": {"vae_name": "ae"}},
+        "30": prompt_manager(POSITIVE),
+        "31": encode(STYLE),
+        "32": {
+            "class_type": "CLIPTextEncode",
+            "inputs": {"text": "", "clip": ["2", 0]},
+        },
+        "33": {
+            "class_type": "ConditioningZeroOut",
+            "inputs": {"conditioning": ["32", 0]},
+        },
+        "34": {
+            "class_type": "FluxGuidance",
+            "inputs": {"guidance": 3.5, "conditioning": ["30", 0]},
+        },
+        "35": {
+            "class_type": composite,
+            "inputs": dict(zip(names, map(list, combined))),
+        },
+        "36": {
+            "class_type": "EmptyLatentBatch",
+            "inputs": {"width": 1080, "height": 1920, "batch_size": 4},
+        },
+        "40": ksampler(["34", 0], ["33", 0], ["36", 0]),
+        "41": {
+            "class_type": "VAEDecode",
+            "inputs": {"samples": ["40", 0], "vae": ["3", 0]},
+        },
+        "42": {
+            "class_type": "Image Filter",
+            "inputs": {"timeout": 600, "images": ["41", 0]},
+        },
+        "43": {"class_type": "PreviewImage", "inputs": {"images": ["42", 0]}},
+        "44": {
+            "class_type": "VAEEncode",
+            "inputs": {"pixels": ["42", 0], "vae": ["3", 0]},
+        },
+        "50": ksampler(["34", 0], ["33", 0], ["44", 0], denoise=0.25),
+        "51": {
+            "class_type": "VAEDecode",
+            "inputs": {"samples": ["50", 0], "vae": ["3", 0]},
+        },
+        "52": {
+            "class_type": "ImageScaleDownBy",
+            "inputs": {"scale_by": 0.75, "images": ["51", 0]},
+        },
+        "53": {"class_type": "PreviewImage", "inputs": {"images": ["51", 0]}},
+        "54": {
+            "class_type": "Image Comparer (rgthree)",
+            "inputs": {"image_a": ["51", 0], "image_b": ["42", 0]},
+        },
+        "60": {
+            "class_type": "UltimateSDUpscale",
+            "inputs": {
+                "upscale_by": 2.0,
+                "seed": 7,
+                "steps": 4,
+                "denoise": 0.35,
+                "image": ["52", 0],
+                "model": ["1", 0],
+                "positive": ["35", 0],
+                "negative": ["33", 0],
+                "vae": ["3", 0],
+            },
+        },
+        "61": {
+            "class_type": "SaveImage",
+            "inputs": {"filename_prefix": "flux", "images": ["60", 0]},
+        },
+    }
+    return graph
+
+
+def edit_batch(count=3):
+    """Image-edit samplers with distinct prompts, all saved with one prefix."""
+    graph = {
+        "1": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": "m"}},
+        "2": {"class_type": "LoadImage", "inputs": {"image": "ref.png"}},
+        "3": {
+            "class_type": "VAEEncode",
+            "inputs": {"pixels": ["2", 0], "vae": ["1", 2]},
+        },
+        "4": {"class_type": "PrimitiveString", "inputs": {"value": "edit"}},
+    }
+    for index in range(count):
+        base = 100 + index * 10
+        graph[str(base)] = {
+            "class_type": "TextEncodeQwenImageEdit",
+            "inputs": {
+                "prompt": f"edit number {index}: change the pose",
+                "clip": ["1", 1],
+            },
+        }
+        graph[str(base + 1)] = ksampler([str(base), 0], [str(base), 0], ["3", 0])
+        graph[str(base + 2)] = {
+            "class_type": "VAEDecode",
+            "inputs": {"samples": [str(base + 1), 0], "vae": ["1", 2]},
+        }
+        graph[str(base + 3)] = {
+            "class_type": "SaveImage",
+            "inputs": {"filename_prefix": ["4", 0], "images": [str(base + 2), 0]},
+        }
+    return graph
+
+
+def trigger_toggle(words="trig9word"):
+    """LoraManager's TriggerWord Toggle: its output is decided at run time."""
+    return {
+        "class_type": "TriggerWord Toggle (LoraManager)",
+        "inputs": {
+            "group_mode": True,
+            "default_active": True,
+            "toggle_trigger_words": {"__value__": [{"text": words, "active": True}]},
+            "orinalMessage": words,
+            "trigger_words": ["7", 2],
+        },
+    }
+
+
+def hires_fix_with_trigger_words():
+    """``hires_fix`` whose PromptManager prepends LoRA trigger words (node 8)."""
+    graph = hires_fix()
+    graph["7"] = {
+        "class_type": "Lora Loader (LoraManager)",
+        "inputs": {"model": ["1", 0], "clip": ["1", 1], "text": "<lora:x:1>"},
+    }
+    graph["8"] = trigger_toggle()
+    graph["2"]["inputs"]["prepend_text"] = ["8", 0]
+    return graph
+
+
+def prompt_manager_text(text, prepend=""):
+    """PromptManagerText: a STRING PromptManager (prepend/main/append)."""
+    return {
+        "class_type": "PromptManagerText",
+        "inputs": {
+            "text": text,
+            "category": "",
+            "tags": "",
+            "search_text": "",
+            "prepend_text": prepend,
+            "append_text": "",
+        },
+    }
+
+
+def trigger_words_through(shape):
+    """``hires_fix_with_trigger_words`` with nodes between the toggle and sampler.
+
+    ``text-encode``: PromptManagerText (prepend <- toggle) -> CLIPTextEncode.
+    ``chained``: a PromptManager whose ``text`` reads that PromptManagerText.
+    ``concat``: PromptManagerText -> StringConcatenate(..., "extra") -> encoder.
+    """
+    graph = hires_fix_with_trigger_words()
+    graph["9"] = prompt_manager_text(POSITIVE, ["8", 0])
+    if shape == "chained":
+        graph["2"]["inputs"].update(prepend_text="", text=["9", 0])
+    elif shape == "text-encode":
+        graph["2"] = {"class_type": "CLIPTextEncode", "inputs": {"text": ["9", 0]}}
+    else:
+        graph["19"] = {
+            "class_type": "StringConcatenate",
+            "inputs": {"string_a": ["9", 0], "string_b": "extra", "delimiter": ", "},
+        }
+        graph["2"] = {"class_type": "CLIPTextEncode", "inputs": {"text": ["19", 0]}}
+    return graph
+
+
+def branches_with_and_without_trigger_words():
+    """Two saved branches: one PromptManager prepends trigger words, one does not."""
+    graph = hires_fix_with_trigger_words()
+    graph["9"] = prompt_manager(POSITIVE)
+    graph["20"]["inputs"].update(positive=["9", 0], latent_image=["4", 0])
+    return graph
+
+
+def generated_text_chain():
+    """``hires_fix`` whose positive text comes from a run-time text generator."""
+    graph = hires_fix()
+    graph["2"] = {
+        "class_type": "CLIPTextEncode",
+        "inputs": {"text": ["6", 0], "clip": ["1", 1]},
+    }
+    graph["6"] = {
+        "class_type": "TextGenerate",
+        "inputs": {"prompt": "write a prompt", "model": ["1", 0]},
+    }
+    return graph
+
+
+def copied(graph):
+    return copy.deepcopy(graph)

tests/test_annotation_schema.py

@@ -30,6 +30,11 @@ FILES = "media_annotation_files"
 BYTES = "media_annotation_bytes"
 IMAGE_TAGS = "media_image_tags"
 TABLES = (METADATA, FILES, BYTES, IMAGE_TAGS)
+REVIEW_TABLES = (
+    "media_review_decisions",
+    "media_review_items",
+    "media_review_metadata",
+)
 # The exact DDL the plan pins; the module must produce precisely these objects.
 DDL = {
     METADATA: (
@@ -202,10 +207,14 @@ class AnnotationSchemaTests(unittest.TestCase):
         )
 
     def drop_group(self, path):
-        """Remove the group from a closed database file (an old backup)."""
+        """Remove the group from a closed database file (an old backup).
+
+        The review queue group cites annotation bytes and predates nothing, so
+        an old backup lacks it as well.
+        """
         with closing(sqlite3.connect(path)) as raw, raw:
             raw.execute("PRAGMA foreign_keys=OFF")
-            for table in reversed(TABLES):
+            for table in REVIEW_TABLES + tuple(reversed(TABLES)):
                 raw.execute(f"DROP TABLE {table}")
 
     def test_fresh_install_and_reopen_is_idempotent(self):

tests/test_api_admin.py

@@ -52,6 +52,7 @@ class AdminAPITestCase(AioHTTPTestCase):
         self.outside_dir = Path(self.tmpdir) / "outside"
         self.outside_dir.mkdir()
 
+        self.addAsyncCleanup(self._drain_and_remove)
         self.config_path = os.path.join(self.tmpdir, "config.json")
         self._orig_env = {
             key: os.environ.pop(key, None) for key in (CONFIG_PATH_ENV, EXTRA_ROOTS_ENV)
@@ -78,6 +79,8 @@ class AdminAPITestCase(AioHTTPTestCase):
 
     async def tearDownAsync(self):
         await super().tearDownAsync()  # closes the aiohttp test client
+        # The automatic preview worker writes into the temp tree: stop it first.
+        self.api.close_auto_thumbnails()
         GalleryConfig.MONITORING_DIRECTORIES = self._orig_gallery_dirs
         PromptManagerConfig.update_config(self._orig_pm_config)
         for key, value in self._orig_env.items():
@@ -89,6 +92,26 @@ class AdminAPITestCase(AioHTTPTestCase):
             sys.modules.pop("folder_paths", None)
         else:
             sys.modules["folder_paths"] = self._orig_folder_paths
+
+    async def _drain_and_remove(self):
+        """The last cleanup: no job outlives the temporary database.
+
+        Registered first, so it runs after every cleanup a test added (which
+        may release its own gated jobs). A job still running then, such as a
+        scan a failed assertion never awaited, is cancelled and awaited
+        before the database and the tree are removed.
+        """
+        api = getattr(self, "api", None)
+        jobs = api._jobs.list() if api is not None else []
+        tasks = [
+            job.task for job in jobs if job.task is not None and not job.task.done()
+        ]
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        if api is not None:
+            # A scan of an ambiguous file captures it for Needs review.
+            api.close_annotation_captures()
         PromptModel.close_all_instances()  # restore may have swapped api.db
         assert_closed(self, self.tmpdir)
         shutil.rmtree(self.tmpdir, ignore_errors=True)
@@ -2221,7 +2244,14 @@ class TestActivityJobs(AdminAPITestCase):
         for name in names:
             (self.output_dir / name).write_bytes(b"not an image")
 
-        def fake_ingest(media_file, metadata, detailed=False):
+        def fake_ingest(
+            media_file,
+            metadata,
+            detailed=False,
+            ambiguous=None,
+            untraced=None,
+            records=None,
+        ):
             key = Path(media_file).relative_to(self.output_dir).as_posix()
             outcome = names[key]
             if isinstance(outcome, Exception):
@@ -2350,8 +2380,10 @@ class TestActivityJobs(AdminAPITestCase):
         first_done, release = threading.Event(), threading.Event()
         original = self.api._ingest_scan_batch_sync
 
-        def gated(batch_results, roots=(), outcomes=None):
-            counts = original(batch_results, roots=roots, outcomes=outcomes)
+        def gated(batch_results, roots=(), outcomes=None, review=None):
+            counts = original(
+                batch_results, roots=roots, outcomes=outcomes, review=review
+            )
             first_done.set()
             release.wait(5)
             return counts

tests/test_api_annotations.py

@@ -1045,7 +1045,15 @@ class TestFailures(AnnotationAPITestCase):
         await self.api.cleanup_annotation_captures(None)
         self.assertFalse(os.path.exists(directory))
         self.assertNotIn(identity, observers._restore_observers)
-        # A later observation starts a fresh store.
+        # The shutdown cleanup is final: a later observation (or a monitor
+        # recording still in flight) creates no new store or directory.
+        status, body = await self.observe({"target": self.target("sub/a.png")})
+        self.assertEqual((status, body["code"]), (500, "capture-error"), body)
+        self.assertIsNone(self.api._captures)
+        self.assertNotIn(identity, observers._restore_observers)
+        # An explicit, non-final close still lets a later observation start
+        # a fresh store (the tests' own store swaps rely on it).
+        self.api._captures_closed = False
         await self.observe_ok()
         self.assertNotEqual(self.api._captures.directory, directory)
 

tests/test_api_autotag.py

@@ -131,6 +131,8 @@ class AutotagAPITestCase(AioHTTPTestCase):
 
     async def tearDownAsync(self):
         await super().tearDownAsync()  # closes the aiohttp test client
+        # The automatic preview worker writes into the temp tree: stop it first.
+        self.api.close_auto_thumbnails()
         self._service_patch.stop()
         if model_gate is not None:
             leaked = model_gate.holder()

tests/test_api_backup_restore.py

@@ -47,11 +47,13 @@ def _texts(path):
 
 
 class BackupRestoreTestCase(AioHTTPTestCase):
+    app_options = {}
+
     async def get_application(self):
         self.tmpdir = tempfile.mkdtemp()
         self.db_path = os.path.join(self.tmpdir, "prompts.db")
 
-        app = web.Application()
+        app = web.Application(**self.app_options)
         routes = web.RouteTableDef()
         self.api = PromptManagerAPI(db=PromptDatabase(self.db_path))
         self.api.add_routes(routes)
@@ -60,6 +62,8 @@ class BackupRestoreTestCase(AioHTTPTestCase):
 
     async def tearDownAsync(self):
         await super().tearDownAsync()  # closes the aiohttp test client
+        # The automatic preview worker writes into the temp tree: stop it first.
+        self.api.close_auto_thumbnails()
         PromptModel.close_all_instances()  # restore may have swapped api.db
         assert_closed(self, self.tmpdir)
         for name in os.listdir(self.tmpdir):
@@ -327,6 +331,15 @@ class TestRestoreRoute(BackupRestoreTestCase):
         self.assertIn("too large", data["error"].lower())
         self.assertEqual([p["text"] for p in self.api.db.search_prompts()], ["keep me"])
 
+    async def test_restore_cap_keeps_the_legacy_shape(self):
+        self.api.restore_max_bytes = 1024
+        upload = self._write("big.db", b"SQLite format 3\x00" + b"\x00" * 8192)
+        resp = await self._restore(upload)
+        data = await resp.json()
+        self.assertEqual(resp.status, 400)
+        self.assertEqual(data["code"], "too-large")
+        self.assertNotIn(self.tmpdir, data["error"])
+
     async def test_non_multipart_request_is_rejected(self):
         resp = await self.client.post("/prompt_manager/restore", data=b"raw bytes")
         self.assertIn(resp.status, (400, 500))
@@ -336,3 +349,132 @@ class TestRestoreRoute(BackupRestoreTestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+MIB = 2**20
+
+
+class TestLargeRestores(BackupRestoreTestCase):
+    """A real library's backup restores: room on disk decides, not 100 MB."""
+
+    # As ComfyUI builds its app: client_max_size is --max-upload-size (100
+    # MB by default). The restore streams with read_chunk, which it does not
+    # cap.
+    app_options = {"client_max_size": 100 * 2**20}
+
+    def _large_db_file(self, texts, pad_bytes):
+        path = self._make_db_file(texts, name="large.db")
+        conn = sqlite3.connect(path)
+        try:
+            conn.execute("CREATE TABLE padding(b BLOB)")
+            conn.execute("INSERT INTO padding VALUES (zeroblob(?))", (pad_bytes,))
+            conn.commit()
+        finally:
+            conn.close()
+        return path
+
+    async def _stream_restore(self, path, chunked=False):
+        with open(path, "rb") as fh:
+            data = fh.read()
+        form = aiohttp.FormData()
+        form.add_field(
+            "database_file",
+            data,
+            filename=os.path.basename(path),
+            content_type="application/octet-stream",
+        )
+        # chunked=False must not be passed: aiohttp 3.14 then frames the body
+        # as chunked while also sending a Content-Length.
+        options = {"chunked": True} if chunked else {}
+        return await self.client.post("/prompt_manager/restore", data=form, **options)
+
+    def _spy_uploads(self):
+        """Patch the upload's mkstemp; the list collects each temp path made."""
+        created = []
+        real_mkstemp = tempfile.mkstemp
+
+        def spy(*args, **kwargs):
+            result = real_mkstemp(*args, **kwargs)
+            created.append(result[1])
+            return result
+
+        return patch("py.api.admin.tempfile.mkstemp", spy), created
+
+    def _assert_removed(self, created):
+        for path in created:
+            for suffix in ("", "-wal", "-shm", "-journal"):
+                self.assertFalse(os.path.exists(path + suffix), path + suffix)
+
+    async def test_a_150_mb_backup_restores(self):
+        self._save("before")
+        upload = self._large_db_file(["restored"], 150 * MIB)
+        self.assertGreater(os.path.getsize(upload), 150 * MIB)
+        spy, created = self._spy_uploads()
+        with spy:
+            resp = await self._stream_restore(upload)
+        data = await resp.json()
+        self.assertEqual(resp.status, 200, data)
+        self.assertEqual(
+            [p["text"] for p in self.api.db.search_prompts()], ["restored"]
+        )
+        self.assertEqual(len(created), 1)
+        self._assert_removed(created)
+
+    async def test_a_short_disk_is_refused_up_front(self):
+        from py.api import maintenance
+
+        self._save("keep me")
+        upload = self._make_db_file(["restored"])
+        spy, created = self._spy_uploads()
+        with spy, patch.object(maintenance, "_free_bytes", return_value=MIB):
+            resp = await self._restore(upload)
+        data = await resp.json()
+        self.assertEqual(resp.status, 507)
+        self.assertEqual(data["code"], "insufficient-space")
+        self.assertTrue(
+            data["error"].startswith("Not enough free disk space to restore a "),
+            data["error"],
+        )
+        self.assertTrue(data["error"].endswith("Nothing was changed."))
+        self.assertNotIn(self.tmpdir, data["error"])
+        self.assertNotIn(tempfile.gettempdir(), data["error"])
+        self.assertEqual([p["text"] for p in self.api.db.search_prompts()], ["keep me"])
+        self.assertEqual(created, [])  # refused before anything was written
+
+    async def test_a_short_disk_is_refused_while_streaming_without_a_length(self):
+        from py.api import maintenance
+
+        self._save("keep me")
+        upload = self._large_db_file(["restored"], 4 * MIB)
+        spy, created = self._spy_uploads()
+        # Room for 1 MiB only, and no Content-Length to refuse up front.
+        with spy, patch.object(maintenance, "restore_room", return_value=MIB):
+            resp = await self._stream_restore(upload, chunked=True)
+        data = await resp.json()
+        self.assertEqual(resp.status, 507)
+        self.assertEqual(data["code"], "insufficient-space")
+        self.assertTrue(data["error"].endswith("Nothing was changed."))
+        self.assertEqual([p["text"] for p in self.api.db.search_prompts()], ["keep me"])
+        self.assertEqual(len(created), 1)
+        self._assert_removed(created)
+
+
+class TestRestoreRoom(unittest.TestCase):
+    def test_room_counts_the_upload_its_staged_copy_and_the_swap(self):
+        from py.api import maintenance
+
+        tmp = tempfile.mkdtemp()
+        try:
+            db_path = os.path.join(tmp, "prompts.db")
+            free = 10 * 2**30
+            with (
+                patch.object(maintenance, "_free_bytes", return_value=free),
+                patch.object(maintenance, "_device", return_value="one disk"),
+            ):
+                room = maintenance.restore_room(db_path)
+            # Upload + staged copy + WAL growth on one disk, no database yet.
+            self.assertEqual(room, (free - maintenance.DISK_MARGIN_BYTES) // 3)
+            self.assertEqual(maintenance.size_label(int(1.6 * 2**30)), "1.6 GB")
+            self.assertEqual(maintenance.size_label(120 * 2**20), "120.0 MB")
+        finally:
+            os.rmdir(tmp)

tests/test_api_core.py

@@ -384,6 +384,8 @@ class CoreRoutesTestCase(AioHTTPTestCase):
 
     async def tearDownAsync(self):
         await super().tearDownAsync()  # closes the aiohttp test client
+        # The automatic preview worker writes into the temp tree: stop it first.
+        self.api.close_auto_thumbnails()
         self.api.db.close_all()
         assert_closed(self, self.tmpdir)
         shutil.rmtree(self.tmpdir, ignore_errors=True)
@@ -471,6 +473,19 @@ class TestUiRoutes(CoreRoutesTestCase):
         self.assertIn(("POST", "/prompt_manager/jobs/scan"), table)
         self.assertIn(("POST", "/prompt_manager/jobs/image-tags"), table)
 
+    async def test_review_routes_are_registered(self):
+        table = {
+            (route.method, route.resource.canonical)
+            for route in self.app.router.routes()
+            if route.resource is not None
+        }
+        for entry in (
+            ("GET", "/prompt_manager/review/items"),
+            ("GET", "/prompt_manager/review/items/{item_id}"),
+            ("POST", "/prompt_manager/review/items/{item_id}/decision"),
+        ):
+            self.assertIn(entry, table)
+
 
 class TestStaticRoutes(CoreRoutesTestCase):