Merge remote-tracking branch 'origin/main' into feat/334-cutover-switch

# Conflicts:
#	web/js/workspace/workspace.css

.github/workflows/portability.yml

@@ -21,15 +21,19 @@ env:
   PYTHONFAULTHANDLER: "1"
 
 # Time limit rule as in test.yml: ceil(1.5 x the slowest of three recent green runs on main) + 3
-# minutes, never under 5. Measured 2026-10-26 in test.yml on runs 40257217681 (3be0ada),
-# 40240706568 (fb9134f), 40228167328 (f9835aa), before these legs moved here in #420:
-#   slowest py3.10 on windows-latest: 12m43s / 15m54s / 14m53s -> 27 min
-#     (macos 6m14s-8m30s, windows 11m42s-15m54s)
+# minutes, never under 5, timed as whole-job wall time. One matrix job, so the slowest leg of each
+# run counts (tests/vendor/ci-workflow.test.mjs recomputes it, #493).
+# Measured 2026-10-29 on main runs 40935337099 (dd247e3), 40938407252 (dd247e3), 40941240624 (dd247e3):
+#   slowest leg: 7m24s (py3.12 windows) / 7m31s (py3.13 windows) / 7m32s (py3.14 windows) -> 15 min
+#     (windows 4m56s-7m32s, macos 4m39s-6m14s)
+#   native-trash (#499) has no green main runs yet: its probe, run 40949370943 (2026-10-29), took
+#     about 1 minute per macOS leg, so ceil(1.5 x 2) + 3 gives it 6 minutes (step 4). Recalibrate
+#     after three green runs.
 jobs:
   test:
     name: py${{ matrix.python-version }} on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 27
+    timeout-minutes: 15
     strategy:
       fail-fast: false
       matrix:
@@ -51,5 +55,52 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements-dev.txt
 
+      # The runner's TEMP is on C:, the OS disk, where a flush took about 6 ms
+      # and a test database's create-to-delete about 111 ms; on the D: work
+      # disk the same took 0.5 ms and 23 ms (macOS: 19 ms). Tests write their
+      # databases under TEMP, so it moves to a folder on D: (measured in #487,
+      # run 40915866444). The runner's TEMP was an 8.3 short name
+      # (C:\Users\RUNNER~1\...), so the new one is spelled by its short name too
+      # and paths still have to be resolved. D: makes no short names by default
+      # (run 40922502209), so they are switched on for it first.
+      - name: Keep test files on the work disk (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          fsutil 8dot3name set D: 0
+          $folder = New-Item -ItemType Directory -Force -Path (Join-Path $env:RUNNER_TEMP "PromptManagerTests")
+          $short = (New-Object -ComObject Scripting.FileSystemObject).GetFolder($folder.FullName).ShortPath
+          Write-Output "test TEMP: $short (long name $($folder.FullName))"
+          if ($short -eq $folder.FullName) { Write-Output "::warning::D: gave the test TEMP no 8.3 short name" }
+          "TEMP=$short" >> $env:GITHUB_ENV
+          "TMP=$short" >> $env:GITHUB_ENV
+
       - name: Run tests
+        env:
+          PM_TEST_SLOWEST: "40"
         run: python -m tests.run_suite -v
+
+  # The real Trash on both macOS CPUs (#499 design §10.2). It runs apart from the suite, so a red
+  # suite never skips the native proof.
+  native-trash:
+    name: native trash on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 6
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, macos-15-intel]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Native trash proof
+        timeout-minutes: 4
+        env:
+          PM_NATIVE_TRASH: macos
+        run: python -m unittest tests.test_trash_macos_native tests.test_trash_macos -v

.github/workflows/test.yml

@@ -28,8 +28,8 @@ env:
 #   py matrix, slowest py3.10 on windows-latest: 12m43s / 15m54s / 14m53s -> 27 min
 #     (ubuntu 5m27s-6m27s, macos 6m14s-8m30s, windows 11m42s-15m54s)
 #     3.10 and 3.11 left the matrix and 3.14 joined it in #356; re-measure after three green main runs.
-#     Windows and macOS moved to portability.yml (#420), which keeps this 27-minute limit; this
-#     Linux-only matrix keeps it too until it is re-measured.
+#     Windows and macOS moved to portability.yml (#420), which has its own measured limit (#493);
+#     this Linux-only matrix keeps 27 minutes until it is re-measured.
 #   real ComfyUI compatibility: 13m32s / 8m55s / 11m46s -> 24 min
 #   coverage gate (85%): 7m26s / 7m22s / 7m54s -> 15 min
 #   perf budget 30s / 29s / 27s, black and flake8 39s / 37s / 39s,

README.md

@@ -251,9 +251,9 @@ match Classic and Focused.
    - **PromptManagerText**: Look for "Prompt Manager Text" in the PromptManager/Text category - outputs STRING for any text node
 
 5. **Access the web interface**:
-   - **Admin Dashboard**: `http://localhost:8188/prompt_manager/admin` - Full management interface
-   - **Metadata Viewer**: `http://localhost:8188/prompt_manager/metadata.html` - Standalone PNG analysis tool
-   - **Simple Interface**: `http://localhost:8188/prompt_manager/` - Basic prompt browser
+   - **Workspace**: click **PM** in ComfyUI's top bar or **Web UI** on a node, or open `http://localhost:8188/prompt_manager/workspace`
+   - **Legacy pages** still work at their URLs, and System's Overview section links to them:
+     `/prompt_manager/admin` (dashboard), `/prompt_manager/admin#/tags` (tags), `/prompt_manager/gallery` (gallery), `/prompt_manager/gallery.html` (metadata viewer)
 
 ### Prerequisites
 
@@ -324,9 +324,10 @@ The comprehensive gallery system provides complete access to all your ComfyUI ou
 
 #### **📁 Accessing the Gallery**
 
-1. **Open the admin interface** at `http://localhost:8188/prompt_manager/admin`
-2. **Click the "🖼️ Gallery" button** to open the output-wide gallery
-3. **Browse all content** from your ComfyUI output directory
+1. **Open the workspace's Images page** at `http://localhost:8188/prompt_manager/workspace#/images`
+2. **Browse all content** from your ComfyUI output directory
+
+The legacy gallery stays at `http://localhost:8188/prompt_manager/gallery`.
 
 #### **🎬 Video & Image Support**
 

TESTING.md

@@ -53,6 +53,14 @@ stdin open and the server (`--exit-on-stdin-eof`) shuts down cleanly, removing i
 temp root, when that pipe closes, so a worker killed without teardown leaves no
 server behind. A test that fails gets the stderr its server wrote during the test
 attached to the report as `server-stderr` (an aiohttp traceback behind a 500).
+Each worker also records its browser's own log (#513, `tools/vendor/browser-logs.mjs`):
+Playwright's `pw:browser` channel, kept as a 300-line tail without printing it
+unless `DEBUG` asks for it. A browser that exits abnormally writes one
+`pm-browser-exit| browser pid=<n> exited: exitCode=<c>, signal=<s>` line to the job
+log, and a test that fails on a closed or crashed target ("Target page, context or
+browser has been closed") gets the tail attached as `browser-stderr.txt`, which the
+uploaded test-results carry. `tests/browser/browser-logs.spec.mjs` kills a browser of
+its own on purpose, so each browser job logs that line once for it.
 A `/__test__/.../reset` still running after 2 s writes a report to the job log,
 passing test or not: every thread's stack taken while it waits, the default
 executor's threads and queue, the open connections and WAL size, then the total
@@ -251,12 +259,29 @@ the process exits non-zero.
   stacks.
 - When the watchdog fires under coverage, that run's coverage data is lost; the
   job fails anyway and the dump is what matters.
+- `PM_TEST_SLOWEST=N` (off by default) lists the N slowest tests after the
+  summary, each timed from its `start:` line to the next one like the hang
+  limit. The Windows and macOS jobs (`portability.yml`) set it to 40, so every
+  run shows where its time went (#487). The list prints only when the run
+  ends: a job GitHub cancels or a watchdog exit prints none, so read the
+  timestamps between `start:` lines instead.
+- On the Windows runners `TEMP` sits on the OS disk C:, where a flush took about
+  6 ms and a test database's create-to-delete about 111 ms (D: 0.5 ms and 23 ms,
+  macOS 19 ms). `portability.yml` points `TEMP`/`TMP` at a folder under
+  `RUNNER_TEMP` on D: before the suite. It switches 8.3 short names on for D:
+  and spells the folder by its short name, as the runner's own TEMP was
+  (`C:\Users\RUNNER~1\...`), logs it, and warns when there is none.
+  A test that waits on a fixed busy timeout, a network name (`\\server\share`:
+  use `\\localhost\<missing share>`) or a default TLS context (it reads the
+  Windows certificate store) costs seconds there; the slowest list shows it.
 
-Every job in `test.yml`, `code-quality.yml` and `viewerjs-check.yml` has
-`timeout-minutes` (`tests/vendor/ci-workflow.test.mjs` checks it). The rule is
-ceil(1.5 x the slowest of three recent green runs on `main`) + 3 minutes, never
-under 5; the three run ids, their times and the resulting limits are written
-in a comment above `jobs:`. The 3 minutes leave room for one watchdog firing, so
+Every job in `test.yml`, `code-quality.yml`, `viewerjs-check.yml` and
+`portability.yml` has `timeout-minutes` (`tests/vendor/ci-workflow.test.mjs`
+checks it). The rule is ceil(1.5 x the slowest of three recent green runs on
+`main`) + 3 minutes, never under 5, timed as whole-job wall time; the three run
+ids, their times and the resulting limits are written in a comment above
+`jobs:`. For `portability.yml` the tooling test recomputes the limit from that
+comment (#493); its one matrix job takes the slowest Windows or macOS leg. The 3 minutes leave room for one watchdog firing, so
 the dump prints before GitHub cancels the job. A job that hits its limit, or a
 watchdog dump, is a failure like any other: read the dump, find the blocking
 call, fix it. Never raise a limit or rerun to get green; a limit changes only
@@ -2399,6 +2424,129 @@ npm run --prefix tools/vendor test:workflows -- workspace-collections.spec.mjs c
   images-concept.spec.mjs inspector-concept.spec.mjs shell-concept.spec.mjs --project chromium --project touch
 ```
 
+### Deleting images (#480)
+
+Images › Delete… removes the checked images (or "Select all N matching", at most 500, or
+the one file of the side panel or the viewer) from the library, and on request moves the
+files to the system trash. **No code path unlinks or overwrites a media file.**
+
+- **D159** (#480, maintainer request): the concept's "Remove links…" (`danger`, app.js
+  432) returns as **Delete…** in the same place (after Export metadata, before Clear), and
+  as the last action of the side panel and after Download in the Images viewer. Its
+  review is the concept's `maintenancePlan` (`dl.meta-grid`, Cancel and a primary) with a
+  radio group first, "What should happen to the files?", nothing checked (the ruling: ask
+  every time): "Remove from the library only" or "Also move the files to the trash". The
+  rows follow the chosen mode (Scope, Not changed, Prompt links, Image details, Backup,
+  Media on disk) and the primary is `danger`: "Remove N images from the library" / "Move
+  N images to the trash". `tests/browser/images-delete-concept.spec.mjs` compares the bar
+  button and the review's grid and actions with the concept.
+- **Routes.** `POST /prompt_manager/images/delete/preview {items | filter}` reviews both
+  modes at once under the maintenance preview lease and answers a reviewed plan
+  (`_plan_response`, operation `delete_images`): `library.count`, `trash.count`, `refused`
+  and `trash_refused` (`{count, counts, rows ≤ 50}` with coded reasons), `records`,
+  `orphaned_prompts` and the backup. Each target is matched to its entry in the current
+  listing (`not-listed` otherwise). `POST /prompt_manager/maintenance/apply {token, mode}`
+  (`mode` required for this plan, refused for any other) starts job kind `image_delete`
+  (admission `records`, not cancellable; groups `trashed`, `removed`, `not_changed`,
+  `errors`): sources unchanged, the promised safety backup, then per file a recheck
+  (containment and fingerprint) and
+  - library mode: one transaction deletes the file's records and writes its removal mark;
+  - trash mode: the file moves first (`utils/trash.py`); a refused move changes nothing;
+    then its records go. A records failure stops the job (`records-failed`); later files
+    are "Not attempted".
+- **What goes** (`database/image_removal.py`): image links under every spelling (pair
+  links by cascade, workflow documents released), image tags, auto-tag marks, pending
+  undecided Needs review items, the own category, collection memberships and the
+  favorite. A decided or revised review item keeps its decision and the annotation rows it
+  cites. Prompts, recorded runs and the vocabulary stay. Previews are removed.
+- **Removal marks** (`image_removals`, `image_removals_meta`): a library-only removal
+  hides exactly that file (locator, size, `mtime_ns`) from the workspace listing, the
+  output scan, the duplicate find, Tag output images and linking. A modified or replaced
+  file shows again. An explicit tag, category, favorite or collection write clears the
+  mark. Older builds ignore the tables (removed files show there); restoring an older
+  backup shows every file again; restoring a pre-delete backup after trash mode brings
+  back records of files that are in the trash (Missing-file links cleans them up). The
+  legacy gallery lists every file on disk, removed or not. Hard links have one mark per
+  path, and on FAT/exFAT/SMB a same-size replacement can stay hidden.
+  Since #501 the thumbnail jobs (System › Thumbnails' counts and its missing, rebuild and
+  convert runs, and the previews after a scan) and the legacy `GET /scan_output_dir`
+  listing skip hidden files too; an on-demand preview the legacy gallery asks for is still
+  made, and a one-image auto-tag (`/autotag/single` + `/autotag/apply`) is an explicit
+  write that shows the file again. System › Maintenance **Missing-file links** also
+  forgets the marks that hide nothing any more (the file is gone from a folder that still
+  exists, or its bytes changed), counted in its scope ("K removed images whose files are
+  gone or changed") and job line, judged only under a source that is readable and lists
+  something (an unplugged drive's empty mount point keeps its marks), never for a source
+  no longer configured, and re-checked at apply (`plan-changed`). The sidebar's Images,
+  Favorites and Needs review counts and the collection counts are read again when an
+  `image_delete` job ends in the tab that followed it (`JOB_END_COUNTS`, `state.mjs`).
+  Tests: `tests/test_image_removal_gaps.py`, the sidebar case in
+  `tests/browser/workspace-images-delete.spec.mjs`.
+- **Trash folders inside an output root** (#501, `utils/media_folders.py`): no walker
+  descends a folder below a root named `.Trash`, `.Trash-<digits>`, `.Trashes` or
+  `$RECYCLE.BIN` (any case), as none descends `thumbnails`: the workspace and legacy
+  listings (`_walk_media`, `_settled_entry`), the metadata scan and duplicate find
+  (`_collect_media_files`), the legacy auto-tag listing (`_collect_scan_files`) and the
+  delete review (`trash-folder`), and the image monitor, which tests the folders below the
+  watched folder holding the new file (a source named like a trash folder is still watched). Tests: `tests/test_media_folders.py`,
+  `tests/test_image_removal_gaps.py`.
+- **Trash backends** (`utils/trash.py`, no dependency): Linux and BSD implement the
+  freedesktop Trash specification (home trash on the same mount, else the mount's
+  `.Trash/$uid` or `.Trash-$uid`), reserve the name with `O_EXCL` and move with
+  `renameat2(RENAME_NOREPLACE)`; without it, across devices, on a read-only mount or with
+  a trash inside an output root the move is refused (`no-trash`, `trash-in-root`). macOS
+  (#499, `utils/trash_macos.py`) calls `-[NSFileManager trashItemAtURL:resultingItemURL:error:]`
+  through `ctypes` (ten fixed `objc_msgSend` prototypes, nil checks before every send, one
+  autorelease pool per call, loaded on first use). It answers in the review dialog, without
+  writing: `network` (not a local volume), `no-trash` (read-only, or no trash folder
+  macOS would use), `cloud-sync` (iCloud Drive, `~/Library/CloudStorage`, or ubiquitous),
+  `trash-in-root` (the trash folder is inside an output root, compared by `(st_dev,
+  st_ino)` of every ancestor) and `no-permission` (folder not writable, an immutable or
+  append flag, a foreign file in a sticky folder). A fresh volume's `.Trashes/<uid>` is
+  predicted (`URLForDirectory` answers 3328/`ENOENT` until macOS makes it). A refused move
+  keeps the file and logs the `NSError`; a move macOS reports done but whose place cannot be
+  shown (no result URL, or one inside an output root) goes under `errors` as
+  `trash-unconfirmed`, keeps its records and stops the job. Windows
+  never uses the Recycle Bin (#500, maintainer ruling (a)): files larger than the bin's
+  capacity are deleted permanently and IFileOperation's `PreDeleteItem` guard cannot detect
+  it (native probe runs 40951037575, 40953347904), so every file answers `windows-recycle`
+  ("Moving files to the Recycle Bin isn't available on Windows: files larger than the bin's
+  capacity would be deleted permanently."). Library-only removal works everywhere. Tests use `tests/fake_trash.py`; the
+  browser test server installs it, so no test touches a real trash. The native proof,
+  `tests/test_trash_macos_native.py`, runs only with `PM_NATIVE_TRASH=macos` in
+  portability.yml's `native-trash` job (`macos-latest` and `macos-15-intel`): the startup
+  volume, a name clash, fresh APFS and FAT32 disk images, an image used as an output root,
+  a read-only image and an unwritable folder (design and probe:
+  `docs/egm/499-macos-trash/`, local).
+
+- **D162** (#498, maintainer ruling Q1 of #480; the concept has no screen for removed images, so this follows D152's
+  Show archived prompts): **Show removed images (N)** in the Images heading actions, before Import, a toggle
+  (`aria-pressed`) shown only while N > 0 or the view is on. N is `removed_total`, every removed image in the selected
+  source(s) whatever the filters (D152 counts the matching ones). The view (`GET /images/output?mode=workspace&
+  removed=1`, refused with `favorites`, `collection`, `category`, `tags` or `sort=rating`; a cursor never crosses
+  views) lists only files a removal mark hides, each card with a "Removed" `.chip` and without the star or Tag action;
+  the caption reads "N removed images · files on disk, hidden from Images", the empty view "No removed images." /
+  "No removed images match.". Entering clears Category and Tags; choosing a category or tags while it is on
+  (toolbar, Refine this view) ends the view. A card's image and Info both inspect (the viewer is
+  not opened: its Collections… and Delete… would write); the panel shows Return to library in Delete…'s place and
+  no Collections… or tag-filter chips. The bar reads "N selected", Return to library, Clear. The view is never saved
+  or restored: leaving the page, Browse or a saved view ends it, and a return that leaves N = 0 ends it too.
+  - **Return to library** (no review: nothing is lost or moved, as D152's Restore) posts `{items | filter}` to
+    `POST /prompt_manager/images/removed/return` (only this route takes `filter.removed`; every other bulk route
+    refuses it). 202 `{job, returned, not_removed}` (400 `no-images` when none is hidden now, `too-many-images` over
+    500; 409 `busy` beside a scan, restore or delete, nothing changed). The job is a `scan`, "Return images to the
+    library": its first step deletes, in one transaction, the marks that still hide their file (same size and
+    `mtime_ns`; the marks generation moves again after the commit), then it scans exactly those files with the scan's
+    pipeline and groups. Toasts: "Returning N images to the library…", then "Returned N images to the library; K
+    linked to their prompts. Tags, categories, collections and favorites do not come back." When it ends, the
+    sidebar's Needs review, Library and Images counts are read again (`JOB_END_COUNTS.scan`).
+  - What comes back: the file in Images; its prompt, links, pairs and Needs review items from its embedded metadata
+    (a file without usable metadata comes back unlinked); previews on demand. Not: image tags, auto-tag marks, own
+    category, collection memberships, favorite (only a safety-backup restore has them). If the server stops between
+    the mark delete and the scan, the files are back unlinked and a "new files" scan links them.
+  Tests: `tests/test_image_return.py`, `tests/js/workspace-images-return.test.js`,
+  `tests/browser/workspace-images-removed.spec.mjs`. A Python change: ComfyUI needs a restart.
+
 ### Prompt library cards and recorded deviations (#249 PR E)
 
 The shelf uses the shared concept toolbar and caption (E1) and the concept's
@@ -2493,8 +2641,8 @@ applied), D35 (singular captions), D36 (sorted categories), D40 (the continuatio
 the grid) and D43 (sorted chips, checked against the concept with its chips sorted).
 D44 needs no mapping: the comparison runs with no Refine filter active, so the button
 reads "Filters" as the concept's does. Nothing else follows the grid: the legacy
-"Current prompt library" link is removed from the shelf; Overview's legacy card ("Open
-existing prompt library") and the sidebar still link `/prompt_manager/admin`
+"Current prompt library" link is removed from the shelf; the legacy Library stays at
+`/prompt_manager/admin` by direct URL, linked only from System (#525, D165)
 (`tests/browser/workspace.spec.mjs`). `library comparison detects
 mutations` injects `.card-footer { padding: 2px }` and removes `.card-meta .chip.red`.
 
@@ -2524,7 +2672,8 @@ Category". It is built only from the concept's Images parts:
   input[type=checkbox]`); Home, End and the arrow keys still move between titles.
 - `div#library-bulkbar` sits between the toolbar and the caption, empty until something
   is checked, then the concept's `.bulkbar`: "N selected", Set category, Clear (D151
-  adds Add tags before Set category, in the Images bar's order). The
+  adds Add tags before Set category, in the Images bar's order; D152 adds Delete… before
+  Clear, and Restore then Delete… on the archived shelf, #492). The
   selection is a set of prompt ids over the loaded shelf: windowed-out cards keep their
   state, Load more keeps it, and any shelf reload (search, category, sort, tags, a
   write) and leaving the page clear it. Clicking a checkbox toggles it and sets the
@@ -2605,6 +2754,216 @@ during a write); `tests/browser/library-concept.spec.mjs` (the bar comparison no
 Add tags); units `tests/js/workspace-library-selection.test.js`; Python
 `tests/test_bulk_library_tags.py`. A Python change: ComfyUI needs a restart.
 
+### Deleting and archiving selected prompts (#443)
+
+**D152** (beyond the concept, on D148's bar; the concept archives a prompt from its recipe
+editor's "Archive…", `app.js` 976, reviewed in `maintenancePlan`, 953–958, and maps the legacy
+delete to a "reference-safe archive", 783): the Prompt library deletes or archives the
+selected prompts in one reviewed step, replacing the legacy admin page's bulk and single
+Delete, which refuses a whole batch when any prompt belongs to a saved pair (maintainer
+rulings of 2026-10-28):
+
+- The bar reads "N selected", [Select all N loaded], Add tags, Set category, **Delete…**
+  (the concept's `danger` class, as its Images bar's "Remove links…"), Clear.
+- Delete… posts `{prompt_ids, expected_epoch}` to `POST
+  /prompt_manager/library/delete/preview`, which classifies each id in this order: not
+  found (missing or not a Library parent), protected (tagged `__protected__`), already
+  archived, archive (the positive or negative of any saved pair, archived pair or not),
+  delete (everything else). From the press until the review opens, every bar action, Clear
+  too, is `aria-disabled` and Delete… reads "Reviewing…" (a double press sends one preview).
+- The review is the shared record-changing review (`openReviewDialog`), titled "Delete
+  selected prompts", "Archive selected prompts" or "Delete or archive selected prompts", its
+  `dl.meta-grid` rows Delete permanently ("N prompts not in a saved pair") and Archive ("N prompts in a saved
+  pair: hidden, restorable", never negative variants: a pair's prompt with none is archived too) (always), Protected (kept) with up to
+  three titles, Already archived, No longer exist, and, when something is deleted, Image
+  links removed and Backup ("Create and verify before deleting", or "Off: no safety backup
+  (System › Backup & export › Recovery policy)"); then `p.small` sentences: why paired
+  prompts are archived and how to restore them, what a delete removes and that it cannot be
+  undone except by restoring the safety backup (which returns the whole library to that
+  moment; kept among the last 10), that a later scan, new image or node run with the same
+  text adds a deleted prompt again, and how to unprotect. The primary is `danger`: "Delete D
+  prompts", "Archive A prompts" or "Delete D and archive A prompts". When nothing can change,
+  or the disk has no room for the promised backup, the review is close-only with the reason.
+  The concept's "Review maintenance plan" title, its demo note, Scope/Protected/Media on
+  disk rows and `ca-primary` start are replaced by these.
+- Start posts the reviewed lists `{archive_ids, delete_ids, expected_epoch, backup}` to `POST
+  /prompt_manager/library/delete` while Delete… reads "Deleting…" (or "Archiving…"). The
+  server takes a `records` hold ("Delete prompts (Library)", refused 409 `busy` beside a scan,
+  restore, maintenance, move or Optimize), checks the disk (507 `insufficient-space`) and,
+  when a delete remains and the reviewed `backup` was "on" or the policy is on now, takes a
+  verified safety backup (500 `backup-failed`, nothing changed). One `BEGIN IMMEDIATE`
+  transaction then deletes only reviewed deletes still unpaired whose prompt row, tags,
+  title and image links are unchanged since the backup (exactly the legacy rows: image
+  link rows, cascaded tags, Library state and pair links of images, released workflow
+  documents; files never), archives the paired ones and any reviewed delete now paired, and
+  counts the rest (`already_archived`, `not_found`, `changed`). Archiving writes a
+  `prompt_archive` row, the prompt's `updated_at` and, when its stored hash is stale or
+  missing and no other row holds the canonical one, the canonical hash, so scans, the
+  monitor and node saves find the archived row instead of adding a copy. A changed epoch
+  answers 409 `storage-changed`; nothing is written.
+- Outcomes: "Deleted D prompts." "Archived A prompts." with already archived, no longer
+  exist, changed and kept-protected sentences and "Safety backup saved: NAME (System ›
+  Backup & export)."; the shelf, categories, cached Library views and sidebar counts reload.
+  Storage restored: "The library was restored or moved since this page loaded. Nothing was
+  deleted or archived."; busy: "NAME is running. Nothing was changed; try again when it
+  finishes."; a failed backup or a short disk: the server's sentence; no answer, 502, 503 or
+  504: "The server did not confirm the change. The Library was reloaded: check the shelf and
+  Show archived prompts."; other refusals: "The selected prompts could not be changed. Try
+  again.", the selection kept.
+- **Show archived prompts (N)** (heading actions, before Export, a plain button; N the
+  archived prompts matching the filters, `archived_total`; the shelf counterpart of #235's
+  Show archived) lists only archived prompts (`GET /prompt_manager/library?shelf=archived`,
+  a cursor never crosses shelves), each card with an "Archived" `.chip`, the caption "N
+  archived prompts · M negative variants hidden with them", the bar "N selected", Restore,
+  Clear, and "No archived prompts." / "No archived prompts match." when empty. On the archived
+  shelf the button reads the concept's own way back, "← Prompt library" (app.js 594; #482), with
+  no `aria-pressed` (its label names where it goes). The shelf stays with the shelf visit, never
+  in a saved view; Browse and a saved view open the active shelf. Restore posts `{prompt_ids, expected_epoch}` to `POST
+  /prompt_manager/library/restore` (every requested archived id, protected or not): "Restored
+  N prompts to the Prompt library."
+- An archived prompt's page shows the concept's `.notice` ("Archived" / "This prompt is archived
+  because it is in a saved pair. It and its N negative variants are hidden from the Prompt library; nothing was
+  removed.", or "It is hidden from…" when it has none) with Restore;
+  everything else on the page works. New prompt or Add negative on an archived prompt's
+  text keeps it archived and toasts "This text is an archived prompt. Restore it to show it
+  in the Prompt library again."
+- Archived prompts: hidden from the shelf, its search, `total`, the sidebar count, Tags &
+  categories' prompt counts (a value only archived prompts hold stays listed with 0) and
+  System › Overview and the restore review's positive counts; still counted by rename and
+  delete impacts and usage statistics; still shown as another prompt's negative variant, on
+  recorded runs and Images, by the legacy pages and the ComfyUI node's search; still reached
+  by run counting, scans and the monitor; never pruned by maintenance (a new protection,
+  "archived in the Library"); exported with `archived: true`. Older builds ignore the table
+  and show them again; the rows stay.
+- Deviation from legacy: a selected `__protected__` prompt is never deleted or archived (the
+  legacy delete removed it); it is listed in the review and the toast.
+
+Tests: `tests/browser/workspace-library-delete.spec.mjs` (mixed review and result on the
+server, Cancel, Show archived prompts and Restore from the bar and the notice, double press,
+failed backup, busy, unconfirmed, restore fence); `tests/browser/library-delete-concept.spec.mjs`
+(the review against the concept's `maintenancePlan`, the bar's Delete… against the concept's
+"Remove links…"); units `tests/js/workspace-library-delete.test.js`; Python
+`tests/test_prompt_archive_schema.py`, `tests/test_bulk_library_delete.py`,
+`tests/test_library_delete_routes.py`. A Python change: ComfyUI needs a restart.
+
+### Deleting a prompt in a saved pair permanently (#482)
+
+**D160** (beyond legacy, maintainer ruling 2026-10-29; follow-up to D152): when the Delete… selection
+holds prompts in a saved pair that no other positive uses as its negative ("deletable"), the review
+asks, in a D90 radio row "Prompts in a saved pair" after the grid: **Archive (hidden, restorable)**
+(checked on every open, never remembered, so the review is D152's) or **Delete permanently, with
+their saved pairs**. Choosing it rewrites the review in place (`openReviewDialog` `setRows`,
+`setPrimary`):
+- Delete permanently "D prompts: X not in a saved pair, Y in a saved pair" (or "Y prompts in a saved
+  pair"), Saved pairs removed "S saved pairs (V with a negative prompt, A archived)", Negatives kept
+  "K negative prompts are kept", Archive "R prompts used as another prompt's negative: hidden,
+  restorable", then D152's protected, already archived, no longer exist, Image links removed (images
+  of every deleted prompt) and Backup rows.
+- Sentences: the pairs go with their titles, categories, ratings, notes, tags, run counts and image
+  links; their negative prompts stay; recorded runs stay in History and Activity by their text; D152's
+  irreversibility (per backup policy) and re-creation sentences, plus "A pair node run with the same
+  text saves a new pair."; and, when R > 0, why those are archived.
+- Primary (`danger`): "Delete D prompts" / "Delete D and archive R prompts"; a short disk keeps it
+  unavailable (`aria-disabled`) with the disk sentence, while Archive still starts.
+
+The preview adds `deletable` (a subset of `archive`, which keeps every archive id for D152 clients),
+`review_digests` (sha256 of each deletable prompt's row and its pairs: negative, archived flag,
+metadata, usage, tags, image-pair links), `paired_counts` and `paired_image_links`, and plans the
+disk whenever anything could be deleted. The write takes optional `delete_paired_ids` with their
+`paired_digests` (both or neither; ids must be reviewed archive ids). In one transaction, after the
+archives, each chosen prompt whose digest is unchanged loses its image-pair links, then its own saved
+pairs (pair tags cascade; review decisions keep their rows with `pair_id` cleared), then itself exactly
+as D152 deletes. Any drift (pair added or edited, new link, pairs gone, now another prompt's negative)
+archives it and counts it `changed`. A paired delete is backed up and disk-checked as a delete. The
+toast adds "Removed S saved pairs."; "N changed since the review and was not deleted." replaces "…was
+kept.". Negatives are never deleted: one no remaining pair uses is listed in the Library afterwards (as
+after the legacy pair delete). Legacy still refuses paired prompts (409).
+
+Tests: `tests/test_bulk_library_delete.py` `TestPairedDelete` (classes and counts, the 7896 empty
+negative, the row diff against the legacy pair deletes then prompt delete, archive-only, a positive
+with its own negative, a self-pair, each drift, validation); `tests/test_library_delete_routes.py`
+`TestPairedDeleteRoutes` (preview, paired-only backup, a D152 body, validation, short disk); units
+`tests/js/workspace-library-delete.test.js`, `tests/js/workspace-toolbar.test.js` (`setRows`,
+`setPrimary`); browser `tests/browser/workspace-library-delete.spec.mjs` (the choice, its grid and
+copy, the server after, archive-only, reset to Archive) and `library-delete-concept.spec.mjs`. A Python
+change: ComfyUI needs a restart.
+
+### Delete… on the archived shelf (#492)
+
+Extends **D160** (coordinator ruling 2026-10-29, cutover item): the archived shelf's bar reads "N selected · Restore ·
+Delete… · Clear". Its Delete… review is the permanent delete only, **without** #482's "Prompts in a saved pair" choice
+(on this shelf "Archive" would change nothing; Cancel keeps them archived). Title "Delete archived prompts"; the grid
+is #482's Delete permanently grid ("Saved pairs removed" and "Negatives kept" only when a selected prompt is in a saved
+pair); an archived prompt used as another prompt's negative cannot be deleted and **stays archived** ("Stays archived: R
+prompts used as another prompt's negative"); one restored since the shelf was read is "No longer archived (kept)" and
+never written; a review with nothing to delete is close-only ("None of the selected prompts can be deleted."). The
+primary is "Delete N prompts"; the review opens with focus on Cancel (it is only a permanent delete; `openReviewDialog`'s
+`focusCancel`). The same preview, safety backup, review digests, `records` hold and epoch fence apply.
+
+The routes take an optional `shelf` (`"active"`, the default, or `"archived"`; anything else 400). Under it an archived
+prompt is classified by its pairs and a prompt without an archive row is `not_archived`; the held write classifies the
+same shelf, so a permanent delete is backed up. The client sends only what it deletes. On this shelf the write archives
+and rewrites nothing; every reviewed id not deleted counts `changed`, and the answer adds `not_archived` ("N were
+restored since the review and kept."). The main shelf's archive sentence now ends "To delete them later or bring them
+back, press Show archived prompts, select them and press Delete… or Restore."
+
+Tests: `tests/test_bulk_library_delete.py` TestArchivedShelfDelete, `tests/test_library_delete_routes.py`
+TestArchivedShelfDeleteRoutes, `tests/js/workspace-library-delete.test.js` (archived shelf) and
+`tests/browser/workspace-library-delete.spec.mjs` (#492 cases). A Python change: ComfyUI needs a restart.
+
+### Delete on a prompt's own page (#481)
+
+**D161** (beyond the concept, coordinator ruling (A) 2026-10-29, open to the maintainer at the live test): the recipe
+editor (Edit metadata, the concept's app.js 976 row "Create text revision", "Archive…", Cancel, Save) reads "Create
+text revision", **"Archive variant…"** (the selected negative variant's archive, #235, which used the concept's
+"Archive…" label) and **"Delete prompt…"** (danger), then Cancel and Save. "Delete prompt…" closes the editor and runs
+D152/D160's Delete… review for that one prompt (`reviewPromptDelete`: the same preview, review with the saved-pair
+choice, backup and write, fenced by the page's `library_epoch`). Cancel changes nothing and returns focus to Edit
+metadata. A delete toasts and opens the Prompt library; an archive (or a drift) toasts and reads the page again, so an
+archived prompt shows its Archived notice. The button is disabled while the editor saves or after a restore.
+
+The concept comparison applies D161 in `mapConcept` (`tests/browser/library-editor-canonical-comparison.mjs`): the
+concept's danger "Archive…" maps to "Archive variant…" followed by a "Delete prompt…" with the same geometry and tokens.
+
+Tests: `tests/browser/workspace-library-delete.spec.mjs` (#481 cases), and `workspace-library-editor.spec.mjs` (the
+hand-off and the comparisons) and `library-editor-visual.spec.mjs` with the renamed button. JS only: no restart.
+
+### Prompt page heading on one row (#524)
+
+**D164** (beyond the concept, which never has four heading actions beside a long title): from 951px, the concept's
+sidebar breakpoint, the prompt page's heading actions keep one row and the title takes the remaining width, clamped to
+two lines with its full text in the DOM and in `title`. Below 951px the concept's wrapping and stacked heading is
+unchanged. A short title lays out as the concept's, so the history concept comparison is unaffected. A deleted prompt's
+page has no "Prompt history · …" description: it is emptied and hidden while the gone message shows.
+
+### Delete review and prompt-page polish (#512)
+
+Found in the live test of #505/#507/#509. **D163** (beyond the concept, maintainer ruling 2026-10-29: delete was hard to
+find on a prompt's page): the prompt page heading ends with a **"⋯" More menu** button after Send to ComfyUI
+(`more-menu.mjs`: `aria-haspopup="menu"`, `aria-expanded`; Enter, Space or ArrowDown opens it on its first item, ArrowUp
+on its last; arrows, Home and End move; Escape closes it and returns focus to ⋯; Tab, an outside press or a choice
+closes it). It holds one danger item, "Delete prompt…", which opens the same review as Edit metadata's Delete prompt…
+(D161, kept) and returns focus to ⋯. The menu uses the concept's button, surface, border and toast shadow, opens
+right-aligned under ⋯, and opens rightwards where the heading wraps it to the left edge (390px). It is held with Edit
+metadata while the page's review or write runs, and disabled on a gone prompt's page.
+
+Also:
+- The Delete… review leaves out rows with nothing in them ("Delete permanently: 0 …", "Archive: 0 …"), close-only
+  reviews included.
+- A review opened from a prompt's page is titled "Delete this prompt" or "Archive this prompt" (following the choice),
+  and its close-only sentence reads "This prompt cannot be deleted or archived."
+- An archived prompt that is another prompt's negative is named so: "1 prompt used as another prompt's negative:
+  hidden, restorable" (or "N prompts in a saved pair (M used as another prompt's negative)"), with the sentence that its
+  variant stays.
+- A prompt page whose prompt no longer exists (404, after a delete or from a stale link) reads "This prompt no longer
+  exists. It may have been deleted." with "Open the Prompt library", no Retry; Edit metadata and ⋯ are disabled.
+- Item 5 of #512 does not fail on the code after #505: the archived shelf's button reads "← Prompt library", and under a
+  remembered search the heading's count equals what the archived shelf lists. A regression test pins both.
+
+Tests: `tests/js/workspace-library-delete.test.js` (#512) and `tests/browser/workspace-library-delete.spec.mjs` (#512
+cases: the menu by mouse, keyboard and at 390px, the gone page, the titles, the count under a search). JS only: no
+restart.
+
 ### No 1–5 prompt rating in the workspace (#447)
 
 **D153** (maintainer ruling 2026-10-28: the star is only for favorites; the concept keeps
@@ -2758,8 +3117,8 @@ npm run --prefix tools/vendor test:workflows -- history-concept.spec.mjs \
 ### Inspect a file page and recorded deviations (#249 local Inspect, PR L2)
 
 `#/inspect` ("Inspect a file") is a native workspace route; it no longer hands off to
-the legacy metadata page, which stays reachable from Overview's "Open existing metadata
-inspector" card (`/prompt_manager/gallery.html`). The page is the concept's `#metadata`
+the legacy metadata page, which stays at its URL
+(`/prompt_manager/gallery.html`) linked only from System (#525, D165). The page is the concept's `#metadata`
 (app.js `renderMetadata` a740–748, selection a1715–1729; style.css 709–722, 1180–1194,
 1543–1545, 1559–1564) in the concept's own classes (`.surface`, `.file-drop`,
 `.spaced-20`, `.local-file-preview`, all from the synced `concept.css`), with no
@@ -2869,6 +3228,12 @@ mapped differences"):
   change within the workspace waits the same way: the shell renders the next route once a
   video still starting on Inspect settles (`leaveGuard`; the latest route wins). Route
   changes at `loadstart` + 0–7 ms hung 4–5 of 120 pages before and 0 of 120 after.
+  The shared viewer's own video gets the same guard (#483): a new selection while the
+  viewer D155 opened is still starting its video leaves the viewer open, untouched, until
+  that video reports metadata or an error (or 15 s), then closes it; the URL is revoked
+  after that, and a viewer asked for meanwhile (the new file's D155 open) opens then. The
+  merge queue hung once without it (run 40903238387: the PNG selection 12 ms after the
+  inline video showed, with the viewer's new video still starting).
   A real page leave cannot wait. With no page code releasing anything, navigating
   away hung 8 of 120 pages and reload 22 of 120 (3 and 8 of 120 with the page's own
   release), so that WebKit teardown stays a known limitation; dispose still releases at
@@ -3823,8 +4188,8 @@ the per-section hand-off panel, was retired by S12 (#329): every section is nati
 - **D104** (Backup & export, S9, Q4): Recovery policy keeps the concept's "Proposed" chip.
   "Create a safety backup before maintenance" is the server's `safety_backup`
   (`maintenance.safety_backup`) policy. Its line says what it does ("Keep a verified copy
-  of the database on disk before maintenance, cleanups and LoRA imports change records. A
-  restore always keeps one."); the concept's "Preview a verified backup before applying
+  of the database on disk before maintenance, cleanups, LoRA imports and prompt deletes
+  change records. A restore always keeps one."); the concept's "Preview a verified backup before applying
   operations that change records." describes nothing the server does. It is drafted behind the Save row and saved with
   `expected_revision` (a configuration changed elsewhere is the conflict status); it is
   disabled with "Server settings could not be read." when the read failed. "Scheduled
@@ -6664,8 +7029,8 @@ Deploying this backend needs a ComfyUI restart (Python and route changes).
 ## Native vocabulary UI (#236)
 
 `#/tags` ("Tags & categories", page title "Tags") is a native workspace route; it no
-longer hands off to the legacy tag manager. That page stays reachable from Overview's
-"Open existing tag manager" card for its own page; tag search and sort, the untagged
+longer hands off to the legacy tag manager. That page stays at
+`/prompt_manager/admin#/tags` linked only from System (#525, D165); tag search and sort, the untagged
 entry (D149) and multi-tag OR (the Library's Tag match, D150) moved to the workspace
 (#444); bulk prompt delete stays on the legacy admin page (bulk tags: the Prompt
 library's selection bar, D151). A prompt's category is changed in the Prompt library
@@ -6787,3 +7152,23 @@ until acceptance. Not compared: hover states and the dialog focus ring (the page
 keyboard ring and link ring offsets are asserted). No coverage floor was lowered;
 `vocabulary-state.mjs`, `vocabulary.mjs` and `vocabulary-dialog.mjs` have additive
 floors in `frontend-coverage-baseline.json`.
+
+## Cutover entry points (#525)
+
+The top-bar PM button, both Web UI buttons and `/prompt_manager/web` open
+`/prompt_manager/workspace#/library` (`web/js/workspace-entry.js`; `web/index.html` keeps its
+own copy, pinned by `tests/js/workspace-entry.test.js`). Overview's cards open native hashes.
+The legacy pages (`/prompt_manager/admin`, `admin#/tags`, `gallery`, `gallery.html`) stay at
+their URLs, and admin's Metadata and Gallery buttons still open their legacy pages (maintainer
+ruling; pinned by `legacy-system-links.spec.mjs`).
+
+- **D165** (beyond the concept, maintainer ruling 2026-10-30): System's Overview section ends
+  with one small line, "Legacy pages: Dashboard · Tags · Gallery · Metadata viewer"
+  (`.legacy-pages`, new tabs), outside `.settings-layout`. The concept has no such line;
+  `mapOverviewConcept` adds it to the page tree.
+- **Load failure** (maintainer ruling 2026-10-30): `web/workspace.html` holds static
+  `#workspace-boot-failure` with the same four links, styled inline so it needs no stylesheet.
+  An inline guard shows it at `load` unless `index.mjs` set `data-workspace-booted`, so a failed
+  fetch of any module and a throw while starting are both covered; `workspace.spec.mjs` tests
+  both. Editing `workspace.html` needs a ComfyUI restart, because the server caches it. The PM button has no
+page-fixture test; it is proven on the managed host (`tests/comfyui/prompt-manager.spec.mjs`).

database/annotations.py

@@ -40,6 +40,7 @@ from .annotation_schema import (
     METADATA_TABLE,
 )
 from .autotag_schema import AUTOTAG_TABLE
+from .image_removal_schema import clear_marks
 from .library_commands import _UUID, LibraryCommandError, _validate_epoch
 from .models import utc_now_iso
 from .vocabulary import validate_vocabulary_tag_name
@@ -236,6 +237,9 @@ class AnnotationOperations:
 
     @staticmethod
     def _annotation_owner(conn: sqlite3.Connection, locator: str, now: str) -> str:
+        # A file with image tags or Needs review state is in the library: a
+        # removal mark never hides it (#480).
+        clear_marks(conn, [locator])
         row = conn.execute(_OWNER, (locator,)).fetchone()
         if row is not None:
             return row[0]

database/image_categories.py

@@ -221,6 +221,7 @@ class ImageCategoryOperations:
         sources. Returns ``{updated, unchanged}``; a file that already had
         exactly this value is ``unchanged`` and keeps its ``updated_at``.
         """
+        from .image_removal_schema import clear_marks_of_keys
         from .models import utc_now_iso  # models imports this module's schema
 
         keys = list(dict.fromkeys(tuple(key) for key in file_keys))
@@ -234,6 +235,7 @@ class ImageCategoryOperations:
                     continue
                 conn.execute(UPSERT_SQL, (*key, category, now))
                 counts["updated"] += 1
+            clear_marks_of_keys(conn, keys)  # #480: a categorized file is listed
         return counts
 
     def clear_image_categories(self, file_keys) -> int:

database/image_collections.py

@@ -402,6 +402,7 @@ class ImageCollectionOperations:
         is created only when at least one item is inserted. Returns
         ``{collection, created, added, already}``.
         """
+        from .image_removal_schema import clear_marks_of_keys
         from .models import utc_now_iso  # models imports this module's schema
 
         if (collection_id is None) == (name is None):
@@ -438,6 +439,7 @@ class ImageCollectionOperations:
                 ).rowcount
                 for root, path in pairs
             )
+            clear_marks_of_keys(conn, pairs)  # #480: a collected file is listed
         return {
             "collection": collection,
             "created": created,

database/image_favorites.py

@@ -104,11 +104,14 @@ class ImageFavoriteOperations:
         """Mark one file as a favorite; repeating it is a no-op. Returns True."""
         from .models import utc_now_iso  # models imports this module's schema
 
+        from .image_removal_schema import clear_marks_of_keys
+
         with self.model.get_connection() as conn:
             conn.execute(
                 "INSERT OR IGNORE INTO image_favorites VALUES (?, ?, ?)",
                 (root_key, relative_path, utc_now_iso()),
             )
+            clear_marks_of_keys(conn, [(root_key, relative_path)])  # #480
         return True
 
     def clear_image_favorite(self, root_key: str, relative_path: str) -> bool:

database/image_removal.py

@@ -0,0 +1,348 @@
+"""Remove a file's records from the library, and its removal mark (#480).
+
+A *removal* describes one physical file the way the API resolved it from the
+walked listing (``py/api/image_delete.py``):
+
+- ``spellings``: every path string records may name it by
+  (``duplicate_spellings.Spellings.of``);
+- ``locator``: its private canonical locator;
+- ``favorites``: ``(root key, relative key)`` under every listed root holding
+  it, the keys of its favorite and its collection memberships;
+- ``category``: its own category's file key, or None.
+
+``remove_image_records`` deletes, in one ``BEGIN IMMEDIATE`` transaction:
+
+- its image records (``generated_images``) under every spelling, plus legacy
+  rows matched by ``image_path``; their saved-pair links go by cascade and the
+  workflow documents they held are released;
+- the image tags and auto-tag marks of its byte records. The annotation file
+  and byte rows go too, unless a Needs review item still cites them
+  (``media_review_items.byte_id`` is ``ON DELETE RESTRICT``): a decided or
+  revised item keeps its decision;
+- its pending, undecided Needs review items (settled as duplicate removal
+  settles them);
+- its own category, favorite and collection memberships.
+
+With ``mark`` it also writes the file's removal mark (library-only removal):
+the file stays on disk, hidden until its bytes change. Prompts, recorded runs
+and the media file itself are never touched here.
+"""
+
+import os
+
+from .annotation_schema import BYTES_TABLE, FILES_TABLE
+from .annotations import _BUMP_INDEX
+from .autotag_schema import AUTOTAG_TABLE
+from .duplicate_copies import (
+    DELETE_FAVORITE_SQL,
+    DELETE_LINK_SQL,
+    DELETE_MEMBERSHIPS_SQL,
+    _file_link_rows,
+)
+from .image_categories import DELETE_SQL as DELETE_CATEGORY_SQL
+from .image_removal_schema import (
+    META_TABLE,
+    TABLE,
+    bump_generation,
+    clear_marks,
+    has_marks_table,
+    mark_of,
+    write_mark as _write_mark,
+)
+from .library import display_title
+from .models import 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
+
+BYTES_OF_LOCATOR_SQL = (
+    f"SELECT b.id FROM {FILES_TABLE} f JOIN {BYTES_TABLE} b "  # nosec B608
+    "ON b.file_id=f.id WHERE f.locator=?"
+)
+TAG_COUNT_SQL = "SELECT COUNT(*) FROM media_image_tags WHERE byte_id=?"
+AUTOTAG_COUNT_SQL = (
+    f"SELECT COUNT(*) FROM {AUTOTAG_TABLE} WHERE byte_id=?"  # nosec B608
+)
+CLEAR_TAGS_SQL = "DELETE FROM media_image_tags WHERE byte_id=?"
+CLEAR_AUTOTAG_SQL = f"DELETE FROM {AUTOTAG_TABLE} WHERE byte_id=?"  # nosec B608
+BUMP_TAG_REVISION_SQL = (
+    f"UPDATE {BYTES_TABLE} SET tag_revision=tag_revision+1 WHERE id=?"  # nosec B608
+)
+REVIEW_REFS_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=?"
+)
+DELETE_FILE_SQL = f"DELETE FROM {FILES_TABLE} WHERE locator=?"  # nosec B608
+FILE_EXISTS_SQL = f"SELECT 1 FROM {FILES_TABLE} WHERE locator=?"  # nosec B608
+FAVORITE_EXISTS_SQL = (
+    "SELECT COUNT(*) FROM image_favorites WHERE root_key=? AND relative_path=?"
+)
+MEMBERSHIP_COUNT_SQL = (
+    "SELECT COUNT(*) FROM image_collection_items WHERE root_key=? AND relative_path=?"
+)
+CATEGORY_EXISTS_SQL = (
+    "SELECT COUNT(*) FROM image_categories WHERE root_key=? AND relative_path=?"
+)
+PAIR_LINK_COUNT_SQL = "SELECT COUNT(*) FROM image_prompt_pairs WHERE image_id=?"
+PROMPT_LINKS_SQL = "SELECT id FROM generated_images WHERE prompt_id=?"
+PROMPT_TITLE_SQL = (
+    "SELECT p.text, s.title FROM prompts p "
+    "LEFT JOIN prompt_library_state s ON s.prompt_id=p.id WHERE p.id=?"
+)
+MARKS_SQL = f"SELECT locator, size, mtime_ns FROM {TABLE}"  # nosec B608
+REVISION_SQL = f"SELECT revision FROM {META_TABLE} WHERE singleton_id=1"  # nosec B608
+MAX_ORPHAN_TITLES = 3
+RECORD_KINDS = (
+    "prompt_links",
+    "pair_links",
+    "image_tags",
+    "auto_tagged",
+    "categories",
+    "collections",
+    "favorites",
+    "review_items",
+)
+
+
+def _link_ids(conn, removal):
+    """``{image id: prompt id}`` of the records naming the file, any spelling."""
+    found = {}
+    for spelled in dict.fromkeys(removal["spellings"]):
+        for image_id, prompt_id in _file_link_rows(conn, spelled):
+            found[image_id] = prompt_id
+    return found
+
+
+def _byte_ids(conn, locator):
+    return [row[0] for row in conn.execute(BYTES_OF_LOCATOR_SQL, (locator,))]
+
+
+def file_locator(path) -> str:
+    """The locator of an absolute path (``normcase(realpath)``)."""
+    return os.path.normcase(os.path.realpath(str(path)))
+
+
+def removed_from_library(conn, path) -> bool:
+    """Whether *path* is hidden by a removal mark whose bytes still match.
+
+    A mark whose file changed (other size or ``mtime_ns``) or is gone is
+    stale: it is deleted on *conn* (the caller's write transaction), and the
+    file is not hidden.
+    """
+    locator = file_locator(path)
+    mark = mark_of(conn, locator)
+    if mark is None:
+        return False
+    try:
+        info = os.lstat(path)
+    except OSError:
+        clear_marks(conn, [locator])
+        return False
+    if (info.st_size, info.st_mtime_ns) == tuple(mark):
+        return True
+    clear_marks(conn, [locator])
+    return False
+
+
+def mark_hides(marks: dict, locator: str, path) -> bool:
+    """Whether a removal mark in *marks* hides the file at *path* (blocking).
+
+    *marks* is ``{locator: (size, mtime_ns)}``. The mark of *locator* hides
+    the file while ``os.lstat(path)`` still has the size and ``mtime_ns`` it
+    was removed with; a file that cannot be looked at is not hidden.
+    """
+    mark = marks.get(locator)
+    if mark is None:
+        return False
+    try:
+        info = os.lstat(path)
+    except OSError:
+        return False
+    return (info.st_size, info.st_mtime_ns) == tuple(mark)
+
+
+def write_mark(conn, locator, size, mtime_ns):
+    _write_mark(conn, locator, size, mtime_ns, utc_now_iso())
+
+
+class ImageRemovalOperations:
+    """PromptDatabase mixin: remove a file's records; removal marks."""
+
+    def count_removal_records(self, removals) -> dict:
+        """Counts of what removing *removals* deletes, in one read snapshot.
+
+        ``{records: {kind: n}, orphaned_prompts: {count, titles}}``: prompts
+        whose every image record is among these files lose their last image
+        (they stay in the Library).
+        """
+        from .maintenance import _read_snapshot
+
+        def read(conn):
+            totals = dict.fromkeys(RECORD_KINDS, 0)
+            links = {}
+            for removal in removals:
+                found = _link_ids(conn, removal)
+                links.update(found)
+                for image_id in found:
+                    totals["pair_links"] += conn.execute(
+                        PAIR_LINK_COUNT_SQL, (image_id,)
+                    ).fetchone()[0]
+                tagged = autotagged = False
+                for byte_id in _byte_ids(conn, removal["locator"]):
+                    tagged |= bool(
+                        conn.execute(TAG_COUNT_SQL, (byte_id,)).fetchone()[0]
+                    )
+                    autotagged |= bool(
+                        conn.execute(AUTOTAG_COUNT_SQL, (byte_id,)).fetchone()[0]
+                    )
+                totals["image_tags"] += int(tagged)
+                totals["auto_tagged"] += int(autotagged)
+                totals["review_items"] += len(
+                    conn.execute(_PENDING_OF_LOCATOR, (removal["locator"],)).fetchall()
+                )
+                totals["favorites"] += int(
+                    any(
+                        conn.execute(FAVORITE_EXISTS_SQL, key).fetchone()[0]
+                        for key in removal["favorites"]
+                    )
+                )
+                totals["collections"] += sum(
+                    conn.execute(MEMBERSHIP_COUNT_SQL, key).fetchone()[0]
+                    for key in removal["favorites"]
+                )
+                if removal.get("category"):
+                    totals["categories"] += conn.execute(
+                        CATEGORY_EXISTS_SQL, removal["category"]
+                    ).fetchone()[0]
+            totals["prompt_links"] = len(links)
+            return {
+                "records": totals,
+                "orphaned_prompts": self._orphaned_prompts(conn, links),
+            }
+
+        return _read_snapshot(self.model.db_path, read)
+
+    @staticmethod
+    def _orphaned_prompts(conn, links):
+        removed = set(links)
+        orphans = []
+        for prompt_id in dict.fromkeys(links.values()):
+            remaining = [
+                row[0]
+                for row in conn.execute(PROMPT_LINKS_SQL, (prompt_id,))
+                if row[0] not in removed
+            ]
+            if not remaining:
+                orphans.append(prompt_id)
+        titles = []
+        for prompt_id in orphans[:MAX_ORPHAN_TITLES]:
+            row = conn.execute(PROMPT_TITLE_SQL, (prompt_id,)).fetchone()
+            if row is not None:
+                titles.append(display_title((row[1],), row[0]) or "")
+        return {"count": len(orphans), "titles": titles}
+
+    def remove_image_records(self, removal, *, mark=None) -> dict:
+        """Delete every record of one file (one transaction); see the module.
+
+        ``mark``: ``(size, mtime_ns)`` to write the file's removal mark, or
+        None (the file was moved to the trash). Returns the counts deleted.
+        """
+        counts = dict.fromkeys(RECORD_KINDS, 0)
+        locator = removal["locator"]
+        with self._pair_transaction() as conn:
+            links = _link_ids(conn, removal)
+            if links:
+                documents = documents_of_rows(conn, "id", list(links))
+                for image_id in links:
+                    counts["pair_links"] += conn.execute(
+                        PAIR_LINK_COUNT_SQL, (image_id,)
+                    ).fetchone()[0]
+                    conn.execute(DELETE_LINK_SQL, (image_id,))
+                release_documents(conn, documents)
+            counts["prompt_links"] = len(links)
+            counts.update(self._remove_annotations(conn, locator))
+            for key in removal["favorites"]:
+                counts["favorites"] += conn.execute(DELETE_FAVORITE_SQL, key).rowcount
+                counts["collections"] += conn.execute(
+                    DELETE_MEMBERSHIPS_SQL, key
+                ).rowcount
+            if removal.get("category"):
+                counts["categories"] += conn.execute(
+                    DELETE_CATEGORY_SQL, tuple(removal["category"])
+                ).rowcount
+            if mark is not None:
+                write_mark(conn, locator, *mark)
+        if counts["review_items"]:
+            notify_review_change(self.model.db_path)
+        return counts
+
+    def _remove_annotations(self, conn, locator) -> dict:
+        """Tags, auto-tag marks, pending review items and, when free, the rows."""
+        counts = {"image_tags": 0, "auto_tagged": 0, "review_items": 0}
+        bytes_ = _byte_ids(conn, locator)
+        for byte_id in bytes_:
+            tags = conn.execute(CLEAR_TAGS_SQL, (byte_id,)).rowcount
+            autotags = conn.execute(CLEAR_AUTOTAG_SQL, (byte_id,)).rowcount
+            if tags:
+                conn.execute(BUMP_TAG_REVISION_SQL, (byte_id,))
+            counts["image_tags"] |= bool(tags)
+            counts["auto_tagged"] |= bool(autotags)
+        for (item_id,) in conn.execute(_PENDING_OF_LOCATOR, (locator,)).fetchall():
+            counts["review_items"] += conn.execute(_SETTLE_ITEM, (item_id,)).rowcount
+        if counts["review_items"]:
+            conn.execute(_BUMP_REVIEW_INDEX)
+        if conn.execute(FILE_EXISTS_SQL, (locator,)).fetchone():
+            if not conn.execute(REVIEW_REFS_SQL, (locator,)).fetchone()[0]:
+                conn.execute(DELETE_FILE_SQL, (locator,))
+            conn.execute(_BUMP_INDEX)
+        counts["image_tags"] = int(counts["image_tags"])
+        counts["auto_tagged"] = int(counts["auto_tagged"])
+        return counts
+
+    def removal_marks(self) -> dict:
+        """``{locator: (size, mtime_ns)}`` of every removal mark (one read)."""
+        conn = self.model.get_connection()
+        if not has_marks_table(conn):
+            return {}
+        return {row[0]: (row[1], row[2]) for row in conn.execute(MARKS_SQL)}
+
+    def removal_revision(self) -> int:
+        conn = self.model.get_connection()
+        if not has_marks_table(conn):
+            return 0
+        row = conn.execute(REVISION_SQL).fetchone()
+        return row[0] if row else 0
+
+    def clear_removal_marks(self, locators) -> int:
+        """Show these files again (their marks go); the count removed."""
+        locators = list(locators)
+        if not locators:
+            return 0
+        with self._pair_transaction() as conn:
+            removed = clear_marks(conn, locators)
+        # #498: again after the commit, so a reader that cached the marks
+        # between the in-transaction bump and the commit reloads them.
+        bump_generation()
+        return removed
+
+    def clear_hiding_marks(self, files) -> set:
+        """Delete the marks that still hide their file (#498, Return to library).
+
+        *files* are ``(locator, path)`` pairs. In one ``BEGIN IMMEDIATE``
+        transaction each mark is read again and deleted only while the file at
+        *path* still has its size and ``mtime_ns``. Returns the locators whose
+        marks went.
+        """
+        cleared = set()
+        files = list(files)
+        if not files:
+            return cleared
+        with self._pair_transaction() as conn:
+            for locator, path in files:
+                mark = mark_of(conn, locator)
+                if mark is not None and mark_hides({locator: mark}, locator, path):
+                    cleared.add(locator)
+            clear_marks(conn, sorted(cleared))
+        bump_generation()
+        return cleared

database/image_removal_schema.py

@@ -0,0 +1,213 @@
+"""Removal marks (#480): files removed from the library that stay on disk.
+
+``image_removals`` holds one row per hidden file: its private canonical
+locator (the ``media_annotation_files.locator`` form) and the ``size`` and
+``mtime_ns`` it had when it was removed. A file at that locator with other
+bytes is a new file and shows again. ``image_removals_meta`` is one row, the
+marks revision, bumped in the same transaction as every mark change so the
+workspace listing caches can tell marks changed.
+
+The group installs like ``image_favorites``: optional in old backups,
+required once a database is current. Older builds ignore it.
+"""
+
+import os
+import re
+import sqlite3
+
+from .annotation_schema import MAX_LOCATOR_LENGTH
+
+TABLE = "image_removals"
+META_TABLE = "image_removals_meta"
+TABLES = (TABLE, META_TABLE)
+_TABLE_DDL = {
+    TABLE: (
+        f"CREATE TABLE {TABLE} (locator TEXT PRIMARY KEY, "
+        "size INTEGER NOT NULL CHECK(size>=0), mtime_ns INTEGER NOT NULL, "
+        "removed_at TEXT NOT NULL) WITHOUT ROWID"
+    ),
+    META_TABLE: (
+        f"CREATE TABLE {META_TABLE} (singleton_id INTEGER PRIMARY KEY "
+        "CHECK(singleton_id=1), revision INTEGER NOT NULL DEFAULT 0 "
+        "CHECK(revision>=0))"
+    ),
+}
+_SEED_META = (
+    f"INSERT OR IGNORE INTO {META_TABLE} (singleton_id, revision) VALUES (1, 0)"
+)
+_COLUMNS = {
+    TABLE: (
+        ("locator", "TEXT", 1, 1),
+        ("size", "INTEGER", 1, 0),
+        ("mtime_ns", "INTEGER", 1, 0),
+        ("removed_at", "TEXT", 1, 0),
+    ),
+    META_TABLE: (
+        ("singleton_id", "INTEGER", 0, 1),
+        ("revision", "INTEGER", 1, 0),
+    ),
+}
+_AUTOINDEX = f"sqlite_autoindex_{TABLE}_1"
+
+
+def _compact(sql: str) -> str:
+    return re.sub(r"\s+", "", sql or "").lower()
+
+
+def _structure_error(conn: sqlite3.Connection, allow_missing: bool) -> str | None:
+    rows = conn.execute(
+        "SELECT type,name,tbl_name,sql FROM sqlite_master WHERE name IN (?,?) "
+        "OR tbl_name IN (?,?)",
+        TABLES + TABLES,
+    ).fetchall()
+    if not rows:
+        return None if allow_missing else "Missing image removal marks schema"
+    tables = {name: sql for kind, name, _tbl, sql in rows if kind == "table"}
+    others = {(kind, name) for kind, name, _tbl, _sql in rows if kind != "table"}
+    if set(tables) != set(TABLES) or others - {("index", _AUTOINDEX)}:
+        return "Image removal marks name is reserved by an unsupported schema object"
+    for table in TABLES:
+        if _compact(tables[table]) != _compact(_TABLE_DDL[table]):
+            return "Image removal marks have an invalid table definition"
+        columns = tuple(
+            (row[1], row[2].upper(), row[3], row[5])
+            for row in conn.execute(f"PRAGMA table_info({table})")
+        )
+        if columns != _COLUMNS[table]:
+            return "Image removal marks have invalid columns"
+    return None
+
+
+def _values_error(conn: sqlite3.Connection) -> str | None:
+    limit = MAX_LOCATOR_LENGTH * 4
+    if conn.execute(
+        f"SELECT 1 FROM {TABLE} WHERE typeof(locator) != 'text' "  # nosec B608
+        f"OR length(CAST(locator AS BLOB)) > {limit} OR locator = '' "
+        "OR typeof(size) != 'integer' OR typeof(mtime_ns) != 'integer' "
+        "OR typeof(removed_at) != 'text' OR length(CAST(removed_at AS BLOB)) > 64 "
+        "LIMIT 1"
+    ).fetchone():
+        return "Image removal marks contain invalid values"
+    meta = conn.execute(
+        f"SELECT singleton_id, typeof(revision) FROM {META_TABLE}"  # nosec B608
+    ).fetchall()
+    if meta != [(1, "integer")]:
+        return "Image removal marks have an invalid revision"
+    return None
+
+
+def image_removals_schema_error(
+    conn: sqlite3.Connection, *, allow_missing: bool = True
+) -> str | None:
+    """Reject unsupported schemas and invalid persisted values (reads only)."""
+    error = _structure_error(conn, allow_missing)
+    if error:
+        return error
+    exists = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (TABLE,)
+    ).fetchone()
+    return _values_error(conn) if exists else None
+
+
+def migrate_image_removals(conn: sqlite3.Connection) -> None:
+    """Install both tables atomically; validate before and after."""
+    conn.execute("SAVEPOINT image_removals_schema")
+    try:
+        error = image_removals_schema_error(conn)
+        if error:
+            raise sqlite3.DatabaseError(error)
+        for sql in _TABLE_DDL.values():
+            conn.execute(sql.replace("CREATE TABLE", "CREATE TABLE IF NOT EXISTS", 1))
+        conn.execute(_SEED_META)
+        error = image_removals_schema_error(conn, allow_missing=False)
+        if error:
+            raise sqlite3.DatabaseError(error)
+        conn.execute("RELEASE image_removals_schema")
+    except BaseException:
+        conn.execute("ROLLBACK TO image_removals_schema")
+        conn.execute("RELEASE image_removals_schema")
+        raise
+
+
+_UNMARK_SQL = f"DELETE FROM {TABLE} WHERE locator=?"  # nosec B608
+_MARK_SQL = (
+    f"INSERT OR REPLACE INTO {TABLE} "  # nosec B608
+    "(locator, size, mtime_ns, removed_at) VALUES (?, ?, ?, ?)"
+)
+_MARK_OF_SQL = f"SELECT size, mtime_ns FROM {TABLE} WHERE locator=?"  # nosec B608
+BUMP_MARKS_SQL = (
+    f"UPDATE {META_TABLE} SET revision=revision+1 WHERE singleton_id=1"  # nosec B608
+)
+
+
+# Bumped whenever this process writes or clears a mark (even in a transaction
+# that later rolls back): readers that cache the marks reload when it moves.
+_generation = 0
+
+
+def generation() -> int:
+    """The marks generation of this process (see ``_generation``)."""
+    return _generation
+
+
+def _bump() -> None:
+    global _generation
+    _generation += 1
+
+
+def bump_generation() -> None:
+    """Move the generation after a commit (a cached read made before it reloads)."""
+    _bump()
+
+
+def has_marks_table(conn: sqlite3.Connection) -> bool:
+    return (
+        conn.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (TABLE,)
+        ).fetchone()
+        is not None
+    )
+
+
+def locator_of_key(root_key: str, relative_key: str) -> str:
+    """The locator of a favorite-style file key (root key + relative key)."""
+    return os.path.normcase(os.path.join(root_key, *relative_key.split("/")))
+
+
+def mark_of(conn: sqlite3.Connection, locator: str):
+    """``(size, mtime_ns)`` of the file's removal mark, or None."""
+    if not has_marks_table(conn):
+        return None
+    row = conn.execute(_MARK_OF_SQL, (locator,)).fetchone()
+    return (row[0], row[1]) if row else None
+
+
+def write_mark(
+    conn: sqlite3.Connection, locator: str, size: int, mtime_ns: int, now: str
+):
+    conn.execute(_MARK_SQL, (locator, int(size), int(mtime_ns), now))
+    conn.execute(BUMP_MARKS_SQL)
+    _bump()
+
+
+def clear_marks(conn: sqlite3.Connection, locators) -> int:
+    """Delete the marks of *locators* on *conn* (no commit); the count removed.
+
+    Every record write for a file calls this (#480): a file with records is
+    in the library, so it is never hidden.
+    """
+    locators = list(dict.fromkeys(locators))
+    if not locators or not has_marks_table(conn):
+        return 0
+    removed = 0
+    for locator in locators:
+        removed += conn.execute(_UNMARK_SQL, (locator,)).rowcount
+    if removed:
+        conn.execute(BUMP_MARKS_SQL)
+        _bump()
+    return removed
+
+
+def clear_marks_of_keys(conn: sqlite3.Connection, file_keys) -> int:
+    """``clear_marks`` for favorite-style ``(root key, relative key)`` pairs."""
+    return clear_marks(conn, [locator_of_key(*key) for key in file_keys])

database/library.py

@@ -7,6 +7,7 @@ from contextlib import contextmanager
 
 from .library_folders import folder_condition, list_library_folders
 from .library_tokens import library_edit_token
+from .prompt_archive import ARCHIVED, SHELVED
 
 _ELIGIBLE = """(EXISTS(SELECT 1 FROM prompt_pairs ep WHERE ep.positive_prompt_id=p.id)
  OR EXISTS(SELECT 1 FROM generated_images eg WHERE eg.prompt_id=p.id)
@@ -106,6 +107,12 @@ ARCHIVE_SCOPES = {
 }
 
 
+# Shelves (#443): the parents on the shelf, or the archived ones.
+PARENT_SCOPES = {"active": SHELVED, "archived": ARCHIVED}
+# A positive pair owner that is on the shelf, as a condition on alias pp.
+SHELVED_PAIR = SHELVED.replace("p.id", "pp.positive_prompt_id")
+
+
 def _escape(value: str) -> str:
     return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
 
@@ -270,6 +277,8 @@ class LibraryOperations:
         rows = conn.execute(
             "SELECT p.id,p.text,ls.title,p.category,p.rating,p.notes,p.created_at,"
             "p.run_count,p.last_used_at,"
+            + ARCHIVED
+            + " AS archived,"
             + (f"{sort_expression} AS _sort," if sort_expression else "")
             + "(SELECT COUNT(*) FROM prompt_pairs v WHERE v.positive_prompt_id=p.id "
             "AND v.archived=0) AS variant_count,"
@@ -293,6 +302,7 @@ class LibraryOperations:
             # Usage is shown, never compared: the token hashes owner fields only.
             row["run_count"] = row["run_count"] if type(row["run_count"]) is int else 0
             row["last_used_at"] = utc_iso(row["last_used_at"])
+            row["archived"] = bool(row["archived"])
             row["edit_token"] = library_edit_token(epoch, row)
         return result
 
@@ -310,10 +320,13 @@ class LibraryOperations:
         sort: str = "newest",
         limit: int = 40,
         after: dict | None = None,
+        shelf: str = "active",
     ) -> dict:
         _limit(limit)
         if sort not in _ORDERS:
             raise ValueError("Unknown library sort order")
+        if not isinstance(shelf, str) or shelf not in PARENT_SCOPES:
+            raise ValueError("shelf must be active or archived")
         where, params = _filter(
             text, category, [] if tags is None else tags, tag_mode, folder_prefixes
         )
@@ -328,15 +341,18 @@ class LibraryOperations:
             ceiling = after["ceiling"]
         where += " AND p.id<=?"
         params.append(ceiling)
-        # One SELECT counts the filtered parents and their active variants.
-        total, variant_total = conn.execute(
-            "SELECT COUNT(*),COALESCE(SUM((SELECT COUNT(*) FROM prompt_pairs v "
-            "WHERE v.positive_prompt_id=p.id AND v.archived=0)),0) FROM "
-            + _FROM
-            + " WHERE "
-            + where,
+        # One SELECT counts the filtered parents of this scope, their active
+        # variants, and the filtered archived parents (Show archived, #443).
+        scope = PARENT_SCOPES[shelf]
+        total, variant_total, archived_total = conn.execute(
+            f"SELECT COALESCE(SUM({scope}),0),"
+            f"COALESCE(SUM(CASE WHEN {scope} THEN (SELECT COUNT(*) "
+            "FROM prompt_pairs v WHERE v.positive_prompt_id=p.id "
+            "AND v.archived=0) ELSE 0 END),0),"
+            f"COALESCE(SUM({ARCHIVED}),0) FROM " + _FROM + " WHERE " + where,
             params,
         ).fetchone()
+        where += f" AND {scope}"
         expression, direction = _ORDERS[sort]
         if after is not None:
             operator = ">" if direction == "ASC" else "<"
@@ -369,6 +385,7 @@ class LibraryOperations:
             "items": rows,
             "total": total,
             "variant_total": variant_total,
+            "archived_total": archived_total,
             # Echoed so a client can tell this read applied its tag match.
             "tag_mode": tag_mode,
             "has_more": has_more,
@@ -386,6 +403,7 @@ class LibraryOperations:
         sort: str = "newest",
         limit: int = 40,
         after: dict | None = None,
+        shelf: str = "active",
     ) -> dict:
         with self.library_snapshot(include_ceiling=True) as (conn, epoch, ceiling):
             return self._list_library(
@@ -400,6 +418,7 @@ class LibraryOperations:
                 sort=sort,
                 limit=limit,
                 after=after,
+                shelf=shelf,
             )
 
     def _is_library_positive(self, conn: sqlite3.Connection, positive_id: int) -> bool:
@@ -644,7 +663,9 @@ class LibraryOperations:
             owners = {}
             order = []
             for row in conn.execute(
-                "SELECT p.id,p.text,ls.title,p.category,p.rating,p.notes FROM "
+                "SELECT p.id,p.text,ls.title,p.category,p.rating,p.notes,"
+                + ARCHIVED
+                + " AS archived FROM "
                 + _FROM
                 + " WHERE "
                 + _ELIGIBLE
@@ -657,6 +678,7 @@ class LibraryOperations:
                     "tags": [],
                     "rating": row["rating"],
                     "notes": row["notes"],
+                    "archived": bool(row["archived"]),
                     "variants": [],
                 }
                 order.append(row["id"])
@@ -701,8 +723,9 @@ class LibraryOperations:
         """System › Overview counts from one snapshot, writing nothing.
 
         ``positive_prompts`` and ``negative_variants`` are the unfiltered
-        Library's ``total`` and ``variant_total``: eligible parents and active
-        pairs (every pair's positive is eligible). ``images`` counts indexed
+        Library's ``total`` and ``variant_total``: eligible parents on the
+        shelf (not archived, #443) and their active 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. ``review_pending`` is
@@ -710,8 +733,14 @@ class LibraryOperations:
         """
         with self.library_snapshot() as (conn, _epoch, _ceiling):
             row = conn.execute(
-                "SELECT (SELECT COUNT(*) FROM prompts p WHERE " + _ELIGIBLE + "),"
-                "(SELECT COUNT(*) FROM prompt_pairs WHERE archived=0),"
+                "SELECT (SELECT COUNT(*) FROM prompts p WHERE "
+                + _ELIGIBLE
+                + " AND "
+                + SHELVED
+                + "),"
+                "(SELECT COUNT(*) FROM prompt_pairs pp WHERE pp.archived=0 AND "
+                + SHELVED_PAIR
+                + "),"
                 "(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),"

database/library_archive.py

@@ -0,0 +1,473 @@
+"""Delete selected Library prompts; archive the paired ones (#443, D152).
+
+A selected Library parent is classified, in this order, as ``not_found``
+(missing, or not a Library parent), ``protected`` (tagged ``__protected__``;
+never changed), ``already_archived``, ``archive`` (the positive or negative of
+any saved pair, archived pair or not: archiving hides it from the shelf and
+removes nothing) or ``delete`` (in no pair: deleted exactly as the legacy
+delete does, through ``delete_prompt_rows``). Every command checks the
+storage epoch first and runs in one ``BEGIN IMMEDIATE`` transaction.
+
+The write executes what the user reviewed: it is given the reviewed archive
+and delete lists, and deletes only reviewed deletes the route backed up
+(``candidates``) whose fingerprint is unchanged since that backup.
+"""
+
+import hashlib
+import json
+import re
+import sqlite3
+from typing import Iterable
+
+from .library import _ELIGIBLE
+from .library_commands import _validate_bulk_ids, _validate_epoch
+from .models import utc_now_iso
+from .prompt_archive import ARCHIVED as _ARCHIVED
+from .prompt_archive import TABLE as ARCHIVE
+from .workflow_documents import documents_of_rows, release_documents
+
+try:
+    from ..utils.hashing import generate_prompt_hash
+except ImportError:
+    from utils.hashing import generate_prompt_hash
+
+# Ids bound per statement: the pair check binds each id twice, which stays
+# under SQLite's historical 999-variable limit (maintenance.py ID_BATCH).
+ID_BATCH = 400
+_PROTECTED = (
+    "EXISTS(SELECT 1 FROM prompt_tags pt JOIN tags t ON t.id=pt.tag_id "
+    "WHERE pt.prompt_id=p.id AND t.name='__protected__')"
+)
+_PAIRED = (
+    "EXISTS(SELECT 1 FROM prompt_pairs pp "
+    "WHERE pp.positive_prompt_id=p.id OR pp.negative_prompt_id=p.id)"
+)
+# #482: used as the negative of another positive's pair (archived or not):
+# never deleted, so that positive's variant stays (archive only).
+_NEGATIVE_OF_OTHER = (
+    "EXISTS(SELECT 1 FROM prompt_pairs op "
+    "WHERE op.negative_prompt_id=p.id AND op.positive_prompt_id!=p.id)"
+)
+# Classes in the order a prompt is tested; the first that holds wins.
+CLASSES = (
+    "not_found",
+    "protected",
+    "already_archived",
+    "not_archived",
+    "archive",
+    "delete",
+)
+# #492: the shelf a Delete… runs on. On the archived shelf an archived prompt is
+# classified by its pairs, and one restored since is ``not_archived``.
+SHELVES = ("active", "archived")
+
+
+def _check_shelf(shelf: str) -> bool:
+    """Whether ``shelf`` is the archived shelf (ValueError when unknown)."""
+    if shelf not in SHELVES:
+        raise ValueError("shelf must be active or archived")
+    return shelf == "archived"
+
+
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+
+
+def _batches(ids: list) -> Iterable[list]:
+    for start in range(0, len(ids), ID_BATCH):
+        yield ids[start : start + ID_BATCH]
+
+
+def delete_prompt_rows(conn: sqlite3.Connection, prompt_ids: list[int]) -> int:
+    """Delete prompts and their image link rows; return the prompts deleted.
+
+    The legacy delete's statements (``delete_prompt``, ``bulk_delete_prompts``)
+    in the caller's transaction: image link rows first (``image_prompt_pairs``
+    cascades, review decisions keep a NULL image), then the prompts (tags and
+    Library state cascade), then the workflow documents no row references.
+    Image files are never touched. The caller checks pairs first.
+    """
+    documents = documents_of_rows(conn, "prompt_id", prompt_ids)
+    deleted = 0
+    for chunk in _batches(list(prompt_ids)):
+        marks = ",".join("?" for _ in chunk)
+        conn.execute(
+            f"DELETE FROM generated_images WHERE prompt_id IN ({marks})",  # nosec
+            chunk,
+        )
+        deleted += conn.execute(
+            f"DELETE FROM prompts WHERE id IN ({marks})", chunk  # nosec B608
+        ).rowcount
+    release_documents(conn, documents)
+    return deleted
+
+
+class LibraryArchiveOperations:
+    """PromptDatabase mixin: classify, archive or delete, and restore parents."""
+
+    def _classify_library_delete(
+        self, conn: sqlite3.Connection, prompt_ids: list[int], shelf: str = "active"
+    ) -> dict:
+        on_archived_shelf = _check_shelf(shelf)
+        found, deletable = {}, set()
+        for chunk in _batches(prompt_ids):
+            marks = ",".join("?" for _ in chunk)
+            for row in conn.execute(
+                f"SELECT p.id,{_PROTECTED},{_ARCHIVED},{_PAIRED},"  # nosec B608
+                f"{_NEGATIVE_OF_OTHER} "
+                f"FROM prompts p WHERE p.id IN ({marks}) AND {_ELIGIBLE}",
+                chunk,
+            ):
+                protected, archived, paired, negative_of_other = row[1:5]
+                if protected:
+                    found[row[0]] = "protected"
+                elif on_archived_shelf and not archived:
+                    found[row[0]] = "not_archived"
+                elif archived and not on_archived_shelf:
+                    found[row[0]] = "already_archived"
+                elif paired:
+                    found[row[0]] = "archive"
+                    if not negative_of_other:
+                        deletable.add(row[0])
+                else:
+                    found[row[0]] = "delete"
+        classes = {name: [] for name in CLASSES}
+        for pid in prompt_ids:
+            classes[found.get(pid, "not_found")].append(pid)
+        # #482: the archive ids Delete permanently may delete with their pairs.
+        classes["deletable"] = [pid for pid in classes["archive"] if pid in deletable]
+        return classes
+
+    @staticmethod
+    def _image_links(conn: sqlite3.Connection, prompt_ids: list[int]) -> int:
+        total = 0
+        for chunk in _batches(prompt_ids):
+            marks = ",".join("?" for _ in chunk)
+            total += conn.execute(
+                "SELECT COUNT(*) FROM generated_images "  # nosec B608
+                f"WHERE prompt_id IN ({marks})",
+                chunk,
+            ).fetchone()[0]
+        return total
+
+    @staticmethod
+    def _fingerprints(conn: sqlite3.Connection, prompt_ids: list[int]) -> dict:
+        """What a safety backup holds of each prompt a delete would remove.
+
+        The prompt row (usage included), its tag ids, its Library title and
+        its image link rows (count and newest id), as a JSON-safe list.
+        """
+        prints = {}
+        for chunk in _batches(prompt_ids):
+            marks = ",".join("?" for _ in chunk)
+            for row in conn.execute(
+                "SELECT p.id,p.text,p.hash,p.category,p.rating,p.notes,"  # nosec
+                "p.updated_at,p.run_count,p.last_used_at,"
+                "(SELECT group_concat(tag_id) FROM (SELECT tag_id FROM prompt_tags "
+                "WHERE prompt_id=p.id ORDER BY tag_id)),"
+                "(SELECT title FROM prompt_library_state WHERE prompt_id=p.id),"
+                "(SELECT COUNT(*) FROM generated_images WHERE prompt_id=p.id),"
+                "(SELECT MAX(id) FROM generated_images WHERE prompt_id=p.id) "
+                f"FROM prompts p WHERE p.id IN ({marks})",
+                chunk,
+            ):
+                prints[row[0]] = [
+                    value if isinstance(value, (int, str, type(None))) else repr(value)
+                    for value in tuple(row)[1:]
+                ]
+        return prints
+
+    @staticmethod
+    def _distinct_images(conn: sqlite3.Connection, prompt_ids: list[int]) -> int:
+        """Image rows of ``prompt_ids`` (each image once; #482 deletes them)."""
+        return LibraryArchiveOperations._image_links(conn, prompt_ids)
+
+    @staticmethod
+    def _pair_prints(conn: sqlite3.Connection, prompt_ids: list[int]) -> dict:
+        """#482: each prompt's own saved pairs, as the review saw them.
+
+        Per pair (by id): its negative, archived flag, metadata, usage, ordered
+        tag ids and its image-pair links (count and newest id).
+        """
+        prints = {pid: [] for pid in prompt_ids}
+        for chunk in _batches(prompt_ids):
+            marks = ",".join("?" for _ in chunk)
+            for row in conn.execute(
+                "SELECT pp.positive_prompt_id,pp.id,pp.negative_prompt_id,"  # nosec
+                "pp.archived,pp.title,pp.category,pp.rating,pp.notes,pp.run_count,"
+                "pp.last_used_at,pp.updated_at,"
+                "(SELECT group_concat(tag_id) FROM (SELECT tag_id FROM "
+                "prompt_pair_tags WHERE pair_id=pp.id ORDER BY tag_id)),"
+                "(SELECT COUNT(*) FROM image_prompt_pairs WHERE pair_id=pp.id),"
+                "(SELECT MAX(id) FROM image_prompt_pairs WHERE pair_id=pp.id) "
+                f"FROM prompt_pairs pp WHERE pp.positive_prompt_id IN ({marks}) "
+                "ORDER BY pp.id",
+                chunk,
+            ):
+                prints[row[0]].append(
+                    [
+                        v if isinstance(v, (int, str, type(None))) else repr(v)
+                        for v in tuple(row)[1:]
+                    ]
+                )
+        return prints
+
+    @classmethod
+    def _review_digests(cls, conn: sqlite3.Connection, prompt_ids: list[int]) -> dict:
+        """#482: one digest per deletable prompt of its row and its pairs."""
+        prompts = cls._fingerprints(conn, prompt_ids)
+        pairs = cls._pair_prints(conn, prompt_ids)
+        return {
+            pid: hashlib.sha256(
+                json.dumps(
+                    [prompts.get(pid), pairs[pid]], separators=(",", ":")
+                ).encode("utf-8")
+            ).hexdigest()
+            for pid in prompt_ids
+        }
+
+    @staticmethod
+    def _paired_counts(
+        conn: sqlite3.Connection, prompt_ids: list[int], selected: list[int]
+    ) -> dict:
+        """#482: what Delete permanently would remove with ``prompt_ids``."""
+        pairs = archived = variants = 0
+        negatives = set()
+        for chunk in _batches(prompt_ids):
+            marks = ",".join("?" for _ in chunk)
+            for archived_flag, negative, positive in conn.execute(
+                "SELECT archived,negative_prompt_id,positive_prompt_id "  # nosec
+                f"FROM prompt_pairs WHERE positive_prompt_id IN ({marks})",
+                chunk,
+            ):
+                pairs += 1
+                archived += 1 if archived_flag else 0
+                if negative is not None:
+                    variants += 1
+                    if negative != positive:
+                        negatives.add(negative)
+        return {
+            "pairs": pairs,
+            "archived_pairs": archived,
+            "variants": variants,
+            "kept_negatives": len(negatives - set(selected)),
+        }
+
+    @staticmethod
+    def _checked_ids(prompt_ids: list[int], expected_epoch: str) -> list[int]:
+        _validate_epoch(expected_epoch)
+        _validate_bulk_ids(prompt_ids)
+        return list(dict.fromkeys(prompt_ids))
+
+    def classify_library_delete(
+        self, prompt_ids: list[int], *, expected_epoch: str, shelf: str = "active"
+    ) -> dict:
+        """What a delete of ``prompt_ids`` would do now (reads only).
+
+        Returns the id lists per class, in request order, ``image_links``
+        (the image link rows the ``delete`` class would remove) and
+        ``fingerprints`` of the ``delete`` class (``_fingerprints``). On the
+        archived ``shelf`` (#492) archived prompts are classified by their pairs.
+        """
+        _check_shelf(shelf)
+        prompt_ids = self._checked_ids(prompt_ids, expected_epoch)
+        with self.library_snapshot() as (conn, _epoch, _ceiling):
+            epoch = self._library_epoch(conn, expected_epoch)
+            classes = self._classify_library_delete(conn, prompt_ids, shelf)
+            deletable = classes["deletable"]
+            return {
+                "library_epoch": epoch,
+                **classes,
+                "image_links": self._image_links(conn, classes["delete"]),
+                "fingerprints": self._fingerprints(conn, classes["delete"]),
+                # #482: Delete permanently, with the deletable prompts' pairs.
+                "review_digests": self._review_digests(conn, deletable),
+                "paired_counts": self._paired_counts(conn, deletable, prompt_ids),
+                "paired_image_links": self._distinct_images(conn, deletable),
+            }
+
+    @staticmethod
+    def _repair_hash(conn: sqlite3.Connection, prompt_id: int) -> None:
+        """Give an archived prompt its canonical hash, so ingestion finds it.
+
+        Scans, the monitor and node saves resolve prompts by hash; a stale or
+        missing one would make them insert a visible copy (Q3). When another
+        row already holds the canonical hash, lookups find that row and no new
+        copy is made, so nothing is written.
+        """
+        text, stored = conn.execute(
+            "SELECT text,hash FROM prompts WHERE id=?", (prompt_id,)
+        ).fetchone()
+        canonical = generate_prompt_hash(text) if isinstance(text, str) else None
+        if canonical is None or stored == canonical:
+            return
+        if conn.execute(
+            "SELECT 1 FROM prompts WHERE hash=? AND id!=?", (canonical, prompt_id)
+        ).fetchone():
+            return
+        conn.execute("UPDATE prompts SET hash=? WHERE id=?", (canonical, prompt_id))
+
+    def archive_or_delete_library_prompts(
+        self,
+        archive_ids: list[int],
+        delete_ids: list[int],
+        *,
+        expected_epoch: str,
+        candidates: dict | None,
+        delete_paired: dict | None = None,
+        shelf: str = "active",
+    ) -> dict:
+        """Archive and delete what the user reviewed, all or nothing.
+
+        ``archive_ids`` and ``delete_ids`` are the reviewed classes.
+        ``candidates`` maps each reviewed delete the route backed up to its
+        fingerprint then (None: every reviewed delete, unchecked; tests and
+        callers without a backup). A reviewed delete is deleted only when it
+        still classifies ``delete`` and its fingerprint is unchanged; one that
+        is now paired, and a reviewed archive now unpaired, are archived (the
+        restorable direction); anything else is kept and counted.
+
+        ``delete_paired`` (#482) maps reviewed archive ids the user chose to
+        Delete permanently to their review digest. Each is deleted with its
+        own saved pairs only while it is still deletable and its digest is
+        unchanged; otherwise it is archived and counted ``changed``.
+
+        On the archived ``shelf`` (#492) the ids are archived already: nothing
+        is archived or rewritten, every reviewed id not deleted (protected or
+        changed) counts ``changed``, and one restored since ``not_archived``.
+        """
+        on_archived_shelf = _check_shelf(shelf)
+        _validate_epoch(expected_epoch)
+        for ids in (archive_ids, delete_ids):
+            if not isinstance(ids, list) or any(
+                type(pid) is not int or not 1 <= pid <= 2**63 - 1 for pid in ids
+            ):
+                raise ValueError("prompt ids must be lists of positive integers")
+        reviewed_delete = set(delete_ids)
+        delete_paired = {} if delete_paired is None else delete_paired
+        if not isinstance(delete_paired, dict) or any(
+            type(pid) is not int
+            or not isinstance(digest, str)
+            or not _DIGEST.match(digest)
+            for pid, digest in delete_paired.items()
+        ):
+            raise ValueError("delete_paired must map prompt ids to review digests")
+        if not set(delete_paired) <= set(archive_ids):
+            raise ValueError("A permanent delete must be a reviewed archive id")
+        if not archive_ids and not delete_ids:
+            raise ValueError("Nothing to delete or archive")
+        if reviewed_delete & set(archive_ids):
+            raise ValueError("A prompt cannot be both archived and deleted")
+        prompt_ids = list(dict.fromkeys([*archive_ids, *delete_ids]))
+        with self._pair_transaction() as conn:
+            epoch = self._library_epoch(conn, expected_epoch)
+            classes = self._classify_library_delete(conn, prompt_ids, shelf)
+            now_prints = self._fingerprints(conn, classes["delete"])
+            deletes, archives, changed = [], [], 0
+            paired_now = set(classes["deletable"])
+            chosen = [pid for pid in classes["archive"] if pid in delete_paired]
+            digests = self._review_digests(
+                conn, [pid for pid in chosen if pid in paired_now]
+            )
+            paired_deletes = []
+            for pid in classes["archive"]:
+                if pid not in delete_paired:
+                    archives.append(pid)
+                elif digests.get(pid) == delete_paired[pid]:
+                    paired_deletes.append(pid)
+                else:
+                    archives.append(pid)  # changed since the review: restorable
+                    changed += 1
+            for pid in classes["delete"]:
+                if pid not in reviewed_delete:
+                    archives.append(pid)  # reviewed as archive, now unpaired
+                    changed += 1 if pid in delete_paired else 0
+                elif candidates is None or candidates.get(pid) == now_prints[pid]:
+                    deletes.append(pid)
+                else:
+                    changed += 1
+            changed += len(classes["protected"])
+            if on_archived_shelf:
+                # Already archived: the rest stay as they are, each one counted.
+                archives = []
+                changed = len(prompt_ids) - len(deletes) - len(paired_deletes)
+                changed -= len(classes["not_found"]) + len(classes["not_archived"])
+            image_links = self._image_links(conn, [*deletes, *paired_deletes])
+            now = utc_now_iso()
+            for pid in archives:
+                self._repair_hash(conn, pid)
+            conn.executemany(
+                f"INSERT INTO {ARCHIVE}(prompt_id, archived_at) VALUES (?, ?)",
+                [(pid, now) for pid in archives],
+            )
+            # A changed row is the newest edit the restore fingerprint reads.
+            conn.executemany(
+                "UPDATE prompts SET updated_at=? WHERE id=?",
+                [(now, pid) for pid in archives],
+            )
+            # #482: the image-pair links (RESTRICT) go first, then the pairs
+            # (pair tags CASCADE, review decisions SET NULL), then the prompts.
+            pairs_removed = 0
+            for chunk in _batches(paired_deletes):
+                marks = ",".join("?" for _ in chunk)
+                pairs_of = (
+                    "SELECT id FROM prompt_pairs "  # nosec B608
+                    f"WHERE positive_prompt_id IN ({marks})"
+                )
+                conn.execute(
+                    f"DELETE FROM image_prompt_pairs WHERE pair_id IN ({pairs_of})",
+                    chunk,
+                )
+                pairs_removed += conn.execute(
+                    "DELETE FROM prompt_pairs "  # nosec B608
+                    f"WHERE positive_prompt_id IN ({marks})",
+                    chunk,
+                ).rowcount
+            deleted = delete_prompt_rows(conn, [*deletes, *paired_deletes])
+            return {
+                "library_epoch": epoch,
+                "deleted": deleted,
+                "archived": len(archives),
+                "already_archived": len(classes["already_archived"]),
+                "not_archived": len(classes["not_archived"]),
+                "not_found": len(classes["not_found"]),
+                "changed": changed,
+                "image_links": image_links,
+                "pairs_removed": pairs_removed,
+            }
+
+    def restore_library_prompts(
+        self, prompt_ids: list[int], *, expected_epoch: str
+    ) -> dict:
+        """Put archived prompts back on the shelf, all or nothing.
+
+        Every requested id with an archive row is restored, whatever its
+        protection or Library parent state: restoring only un-hides it.
+        """
+        prompt_ids = self._checked_ids(prompt_ids, expected_epoch)
+        with self._pair_transaction() as conn:
+            epoch = self._library_epoch(conn, expected_epoch)
+            restored, existing = [], set()
+            for chunk in _batches(prompt_ids):
+                marks = ",".join("?" for _ in chunk)
+                for pid, archived in conn.execute(
+                    f"SELECT p.id,{_ARCHIVED} FROM prompts p "  # nosec B608
+                    f"WHERE p.id IN ({marks})",
+                    chunk,
+                ):
+                    existing.add(pid)
+                    if archived:
+                        restored.append(pid)
+            now = utc_now_iso()
+            conn.executemany(
+                f"DELETE FROM {ARCHIVE} WHERE prompt_id=?", [(pid,) for pid in restored]
+            )
+            conn.executemany(
+                "UPDATE prompts SET updated_at=? WHERE id=?",
+                [(now, pid) for pid in restored],
+            )
+            return {
+                "library_epoch": epoch,
+                "restored": len(restored),
+                "unchanged": len(existing) - len(restored),
+                "not_found": len(prompt_ids) - len(existing),
+            }

database/maintenance.py

@@ -15,6 +15,8 @@ change:
   ``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.
+  It also forgets the removal marks (#480) that hide nothing any more: the
+  file is gone or changed, under a readable source (#501, ``_stale_marks``).
 
 ``preview_maintenance`` reads one snapshot on its own ``mode=ro`` connection
 (``health.readonly_uri``) and closes it in ``finally``; files are looked at
@@ -41,6 +43,8 @@ from pathlib import Path
 
 from .execution_contexts import LIVE_HINT_CTES
 from .health import BATCH_ROWS, link_states, readable_roots, readonly_uri
+from .image_removal_schema import TABLE as MARKS_TABLE
+from .image_removal_schema import clear_marks, has_marks_table
 from .pairs import PairDependencyError
 from .workflow_documents import documents_of_rows, release_documents
 
@@ -85,6 +89,12 @@ PROTECTIONS = (
         "with Library state (a title or an explicit parent)",
         "with Library state (a title or an explicit parent)",
     ),
+    (
+        # #443: an archived prompt is restorable, never pruned.
+        "EXISTS (SELECT 1 FROM prompt_archive pa WHERE pa.prompt_id = p.id)",
+        "archived in the Library",
+        "archived in the Library",
+    ),
     (
         "p.id IN (SELECT prompt_id FROM live_hint_prompts)",
         "used by recorded runs",
@@ -93,7 +103,8 @@ PROTECTIONS = (
 )
 
 # Exempt references: images, pairs, the __protected__ tag, Library parent
-# state, and live recorded-run hints (computed once, see LIVE_HINT_CTES).
+# state, the Library archive, and live recorded-run hints (computed once,
+# see LIVE_HINT_CTES).
 ORPHANED_PROMPTS_SQL = (
     "WITH "
     + LIVE_HINT_CTES
@@ -187,6 +198,8 @@ class MaintenanceDraft:
     protected: dict
     media: dict
     details: list = field(default_factory=list)
+    # missing_links only: locators of removal marks whose file is gone (#501).
+    marks: list = field(default_factory=list)
 
     def public(self):
         """The plan fields a response may carry (no fingerprint, no targets)."""
@@ -289,6 +302,90 @@ def _delete_ids(conn, table, ids):
     return removed
 
 
+def _mark_rows(conn, only=None):
+    """``[(locator, size, mtime_ns)]`` of the removal marks (all, or those
+    among *only*), sorted by locator."""
+    if not has_marks_table(conn):
+        return []
+    sql = f"SELECT locator, size, mtime_ns FROM {MARKS_TABLE}"  # nosec B608
+    if only is None:
+        return sorted(tuple(row) for row in conn.execute(sql))
+    found = []
+    for batch in _batches(sorted(only)):
+        found.extend(
+            tuple(row)
+            for row in conn.execute(
+                f"{sql} WHERE locator IN ({_marks(batch)})", batch  # nosec B608
+            )
+        )
+    return sorted(found)
+
+
+def _lists_something(folder):
+    """Whether *folder* holds at least one entry (an unplugged drive's mount
+    point, or an unbound volume, is an empty folder that reads fine)."""
+    try:
+        with os.scandir(folder) as entries:
+            return next(entries, None) is not None
+    except OSError:
+        return False
+
+
+def _name_listed(path):
+    """Whether *path*'s folder lists its name, compared under ``normcase``.
+
+    A locator is ``normcase``d; on a case-sensitive NTFS folder ``lstat`` of
+    the lower-cased spelling fails for a file that is there.
+    """
+    folder, name = os.path.split(path)
+    wanted = os.path.normcase(name)
+    try:
+        with os.scandir(folder) as entries:
+            return any(os.path.normcase(entry.name) == wanted for entry in entries)
+    except OSError:
+        return True  # cannot tell: keep the mark
+
+
+def _stale_mark(locator, size, mtime_ns):
+    """Whether the file of a mark is gone or has other bytes (blocking)."""
+    try:
+        info = os.lstat(locator)
+    except (FileNotFoundError, NotADirectoryError):
+        return os.path.isdir(os.path.dirname(locator)) and not _name_listed(locator)
+    except OSError:
+        return False
+    return (info.st_size, info.st_mtime_ns) != (size, mtime_ns)
+
+
+def _stale_marks(marks, roots):
+    """``[(locator, owner)]`` of the marks that hide nothing any more (#501).
+
+    *marks* are ``(locator, size, mtime_ns)`` rows. A mark is stale when its
+    file was changed, or is gone from a folder that still exists. Only marks
+    under a source that can be read now and lists something are judged (an
+    unplugged drive's marks, or its empty mount point's, stay); any doubt
+    keeps the mark. *owner* is the index of the longest source holding it.
+    Locators are ``normcase(realpath)`` paths, so the sources are too.
+    """
+    readable = readable_roots(roots)
+    prefixes = [
+        os.path.normcase(os.path.realpath(root)).rstrip("\\/") + os.sep
+        for root in roots
+    ]
+    judged = {}
+    stale = []
+    for locator, size, mtime_ns in marks:
+        owners = [i for i, prefix in enumerate(prefixes) if locator.startswith(prefix)]
+        if not owners:
+            continue  # under no source now (a source removed from the settings)
+        owner = max(owners, key=lambda i: len(prefixes[i]))
+        if owner not in judged:
+            judged[owner] = readable[owner] and _lists_something(roots[owner])
+        if judged[owner] and _stale_mark(locator, size, mtime_ns):
+            stale.append((locator, owner))
+    return stale
+
+
 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)
@@ -431,8 +528,11 @@ class MaintenanceOperations:
         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)
+            rows, marks = _read_snapshot(
+                self.model.db_path,
+                lambda conn: (self._link_rows(conn), _mark_rows(conn)),
+            )
+            return self._plan_missing_links(rows, roots, _stale_marks(marks, roots))
         reader = (
             self._plan_duplicate_prompts
             if operation == "duplicate_prompts"
@@ -563,13 +663,15 @@ class MaintenanceOperations:
         )
 
     @staticmethod
-    def _links_fingerprint(candidates):
+    def _links_fingerprint(candidates, stale=()):
         fingerprint = _Fingerprint("missing_links")
         for row, owner in candidates:
             fingerprint.add([row[0], row[1], row[3], owner])
+        for locator, owner in stale:
+            fingerprint.add(["mark", locator, owner])
         return fingerprint.hexdigest()
 
-    def _plan_missing_links(self, rows, roots):
+    def _plan_missing_links(self, rows, roots, stale=()):
         readable = readable_roots(roots)
         candidates, unavailable, outside = [], 0, 0
         for row, owner, state in link_states(rows, roots, readable):
@@ -597,29 +699,47 @@ class MaintenanceOperations:
                 )
             )
         count = len(candidates)
+        parts = []
+        if count:
+            parts.append(
+                _plural(count, "link to a missing file", "links to missing files")
+            )
+        if stale:
+            parts.append(
+                _plural(
+                    len(stale),
+                    "removed image whose file is gone or changed",
+                    "removed images whose files are gone or changed",
+                )
+            )
+        details = [
+            {
+                "label": _relative(row[1], roots[owner]),
+                "detail": f"{_source_name(roots[owner], owner)} · the file is missing",
+            }
+            for row, owner in candidates
+        ] + [
+            {
+                "label": _relative(locator, os.path.realpath(roots[owner])),
+                "detail": (
+                    f"{_source_name(roots[owner], owner)} · removed image, "
+                    "the file is gone or changed"
+                ),
+            }
+            for locator, owner in stale
+        ]
         return MaintenanceDraft(
             operation="missing_links",
-            fingerprint=self._links_fingerprint(candidates),
+            fingerprint=self._links_fingerprint(candidates, stale),
             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"
-                ),
+                "count": count + len(stale),
+                "label": "; ".join(parts) or "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]
-            ],
+            details=details[:MAX_DETAILS],
+            marks=[locator for locator, _owner in stale],
         )
 
     def _plan_optimize(self):
@@ -669,14 +789,18 @@ class MaintenanceOperations:
 
     # ── apply ─────────────────────────────────────────────────────────
 
-    def apply_maintenance(self, operation, fingerprint, targets, roots=()) -> dict:
+    def apply_maintenance(
+        self, operation, fingerprint, targets, roots=(), marks=()
+    ) -> 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}``).
+        (``{prompt_id[, kept_id]}`` or ``{image_path}``). ``marks`` are a
+        missing-links plan's stale removal marks; that apply also returns
+        ``marks``, how many it forgot.
         """
         if operation not in MAINTENANCE_OPERATIONS or operation == "workflow_storage":
             raise ValueError(f"Unknown maintenance operation {operation!r}")
@@ -689,9 +813,12 @@ class MaintenanceOperations:
         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:
+            if operation == "missing_links":
+                return self._apply_missing_links(
+                    conn, fingerprint, targets, roots, list(marks)
+                )
             return appliers[operation](conn, fingerprint, targets, roots)
 
     def _apply_duplicate_prompts(self, conn, fingerprint, targets, _roots):
@@ -720,7 +847,7 @@ class MaintenanceOperations:
         ]
         return {"changed": changed, "rows": rows}
 
-    def _apply_missing_links(self, conn, fingerprint, targets, roots):
+    def _apply_missing_links(self, conn, fingerprint, targets, roots, marks):
         rows = []
         for batch in _batches(sorted(targets)):
             rows.extend(
@@ -737,10 +864,14 @@ class MaintenanceOperations:
             if state != "missing":  # back, or its source went away
                 raise PlanChanged("missing_links")
             candidates.append((row, owner))
-        if self._links_fingerprint(candidates) != fingerprint:
+        stale = _stale_marks(_mark_rows(conn, marks) if marks else [], roots)
+        if [locator for locator, _owner in stale] != marks:  # a mark went or is valid
+            raise PlanChanged("missing_links")
+        if self._links_fingerprint(candidates, stale) != fingerprint:
             raise PlanChanged("missing_links")
         changed = _delete_ids(conn, "generated_images", [row[0] for row in rows])
         return {
             "changed": changed,
+            "marks": clear_marks(conn, marks),
             "rows": [{"image_path": row[1]} for row in rows[:MAX_RESULT_ROWS]],
         }

database/models.py

@@ -44,6 +44,8 @@ try:
 except ImportError:
     from utils.hashing import register_prompt_functions
 from .image_categories import image_categories_schema_error, migrate_image_categories
+from .image_removal_schema import image_removals_schema_error, migrate_image_removals
+from .prompt_archive import migrate_prompt_archive, prompt_archive_schema_error
 from .workflow_documents import (
     DOCUMENT_ID_COLUMNS,
     migrate_workflow_documents,
@@ -366,6 +368,10 @@ class PromptModel:
         migrate_autotag_state(conn)
         # Image categories (#332): independent of every table above.
         migrate_image_categories(conn)
+        # The Library parent archive (#443): independent of every table above.
+        migrate_prompt_archive(conn)
+        # Removal marks (#480): independent of every table above.
+        migrate_image_removals(conn)
         # Last: the older generated_images rebuilds run only before file_path.
         migrate_workflow_documents(conn)
 
@@ -1242,6 +1248,16 @@ class PromptModel:
             )
             if categories_error:
                 return False, categories_error
+            archive_error = prompt_archive_schema_error(
+                conn, allow_missing=not require_library_state
+            )
+            if archive_error:
+                return False, archive_error
+            removals_error = image_removals_schema_error(
+                conn, allow_missing=not require_library_state
+            )
+            if removals_error:
+                return False, removals_error
             views_error = saved_views_schema_error(
                 conn, allow_missing=not require_library_state
             )

database/operations.py

@@ -18,12 +18,14 @@ from .models import PromptModel, normalize_image_path, utc_now_iso
 from .pairs import PairDependencyError, PairOperations  # noqa: F401 (re-exported)
 from .library import LibraryOperations, titled
 from .image_favorites import ImageFavoriteOperations
+from .image_removal import ImageRemovalOperations, removed_from_library
 from .image_collections import ImageCollectionOperations
 from .annotations import AnnotationOperations
 from .review import ReviewOperations
 from .review_decisions import ReviewDecisionOperations
 from .saved_views import SavedViewOperations
 from .library_commands import LibraryCommandOperations
+from .library_archive import LibraryArchiveOperations, delete_prompt_rows
 from .vocabulary import VocabularyOperations
 from .execution_history import ExecutionHistoryOperations
 from .execution_contexts import ExecutionContextOperations
@@ -448,6 +450,7 @@ class PromptDatabase(
     PairOperations,
     LibraryOperations,
     LibraryCommandOperations,
+    LibraryArchiveOperations,
     VocabularyOperations,
     ExecutionHistoryOperations,
     ExecutionContextOperations,
@@ -465,6 +468,7 @@ class PromptDatabase(
     WorkflowStorageOperations,
     CategoryImportOperations,
     ImageCategoryOperations,
+    ImageRemovalOperations,
 ):
     """Database operations class for managing prompts."""
 
@@ -1806,6 +1810,11 @@ class PromptDatabase(
         """
         if not isinstance(metadata, dict):
             metadata = {}
+        if removed_from_library(conn, image_path):
+            # #480: the user removed this exact file from the library; its
+            # bytes are unchanged, so nothing links it again.
+            self.logger.debug("Not linking a file removed from the library")
+            return 0
         filename = os.path.basename(image_path)
         file_path = normalize_image_path(image_path)
         file_size, width, height, image_format = _coerce_file_info(metadata)
@@ -2344,16 +2353,10 @@ class PromptDatabase(
         Returns:
             Number of prompts actually deleted.
         """
-        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)
+            # The workspace Library's delete runs the same statements (#443).
+            count = delete_prompt_rows(conn, list(dict.fromkeys(prompt_ids)))
             conn.commit()
         return count
 

database/prompt_archive.py

@@ -0,0 +1,107 @@
+"""Library parent archive (#443, D152): prompts hidden from the shelf, restorable.
+
+A row means the Library parent is archived; no row means it is on the shelf.
+Nothing else about the prompt changes: its text, metadata, tags, run count,
+image links, pairs and recorded runs stay. Restore deletes the row. Deleting
+the prompt (any path) drops the row by cascade.
+
+A table of its own, not a column: ``prompt_library_state`` is validated by its
+exact definition, so a new column there would make older builds refuse the
+upgraded database, while older builds ignore an unknown table (they show the
+archived prompts again and keep the rows). Optional in old backups, required
+once a database is current.
+"""
+
+import re
+import sqlite3
+
+TABLE = "prompt_archive"
+MAX_STAMP_BYTES = 64
+# What ``utc_now_iso`` writes starts with a date; anything else was not written here.
+_STAMP_GLOB = "[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]T*"
+_DDL = (
+    f"CREATE TABLE {TABLE} (prompt_id INTEGER PRIMARY KEY, "
+    "archived_at TEXT NOT NULL, "
+    "FOREIGN KEY(prompt_id) REFERENCES prompts(id) ON DELETE CASCADE)"
+)
+_COLUMNS = (("prompt_id", "INTEGER", 0, 1), ("archived_at", "TEXT", 1, 0))
+_FOREIGN_KEYS = {("prompt_id", "prompts", "id", "CASCADE")}
+# A predicate on ``p`` (the prompts alias): the parent is not archived.
+SHELVED = f"NOT EXISTS(SELECT 1 FROM {TABLE} pa WHERE pa.prompt_id=p.id)"
+ARCHIVED = f"EXISTS(SELECT 1 FROM {TABLE} pa WHERE pa.prompt_id=p.id)"
+
+
+def _compact(sql: str) -> str:
+    return re.sub(r"\s+", "", sql or "").lower()
+
+
+def _structure_error(conn: sqlite3.Connection, allow_missing: bool) -> str | None:
+    objects = conn.execute(
+        "SELECT type,sql FROM sqlite_master WHERE name=? "
+        "OR (type IN ('index','trigger') AND tbl_name=?)",
+        (TABLE, TABLE),
+    ).fetchall()
+    if not objects:
+        return None if allow_missing else "Missing prompt archive schema"
+    tables = [sql for kind, sql in objects if kind == "table"]
+    if len(tables) != 1 or len(objects) != 1:
+        return "Prompt archive name is reserved by an unsupported schema object"
+    if _compact(tables[0]) != _compact(_DDL):
+        return "Prompt archive has an invalid table definition"
+    columns = tuple(
+        (row[1], row[2].upper(), row[3], row[5])
+        for row in conn.execute(f"PRAGMA table_info({TABLE})")
+    )
+    if columns != _COLUMNS:
+        return "Prompt archive 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:
+        return "Prompt archive has invalid foreign key definitions"
+    return None
+
+
+def prompt_archive_schema_error(
+    conn: sqlite3.Connection, *, allow_missing: bool = True
+) -> str | None:
+    """Reject an unsupported archive schema or values; reads only.
+
+    A missing table is acceptable for backups that predate it unless
+    ``allow_missing`` is false.
+    """
+    error = _structure_error(conn, allow_missing)
+    if error is not None:
+        return error
+    if not conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (TABLE,)
+    ).fetchone():
+        return None
+    if conn.execute(f"PRAGMA foreign_key_check({TABLE})").fetchone():
+        return "Prompt archive contains foreign key violations"
+    if conn.execute(
+        f"SELECT 1 FROM {TABLE} WHERE typeof(archived_at)!='text' "  # nosec B608
+        f"OR length(CAST(archived_at AS BLOB))>{MAX_STAMP_BYTES} "
+        f"OR archived_at NOT GLOB '{_STAMP_GLOB}' LIMIT 1"
+    ).fetchone():
+        return "Prompt archive contains invalid values"
+    return None
+
+
+def migrate_prompt_archive(conn: sqlite3.Connection) -> None:
+    """Install the table atomically; validate before and after (no backfill)."""
+    conn.execute("SAVEPOINT prompt_archive_schema")
+    try:
+        error = _structure_error(conn, True)
+        if error:
+            raise sqlite3.DatabaseError(error)
+        conn.execute(_DDL.replace("CREATE TABLE", "CREATE TABLE IF NOT EXISTS", 1))
+        error = _structure_error(conn, False)
+        if error:
+            raise sqlite3.DatabaseError(error)
+        conn.execute("RELEASE prompt_archive_schema")
+    except BaseException:
+        conn.execute("ROLLBACK TO prompt_archive_schema")
+        conn.execute("RELEASE prompt_archive_schema")
+        raise

database/restore_stage.py

@@ -149,6 +149,7 @@ def library_summary(conn: sqlite3.Connection) -> Dict[str, int]:
     collections (#331).
     """
     from .library import _ELIGIBLE
+    from .prompt_archive import SHELVED, TABLE as ARCHIVE
 
     has_state = conn.execute(
         "SELECT 1 FROM sqlite_master WHERE type='table' AND "
@@ -157,9 +158,15 @@ def library_summary(conn: sqlite3.Connection) -> Dict[str, int]:
     has_pairs = conn.execute(
         "SELECT 1 FROM sqlite_master WHERE type='table' AND name='prompt_pairs'"
     ).fetchone()
+    has_archive = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (ARCHIVE,)
+    ).fetchone()
     if has_state and has_pairs:
+        # Archived parents (#443) are off the shelf, as in library_counts.
         positives = conn.execute(
-            "SELECT COUNT(*) FROM prompts p WHERE " + _ELIGIBLE
+            "SELECT COUNT(*) FROM prompts p WHERE "
+            + _ELIGIBLE
+            + (" AND " + SHELVED if has_archive else "")
         ).fetchone()[0]
     else:
         positives = _count(conn, "prompts")

database/vocabulary.py

@@ -20,7 +20,8 @@ counted, hashed into the token and renamed with the prompts and pairs.
 
 import sqlite3
 
-from .library import _ELIGIBLE, UNTAGGED, _escape, _limit
+from .library import _ELIGIBLE, SHELVED_PAIR, UNTAGGED, _escape, _limit
+from .prompt_archive import SHELVED
 from .library_commands import _TOKEN, LibraryCommandError, _validate_epoch
 from .library_tokens import canonical_token
 from .models import utc_now_iso
@@ -40,17 +41,21 @@ _IMAGE_FILES = (
 
 def _tag_rows(page: str, order: str = "page.id") -> str:
     """Count rows for the registry rows selected by ``page`` (id, name)."""
-    # Eligible parent components carrying a tag in the page, plus the
-    # positive parent of every active pair carrying it (always eligible).
+    # Eligible parent components on the shelf carrying a tag in the page,
+    # plus the positive parent of every active pair carrying it (always
+    # eligible) when that parent is on the shelf: archived parents (#443)
+    # are hidden with their pairs, so Browse lists what was counted.
     return (
         "WITH page AS (" + page + "),"
         "owners(tag_id,pid) AS ("
         "SELECT pt.tag_id,p.id FROM prompts p "
         "JOIN prompt_tags pt ON pt.prompt_id=p.id "
         "WHERE pt.tag_id IN (SELECT id FROM page) AND " + _ELIGIBLE + " "
+        "AND " + SHELVED + " "
         "UNION SELECT ppt.tag_id,pp.positive_prompt_id FROM prompt_pairs pp "
         "JOIN prompt_pair_tags ppt ON ppt.pair_id=pp.id "
-        "WHERE pp.archived=0 AND ppt.tag_id IN (SELECT id FROM page)),"
+        "WHERE pp.archived=0 AND " + SHELVED_PAIR + " "
+        "AND ppt.tag_id IN (SELECT id FROM page)),"
         "images(tag_id,n) AS (" + _IMAGE_FILES + " "
         "WHERE mit.tag_id IN (SELECT id FROM page) GROUP BY mit.tag_id) "
         "SELECT page.id,page.name,COUNT(DISTINCT owners.pid) AS prompt_count,"
@@ -79,8 +84,10 @@ _RANKED_TAG_PAGE = (
     "WITH owners(tag_id,pid) AS ("
     "SELECT pt.tag_id,p.id FROM prompts p "
     "JOIN prompt_tags pt ON pt.prompt_id=p.id WHERE " + _ELIGIBLE + " "
+    "AND " + SHELVED + " "
     "UNION SELECT ppt.tag_id,pp.positive_prompt_id FROM prompt_pairs pp "
-    "JOIN prompt_pair_tags ppt ON ppt.pair_id=pp.id WHERE pp.archived=0),"
+    "JOIN prompt_pair_tags ppt ON ppt.pair_id=pp.id WHERE pp.archived=0 "
+    "AND " + SHELVED_PAIR + "),"
     "counted AS (SELECT t.id,t.name,COUNT(DISTINCT o.pid) AS prompt_count "
     "FROM tags t LEFT JOIN owners o ON o.tag_id=t.id WHERE {search} "
     "GROUP BY t.id),"
@@ -94,7 +101,13 @@ _RANKED_TAG_PAGE = (
     "ORDER BY page.prompt_count {direction},page.id"
 )
 _UNTAGGED_COUNT = (
-    "SELECT COUNT(*) FROM prompts p WHERE (" + _ELIGIBLE + ") AND " + UNTAGGED
+    "SELECT COUNT(*) FROM prompts p WHERE ("
+    + _ELIGIBLE
+    + ") AND "
+    + UNTAGGED
+    # Untagged prompts opens the shelf, which hides archived parents (#443).
+    + " AND "
+    + SHELVED
 )
 _TAG_ONE = _tag_rows("SELECT id,name FROM tags WHERE id=?")
 # Every owner kind a tag can sit on, for the delete confirmation.
@@ -134,7 +147,9 @@ def _validate_tag_id(tag_id: object) -> None:
 
 
 # Category values in Tags & categories (#332 §7): the prompt-backed values
-# (nonblank values on eligible parents or on active pairs, grouped exactly, so
+# (nonblank values on eligible parents or on active pairs; ``prompt_count``
+# counts only parents on the shelf, so a value only archived parents (#443)
+# hold stays listed with 0, as a tag does; grouped exactly, so
 # whitespace and case variants stay distinct; /library/options lists the same
 # prompt-backed set with its own query) plus the values only image rows hold.
 # A prompt-backed value is ordered by its oldest owning positive; an image-only
@@ -143,15 +158,17 @@ def _validate_tag_id(tag_id: object) -> None:
 # files missing on disk. No FULL OUTER JOIN, so it runs on SQLite 3.31+.
 _IMAGE_ONLY_FIRST_PID = 2**63 - 1
 _CATEGORY_ROWS = (
-    "WITH owners(value,pid) AS ("
-    "SELECT p.category,p.id FROM prompts p WHERE p.category IS NOT NULL "
-    "AND TRIM(p.category)!='' AND " + _ELIGIBLE + " "
-    "UNION SELECT pp.category,pp.positive_prompt_id FROM prompt_pairs pp "
+    "WITH owners(value,pid,shelved) AS ("
+    "SELECT p.category,p.id," + SHELVED + " FROM prompts p "
+    "WHERE p.category IS NOT NULL AND TRIM(p.category)!='' AND " + _ELIGIBLE + " "
+    "UNION SELECT pp.category,pp.positive_prompt_id," + SHELVED_PAIR + " "
+    "FROM prompt_pairs pp "
     "WHERE pp.archived=0 AND pp.category IS NOT NULL AND TRIM(pp.category)!=''),"
     "image_values(value,image_count) AS ("
     "SELECT category,COUNT(*) FROM image_categories GROUP BY category),"
     "grouped(value,first_pid,prompt_count) AS ("
-    "SELECT value,MIN(pid),COUNT(DISTINCT pid) FROM owners GROUP BY value "
+    "SELECT value,MIN(pid),COUNT(DISTINCT CASE WHEN shelved THEN pid END) "
+    "FROM owners GROUP BY value "
     "UNION ALL SELECT value," + str(_IMAGE_ONLY_FIRST_PID) + ",0 FROM image_values "
     "WHERE value NOT IN (SELECT value FROM owners)),"
     "counted AS (SELECT g.value,g.first_pid,g.prompt_count,"

py/api/__init__.py

@@ -19,6 +19,7 @@ Split into domain-specific mixins for maintainability:
 - SystemRoutesMixin: System health check, Overview and usage statistics
 - LibraryLocationRoutesMixin: where the library lives, Move library, Keep it here
 - MaintenanceRoutesMixin: reviewed maintenance plans (preview, apply)
+- LibraryDeleteRoutesMixin: the Library's Delete… (archive paired) and Restore
 - WorkflowStorageRoutesMixin: store each workflow once, then Reclaim space
 - DuplicateFilesMixin: duplicate image files as find and removal jobs
 - LoraImportRoutesMixin: the reviewed, staged LoRA reference import job
@@ -40,8 +41,10 @@ from aiohttp import web
 from PIL import Image
 
 from .prompts import PromptRoutesMixin
+from .revalidation import revalidated_response
 from .pairs import PairRoutesMixin
 from .library import LibraryRoutesMixin
+from .library_delete import LibraryDeleteRoutesMixin
 from .vocabulary import VocabularyRoutesMixin
 from .annotations import AnnotationRoutesMixin
 from .review import ReviewRoutesMixin
@@ -74,6 +77,8 @@ from .autotag_routes import AutotagRoutesMixin
 from .lora_integration import LoraIntegrationMixin
 from .lora_import_routes import LoraImportRoutesMixin
 from .image_categories import ImageCategoryRoutesMixin
+from .image_delete import ImageDeleteMixin
+from .image_return import ImageReturnMixin
 from .source_rescope import SourceRescopeMixin
 
 try:
@@ -313,6 +318,7 @@ async def _gzip_middleware(request, handler):
 class PromptManagerAPI(
     PairRoutesMixin,
     LibraryRoutesMixin,
+    LibraryDeleteRoutesMixin,
     VocabularyRoutesMixin,
     AnnotationRoutesMixin,
     ReviewRoutesMixin,
@@ -343,6 +349,8 @@ class PromptManagerAPI(
     LoraIntegrationMixin,
     LoraImportRoutesMixin,
     ImageCategoryRoutesMixin,
+    ImageDeleteMixin,
+    ImageReturnMixin,
     SourceRescopeMixin,
 ):
     """REST API handler for PromptManager operations and web interface.
@@ -423,6 +431,12 @@ class PromptManagerAPI(
         # Reviewed maintenance plans under single-use tokens; a restart
         # forgets them (py/api/maintenance.py).
         self._maintenance_plans = PlanStore()
+        # #480: the removal marks the workspace listing hides, read once now so
+        # a listing page reads no table until a mark or the database changes.
+        try:
+            self._removal_marks()
+        except Exception:
+            self.logger.warning("Removal marks could not be read", exc_info=True)
 
         # A safety backup interrupted by a crash leaves its temp copy behind.
         try:
@@ -653,40 +667,45 @@ class PromptManagerAPI(
 
         @routes.get("/prompt_manager/workspace")
         async def serve_workspace_ui(request: web.Request) -> web.Response:
-            return self._serve_html_page("workspace.html", "Workspace")
+            return self._serve_html_page(request, "workspace.html", "Workspace")
 
         @routes.get("/prompt_manager/web")
         async def serve_web_ui(request):
-            return self._serve_html_page("index.html", "Web UI", cache=False)
+            return self._serve_html_page(request, "index.html", "Web UI", cache=False)
 
         @routes.get("/prompt_manager/gallery.html")
         async def serve_gallery_ui(request):
-            return self._serve_html_page("metadata.html", "Gallery")
+            return self._serve_html_page(request, "metadata.html", "Gallery")
 
         @routes.get("/prompt_manager/admin")
         async def serve_admin_ui(request):
-            return self._serve_html_page("admin.html", "Admin UI")
+            return self._serve_html_page(request, "admin.html", "Admin UI")
 
         @routes.get("/prompt_manager/gallery")
         async def serve_gallery_admin_ui(request):
-            return self._serve_html_page("gallery.html", "Gallery")
+            return self._serve_html_page(request, "gallery.html", "Gallery")
 
         # ── Static file serving ───────────────────────────────────────
 
         @routes.get("/prompt_manager/lib/{filepath:.*}")
         async def serve_lib_static(request):
             """Serve static library files (JS, CSS) from web/lib directory."""
-            return self._serve_static_file("lib", request.match_info.get("filepath"))
+            return self._serve_static_file(
+                request, "lib", request.match_info.get("filepath")
+            )
 
         @routes.get("/prompt_manager/js/{filepath:.*}")
         async def serve_js_static(request):
             """Serve static JavaScript files from web/js directory."""
-            return self._serve_static_file("js", request.match_info.get("filepath"))
+            return self._serve_static_file(
+                request, "js", request.match_info.get("filepath")
+            )
 
         # ── Register domain-specific routes from mixins ───────────────
 
         self._register_pair_routes(routes)
         self._register_library_routes(routes)
+        self._register_library_delete_routes(routes)
         self._register_vocabulary_routes(routes)
         self._register_annotation_routes(routes)
         self._register_review_routes(routes)
@@ -710,6 +729,8 @@ class PromptManagerAPI(
         self._register_lora_routes(routes)
         self._register_lora_import_routes(routes)
         self._register_image_category_routes(routes)
+        self._register_image_delete_routes(routes)
+        self._register_image_return_routes(routes)
         self._register_rescope_routes(routes)
 
         # Register gzip compression middleware (once)
@@ -726,8 +747,11 @@ class PromptManagerAPI(
 
         self.logger.info("All routes registered with decorator pattern")
 
-    def _serve_static_file(self, subdir, filepath):
-        """Serve ``web/<subdir>/<filepath>``; 403 outside it, 404 when missing."""
+    def _serve_static_file(self, request, subdir, filepath):
+        """Serve ``web/<subdir>/<filepath>``; 403 outside it, 404 when missing.
+
+        A served file is revalidated on every reuse (#478, ``revalidation``).
+        """
         root = os.path.join(_get_project_root(), "web", subdir)
         exact = STATIC_EXACT_FILES.get((subdir, filepath))
         # An exact file passes the same containment check, its extension only.
@@ -742,10 +766,13 @@ class PromptManagerAPI(
             return web.Response(text="Not Found", status=404)
         with open(file_path, "rb") as f:
             content = f.read()
-        return web.Response(body=content, content_type=content_type)
+        return revalidated_response(request, content, content_type)
 
-    def _serve_html_page(self, filename, title, cache=True):
-        """Serve ``web/<filename>``; 404 when missing, 500 when unreadable."""
+    def _serve_html_page(self, request, filename, title, cache=True):
+        """Serve ``web/<filename>``; 404 when missing, 500 when unreadable.
+
+        A served page is revalidated on every reuse (#478, ``revalidation``).
+        """
         html_path = os.path.join(_get_project_root(), "web", filename)
         try:
             if cache and html_path in self._html_cache:
@@ -762,7 +789,9 @@ class PromptManagerAPI(
                     content_type="text/html",
                     status=404,
                 )
-            return web.Response(text=content, content_type="text/html", charset="utf-8")
+            return revalidated_response(
+                request, content.encode("utf-8"), "text/html", charset="utf-8"
+            )
         except Exception:
             self.logger.exception(f"Failed to load {title}")
             return web.Response(

py/api/admin.py

@@ -36,10 +36,13 @@ except ImportError:
 
 try:
     from ...utils import exit_signal
+    from ...utils.media_folders import is_skipped_folder
 except ImportError:
     from utils import exit_signal
+    from utils.media_folders import is_skipped_folder
 
 try:
+    from ...database.image_removal import mark_hides
     from ...database.pair_ingestion import SCAN_MARKS, ingest_resolved_pair
     from ...database.run_attribution import (
         RecordedOutput,
@@ -60,6 +63,7 @@ try:
         decide_file_prompt,
     )
 except ImportError:
+    from database.image_removal import mark_hides
     from database.pair_ingestion import SCAN_MARKS, ingest_resolved_pair
     from database.run_attribution import (
         RecordedOutput,
@@ -118,10 +122,11 @@ DUPLICATE_FIND_LEGACY_TITLE = "Find duplicate image files (gallery page)"
 def _collect_media_files(output_dirs, extensions):
     """Media files under ``output_dirs`` (blocking), bounded and symlink-free.
 
-    Walks each root without following symlinks, skips ``thumbnails``
-    directories and symlinked files, never descends more than MAX_SCAN_DEPTH
-    levels and stops after MAX_SCAN_FILES files in total. Extensions match
-    case-insensitively and each path is listed once.
+    Walks each root without following symlinks, skips ``thumbnails`` and
+    trash folders (``utils.media_folders``) and symlinked files, never
+    descends more than MAX_SCAN_DEPTH levels and stops after MAX_SCAN_FILES
+    files in total. Extensions match case-insensitively and each path is
+    listed once.
     """
     wanted = {ext.lower() for ext in extensions}
     found = []
@@ -136,7 +141,7 @@ def _collect_media_files(output_dirs, extensions):
             dirnames[:] = sorted(
                 d
                 for d in dirnames
-                if d != "thumbnails"
+                if not is_skipped_folder(d)
                 and depth < MAX_SCAN_DEPTH
                 and not os.path.islink(os.path.join(current, d))
             )
@@ -236,7 +241,12 @@ SCAN_FINAL_STATES = {
     "error": "failed",
 }
 # The scope as the scan log's first line names it (the review dialog's words).
-SCAN_SCOPE_LOG = {"new": "new and unresolved files", "all": "all files"}
+SCAN_SCOPE_LOG = {
+    "new": "new and unresolved files",
+    "all": "all files",
+    "returned": "images returned to the library",
+}
+RETURN_JOB_TITLE = "Return images to the library"  # #498
 MIN_BATCHES_FOR_ESTIMATE = 2  # "about X min left" waits for this many batches
 # Log line prefix per outcome group (spec: + added, = known, ? review, ! error,
 # - no usable metadata).
@@ -883,6 +893,8 @@ class AdminRoutesMixin:
         extensions = IMAGE_EXTENSIONS + VIDEO_EXTENSIONS
         media_files = []
         seen = set()
+        # #480: a file removed from the library is never a copy or a keeper.
+        marks = self._removal_marks()
         for slot, root in enumerate(roots):
             for path in _collect_media_files([root], extensions):
                 try:
@@ -891,6 +903,9 @@ class AdminRoutesMixin:
                     stat = os.stat(path)
                 except OSError:
                     continue
+                locator = os.path.normcase(os.path.realpath(str(path)))
+                if locator in marks and mark_hides(marks, locator, path):
+                    continue
                 key = _physical_file_key(path, stat)
                 if key not in seen:
                     seen.add(key)
@@ -1371,13 +1386,17 @@ class AdminRoutesMixin:
             }
         )
 
-    def _start_scan_job(self, files=DEFAULT_SCAN_SCOPE, roots=None, output_dirs=None):
+    def _start_scan_job(
+        self, files=DEFAULT_SCAN_SCOPE, roots=None, output_dirs=None, returned=None
+    ):
         """Register the scan job synchronously; its runner starts on the loop.
 
         ``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.
+        Raises JobBusy while another record-changing job runs. ``returned``
+        (#498, ``[(path, locator)]``) makes it "Return images to the library":
+        those files' removal marks go first, then only they are scanned.
         """
         if files not in SCAN_SCOPES:
             raise ValueError(f"Unknown scan scope: {files!r}")
@@ -1385,20 +1404,26 @@ class AdminRoutesMixin:
             output_dirs is None or not roots or max(roots) >= len(output_dirs)
         ):
             raise ValueError("A scoped scan needs the sources its roots index")
+        scope = {"files": files, "roots": None if roots is None else list(roots)}
+        if returned is not None:
+            scope = {"files": "returned", "roots": None, "images": len(returned)}
         job = self._jobs.start(
             SCAN_JOB_KIND,
-            SCAN_JOB_TITLE,
+            SCAN_JOB_TITLE if returned is None else RETURN_JOB_TITLE,
             record_changing=True,
-            scope={"files": files, "roots": None if roots is None else list(roots)},
-            runner=functools.partial(self._run_scan_job, output_dirs=output_dirs),
+            scope=scope,
+            runner=functools.partial(
+                self._run_scan_job, output_dirs=output_dirs, returned=returned
+            ),
             groups=SCAN_GROUP_NAMES,
         )
         self._scan_job = job
         return job
 
-    async def _run_scan_job(self, job, output_dirs=None):
+    async def _run_scan_job(self, job, output_dirs=None, returned=None):
         final = None
-        async for payload in self._scan_images_events(job, output_dirs):
+        extra = {} if returned is None else {"returned": returned}
+        async for payload in self._scan_images_events(job, output_dirs, **extra):
             job.publish(payload)
             final = payload.get("type")
         state = SCAN_FINAL_STATES.get(final, "finished")
@@ -1436,7 +1461,7 @@ class AdminRoutesMixin:
             )
         return response
 
-    async def _scan_images_events(self, job, output_dirs=None):
+    async def _scan_images_events(self, job, output_dirs=None, returned=None):
         """Yield progress payloads while scanning the output directories.
 
         Every effective source is walked, or only those ``job.scope["roots"]``
@@ -1474,9 +1499,16 @@ class AdminRoutesMixin:
                 0, f"Scanning {len(walked)} directory(ies) for media files..."
             )
 
-            media_files = await self._run_in_executor(
-                self._collect_output_media_sync, walked
-            )
+            if returned is None:
+                media_files = await self._run_in_executor(
+                    self._collect_output_media_sync, walked
+                )
+            else:
+                # #498: only the files whose marks this job deleted.
+                media_files = await self._run_in_executor(
+                    self._clear_returned_marks, returned
+                )
+                job.log_line(f"Returned {_plural(len(media_files), 'image')}")
             counts = dict.fromkeys(SCAN_COUNT_KEYS, 0)
             job.update(
                 total=len(media_files),
@@ -1551,8 +1583,13 @@ class AdminRoutesMixin:
             if job.cancelled:
                 return
             batch = media_files[batch_start : batch_start + SCAN_BATCH_SIZE]
-            skipped = [f for f in batch if str(f) in known]
-            to_read = [f for f in batch if str(f) not in known]
+            # #480: a file removed from the library is not read or linked
+            # again while its bytes are unchanged.
+            removed = await self._run_in_executor(self._removed_paths, batch)
+            skipped = [f for f in batch if str(f) in known or str(f) in removed]
+            to_read = [
+                f for f in batch if str(f) not in known and str(f) not in removed
+            ]
             outcomes = [_scan_outcome(f, roots, "skipped") for f in skipped]
             counts["processed"] += len(skipped)
             counts["unchanged"] += len(skipped)

py/api/autotag_routes.py

@@ -23,6 +23,11 @@ from .prompts import thumbnail_url_for
 from . import thumbnail_settings
 from .. import model_gate
 
+try:
+    from ...utils.media_folders import is_skipped_folder
+except ImportError:
+    from utils.media_folders import is_skipped_folder
+
 from aiohttp import web
 
 _INTERNAL_ERROR = "An internal error occurred. Check server logs for details."
@@ -1319,8 +1324,9 @@ class AutotagRoutesMixin:
     def _collect_scan_files(output_path: Path):
         """Media files under ``output_path`` from a bounded, symlink-free walk.
 
-        Descends at most ``_SCAN_MAX_DEPTH`` levels, skips ``thumbnails``
-        trees and symlinked files, and stops after ``_SCAN_MAX_FILES`` files.
+        Descends at most ``_SCAN_MAX_DEPTH`` levels, skips ``thumbnails`` and
+        trash folders (``utils.media_folders``) and symlinked files, and stops
+        after ``_SCAN_MAX_FILES`` files.
         Returns ``(paths, truncated)``.
         """
         found = []
@@ -1330,7 +1336,7 @@ class AutotagRoutesMixin:
             dirnames[:] = sorted(
                 name
                 for name in dirnames
-                if name != "thumbnails" and depth + 1 <= _SCAN_MAX_DEPTH
+                if not is_skipped_folder(name) and depth + 1 <= _SCAN_MAX_DEPTH
             )
             for name in sorted(filenames):
                 if Path(name).suffix.lower() not in _MEDIA_EXTENSIONS:
@@ -1357,6 +1363,10 @@ class AutotagRoutesMixin:
             files, truncated = await self._run_in_executor(
                 self._collect_scan_files, output_path
             )
+            # #501: a file removed from the library is not offered for tagging.
+            files = await self._run_in_executor(
+                self._without_removed, output_path, files
+            )
             has_thumbnails = (output_path / "thumbnails").is_dir()
 
             images = []

py/api/image_categories.py

@@ -232,15 +232,17 @@ class ImageCategoryRoutesMixin:
             return None, _coded(400, "too-many-images", TOO_MANY)
         return tuple(selection.targets), None
 
-    async def _category_request(self, request, fields: frozenset):
+    async def _category_request(self, request, fields: frozenset, data=None):
         """``(data, targets, roots, None)`` or ``(None, None, None, error)``.
 
         The images are ``items`` (1 to 500 targets) or ``filter`` (all images
-        an Images listing filter admits), besides *fields*.
+        an Images listing filter admits), besides *fields*. *data* is the body
+        when the caller has already read it (a body is read once).
         """
-        data, error = await _json_body_or_error(request)
-        if error is not None:
-            return None, None, None, error
+        if data is None:
+            data, error = await _json_body_or_error(request)
+            if error is not None:
+                return None, None, None, error
         names = set(data) - fields
         if set(data) & fields != fields or names not in ({"items"}, {"filter"}):
             return (

py/api/image_delete.py

@@ -0,0 +1,521 @@
+"""Delete selected images: remove them from the library, or trash them (#480).
+
+``POST /prompt_manager/images/delete/preview {items | filter}`` reviews the
+selection for both modes at once and answers a reviewed plan (the System ›
+Maintenance contract, ``py/api/maintenance.py``): the token, the counts of
+the records each file loses, the refused files with a coded reason (both
+modes, and the trash-only ones), the prompts that lose their last image and
+the safety backup. It writes nothing. ``items`` are Images listing identities
+(at most 500); ``filter`` is "Select all N matching". Each target is matched
+to its entry in the current listing (``not-listed`` otherwise), so every
+later step uses the walked spelling, never the request's text.
+
+``POST /prompt_manager/maintenance/apply {token, mode}`` runs the plan as the
+``image_delete`` job (admission ``records``, not cancellable): the sources
+are checked, the promised safety backup is taken, then each file is checked
+again (containment and fingerprint) and
+
+- ``mode="library"``: its records are deleted and its removal mark written
+  in one transaction; the file stays on disk, hidden;
+- ``mode="trash"``: it is moved to the trash first (``utils/trash.py``); a
+  refused move leaves the file and its records alone; after a move its
+  records are deleted.
+
+No path here unlinks a media file. A failed records write stops the job; the
+files after it are not attempted.
+"""
+
+import hashlib
+import json
+import os
+import stat as stat_module
+from pathlib import Path
+
+from .admin import DELETABLE_MEDIA_EXTENSIONS, _remove_thumbnail
+from .duplicate_review import (
+    CHANGED_CONTENT,
+    GONE,
+    LINK,
+    OUTSIDE_SOURCE,
+    UNREADABLE,
+    file_problem,
+)
+from .images import _favorite_relative_key, _favorite_root_key
+from .jobs import IMAGE_DELETE_GROUP_NAMES, IMAGE_DELETE_JOB_KIND, JobBusy
+from .job_routes import busy_response
+from .maintenance import MAINTENANCE_PREVIEW_LEASE, _fail_job, _failure, backup_note
+
+try:
+    from ...database import image_removal_schema
+    from ...database.image_removal import mark_hides
+    from ...database.annotation_schema import MAX_LOCATOR_LENGTH
+    from ...utils import trash
+    from ...utils.media_folders import is_trash_folder
+except ImportError:
+    from database import image_removal_schema
+    from database.image_removal import mark_hides
+    from database.annotation_schema import MAX_LOCATOR_LENGTH
+    from utils import trash
+    from utils.media_folders import is_trash_folder
+
+IMAGE_DELETE = "delete_images"
+MODES = ("library", "trash")
+TITLES = {
+    "library": "Delete images (remove from the library)",
+    "trash": "Delete images (move to the trash)",
+}
+MAX_DETAIL_ROWS = 50
+# The system moved the file but its place in a trash could not be shown (#499).
+TRASH_UNCONFIRMED = "trash-unconfirmed"
+RECORDS_FAILED_CODE = "records-failed"
+
+# Reason codes (design §4.4) and the sentence each shows.
+REASONS = {
+    "not-listed": "No longer listed in Images.",
+    "outside": "Outside the output folders.",
+    "link": "A link, not a file.",
+    "gone": "The file no longer exists.",
+    "unreadable": "The file can't be read.",
+    "thumbnail": "A generated preview, not an image.",
+    "not-media": "Not a media file.",
+    "trash-folder": "Inside a trash folder.",
+    "path-too-long": "The path is too long.",
+    "changed": "The file changed after the review.",
+    trash.NO_TRASH: "This drive has no trash.",
+    trash.NETWORK: "Network drives can't use the trash.",
+    trash.TRASH_IN_ROOT: "This drive's trash is inside an output folder.",
+    trash.LOCKED: "The file is open in another program. Close it and try again.",
+    trash.FAILED: "The file could not be moved to the trash.",
+    trash.NO_PERMISSION: (
+        "PromptManager isn't allowed to move this file (no permission, or it is "
+        "locked in Finder)."
+    ),
+    trash.CLOUD_SYNC: (
+        "Files in iCloud Drive or a cloud-synced folder can't be moved to the "
+        "trash here."
+    ),
+    TRASH_UNCONFIRMED: (
+        "Moved by macOS, but its place in the trash could not be confirmed."
+    ),
+    trash.WINDOWS_RECYCLE: (
+        "Moving files to the Recycle Bin isn't available on Windows: files larger "
+        "than the bin's capacity would be deleted permanently."
+    ),
+    "not-attempted": "Not attempted: the job stopped after an error.",
+}
+_PROBLEM_CODES = {
+    OUTSIDE_SOURCE: "outside",
+    LINK: "link",
+    GONE: "gone",
+    UNREADABLE: "unreadable",
+    CHANGED_CONTENT: "changed",
+}
+SOURCES_CHANGED = "The sources changed since the review; nothing was changed."
+RECORDS_FAILED = "The image records could not be removed; the job stopped."
+
+
+def lexical_problem(relative: str) -> str | None:
+    """The refusal code a root-relative POSIX path earns before any file access."""
+    parts = relative.split("/")
+    if "thumbnails" in parts[:-1]:
+        return "thumbnail"
+    if any(is_trash_folder(part) for part in parts[:-1]):
+        return "trash-folder"
+    if os.path.splitext(parts[-1])[1].lower() not in DELETABLE_MEDIA_EXTENSIONS:
+        return "not-media"
+    return None
+
+
+def file_check(path, root, relative, *, expected=None):
+    """``(code, lstat)``: why *path* may not be deleted, or ``(None, lstat)``.
+
+    Text first (inside the root, not a preview or trash folder, a media
+    file), then ``duplicate_review.file_problem``: a regular file, not a
+    link, whose resolved path is still inside the resolved root. With
+    *expected* (``{size, mtime_ns, inode}`` from the review) the file must
+    still be those bytes. Every handle is closed when this returns.
+    """
+    code = lexical_problem(relative)
+    if code:
+        return code, None
+    try:
+        info = os.lstat(path)
+    except FileNotFoundError:
+        return "gone", None
+    except OSError:
+        return "unreadable", None
+    if getattr(info, "st_file_attributes", 0) & getattr(
+        stat_module, "FILE_ATTRIBUTE_REPARSE_POINT", 0
+    ):
+        return "link", info
+    if expected is None:
+        problem = file_problem(path, root, None, info.st_size, hash_check=False)
+    else:
+        problem = file_problem(
+            path,
+            root,
+            None,
+            expected["size"],
+            hash_check=False,
+            mtime_ns=expected["mtime_ns"],
+            inode=expected["inode"],
+        )
+    if problem:
+        return _PROBLEM_CODES.get(problem, "outside"), info
+    if len(os.path.normcase(os.path.realpath(path))) > MAX_LOCATOR_LENGTH:
+        return "path-too-long", info
+    return None, info
+
+
+def _row(target, code):
+    return {
+        "path": target["rel"],
+        "root_label": target["root_label"],
+        "code": code,
+        "detail": REASONS[code],
+    }
+
+
+def _summary(rows):
+    counts = {}
+    for row in rows:
+        counts[row["code"]] = counts.get(row["code"], 0) + 1
+    return {"count": len(rows), "counts": counts, "rows": rows[:MAX_DETAIL_ROWS]}
+
+
+def _fingerprint(targets) -> str:
+    material = [
+        (t["root_index"], t["rel"], t["size"], t["mtime_ns"], t["inode"])
+        for t in targets
+    ]
+    return hashlib.sha256(json.dumps(material).encode("utf-8")).hexdigest()
+
+
+class ImageDeleteMixin:
+    """The Images Delete… review and its apply job (#480)."""
+
+    def _register_image_delete_routes(self, routes):
+        # A fixed path beside the dynamic /images/{image_id} routes: aiohttp
+        # (3.10+) looks fixed paths up first (see image_categories.py).
+        @routes.post("/prompt_manager/images/delete/preview")
+        async def preview_image_delete_route(request):
+            return await self.preview_image_delete(request)
+
+    # ── review ────────────────────────────────────────────────────────
+
+    async def preview_image_delete(self, request):
+        """Review the selection under the maintenance preview lease."""
+        try:
+            async with self._jobs.lease(MAINTENANCE_PREVIEW_LEASE):
+                return await self._preview_image_delete(request)
+        except JobBusy as busy:
+            return busy_response(busy)
+
+    async def _preview_image_delete(self, request):
+        _data, targets, roots, error = await self._category_request(
+            request, frozenset()
+        )
+        if error is not None:
+            return error
+        db = self.db
+        identity = self._database_identity(db)
+        try:
+            files = {}
+            for index in dict.fromkeys(t[0] for t in targets):
+                files[index] = await self._get_gallery_files(roots[index])
+            review = await self._run_in_executor(
+                self._review_image_delete, db, roots, targets, files
+            )
+        except Exception:
+            self.logger.exception("Image delete review failed")
+            return _failure("The review failed. Check server logs for details.", 500)
+        return await self._plan_response(
+            db,
+            identity,
+            IMAGE_DELETE,
+            _fingerprint(review["targets"]),
+            review["public"],
+            {"targets": review["targets"]},
+        )
+
+    def _review_image_delete(self, db, roots, targets, files):
+        """Every target checked now (blocking); ``{targets, public}``."""
+        listings, seen = {}, set()
+        acted, refused, trash_refused = [], [], []
+        spellings = self._source_spellings()
+        root_texts = [str(root) for root in roots]
+        for index, _scope, relative in targets:
+            root = roots[index]
+            if index not in listings:
+                listings[index] = self._favorite_listing(root, files[index])
+            spelled = listings[index].get(_favorite_relative_key(relative))
+            target = {
+                "root_index": index,
+                "root_scope": _scope,
+                "root": str(root),
+                "root_label": self._public_path(root),
+                "rel": spelled or relative,
+            }
+            if spelled is None:
+                refused.append(_row(target, "not-listed"))
+                continue
+            absolute = os.path.join(str(root), *spelled.split("/"))
+            code, info = file_check(absolute, str(root), spelled)
+            if code:
+                refused.append(_row(target, code))
+                continue
+            identity = (info.st_dev, info.st_ino)
+            if identity in seen:
+                continue  # one physical file named twice (nested roots, hardlinks)
+            seen.add(identity)
+            target.update(self._removal_of(absolute, info, spellings))
+            target["trash"] = trash.trash_available(absolute, root_texts)
+            if target["trash"]:
+                trash_refused.append(_row(target, target["trash"]))
+            acted.append(target)
+        counted = db.count_removal_records([t["removal"] for t in acted])
+        library_count = len(acted)
+        public = {
+            "operation": IMAGE_DELETE,
+            "scope": {"count": library_count, "label": "images"},
+            "library": {"count": library_count},
+            "trash": {"count": library_count - len(trash_refused)},
+            "protected": {"count": len(refused), "reasons": []},
+            "refused": _summary(refused),
+            "trash_refused": _summary(trash_refused),
+            "records": counted["records"],
+            "orphaned_prompts": counted["orphaned_prompts"],
+            "media": {"deletes_files": False, "label": "Chosen in the review"},
+            "details": [],
+        }
+        return {"targets": acted, "public": public}
+
+    @staticmethod
+    def _removal_of(absolute, info, spellings):
+        favorites = [
+            (_favorite_root_key(root), _favorite_relative_key(relative))
+            for root, relative in spellings.favorites(absolute).items()
+        ]
+        return {
+            "abs": absolute,
+            "size": info.st_size,
+            "mtime_ns": info.st_mtime_ns,
+            "inode": [info.st_dev, info.st_ino],
+            "removal": {
+                "spellings": list(spellings.of(absolute).values()),
+                "locator": os.path.normcase(os.path.realpath(absolute)),
+                "favorites": favorites,
+                "category": spellings.category_key(absolute),
+            },
+        }
+
+    # ── apply ─────────────────────────────────────────────────────────
+
+    def _start_image_delete(self, db, plan, mode, backup_on):
+        """Register the delete job for a reviewed plan (on the loop)."""
+        return self._jobs.start(
+            IMAGE_DELETE_JOB_KIND,
+            TITLES[mode],
+            admission="records",
+            cancellable=False,
+            scope={"operation": IMAGE_DELETE, "mode": mode},
+            groups=IMAGE_DELETE_GROUP_NAMES,
+            runner=lambda job: self._run_image_delete(job, db, plan, mode, backup_on),
+        )
+
+    async def _run_image_delete(self, job, db, plan, mode, 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._delete_images(job, db, targets, mode, backup)
+        finally:
+            if backup:
+                await self._prune_backup_pool(job, db)
+
+    async def _delete_images(self, job, db, targets, mode, backup):
+        job.update(total=len(targets), status_line=TITLES[mode])
+        roots = [str(root) for root in self._get_all_output_dirs()]
+        done_group = "trashed" if mode == "trash" else "removed"
+        changed, failed = 0, None
+        for done, target in enumerate(targets, start=1):
+            if failed:
+                self._record_delete(job, "not_changed", target, "not-attempted")
+                continue
+            group, code, label = await self._run_in_executor(
+                self._delete_one_image, db, target, mode, roots
+            )
+            if group == "errors":
+                failed = code or RECORDS_FAILED_CODE
+                text = REASONS[code] if code else RECORDS_FAILED
+                job.record(
+                    "errors",
+                    {
+                        "path": target["rel"],
+                        "root": target["root_label"],
+                        "root_index": target["root_index"],
+                        "root_scope": target["root_scope"],
+                        "detail": text,
+                    },
+                    f"! {target['root_label']}/{target['rel']} · {text}",
+                )
+            elif group == done_group:
+                changed += 1
+                detail = (
+                    f"Moved to the {label}" if label else "Removed from the library"
+                )
+                self._record_delete(job, group, target, None, detail)
+            else:
+                self._record_delete(job, group, target, code)
+            job.update(processed=done, progress=int(done / len(targets) * 100))
+        if changed:
+            self.invalidate_gallery_cache()
+        verb = "Moved" if mode == "trash" else "Removed"
+        where = "to the trash" if mode == "trash" else "from the library"
+        line = f"{verb} {changed:,} of {len(targets):,} images {where}"
+        job.log_line(line)
+        job.update(progress=100, status_line=f"{line} · {backup_note(backup)}")
+        if failed:
+            # "records-failed" names every stop at an errors row (the page's
+            # "Stopped after N of M" toast); the row says which error it was.
+            job.scope["failure"] = RECORDS_FAILED_CODE
+            job.publish({"type": "error", "code": failed, "message": line})
+            job.finish("failed")
+
+    @staticmethod
+    def _record_delete(job, group, target, code, detail=None):
+        text = detail or REASONS[code]
+        row = {
+            "path": target["rel"],
+            "root": target["root_label"],
+            "root_index": target["root_index"],
+            "root_scope": target["root_scope"],
+            "code": code,
+            "detail": text,
+        }
+        mark = {"removed": "-", "trashed": "-"}.get(group, "=")
+        job.record(
+            group, row, f"{mark} {target['root_label']}/{target['rel']} · {text}"
+        )
+
+    def _delete_one_image(self, db, target, mode, roots):
+        """``(group, code, trash label)`` for one reviewed file (blocking)."""
+        code, _info = file_check(
+            target["abs"],
+            target["root"],
+            target["rel"],
+            expected={
+                "size": target["size"],
+                "mtime_ns": target["mtime_ns"],
+                "inode": target["inode"],
+            },
+        )
+        if code:
+            return "not_changed", code, None
+        label = None
+        if mode == "trash":
+            try:
+                label = trash.move_to_trash(target["abs"], roots)
+            except trash.TrashRefused as refused:
+                code = refused.code if refused.code in REASONS else trash.FAILED
+                self.logger.info(
+                    "Not moved to the trash (%s): %s %s",
+                    code,
+                    target["rel"],
+                    refused.detail,
+                )
+                return "not_changed", code, None
+            except trash.TrashUnconfirmed as unconfirmed:
+                # The file left its folder: keep its records, stop the job.
+                self.logger.warning(
+                    "Trash move not confirmed: %s %s", target["rel"], unconfirmed.detail
+                )
+                return "errors", TRASH_UNCONFIRMED, None
+            mark = None
+        else:
+            mark = (target["size"], target["mtime_ns"])
+        try:
+            db.remove_image_records(target["removal"], mark=mark)
+        except Exception:
+            self.logger.exception("Removing an image's records failed")
+            return "errors", None, label
+        _remove_thumbnail(Path(target["root"]), Path(target["rel"]), self.logger)
+        return ("trashed" if mode == "trash" else "removed"), None, label
+
+    # ── the workspace listing ─────────────────────────────────────────
+
+    def _removal_marks(self) -> dict:
+        """The removal marks, cached until a mark changes or the database does.
+
+        A listing page reads no table while nothing changed: the cache follows
+        this process's marks generation and the database identity (a restore).
+        """
+        key = (self._database_identity(self.db), image_removal_schema.generation())
+        cached = getattr(self, "_marks_cache", None)
+        if cached is None or cached[0] != key:
+            cached = (key, self.db.removal_marks())
+            self._marks_cache = cached
+        return cached[1]
+
+    def _hidden_entries(self, listings) -> set:
+        """Normalized paths of listed files a removal mark hides (blocking).
+
+        Only marked locators are looked at, and only those files are
+        ``lstat``'ed: a mark hides a file while its size and ``mtime_ns`` are
+        still the ones it was removed with.
+        """
+        marks = self._removal_marks()
+        if not marks:
+            return set()
+        located = self._workspace_locators(listings)
+        return {
+            entry.normalized
+            for locator, entry in ((locator, located.get(locator)) for locator in marks)
+            if entry is not None and mark_hides(marks, locator, entry.path)
+        }
+
+    def _removed_paths(self, paths) -> set:
+        """The absolute paths among *paths* a removal mark hides (blocking)."""
+        marks = self._removal_marks()
+        if not marks:
+            return set()
+        return {
+            str(path)
+            for path in paths
+            if mark_hides(marks, os.path.normcase(os.path.realpath(str(path))), path)
+        }
+
+    def _removal_check_under(self, root):
+        """``hidden(path) -> bool`` for files a walk of *root* found (blocking).
+
+        A walk never follows a link below *root*, so a file's locator is
+        ``normcase(join(realpath(root), relative))``: no ``realpath`` per
+        file, and an ``lstat`` only for a marked one. Without marks it
+        answers False at once.
+        """
+        marks = self._removal_marks()
+        if not marks:
+            return lambda _path: False
+        root = os.fspath(root)
+        real = os.path.realpath(root)
+
+        def hidden(path):
+            relative = os.path.relpath(os.fspath(path), root)
+            locator = os.path.normcase(os.path.join(real, relative))
+            return mark_hides(marks, locator, path)
+
+        return hidden
+
+    def _without_removed(self, root, paths) -> list:
+        """*paths* found by a walk of *root*, less the hidden ones (blocking)."""
+        removed = self._removal_check_under(root)
+        return [path for path in paths if not removed(path)]
+
+
+def parse_mode(value):
+    """The apply's ``mode``, or None when it is not one of MODES."""
+    return value if isinstance(value, str) and value in MODES else None

py/api/image_return.py

@@ -0,0 +1,148 @@
+"""Return removed images to the library (#498).
+
+``POST /prompt_manager/images/removed/return {items | filter}`` names files a
+removal mark hides (#480, "Remove from the library only"): ``items`` are 1 to
+500 listing identities, ``filter`` the removed view's listing query
+(``removed: "1"`` plus the view's other parameters, at most 500 images). Only
+this route takes ``removed``: every other bulk route refuses it, because an
+explicit write there would show a file again without re-reading it.
+
+The route answers 202 ``{job, returned, not_removed}`` after starting a
+``scan`` job titled "Return images to the library" (admission ``records``:
+409 ``busy`` beside a scan, restore or delete, nothing changed). The job
+first deletes the marks that still hide their file (same size and
+``mtime_ns``), in one transaction, then scans exactly those files with the
+scan's own pipeline: prompts, links, pairs and Needs review items come back
+from the files' embedded metadata. Image tags, auto-tag marks, the own
+category, collection memberships and the favorite were deleted by the remove
+and do not come back. No file is moved, written or deleted.
+"""
+
+import os
+from pathlib import Path
+
+from aiohttp import web
+
+from .image_categories import TOO_MANY, _coded
+from .images import (
+    ListingSourceChanged,
+    _favorite_relative_key,
+    _json_body_or_error,
+    parse_listing_filter,
+)
+from .image_tag_jobs import MAX_JOB_TARGETS
+from .jobs import JobBusy
+from .job_routes import busy_response
+
+try:
+    from ...database.image_removal import mark_hides
+except ImportError:
+    from database.image_removal import mark_hides
+
+NONE_REMOVED = "None of the selected images are removed from the library."
+SOURCE_CHANGED = "The image sources changed. Reload Images and try again."
+
+
+def _bad(message):
+    return web.json_response({"success": False, "error": message}, status=400)
+
+
+class ImageReturnMixin:
+    """Return to library (#498): clear the marks, then scan those files."""
+
+    def _register_image_return_routes(self, routes):
+        # A fixed path beside the dynamic /images/{image_id} routes.
+        @routes.post("/prompt_manager/images/removed/return")
+        async def return_removed_images_route(request):
+            return await self.return_removed_images(request)
+
+    async def return_removed_images(self, request):
+        data, error = await _json_body_or_error(request)
+        if error is not None:
+            return error
+        if set(data) == {"filter"}:
+            targets, roots, error = await self._removed_filter_targets(data["filter"])
+        else:
+            _data, targets, roots, error = await self._category_request(
+                request, frozenset(), data=data
+            )
+        if error is not None:
+            return error
+        files = {}
+        for index in dict.fromkeys(t[0] for t in targets):
+            files[index] = await self._get_gallery_files(roots[index])
+        returned, not_removed = await self._run_in_executor(
+            self._hidden_targets, roots, targets, files
+        )
+        if not returned:
+            return _coded(400, "no-images", NONE_REMOVED)
+        try:
+            job = self._start_scan_job(
+                files="all", output_dirs=list(roots), returned=returned
+            )
+        except JobBusy as busy:
+            return busy_response(busy)
+        return web.json_response(
+            {
+                "success": True,
+                "job": job.summary(),
+                "returned": len(returned),
+                "not_removed": not_removed,
+            },
+            status=202,
+        )
+
+    async def _removed_filter_targets(self, raw):
+        """``(targets, roots, None)`` for the removed view's filter, else an error."""
+        if not isinstance(raw, dict) or raw.get("removed") != "1":
+            return None, None, _bad('filter must hold removed: "1"')
+        rest = {key: value for key, value in raw.items() if key != "removed"}
+        try:
+            parse_listing_filter(rest)
+            selection = await self.resolve_listing_filter(
+                {**rest, "removed": "1"}, MAX_JOB_TARGETS
+            )
+        except ListingSourceChanged:
+            return None, None, _coded(409, "source-changed", SOURCE_CHANGED)
+        except ValueError as exc:
+            return None, None, _bad(str(exc))
+        if selection.truncated:
+            return None, None, _coded(400, "too-many-images", TOO_MANY)
+        if not selection.targets:
+            return None, None, _coded(400, "no-images", NONE_REMOVED)
+        return tuple(selection.targets), list(self._get_all_output_dirs()), None
+
+    def _hidden_targets(self, roots, targets, files):
+        """``([(path, locator)], not_removed)``: the targets a mark hides now.
+
+        Each target is matched to its listed spelling (the walk's). One
+        physical file named twice (nested roots) is returned once; a target
+        that is not listed or not hidden counts in ``not_removed``.
+        """
+        marks = self._removal_marks()
+        listings, seen, returned, not_removed = {}, set(), [], 0
+        for index, _scope, relative in targets:
+            root = roots[index]
+            if index not in listings:
+                listings[index] = self._favorite_listing(root, files[index])
+            spelled = listings[index].get(_favorite_relative_key(relative))
+            if spelled is None:
+                not_removed += 1
+                continue
+            path = os.path.join(str(root), *spelled.split("/"))
+            locator = os.path.normcase(os.path.realpath(path))
+            if locator in seen:
+                continue
+            if not mark_hides(marks, locator, path):
+                not_removed += 1
+                continue
+            seen.add(locator)
+            returned.append((Path(path), locator))
+        return returned, not_removed
+
+    def _clear_returned_marks(self, returned) -> list:
+        """The paths whose marks this deleted (blocking; one transaction)."""
+        cleared = self.db.clear_hiding_marks(
+            [(locator, str(path)) for path, locator in returned]
+        )
+        return [path for path, locator in returned if locator in cleared]

py/api/image_tag_jobs.py

@@ -488,7 +488,11 @@ class ImageTagJobsMixin:
                     _still_targets, self, index, root, files, seen
                 )
             )
-        return found
+        # #480: a file removed from the library is never tagged by a batch.
+        hidden = await self._run_in_executor(
+            self._removed_paths, [target.path for target in found]
+        )
+        return [target for target in found if target.path not in hidden]
 
     async def _start_autotag(
         self, *, model_type, existing, options, keep_in_memory, title, owner_kind

py/api/images.py

@@ -66,6 +66,7 @@ try:
     from ...database.models import normalize_image_path
     from ...database.run_attribution import recorded_output_lookup
     from ...utils.card_seed import card_seed, header_params, parsed_positive
+    from ...utils.media_folders import in_skipped_folder, is_skipped_folder
     from ...utils.parallel import map_parallel
     from ...utils.json_strict import dumps_strict
     from ...utils.inspection_response import (
@@ -91,6 +92,7 @@ except ImportError:
     from database.models import normalize_image_path
     from database.run_attribution import recorded_output_lookup
     from utils.card_seed import card_seed, header_params, parsed_positive
+    from utils.media_folders import in_skipped_folder, is_skipped_folder
     from utils.parallel import map_parallel
     from utils.json_strict import dumps_strict
     from utils.inspection_response import (
@@ -915,7 +917,8 @@ def _name_suffix(name):
 def _walk_media(output_path, max_files):
     """Yield the ``os.DirEntry`` of each media file under *output_path*.
 
-    Symlinks are never followed, ``thumbnails/`` is skipped, descent stops
+    Symlinks are never followed, ``thumbnails/`` and trash folders are
+    skipped (``utils.media_folders``, #501), descent stops
     at MAX_SCAN_DEPTH and at most *max_files* entries are produced. The order
     is ``os.walk``'s (top-down, subfolders in ``os.scandir`` order, files by
     name), which the gallery's ties in mtime keep. Each entry's type comes
@@ -927,8 +930,6 @@ def _walk_media(output_path, max_files):
     produced = 0
     while stack:
         top, rel_parts = stack.pop()
-        if "thumbnails" in rel_parts:
-            continue
         dirs, files = [], []
         try:
             with os.scandir(top) as entries:
@@ -952,7 +953,7 @@ def _walk_media(output_path, max_files):
         if len(rel_parts) >= MAX_SCAN_DEPTH:
             continue
         for entry in reversed(dirs):
-            if not entry.is_symlink():
+            if not entry.is_symlink() and not is_skipped_folder(entry.name):
                 stack.append((entry.path, rel_parts + (entry.name,)))
 
 
@@ -976,7 +977,7 @@ def _settled_entry(root, relative):
     *folders, name = relative.split(os.sep)
     if _name_suffix(name).lower() not in MEDIA_EXTENSIONS:
         return None
-    if "thumbnails" in folders or len(folders) > MAX_SCAN_DEPTH:
+    if in_skipped_folder(folders) or len(folders) > MAX_SCAN_DEPTH:
         return None
     folder = os.fspath(root)
     for part in ("", *folders):
@@ -1159,7 +1160,10 @@ def _workspace_filters(query: Mapping) -> dict:
     the linked positive, and ``favorites=1`` keeps only favorites (the
     Favorites page, #249 D51). ``collection=<id>`` (1 to 9 digits) keeps only
     that collection's members (#331); it wins over ``favorites`` (a page never
-    sets both). Raises ValueError for any unknown or oversized value.
+    sets both). ``removed=1`` lists only the files a removal mark hides (#498,
+    Show removed images); such a file has no records, so it never combines
+    with ``favorites``, ``collection``, ``category``, ``tags`` or the rating
+    sort. Raises ValueError for any unknown or oversized value.
     """
     text = query.get("q", "").strip()
     folded = text.casefold()
@@ -1174,6 +1178,12 @@ def _workspace_filters(query: Mapping) -> dict:
     )
     favorites = query.get("favorites", "0")
     collection = query.get("collection", "")
+    removed = query.get("removed", "0")
+    if removed not in ("0", "1") or (
+        removed == "1"
+        and (favorites == "1" or collection or category or tags or order == "rating")
+    ):
+        raise ValueError("Invalid gallery filters")
     if (
         favorites not in ("0", "1")
         or (collection != "" and _COLLECTION_ID.fullmatch(collection) is None)
@@ -1201,6 +1211,7 @@ def _workspace_filters(query: Mapping) -> dict:
         "tags": tags,
         "favorites": favorites == "1" and not collection,
         "collection": int(collection) if collection else None,
+        "removed": removed == "1",
     }
 
 
@@ -2072,6 +2083,7 @@ class ImageRoutesMixin:
                         filters["tags"],
                         filters["favorites"],
                         filters["collection"],
+                        filters["removed"],
                     ]
                 ).encode()
             ).hexdigest()
@@ -2101,6 +2113,11 @@ class ImageRoutesMixin:
                     self._select_workspace_page, listings, filters, after, limit, scope
                 )
             )
+            # #498: Show removed images (N), every removed file in the selected
+            # source(s) whatever the filters (the hidden set is cached work).
+            removed_total = len(
+                await self._run_in_executor(self._hidden_entries, listings)
+            )
         except CollectionMissing:
             return collection_not_found()
         except Exception:
@@ -2127,6 +2144,7 @@ class ImageRoutesMixin:
             "limit": limit,
             "has_more": has_more,
             "next_cursor": next_cursor,
+            "removed_total": removed_total,
         }
         if positive_count is _COUNT_OMITTED:
             del result["positive_count"]
@@ -2450,6 +2468,13 @@ class ImageRoutesMixin:
             def key(entry):
                 return _workspace_key(entry, order)
 
+        # #480: files removed from the library stay on disk, hidden here; the
+        # removed view (#498) lists only them.
+        hidden = self._hidden_entries(listings)
+        if filters.get("removed"):
+            entries = [entry for entry in entries if entry.normalized in hidden]
+        elif hidden:
+            entries = [entry for entry in entries if entry.normalized not in hidden]
         return (
             entries,
             key,
@@ -3071,7 +3096,9 @@ class ImageRoutesMixin:
         no symlinks), each preview folder is listed once, and at most
         MAX_THUMBNAIL_FILES targets are queued per batch (a job plans again
         after each batch); ``remaining`` counts the targets beyond that cap.
-        Sources in *exclude* (worked on by an earlier batch) are left out.
+        Sources in *exclude* (worked on by an earlier batch) are left out, and
+        so are files removed from the library (#501: a removal mark hides
+        them, and their previews went with their records).
         ``stop()`` true ends the walk before the next file.
         """
         settings = writer_settings(settings)
@@ -3080,11 +3107,14 @@ class ImageRoutesMixin:
         plan = {key: 0 for key in _PLAN_COUNTS}
         plan.update(targets=[], fresh_files=[])
         folders = {}
+        removed = self._removal_check_under(output_path)
         for src in _iter_media_files(output_path, MAX_GALLERY_FILES):
             if stop is not None and stop():
                 break
             if exclude and src in exclude:
                 continue
+            if removed(src):
+                continue
             rel_no_ext = src.relative_to(output_path).with_suffix("")
             stem = f"{rel_no_ext.name}{thumbnail_settings.THUMB_SUFFIX}"
             dst = thumbnails_dir / rel_no_ext.parent / (stem + settings.extension)

py/api/jobs.py

@@ -123,6 +123,11 @@ MODEL_DOWNLOAD_JOB_KIND = "model_download"
 DUPLICATES_JOB_KIND = "duplicates"
 DUPLICATE_GROUP_NAMES = ("groups_found",)
 DUPLICATE_CLEANUP_GROUP_NAMES = ("removed", "kept", "errors")
+# The workspace Library's Delete… (#443, py/api/library_delete.py): a
+# ``records`` hold around its safety backup and write.
+PROMPT_DELETE_JOB_KIND = "prompt_delete"
+IMAGE_DELETE_JOB_KIND = "image_delete"  # #480
+IMAGE_DELETE_GROUP_NAMES = ("trashed", "removed", "not_changed", "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"

py/api/library.py

@@ -157,6 +157,13 @@ def _archive_scope(request: web.Request) -> str:
     return value
 
 
+def _shelf(request: web.Request) -> str:
+    value = request.query.get("shelf", "active")
+    if value not in ("active", "archived"):
+        raise ValueError("shelf must be active or archived")
+    return value
+
+
 def _missing() -> web.Response:
     return web.json_response(
         {"success": False, "error": "Positive prompt not found"}, status=404
@@ -332,6 +339,9 @@ class LibraryRoutesMixin:
             "tags": sorted(set(request.query.getall("tag", []))),
             "tag_mode": request.query.get("tag_mode", "all"),
             "sort": request.query.get("sort", "newest"),
+            # #443: which shelf; part of the cursor scope, so a cursor never
+            # crosses shelves. Not the variant ``archive`` scope of /{id}.
+            "shelf": _shelf(request),
         }
         limit = _page_limit(request)
         cursor = request.query.get("cursor")

py/api/library_delete.py

@@ -0,0 +1,321 @@
+"""Delete or archive selected Library prompts, and restore archived ones (#443).
+
+The workspace Prompt library's Delete… (D152). The legacy ``POST
+/prompt_manager/bulk/delete`` and ``DELETE /prompt_manager/delete/{id}`` are
+separate and unchanged.
+
+- ``POST /prompt_manager/library/delete/preview {prompt_ids, expected_epoch}``
+  classifies the selection (reads only, under a lease): the ids to ``delete``
+  (in no saved pair), to ``archive`` (paired), the ``protected`` ones (tagged
+  ``__protected__``, kept), counts of ``already_archived`` and ``not_found``,
+  the ``image_links`` a delete removes, the safety ``backup`` policy and,
+  when a backup would be taken, the ``disk`` it needs.
+- ``POST /prompt_manager/library/delete {archive_ids, delete_ids,
+  expected_epoch, backup}`` executes that review under a ``records`` hold
+  (refused 409 ``busy`` beside a scan, restore, maintenance, move or
+  Optimize). When a delete remains and a backup was promised (the reviewed
+  ``backup`` was "on" or the policy is on now) it checks the disk (507
+  ``insufficient-space``) and takes a verified safety backup (500
+  ``backup-failed``); then one transaction deletes the reviewed deletes whose
+  fingerprint is unchanged since the backup and archives the paired ones.
+- ``POST /prompt_manager/library/restore {prompt_ids, expected_epoch}``
+  removes the archive mark (under a lease).
+
+A changed storage epoch answers 409 ``storage-changed``; nothing is written.
+"""
+
+import sqlite3
+
+from aiohttp import web
+
+try:
+    from ...database.library_commands import LibraryCommandError
+    from ...database.safety_backup import SafetyBackupFailed
+except ImportError:
+    from database.library_commands import LibraryCommandError
+    from database.safety_backup import SafetyBackupFailed
+
+from . import maintenance as _maintenance
+from .admin import _prune_safety_backups
+from .job_routes import busy_response
+from .jobs import PROMPT_DELETE_JOB_KIND, JobBusy
+from .prompts import parse_bulk_prompt_ids
+
+PREVIEW_URL = "/prompt_manager/library/delete/preview"
+DELETE_URL = "/prompt_manager/library/delete"
+RESTORE_URL = "/prompt_manager/library/restore"
+DELETE_TITLE = "Delete prompts (Library)"
+_SELECTION_KEYS = frozenset({"prompt_ids", "expected_epoch"})
+_DELETE_KEYS = frozenset({"archive_ids", "delete_ids", "expected_epoch", "backup"})
+# #482: Delete permanently, with its digests; both or neither (a #443 body).
+_PAIRED_KEYS = frozenset({"delete_paired_ids", "paired_digests"})
+# #492: the shelf the Delete… runs on, optional on its own (default "active").
+_SHELF_KEYS = frozenset({"shelf"})
+STORAGE_CHANGED = "Prompt storage was restored; refresh the library"
+
+
+def _failure(status, code, error, **extra):
+    return web.json_response(
+        {"success": False, "code": code, "error": error, **extra}, status=status
+    )
+
+
+def _invalid(message):
+    return _failure(400, "invalid-request", message)
+
+
+def _storage_changed(exc):
+    return _failure(409, exc.code, STORAGE_CHANGED, library_epoch=exc.epoch)
+
+
+async def _body(request, keys, *groups):
+    """The JSON object with exactly ``keys``, plus all or none of each group."""
+    try:
+        data = await request.json()
+    except ValueError:
+        raise ValueError("Expected a JSON object") from None
+    if not isinstance(data, dict):
+        raise ValueError("Expected a JSON object")
+    extra = set(data) - keys
+    partial = False
+    for group in groups:
+        if extra & group:
+            partial = partial or not group <= extra
+            extra -= group
+    if not keys <= set(data) or extra or partial:
+        raise ValueError("Request must contain exactly " + ", ".join(sorted(keys)))
+    return data
+
+
+def _shelf(data):
+    """#492: the shelf a Delete… was reviewed on."""
+    shelf = data.get("shelf", "active")
+    if shelf not in ("active", "archived"):
+        raise ValueError("shelf must be active or archived")
+    return shelf
+
+
+def _paired_delete(data, archive_ids):
+    """#482: the reviewed archive ids to delete with their pairs -> digest."""
+    if "delete_paired_ids" not in data:
+        return {}
+    ids = _reviewed_ids(data["delete_paired_ids"], "delete_paired_ids")
+    digests = data["paired_digests"]
+    if not isinstance(digests, dict):
+        raise ValueError("paired_digests must map prompt ids to digests")
+    if not set(ids) <= set(archive_ids):
+        raise ValueError("delete_paired_ids must be reviewed archive ids")
+    chosen = {}
+    for pid in ids:
+        digest = digests.get(str(pid))
+        if not isinstance(digest, str) or len(digest) != 64:
+            raise ValueError("Every delete_paired_ids entry needs its review digest")
+        chosen[pid] = digest
+    return chosen
+
+
+def _reviewed_ids(value, name):
+    """A reviewed id list: possibly empty, else as ``parse_bulk_prompt_ids``."""
+    if value == []:
+        return []
+    try:
+        return parse_bulk_prompt_ids(value)
+    except ValueError as exc:
+        raise ValueError(str(exc).replace("prompt_ids", name)) from None
+
+
+class LibraryDeleteRoutesMixin:
+    """Mixin providing the workspace Library's delete, archive and restore."""
+
+    def _register_library_delete_routes(self, routes):
+        routes.post(PREVIEW_URL)(self.preview_library_delete)
+        routes.post(DELETE_URL)(self.delete_library_prompts)
+        routes.post(RESTORE_URL)(self.restore_library_prompts)
+
+    async def preview_library_delete(self, request):
+        try:
+            data = await _body(request, _SELECTION_KEYS, _SHELF_KEYS)
+            ids = parse_bulk_prompt_ids(data["prompt_ids"])
+            shelf = _shelf(data)
+        except ValueError as exc:
+            return _invalid(str(exc))
+        db = self.db
+        policy = self._safety_backup_policy()
+        try:
+            async with self._jobs.lease("Library delete review"):
+                review = await self._run_in_executor(
+                    db.classify_library_delete,
+                    ids,
+                    expected_epoch=data["expected_epoch"],
+                    shelf=shelf,
+                )
+                disk = None
+                if (review["delete"] or review["deletable"]) and policy == "on":
+                    public, short, _size = await self._run_in_executor(
+                        _maintenance.disk_plan,
+                        db.model.db_path,
+                        backup=True,
+                        vacuum=False,
+                    )
+                    disk = {
+                        **public,
+                        "message": (
+                            None
+                            if short is None
+                            else _maintenance.short_space_message(short)
+                        ),
+                    }
+        except JobBusy as busy:
+            return busy_response(busy)
+        except LibraryCommandError as exc:
+            return _storage_changed(exc)
+        except ValueError as exc:
+            return _invalid(str(exc))
+        except (OSError, sqlite3.Error):
+            self.logger.exception("Library delete review failed")
+            return _failure(500, "review-failed", "The delete could not be reviewed")
+        return web.json_response(
+            {
+                "success": True,
+                "library_epoch": review["library_epoch"],
+                "delete": review["delete"],
+                "archive": review["archive"],
+                "protected": review["protected"],
+                "already_archived": len(review["already_archived"]),
+                "not_archived": len(review["not_archived"]),
+                "not_found": len(review["not_found"]),
+                "image_links": review["image_links"],
+                # #482: the archive ids Delete permanently may delete with pairs.
+                "deletable": review["deletable"],
+                "review_digests": {
+                    str(pid): digest for pid, digest in review["review_digests"].items()
+                },
+                "paired_counts": review["paired_counts"],
+                "paired_image_links": review["paired_image_links"],
+                "backup": policy,
+                "disk": disk,
+            }
+        )
+
+    async def delete_library_prompts(self, request):
+        try:
+            data = await _body(request, _DELETE_KEYS, _PAIRED_KEYS, _SHELF_KEYS)
+            shelf = _shelf(data)
+            archive_ids = _reviewed_ids(data["archive_ids"], "archive_ids")
+            delete_ids = _reviewed_ids(data["delete_ids"], "delete_ids")
+            if not archive_ids and not delete_ids:
+                raise ValueError("Nothing to delete or archive")
+            if len(archive_ids) + len(delete_ids) > 1000:
+                raise ValueError("At most 1000 prompts can be changed at once")
+            if set(archive_ids) & set(delete_ids):
+                raise ValueError("A prompt cannot be both archived and deleted")
+            if data["backup"] not in ("on", "off"):
+                raise ValueError("backup must be on or off")
+            paired = _paired_delete(data, archive_ids)
+        except ValueError as exc:
+            return _invalid(str(exc))
+        busy = self._jobs.blocker(PROMPT_DELETE_JOB_KIND, admission="records")
+        if busy is not None:
+            return busy_response(JobBusy(busy))
+        try:
+            async with self._jobs.hold(
+                PROMPT_DELETE_JOB_KIND, DELETE_TITLE, admission="records"
+            ) as job:
+                response = await self._held_library_delete(
+                    self.db, data, archive_ids, delete_ids, paired, shelf
+                )
+                if response.status >= 400:
+                    job.finish("failed")
+                return response
+        except JobBusy as busy:
+            return busy_response(busy)
+
+    async def _held_library_delete(
+        self, db, data, archive_ids, delete_ids, paired, shelf="active"
+    ):
+        epoch = data["expected_epoch"]
+        promised = data["backup"] == "on" or self._safety_backup_policy() == "on"
+        backup = None
+        try:
+            candidates = None
+            if delete_ids or paired:
+                review = await self._run_in_executor(
+                    db.classify_library_delete,
+                    [*delete_ids, *paired],
+                    expected_epoch=epoch,
+                    # #492: the same shelf, or archived ids would skip the backup.
+                    shelf=shelf,
+                )
+                candidates = review["fingerprints"]
+                # #482: a permanent delete of a prompt in a saved pair is backed up too.
+                if (candidates or review["deletable"]) and promised:
+                    _disk, short, _size = await self._run_in_executor(
+                        _maintenance.disk_plan,
+                        db.model.db_path,
+                        backup=True,
+                        vacuum=False,
+                    )
+                    if short is not None:
+                        return _failure(
+                            507,
+                            "insufficient-space",
+                            _maintenance.short_space_message(short),
+                        )
+                    backup = await self._run_in_executor(
+                        _maintenance.take_safety_backup, db.model
+                    )
+            result = await self._run_in_executor(
+                db.archive_or_delete_library_prompts,
+                archive_ids,
+                delete_ids,
+                expected_epoch=epoch,
+                candidates=candidates if candidates is not None else {},
+                delete_paired=paired,
+                shelf=shelf,
+            )
+        except LibraryCommandError as exc:
+            return _storage_changed(exc)
+        except SafetyBackupFailed as error:
+            self.logger.error("Safety backup before a Library delete failed")
+            return _failure(
+                500, "backup-failed", _maintenance.backup_failed_message(error)
+            )
+        except ValueError as exc:
+            return _invalid(str(exc))
+        except (OSError, sqlite3.Error):
+            self.logger.exception("Library delete failed")
+            return _failure(500, "delete-failed", "The prompts could not be changed")
+        finally:
+            if backup is not None:
+                await self._prune_after_delete(db)
+        return web.json_response({"success": True, **result, "backup": backup})
+
+    async def _prune_after_delete(self, db):
+        try:
+            await self._run_in_executor(_prune_safety_backups, db.model.db_path)
+        except Exception:  # pruning old copies never fails the delete
+            self.logger.exception("Could not prune old safety backups")
+
+    async def restore_library_prompts(self, request):
+        try:
+            data = await _body(request, _SELECTION_KEYS)
+            ids = parse_bulk_prompt_ids(data["prompt_ids"])
+        except ValueError as exc:
+            return _invalid(str(exc))
+        try:
+            async with self._jobs.lease("Library restore"):
+                result = await self._run_in_executor(
+                    self.db.restore_library_prompts,
+                    ids,
+                    expected_epoch=data["expected_epoch"],
+                )
+        except JobBusy as busy:
+            return busy_response(busy)
+        except LibraryCommandError as exc:
+            return _storage_changed(exc)
+        except ValueError as exc:
+            return _invalid(str(exc))
+        except (OSError, sqlite3.Error):
+            self.logger.exception("Library restore failed")
+            return _failure(500, "restore-failed", "The prompts could not be restored")
+        return web.json_response({"success": True, **result})

py/api/maintenance.py

@@ -281,7 +281,7 @@ def short_space_message(short):
     )
 
 
-def _changed_line(operation, count):
+def _changed_line(operation, count, marks=0):
     if operation == "optimize":
         return "Optimized the database"
     if operation == "duplicate_prompts":
@@ -291,7 +291,11 @@ def _changed_line(operation, count):
         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}"
+    line = f"Removed {count:,} {noun}"
+    if marks:
+        gone = "removed image" if marks == 1 else "removed images"
+        line += f"; forgot {marks:,} {gone} whose files are gone or changed"
+    return line
 
 
 def take_safety_backup(model, label="backup"):
@@ -419,6 +423,7 @@ class MaintenanceRoutesMixin:
             draft.public(),
             {
                 "targets": draft.targets,
+                "marks": draft.marks,
                 "roots": roots,
                 "protected": draft.protected["count"],
                 "rows": draft.scope["count"],
@@ -488,7 +493,9 @@ class MaintenanceRoutesMixin:
     # ── apply ─────────────────────────────────────────────────────────
 
     async def apply_maintenance_plan(self, request):
-        data, error = await self._read_maintenance_body(request, ("token",))
+        from .image_delete import IMAGE_DELETE, parse_mode
+
+        data, error = await self._read_maintenance_body(request, ("token", "mode"))
         if error is not None:
             return error
         token = data.get("token")
@@ -497,6 +504,13 @@ class MaintenanceRoutesMixin:
         plan, refused = self._peek_plan(token)
         if refused is not None:
             return refused
+        mode = None
+        if plan.operation == IMAGE_DELETE:
+            mode = parse_mode(data.get("mode"))
+            if mode is None:
+                return _invalid('mode must be "library" or "trash"')
+        elif "mode" in data:
+            return _invalid("Unknown field: mode")
         store = self._maintenance_plans
         if plan.operation == ROTATED_LOGS:
             # Log files only: no database identity, backup or disk check.
@@ -544,6 +558,8 @@ class MaintenanceRoutesMixin:
         try:
             if plan.operation == DUPLICATE_FILES:
                 job = self._start_duplicate_cleanup(db, plan, backup)
+            elif plan.operation == IMAGE_DELETE:
+                job = self._start_image_delete(db, plan, mode, backup)
             elif plan.operation == WORKFLOW_STORAGE:
                 job = self._start_workflow_storage(db, backup)
             else:
@@ -642,6 +658,7 @@ class MaintenanceRoutesMixin:
                 plan.fingerprint,
                 payload["targets"],
                 payload["roots"],
+                payload.get("marks", ()),
             )
         except PlanChanged:
             return _fail_job(job, "plan-changed", PLAN_CHANGED)
@@ -653,7 +670,7 @@ class MaintenanceRoutesMixin:
         )
         job.record_counted("changed", result["changed"], rows)
         job.record_counted("protected", payload["protected"])
-        line = _changed_line(plan.operation, result["changed"])
+        line = _changed_line(plan.operation, result["changed"], result.get("marks", 0))
         job.log_line(line)
         job.update(progress=100, status_line=f"{line} · {backup_note(backup)}")
 

py/api/revalidation.py

@@ -0,0 +1,47 @@
+"""Revalidated responses for the pages and static files PromptManager serves.
+
+``Cache-Control: no-cache`` lets the browser keep a copy but makes it ask the
+server before every reuse, so a PromptManager update reaches the browser on a
+normal reload (#478). The ETag lets an unchanged file answer 304 without a
+body, which keeps that reload cheap.
+
+The tag hashes the bytes rather than the file's mtime and size: an update can
+keep both (an archive extract, a same-length edit within one clock tick), and
+the handlers read the whole file anyway. It is weak because the gzip
+middleware may send the same content in a different encoding.
+"""
+
+import hashlib
+
+from aiohttp import web
+
+REVALIDATE = "no-cache"
+
+
+def entity_tag(body: bytes) -> str:
+    """Weak ETag for ``body``."""
+    return f'W/"{hashlib.sha256(body).hexdigest()[:32]}"'
+
+
+def etag_matches(if_none_match, etag: str) -> bool:
+    """True when an If-None-Match header names ``etag`` (weak comparison)."""
+    if not if_none_match:
+        return False
+    if if_none_match.strip() == "*":
+        return True
+    opaque = etag.removeprefix("W/")
+    return any(
+        candidate.strip().removeprefix("W/") == opaque
+        for candidate in if_none_match.split(",")
+    )
+
+
+def revalidated_response(request, body: bytes, content_type: str, charset=None):
+    """200 with ``body``, or 304 when the request already holds this version."""
+    etag = entity_tag(body)
+    headers = {"Cache-Control": REVALIDATE, "ETag": etag}
+    if etag_matches(request.headers.get("If-None-Match"), etag):
+        return web.Response(status=304, headers=headers)
+    return web.Response(
+        body=body, content_type=content_type, charset=charset, headers=headers
+    )

tests/browser/browser-logs.spec.mjs

@@ -0,0 +1,26 @@
+// #513: a worker records its browser's own log, so a browser that dies between two tests leaves its exit and stderr
+// behind instead of only "Target page, context or browser has been closed" on the next test.
+import { test, expect } from './fixtures.mjs';
+import { isTargetGone } from '../../tools/vendor/browser-logs.mjs';
+
+test('the worker records the launch of the browser its tests use', async ({ browser, browserLogs }) => {
+    expect(browser.isConnected()).toBe(true);
+    expect(browserLogs.launches().length).toBeGreaterThan(0);
+});
+
+test('a killed browser leaves its signal and stderr in the worker log', async ({ playwright, browserName, browserLogs }) => {
+    const before = browserLogs.launches();
+    const victim = await playwright[browserName].launch();
+    const pid = browserLogs.launches().find(item => !before.includes(item));
+    expect(pid, 'the new browser\'s launch was recorded').toBeGreaterThan(0);
+    const disconnected = new Promise(resolve => victim.once('disconnected', resolve));
+    // Playwright starts a browser in a process group of its own; WebKit's launched pid is a wrapper script.
+    process.kill(-pid, 'SIGKILL');
+    await disconnected;
+    const error = await victim.newContext().then(() => null, item => item);
+    expect(error, 'a dead browser refuses a new context').not.toBeNull();
+    expect(isTargetGone(error.message)).toBe(true);
+    // The pipe can close before the launcher has logged the exit.
+    await expect.poll(() => browserLogs.exits()).toContainEqual({ pid, exitCode: null, signal: 'SIGKILL' });
+    expect(browserLogs.tail()).toContain(`[pid=${pid}] <process did exit: exitCode=null, signal=SIGKILL>`);
+});

tests/browser/classic-node.spec.mjs

@@ -7,7 +7,7 @@ test.beforeEach(async ({page, browserName}) => {
     page.classicErrors = [];
     page.on('pageerror', error => page.classicErrors.push(error.message));
     await page.route('**/scripts/app.js', route => route.fulfill({contentType:'text/javascript', body:'export const app = window.fixtureApp;'}));
-    await page.route('**/scripts/api.js', route => route.fulfill({contentType:'text/javascript', body:'export const api = {fileURL: path => path, queuePrompt: async (...args) => args};'}));
+    await page.route('**/scripts/api.js', route => route.fulfill({contentType:'text/javascript', body:'export const api = {fileURL: path => (window.fixtureApiBase ?? "") + path, queuePrompt: async (...args) => args};'}));
     await page.route('**/extensions/promptmanager/prompt_manager.js', route => route.fulfill({contentType:'text/javascript', body:readFileSync(new URL('../../web/comfy/prompt_manager.js', import.meta.url),'utf8')}));
     await page.goto('/prompt_manager/test');
     await page.evaluate(() => {
@@ -64,6 +64,28 @@ test('Classic keeps immediate selection, search query and metadata serialization
     await expect(page.getByRole('button',{name:'🌐 Web UI',exact:true})).toBeVisible();
 });
 
+test('Classic Web UI opens the workspace Library in the saved display mode, through the mount prefix (#525)',async({page})=>{
+    await page.evaluate(()=>{window.fixtureApiBase='/mounted';window.open=(...args)=>{window.openArgs=args;return {};};});
+    const webUi=page.getByRole('button',{name:'🌐 Web UI',exact:true});
+    for (const [mode,args] of [
+        ['newtab',['/mounted/prompt_manager/workspace#/library','_blank']],
+        ['popup',['/mounted/prompt_manager/workspace#/library','_blank','width=1200,height=800,scrollbars=yes,resizable=yes']],
+    ]) {
+        await page.evaluate(value=>{node.properties.webuiDisplayMode=value;},mode);
+        await webUi.click();
+        expect(await page.evaluate(()=>window.openArgs)).toEqual(args);
+    }
+});
+
+test('Classic Web UI reports a blocked popup and keeps the canvas open (#525)',async({page})=>{
+    const before=page.url();
+    await page.evaluate(()=>{window.open=()=>null;});
+    await page.getByRole('button',{name:'🌐 Web UI',exact:true}).click();
+    await expect(page.getByText('Allow popups to open Web UI, then try again.')).toBeVisible();
+    expect(page.url()).toBe(before);
+    await expect(page.locator('.pm-classic')).toBeVisible();
+});
+
 test('Classic detaches native text synchronization on removal',async({page})=>{
     // The page installs the text sync (serializeValue and its listeners) in a 50 ms timer; wait for it, not for time.
     await expect.poll(()=>page.evaluate(()=>typeof node.widgets.find(item=>item.name==='text').serializeValue)).toBe('function');

tests/browser/concept-inventory.mjs

@@ -421,7 +421,8 @@ export function measureInventory(scope) {
             description:when(description,()=>({className:description.className,text:description.textContent,...font(description),...edges(description)})),
             actions:when(actions,()=>({...layout(actions),...edges(actions),
                 fullWidth:px(rect(actions).width)===px(rect(heading).width),stacked:copy?rect(actions).top>=rect(copy).bottom-0.5:null,
-                buttons:[...actions.querySelectorAll('button')].map(node=>({text:node.textContent.trim(),primary:node.classList.contains('ca-primary'),
+                // D163: a closed menu's items are not heading actions.
+                buttons:[...actions.querySelectorAll('button')].filter(node=>!node.closest('[role="menu"]')).map(node=>({text:node.textContent.trim(),primary:node.classList.contains('ca-primary'),
                     ...font(node),...edges(node),minHeight:getComputedStyle(node).minHeight,height:px(rect(node).height)}))}))};
     }
     // ---- Images (#249 C7). Every box is relative to its section, every section to `main` (vertical rhythm). ----

tests/browser/fixtures.mjs

@@ -4,13 +4,29 @@
 // points at that worker's server. A server that dies fails the running test
 // with its stderr tail, and the next test in the worker gets a fresh server.
 // A test that fails gets the stderr its server wrote during it attached as
-// `server-stderr`.
+// `server-stderr`. The worker also records its browser's own log (#513): a
+// browser that exits abnormally prints one `pm-browser-exit|` line, and a test
+// that fails on a closed or crashed target gets that log attached as
+// `browser-stderr`.
 import { test as base, expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
 import { attachServerStderr, createServerSupervisor, startBrowserServer } from '../../tools/vendor/start-browser-server.mjs';
+import { attachBrowserLogs, createBrowserLogRecorder } from '../../tools/vendor/browser-logs.mjs';
 
 const SERVER_FIXTURE_TIMEOUT_MS = 90_000;
 
 export const test = base.extend({
+    browserLogs: [async ({}, use) => {
+        const recorder = createBrowserLogRecorder();
+        try {
+            await use(recorder);
+        } finally {
+            recorder.uninstall();
+        }
+    }, { scope: 'worker', auto: true }],
+    browserLogsOnFailure: [async ({ browserLogs }, use, testInfo) => {
+        await use();
+        await attachBrowserLogs(testInfo, browserLogs);
+    }, { auto: true }],
     testServer: [async ({}, use) => {
         const supervisor = createServerSupervisor({ start: () => startBrowserServer() });
         try {

tests/browser/focused-node.spec.mjs

@@ -485,7 +485,7 @@ test(`${variant} respects the existing Web UI display preference`,async({page})=
     });
     await page.evaluate(()=>node._focusedSettingsReady);
     await page.getByRole('button',{name:'Web UI ↗',exact:true}).click();
-    expect(await page.evaluate(()=>window.openArgs)).toEqual(['/prompt_manager/web','_blank']);
+    expect(await page.evaluate(()=>window.openArgs)).toEqual(['/prompt_manager/workspace#/library','_blank']);
 });
 
 test(`${variant} reports blocked Web UI popups without leaving the workflow`,async({page})=>{

tests/browser/full-inspector.spec.mjs

@@ -149,8 +149,8 @@ test('panel matches the concept order and copy',async({page,request})=>{
     await expect(panel.locator('.meta-grid dt')).toHaveText(['Seed','Steps','CFG','Sampler','Scheduler','Model']);
     await expect(panel.locator('.meta-grid dd')).toHaveText(['9007199254740993','28','6.5','dpmpp_2m','karras','fixture-model.safetensors']);
     const footer=panel.locator('.detail-footer');
-    // #331 D139: every listed file's footer ends with Collections… (folder icon).
-    await expect(footer.locator('button')).toHaveText(['Send to ComfyUI','Prompt history','Collections…']);
+    // #331 D139: every listed file's footer has Collections… (folder icon); #480 D159: Delete… ends it.
+    await expect(footer.locator('button')).toHaveText(['Send to ComfyUI','Prompt history','Collections…','Delete…']);
     await expect(footer.locator('button.send')).toHaveAccessibleName(`Send prompt pair to ComfyUI: ${POSITIVE_TITLE}`);
     await expect(footer.locator('button.send svg.icon')).toHaveCount(1);await expect(footer.locator('button:not(.send) svg.icon')).toHaveCount(2);
     await expect(panel).not.toContainText(/prompt evidence|Positive prompt tags/);
@@ -162,10 +162,10 @@ test('panel matches the concept order and copy',async({page,request})=>{
     await selectFile(page,'ambiguous.png');await expect(panel.locator('.prompt-section.positive .prompt-text')).toHaveText('embedded positive');
     await expect(panel.locator('span.chip.blue')).toHaveText('Embedded parameters');
     await expect(panel.locator('.panel-heading .chip')).toHaveText('File extension PNG');await expect(panel.locator('.panel-heading .chip .ca-visually-hidden')).toHaveText('File extension ');
-    await expect(panel.locator('.detail-footer button')).toHaveText(['Send to ComfyUI','Collections…']);
-    // Unlinked: no badge, category, tags, pair or history; the footer holds only Collections… (D139).
+    await expect(panel.locator('.detail-footer button')).toHaveText(['Send to ComfyUI','Collections…','Delete…']);
+    // Unlinked: no badge, category, tags, pair or history; the footer holds Collections… (D139) and Delete… (D159).
     reads.patch=null;await selectFile(page,'empty.png');await expect(panel.locator('.panel-heading h2')).toHaveText('empty.png');
-    await expect(panel.locator('.detail-footer button')).toHaveText(['Collections…']);
+    await expect(panel.locator('.detail-footer button')).toHaveText(['Collections…','Delete…']);
     expect(await panelStructure(panel)).toEqual({outer:['img.detail-cover','div.detail-inner','div.detail-footer'],
         inner:['div.panel-heading','p.small','section.prompt-section.positive','section.prompt-section.negative','dl.meta-grid']});
     await expect(panel.locator('.meta-grid dd')).toHaveText(Array(6).fill('Not recorded'));
@@ -266,7 +266,7 @@ test('pair send and history appear only with real roles and link',async({page,re
     await expect(panel.getByRole('button',{name:'Send prompt pair to ComfyUI: explicit-empty.png',exact:true})).toBeVisible();
     await expect(panel.getByRole('button',{name:'Prompt history',exact:true})).toHaveCount(0);
     await selectFile(page,'empty.png');await expect(panel.locator('.panel-heading h2')).toHaveText('empty.png');
-    await expect(panel.locator('.detail-footer button')).toHaveText(['Collections…']);await expect(panel.getByRole('button',{name:/^Send prompt pair/})).toHaveCount(0);
+    await expect(panel.locator('.detail-footer button')).toHaveText(['Collections…','Delete…']);await expect(panel.getByRole('button',{name:/^Send prompt pair/})).toHaveCount(0);
 });
 
 test('no provenance, raw or download controls in the side panel',async({page,request})=>{
@@ -627,6 +627,10 @@ test('viewer matches the concept shell and toolbar order',async({page,request})=
         expect(modePaths.map(path=>path.split(' > ').slice(2).join(' > '))).toEqual(['button#viewer-mode.icon-btn','button#viewer-mode.icon-btn > svg.icon','button#viewer-mode.icon-btn > svg.icon > path']);
         expect(production.paths[production.paths.indexOf(modePaths[2])+1]).toBe('dialog#viewer-dialog > div.dialog-header > button#viewer-close');
         production.paths=production.paths.filter(path=>!modePaths.includes(path));
+        // #480 D159: the Images viewer's Delete… (`danger`) follows Download; the concept has none.
+        expect(production.toolbar[8].text).toBe('Delete…');
+        production.toolbar.splice(8,1);
+        production.paths=production.paths.filter(path=>!path.includes('button.danger'));
         // #249 D34: after Next → production appends its own status lines (position, then the transform and slideshow
         // reasons), and Download stays the original-file link; every other control keeps the concept's text and order.
         const appended=production.toolbar.slice(9);

tests/browser/history-concept.spec.mjs

@@ -26,7 +26,8 @@ const SECTIONS=['heading','history','noPageScroll'];
  */
 export function mapHistoryConcept(reference) {
     const {history}=reference.oracle;
-    return {...reference,history:{...history,
+    // D163 (#512): the heading as laid out with the More menu button (the oracle's heading).
+    return {...reference,heading:reference.oracle.heading,history:{...history,
         // D24: "N tracked runs" is the recorded window's `recorded_run_count`; the fixture records one run per image, so
         // the concept's "4 tracked runs" holds by construction (asserted on both documents below).
         summary:history.summary,
@@ -120,11 +121,14 @@ async function conceptAsRecorded(page) {
         const add=[...document.querySelectorAll('.timeline-panel .row-actions > button')].find(node=>node.textContent==='+ Add negative');
         const archived=add.cloneNode(false);archived.removeAttribute('data-action');archived.removeAttribute('data-prompt');
         archived.setAttribute('aria-pressed','false');archived.textContent=label;add.after(archived);
-        window.__historyOracle={timeline,order:[...lanes].reverse(),texts,archived};
+        // D163 (#512): the heading ends with the "⋯" More menu button, drawn as the concept's Edit metadata button.
+        const edit=[...document.querySelectorAll('#main > .heading .heading-actions > button')].find(node=>node.textContent.trim()==='Edit metadata');
+        const moreButton=edit.cloneNode(false);moreButton.removeAttribute('data-action');moreButton.textContent='⋯';edit.parentElement.append(moreButton);
+        window.__historyOracle={timeline,order:[...lanes].reverse(),texts,archived,moreButton};
     },SHOW_ARCHIVED);
     await settle(page);
     return ()=>page.evaluate(()=>{
-        const {timeline,order,texts,archived}=window.__historyOracle;
+        const {timeline,order,texts,archived,moreButton}=window.__historyOracle;moreButton.remove();
         order.forEach((lane,index)=>{lane.style.setProperty('--lane-offset',`${38+index*47}px`);timeline.append(lane);});
         for(const [span,text] of texts)span.textContent=text;
         archived.remove();delete window.__historyOracle;

tests/browser/images-concept.spec.mjs

@@ -31,13 +31,15 @@ function captionDay(seconds,now=new Date()) {
 }
 
 /**
- * D8 (amended by #249 PR D and #331): the selection bar's real actions only; Remove links… is left out. Add to
- * collection compares in place (D138).
+ * D8 (amended by #249 PR D and #331): the selection bar's real actions only. Add to collection compares in place
+ * (D138). #480 D159: Remove links… returns as Delete…; OMITTED_BULK names the concept button it replaces.
  */
 const OMITTED_BULK=Object.freeze(['Remove links…']);
 const OMITTED_BULK_SELECTORS=Object.freeze(['bulk-remove'].map(action=>`#bulkbar [data-action="${action}"]`));
 /** D85: Auto-tag selected follows the concept's Add tags, a concept button of its own text. */
 const AUTO_TAG_CLONE=Object.freeze([{selector:'#bulkbar [data-action="bulk-tags"]',text:'Auto-tag selected'}]);
+/** #480 D159: Delete… takes the place of Remove links… (the concept's `danger` button, under another text). */
+const DELETE_CLONE=Object.freeze([{selector:'#bulkbar [data-action="bulk-remove"]',text:'Delete…'}]);
 
 /**
  * `withoutItems` for a row with padding and a border (the `.bulkbar`): its items flow again inside the content box,
@@ -452,10 +454,12 @@ for(const [width,height] of SIZES)for(const theme of THEMES)test(`images selecti
     const restore=await mutate(page,{remove:[...OMITTED_BULK_SELECTORS]});
     const removed=(await inventoryOf(page,'#main')).bulkbar;
     await restore();
-    // The oracle for production's bar: the concept page itself without the omitted actions and with D85's button.
-    const restoreProduction=await mutate(page,{remove:[...OMITTED_BULK_SELECTORS],clone:AUTO_TAG_CLONE});
+    // The oracle for production's bar: the concept page itself with D85's button and D159's Delete… in place of
+    // Remove links….
+    const restoreClones=await mutate(page,{clone:[...AUTO_TAG_CLONE,...DELETE_CLONE]});
+    const restoreRemoved=await mutate(page,{remove:[...OMITTED_BULK_SELECTORS]});
     const oracle=await inventoryOf(page,'#main');
-    await restoreProduction();
+    await restoreRemoved();await restoreClones();
     await captureCanonicalState(page,testInfo,`concept-images-selected-${width}-${theme}`);
     await openProductionLoaded(page,theme,'no-preference');
     const emptyActual=await inventoryOf(page,'#workspace-main');
@@ -468,7 +472,7 @@ for(const [width,height] of SIZES)for(const theme of THEMES)test(`images selecti
         'Add to collection','Export metadata','Remove links…','Clear']);
     expect.soft(diffInventory(stripExact(mapBulkbar(reference.bulkbar,0).bulkbar.bar),stripExact(removed.bar)),'bar without the omitted actions').toEqual([]);
     expect.soft(actual.bulkbar.bar.items.map(item=>item.text),'production bar').toEqual(['1 selected','Add tags','Auto-tag selected',
-        'Set category','Add to collection','Export metadata','Clear']);
+        'Set category','Add to collection','Export metadata','Delete…','Clear']);
     expect.soft(compare(empty,emptyActual,manifest,['bulkbar','cards','panel']),'nothing checked').toEqual([]);
     expect.soft(compare(oracle,actual,manifest,['bulkbar','cards','panel']),'one card checked').toEqual([]);
     // The bar comparison notices a change to the production bar.

tests/browser/images-delete-concept.spec.mjs

@@ -0,0 +1,106 @@
+import {test,expect} from './fixtures.mjs';
+import {SIZES,THEMES,seedConceptAt,openConcept,openProduction,diffInventory,mutate} from './concept-inventory.mjs';
+
+// #480 (D159): the Images selection bar's Delete… against the concept's "Remove links…" (app.js a432, `danger`) and
+// its review against the concept's `maintenancePlan` (a953–957): the bar button's place and style, the review's
+// `dl.meta-grid` rows and its actions, on the concept-shaped fixture, at 1600x1100 and 390x844 in both themes.
+// Paired screenshots are artifacts only; there are no PNG baselines.
+test.use({locale:'en-US',timezoneId:'UTC'});
+
+const CARDS='.gallery-body > .image-grid > .media-card';
+
+/** Runs in the page: the selection bar's danger button and where it sits among the bar's buttons. */
+function measureBar() {
+    const bar=document.querySelector('#bulkbar > .bulkbar');
+    const buttons=[...bar.querySelectorAll(':scope > button')];
+    const danger=bar.querySelector(':scope > button.danger');
+    const css=(node,...keys)=>Object.fromEntries(keys.map(key=>[key,getComputedStyle(node)[key]]));
+    return {
+        // The danger action sits right before Clear, the last button.
+        dangerBeforeClear:buttons.indexOf(danger)===buttons.length-2,
+        lastText:buttons.at(-1).textContent.trim(),
+        danger:css(danger,'color','backgroundColor','borderTopColor','fontSize','fontWeight','paddingTop','paddingLeft',
+            'borderTopLeftRadius','height'),
+    };
+}
+
+/** Runs in the page: the open review's grid and actions (the parts production shares with the concept). */
+function measureReview() {
+    const dialog=document.querySelector('dialog#modal[open]');
+    const css=(node,...keys)=>node?Object.fromEntries(keys.map(key=>[key,getComputedStyle(node)[key]])):null;
+    const grid=dialog.querySelector('#modal-body dl.meta-grid');
+    const entry=grid.querySelector(':scope > div');
+    const actions=dialog.querySelector('#modal-body > .dialog-actions');
+    const [cancel]=actions.children;
+    return {
+        grid:css(grid,'display','gridTemplateColumns','columnGap','rowGap'),
+        dt:css(entry.querySelector('dt'),'fontSize','color','textTransform','letterSpacing'),
+        dd:css(entry.querySelector('dd'),'fontSize','color','marginLeft'),
+        terms:[...grid.querySelectorAll('dt')].map(dt=>dt.textContent.trim()),
+        actions:css(actions,'display','justifyContent','columnGap','marginTop'),
+        cancel:{text:cancel.textContent.trim(),...css(cancel,'backgroundColor','color','fontSize','paddingTop','paddingLeft')},
+    };
+}
+
+async function checkFirst(page) {
+    await page.locator(CARDS).first().locator('.image-overlays > label > input[type="checkbox"]').check();
+}
+
+async function concept(page,theme) {
+    await openConcept(page,'images',theme);
+    await checkFirst(page);
+    const bar=await page.evaluate(measureBar);
+    await page.locator('#main #bulkbar').getByRole('button',{name:'Remove links…',exact:true}).click();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Review maintenance plan');
+    await page.mouse.move(0,0);
+    return {bar,review:await page.evaluate(measureReview)};
+}
+
+async function production(page,theme) {
+    await openProduction(page,'images',theme);
+    await expect(page.locator(CARDS).first()).toBeVisible();
+    await checkFirst(page);
+    const bar=await page.evaluate(measureBar);
+    await page.locator('#workspace-main #bulkbar').getByRole('button',{name:'Delete…',exact:true}).click();
+    const dialog=page.locator('dialog#modal[open]');
+    await expect(dialog.locator('#modal-title')).toHaveText('Delete 1 image');
+    await dialog.getByRole('radio',{name:/^Remove from the library only/}).check();
+    await page.mouse.move(0,0);
+    return {bar,review:await page.evaluate(measureReview)};
+}
+
+/**
+ * D159: production's rows follow the chosen mode (Scope, then what the files lose, Backup and Media on disk; the
+ * concept's sample has Scope, Protected, Backup and Media on disk). The geometry, tokens and the Cancel button match.
+ */
+function mapConcept(reference,actual) {
+    return {...reference,review:{...reference.review,terms:actual.review.terms}};
+}
+
+test.beforeEach(async({page,request},testInfo)=>{testInfo.manifest=await seedConceptAt(page,request);});
+
+for(const theme of THEMES)for(const [width,height] of SIZES) {
+    test(`delete matches the concept's remove links ${theme} ${width}x${height}`,async({page},testInfo)=>{
+        await page.setViewportSize({width,height});
+        const reference=await concept(page,theme);
+        await page.screenshot({path:testInfo.outputPath(`concept-remove-links-${theme}-${width}.png`)});
+        const actual=await production(page,theme);
+        await page.screenshot({path:testInfo.outputPath(`production-delete-${theme}-${width}.png`)});
+        expect(reference.review.terms).toEqual(['Scope','Protected','Backup','Media on disk']);
+        expect(actual.review.terms[0]).toBe('Scope');
+        expect(actual.review.terms.slice(-2)).toEqual(['Backup','Media on disk']);
+        expect(diffInventory(mapConcept(reference,actual),actual)).toEqual([]);
+    });
+}
+
+test('delete comparison detects mutations',async({page})=>{
+    await page.setViewportSize({width:1600,height:1100});
+    const reference=await concept(page,'dark');
+    const actual=await production(page,'dark');
+    const expected=mapConcept(reference,actual);
+    expect(diffInventory(expected,actual)).toEqual([]);
+    const undo=await mutate(page,{css:'dialog#modal dl.meta-grid { column-gap: 31px; } dialog#modal .dialog-actions { gap: 29px; }'});
+    const paths=diffInventory(expected,{...actual,review:await page.evaluate(measureReview)}).map(item=>item.path);
+    expect(paths).toEqual(expect.arrayContaining(['review.grid.columnGap','review.actions.columnGap']));
+    await undo();
+});

tests/browser/images-removed-concept.spec.mjs

@@ -0,0 +1,65 @@
+import {test,expect} from './fixtures.mjs';
+import {seedConceptAt,openConcept,openProduction} from './concept-inventory.mjs';
+
+// #498 (D162): the concept has no Show removed images screen, so production builds it from the concept's own parts:
+// the heading action button (as the concept's Images heading button), the card's `.chip` (as a concept card chip) and
+// the selection bar's buttons (as the concept bar's plain buttons). Each is compared with its concept counterpart.
+test.use({locale:'en-US',timezoneId:'UTC'});
+
+const CARDS='.gallery-body > .image-grid > .media-card';
+const KEYS=['color','backgroundColor','borderTopColor','borderTopWidth','fontSize','fontWeight','paddingTop','paddingLeft',
+    'borderTopLeftRadius','height'];
+const CHIP_KEYS=['color','backgroundColor','borderTopColor','fontSize','fontWeight','paddingTop','paddingLeft',
+    'borderTopLeftRadius'];
+
+/** Runs in the page: the computed style of the first node `selector` matches. */
+function styleOf([selector,keys]) {
+    const node=document.querySelector(selector);
+    return node?Object.fromEntries(keys.map(key=>[key,getComputedStyle(node)[key]])):null;
+}
+
+async function measure(page,selectors) {
+    const found={};
+    for (const [name,selector,keys] of selectors) found[name]=await page.evaluate(styleOf,[selector,keys]);
+    return found;
+}
+
+test.beforeEach(async({page,request})=>{await seedConceptAt(page,request);});
+
+for (const theme of ['dark','light']) {
+    test(`Show removed images uses the concept's heading button, chip and bar buttons (${theme})`,async({page})=>{
+        await page.setViewportSize({width:1600,height:1100});
+        await openConcept(page,'images',theme);
+        await page.locator(CARDS).first().locator('.image-overlays > label > input[type="checkbox"]').check();
+        await page.mouse.move(0,0);
+        const reference=await measure(page,[
+            ['heading','#main .heading-actions > button:not(.ca-primary)',KEYS],
+            ['chip','#main .chip',CHIP_KEYS],
+            ['bar','#main #bulkbar > .bulkbar > button:not(.danger)',KEYS],
+        ]);
+
+        await openProduction(page,'images',theme);
+        await expect(page.locator(CARDS).first()).toBeVisible();
+        await page.locator(CARDS).first().locator('.image-overlays > label > input[type="checkbox"]').check();
+        await page.locator('#workspace-main #bulkbar').getByRole('button',{name:'Delete…',exact:true}).click();
+        const dialog=page.locator('dialog#modal[open]');
+        await dialog.getByRole('radio',{name:/^Remove from the library only/}).check();
+        await dialog.locator('.dialog-actions button.danger').click();
+        const toggle=page.locator('.heading-actions').getByRole('button',{name:/^Show removed images \(1\)$/});
+        await expect(toggle).toBeVisible();
+        await page.mouse.move(0,0);
+        const heading=await measure(page,[['heading','#workspace-main .heading-actions > button[aria-pressed]',KEYS]]);
+        await toggle.click();
+        await expect(page.locator(`${CARDS} .chip`,{hasText:'Removed'})).toBeVisible();
+        await page.locator(CARDS).first().locator('.image-overlays > label > input[type="checkbox"]').check();
+        await expect(page.locator('#workspace-main #bulkbar').getByRole('button',{name:'Return to library'})).toBeVisible();
+        await page.mouse.move(0,0);
+        const actual={...heading,...await measure(page,[
+            ['chip',`${CARDS} .media-info .chip`,CHIP_KEYS],
+            ['bar','#workspace-main #bulkbar > .bulkbar > button',KEYS],
+        ])};
+        // Every part was found on both sides: two missing nodes must never compare equal.
+        expect(Object.values(reference).every(Boolean)).toBe(true);
+        expect(actual).toEqual(reference);
+    });
+}

tests/browser/inspector-concept.spec.mjs

@@ -56,7 +56,8 @@ function withCategoryScope(inventory) {
  * equal production. `reference.viewerPlain` is the concept's own full details
  * with its tag chips made plain (D20), D117's summary button added and, under a coarse pointer, D34's targets, all at
  * runtime: the browser lays out what follows them, as the Images spec's removed toolbar items do. D139's
- * "Collections…" is drawn after Prompt history in both the concept's panel footer and its full details.
+ * "Collections…" is drawn after Prompt history in both the concept's panel footer and its full details; #480's
+ * D159 "Delete…" follows it in the panel footer.
  */
 export function mapInspectorConcept(reference,{viewport}) {
     const {panel,viewerPlain,fileControls}=reference;
@@ -125,6 +126,13 @@ async function withCollectionsButton(page,selector) {
         for(const key of Object.keys(button.dataset))delete button.dataset[key];
         button.append(document.querySelector('.filter-row .chip > svg.icon').cloneNode(true),' Collections…');
         history.after(button);(window.__collectionsButtons??=[]).push(button);
+        // #480 D159: Delete… ends the panel's actions, drawn as the concept's own `danger` button (its Remove links…).
+        if(selector.startsWith('#image-inspector')) {
+            const remove=history.cloneNode(false);
+            for(const key of Object.keys(remove.dataset))delete remove.dataset[key];
+            remove.className='danger';remove.textContent='Delete…';
+            button.after(remove);window.__collectionsButtons.push(remove);
+        }
     },selector);
     await settle(page);
     return async()=>{await page.evaluate(()=>{for(const button of window.__collectionsButtons??[])button.remove();delete window.__collectionsButtons;});};
@@ -373,7 +381,7 @@ test('a recipe-linked image without recipe metadata shows its positive prompt me
     await expect(tags.locator('.role-label')).toHaveText('Prompt tags · 3');
     await expect(tags.locator('.tags > button.chip')).toHaveText(['minimal','warm_light','editorial']);
     await expect(tags.locator('span.chip')).toHaveCount(0);
-    await expect(panelOf(page).locator('.detail-footer button')).toHaveText(['Send to ComfyUI','Prompt history','Collections…']);
+    await expect(panelOf(page).locator('.detail-footer button')).toHaveText(['Send to ComfyUI','Prompt history','Collections…','Delete…']);
 });
 
 // #391: a tag chip replaces the collection; until its listing answers the caption says it is loading, never that the

tests/browser/library-concept.spec.mjs

@@ -44,7 +44,12 @@ export function mapLibraryConcept(reference) {
         // "4 runs" and "Used today". The two-line clamp is
         // applied below through `clampedCards`, measured on the concept with `CLAMP_CSS` (its samples wrap at 390px).
         footer:card.footer}));
-    return {...reference,library:{...library,toolbar,
+    // D152 (#443): Show archived prompts (N) comes first in the heading actions, a plain button like Export (the concept
+    // fixture has nothing archived, so N is 0).
+    const actions=reference.heading.actions;
+    const plain=actions.buttons.find(button=>!button.primary);
+    const heading={...reference.heading,actions:{...actions,buttons:[{...plain,text:'Show archived prompts (0)'},...actions.buttons]}};
+    return {...reference,heading,library:{...library,toolbar,
         // D35: the caption uses the singular for one.
         caption:{...library.caption,top:library.caption.top-rise,spans:library.caption.spans.map(span=>({...span,text:countCopy(span.text)}))},
         ...(({grid,cards:clamped})=>({grid:{...grid,top:grid.top-rise},cards:clamped}))(clampedCards({grid:library.grid,cards})),

tests/browser/library-delete-concept.spec.mjs

@@ -0,0 +1,148 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { SIZES, THEMES, seedConcept, openConcept, openProduction, diffInventory, mutate } from './concept-inventory.mjs';
+
+// #443 D152: the Library's Delete… review against the concept's own reviewed archive: the recipe editor's "Archive…"
+// (app.js 976), which opens `maintenancePlan("archive <title>")` (953–958, 1309–1310). The concept's shell, grid tokens,
+// `p.small` and actions are kept; its title, demo note, rows, note text and `ca-primary` start are replaced by D152's,
+// and the start takes the concept's `danger` class, measured on the editor's own "Archive…". The bar's Delete… is
+// compared with the concept Images bar's danger action, "Remove links…" (app.js 432).
+test.use({ locale: 'en-US', timezoneId: 'UTC' });
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await seedConcept(request);
+    page.conceptErrors = [];
+    page.on('pageerror', error => page.conceptErrors.push(error.message));
+});
+test.afterEach(async ({ page, browserName }) => {
+    await saveCoverage(page, browserName);
+    expect(page.conceptErrors).toEqual([]);
+});
+
+/** Runs in the page: the open review dialog's title, body tree, grid, notes and actions with the concept's tokens. */
+function measureReview() {
+    const dialog = document.querySelector('dialog#modal[open]');
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const text = node => node?.textContent.trim() ?? null;
+    const body = dialog.querySelector('#modal-body');
+    const grid = body.querySelector(':scope > dl.meta-grid');
+    const notes = [...body.querySelectorAll(':scope > p.small')];
+    const actions = body.querySelector(':scope > .dialog-actions');
+    return {
+        title: text(dialog.querySelector('#modal-title')),
+        tree: [...body.children].map(name).filter(item => item !== 'p.demo-note' && item !== 'h3'),
+        grid: { rows: [...grid.children].map(row => [text(row.querySelector('dt')), text(row.querySelector('dd'))]),
+            ...css(grid, 'display', 'gridTemplateColumns', 'columnGap', 'rowGap'),
+            dt: css(grid.querySelector('dt'), 'fontSize', 'color', 'textTransform'), dd: css(grid.querySelector('dd'), 'fontSize', 'color') },
+        notes: notes.map(note => ({ text: text(note), ...css(note, 'fontSize', 'color', 'marginTop') })),
+        actions: { tree: [...actions.children].map(name), ...css(actions, 'display', 'justifyContent', 'columnGap', 'marginTop'),
+            buttons: [...actions.children].map(item => ({ text: text(item), className: item.className,
+                ...css(item, 'backgroundColor', 'color', 'fontSize', 'paddingTop', 'paddingLeft', 'borderTopColor') })) },
+    };
+}
+
+/** Runs in the page: a button's class and tokens (the concept's danger button, or production's). */
+function measureButton(selector) {
+    const node = document.querySelector(selector);
+    const style = getComputedStyle(node);
+    return { className: node.className, ...Object.fromEntries(['backgroundColor', 'color', 'fontSize', 'fontWeight', 'paddingTop',
+        'paddingLeft', 'borderTopColor', 'borderTopLeftRadius', 'height'].map(key => [key, key === 'height'
+        ? `${Math.round(node.getBoundingClientRect().height * 100) / 100}px` : style[key]])) };
+}
+
+async function conceptReview(page, theme) {
+    await openConcept(page, 'prompt/alpine', theme);
+    await page.locator('#main .heading-actions').getByRole('button', { name: 'Edit metadata', exact: true }).click();
+    const archive = page.locator('dialog#modal[open] .dialog-actions button', { hasText: 'Archive…' });
+    await expect(archive).toBeVisible();await page.mouse.move(0, 0);
+    const danger = await page.evaluate(measureButton, 'dialog#modal[open] .dialog-actions button.danger');
+    await archive.click();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Review maintenance plan');
+    await page.mouse.move(0, 0);
+    return { danger, review: await page.evaluate(measureReview) };
+}
+
+async function seedMixed(request) {
+    // One unpaired prompt beside the concept's paired ones, so the review deletes one and archives one.
+    await expect(await request.post('/prompt_manager/save', { data: { text: 'Unpaired study', category: 'Studies' } })).toBeOK();
+    const items = (await (await request.get('/prompt_manager/library?limit=100')).json()).items;
+    return { unpaired: items.find(item => item.text === 'Unpaired study'), paired: items.find(item => item.variant_count > 0) };
+}
+
+async function productionReview(page, request, theme) {
+    const { unpaired, paired } = await seedMixed(request);
+    await openProduction(page, 'library', theme);
+    for (const item of [unpaired, paired]) await page.locator(`article[data-prompt-id="${item.id}"] .image-overlays input`).check();
+    await page.locator('#library-bulkbar .bulkbar').getByRole('button', { name: 'Delete…', exact: true }).click();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Delete or archive selected prompts');
+    await page.mouse.move(0, 0);
+    return page.evaluate(measureReview);
+}
+
+/** D152's changes to the concept's review; everything else must equal the concept. */
+function mapDeleteConcept({ danger, review }) {
+    const [cancel] = review.actions.buttons;
+    const note = review.notes.at(-1);
+    return {
+        ...review,
+        title: 'Delete or archive selected prompts',
+        // #482: the paired prompt is deletable, so the review asks Archive or Delete permanently (a D90 radio row).
+        tree: ['dl.meta-grid', 'div.field', 'p.small', 'p.small', 'div.dialog-actions'],
+        grid: { ...review.grid, rows: [['Delete permanently', '1 prompt not in a saved pair'],
+            ['Archive', '1 prompt in a saved pair: hidden, restorable'],
+            ['Image links removed', '0 images will no longer show these prompts (files stay on disk)'],
+            ['Backup', 'Create and verify before deleting']] },
+        notes: [
+            { ...note, text: 'Prompts in a saved pair, as its positive or its negative, are archived instead of deleted, so the '
+                + 'pair and its runs stay intact. To delete them later or bring them back, press Show archived prompts, select them '
+                + 'and press Delete… or Restore.' },
+            // A second paragraph takes the concept's own `p + p` margin (style.css 93-95).
+            { ...note, marginTop: '10px', text: "Deleting removes each prompt's text, title, category, tags, rating, notes, run count, last use and "
+                + 'image links. Deleted prompts cannot be brought back one by one: the only way back is to restore the safety '
+                + 'backup taken first (System › Backup & export), which returns the whole library to that moment. It is kept '
+                + 'among the last 10 safety backups. Image files, favorites, collections and recorded runs stay. A later scan, a '
+                + 'new image or a node run with the same text adds it again as a new prompt.' },
+        ],
+        actions: { ...review.actions, tree: [review.actions.tree[0], 'button.danger'], buttons: [cancel, { text: 'Delete 1 and archive 1 prompt', className: danger.className,
+            backgroundColor: danger.backgroundColor, color: danger.color, fontSize: danger.fontSize, paddingTop: danger.paddingTop,
+            paddingLeft: danger.paddingLeft, borderTopColor: danger.borderTopColor }] },
+    };
+}
+
+for (const theme of THEMES) for (const [width, height] of SIZES) {
+    test(`the Delete… review matches the concept's reviewed archive ${theme} ${width}x${height}`, async ({ page, request }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        const concept = await conceptReview(page, theme);
+        expect(concept.review.tree).toEqual(['dl.meta-grid', 'p.small', 'div.dialog-actions']);
+        await page.screenshot({ path: testInfo.outputPath(`concept-archive-review-${theme}-${width}.png`) });
+        const production = await productionReview(page, request, theme);
+        await page.screenshot({ path: testInfo.outputPath(`production-delete-review-${theme}-${width}.png`) });
+        expect(diffInventory(mapDeleteConcept(concept), production)).toEqual([]);
+    });
+}
+
+test('the Delete… review comparison detects mutations', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const concept = await conceptReview(page, 'dark');
+    await productionReview(page, request, 'dark');
+    const expected = mapDeleteConcept(concept);
+    const paths = async () => diffInventory(expected, await page.evaluate(measureReview)).map(item => item.path);
+    expect(await paths()).toEqual([]);
+    await mutate(page, { css: '#modal-body .dialog-actions .danger { padding-left: 2px }' });
+    expect(await paths()).toContain('actions.buttons.1.paddingLeft');
+});
+
+test('the bar\'s Delete… matches the concept Images bar\'s danger action', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await openConcept(page, 'images', 'dark');
+    await page.locator('#image-grid .media-card').first().locator('input[data-select]').check();
+    await expect(page.locator('#bulkbar .bulkbar')).toBeVisible();await page.mouse.move(0, 0);
+    const reference = await page.evaluate(measureButton, '#bulkbar .bulkbar button.danger');
+    const { paired } = await seedMixed(request);
+    await openProduction(page, 'library', 'dark');
+    await page.locator(`article[data-prompt-id="${paired.id}"] .image-overlays input`).check();
+    await expect(page.locator('#library-bulkbar .bulkbar')).toBeVisible();await page.mouse.move(0, 0);
+    expect(await page.evaluate(measureButton, '#library-bulkbar .bulkbar button.danger')).toEqual(reference);
+});

tests/browser/library-editor-canonical-comparison.mjs

@@ -26,9 +26,15 @@ export function inventoryOf(dialog) {
     };
 }
 // Documented differences only: prototype Save label, prototype demo note, data-dependent values, and D153 (#447): the
-// concept's "Rating" select is not drawn.
+// concept's "Rating" select is not drawn. D161 (#481): the concept's one danger "Archive…" becomes "Archive variant…" and
+// is followed by the prompt's own "Delete prompt…", drawn as the same danger button.
+function mapButton(item) {
+    if(item.text==='Save in prototype') return [{...item,text:'Save'}];
+    if(item.text==='Archive…') return [{...item,text:'Archive variant…'},{...item,text:'Delete prompt…'}];
+    return [item];
+}
 export function mapConcept(reference) {
-    return {...reference,demo:false,fields:reference.fields.filter(item=>item.label!=='Rating'),actions:{...reference.actions,buttons:reference.actions.buttons.map(item=>item.text==='Save in prototype'?{...item,text:'Save'}:item)}};
+    return {...reference,demo:false,fields:reference.fields.filter(item=>item.label!=='Rating'),actions:{...reference.actions,buttons:reference.actions.buttons.flatMap(mapButton)}};
 }
 
 // Flatten an inventory to path->value so a comparison reports exactly which leaves differ.

tests/browser/library-editor-visual.spec.mjs

@@ -24,7 +24,7 @@ for(const [width,height,theme] of [[1600,1100,'dark'],[390,844,'light']])test(`e
     await variants(page).getByRole('button',{name:'Select negative variant 2',exact:true}).click();
     await page.getByRole('button',{name:'Edit metadata',exact:true}).click();await expect(editor(page)).toBeVisible();
     await expect(editor(page).getByRole('button',{name:'Save',exact:true})).toBeEnabled();
-    await editor(page).getByRole('button',{name:'Archive…',exact:true}).click();
+    await editor(page).getByRole('button',{name:'Archive variant…',exact:true}).click();
     await expect(editor(page).getByRole('button',{name:'Archive',exact:true})).toBeEnabled();await shot('editor-archive');
 
     let release;const held=new Promise(resolve=>{release=resolve;});

tests/browser/malloc_tuning.py

@@ -0,0 +1,31 @@
+"""Keep the browser test server's large frees going back to the OS (#516).
+
+glibc serves an allocation of at least the mmap threshold (128 KiB at start) with its
+own mmap and unmaps it on free. Freeing such a block also raises the threshold, up to
+32 MiB, so the server's later image-sized buffers (PIL pixel data, PNG encoding,
+whole-file reads in the executor threads) come from per-thread malloc arenas instead.
+Those arenas fragment and keep their pages: a server grew from 13 MB to 0.6-1 GB RSS
+over one page-workflow shard while its Python heap stayed near 12 MB. Setting
+M_MMAP_THRESHOLD fixes the threshold at its start value and turns the raising off.
+"""
+
+import ctypes
+import sys
+
+M_MMAP_THRESHOLD = -3
+MMAP_THRESHOLD_BYTES = 128 * 1024
+
+
+def pin_mmap_threshold(libc=None) -> bool:
+    """Fix glibc's mmap threshold; False where there is no glibc ``mallopt``."""
+    if not sys.platform.startswith("linux"):
+        return False
+    if libc is None:
+        try:
+            libc = ctypes.CDLL(None)
+        except OSError:
+            return False
+    mallopt = getattr(libc, "mallopt", None)
+    if mallopt is None:
+        return False
+    return bool(mallopt(M_MMAP_THRESHOLD, MMAP_THRESHOLD_BYTES))

tests/browser/server.py

@@ -20,6 +20,7 @@ from PIL import Image
 from PIL.PngImagePlugin import PngInfo
 
 from tests.browser.folder_trash import close_trash, replace_folder
+from tests.browser.malloc_tuning import pin_mmap_threshold
 from tests.browser.request_hold import register_request_holds
 from tests.browser import slow_reset_watch
 from tests.browser.fast_reset import SEED_ON_LIVE_ENV, ScratchSeeder
@@ -220,6 +221,12 @@ def create_app(root: Path) -> web.Application:
     PromptManagerConfig.DEFAULT_DB_PATH = str(root / "browser.db")
     GalleryConfig.MONITORING_DIRECTORIES = [str(root / "output"), str(root / "input")]
 
+    # #480: Delete… never reaches a real system trash from a page test; the fake
+    # renames into this server's root, which goes when the server exits.
+    from tests import fake_trash
+
+    fake_trash.install(root / "fake-trash")
+
     from py.api import PromptManagerAPI
     from py import autotag
     from utils.hashing import generate_prompt_hash
@@ -749,6 +756,8 @@ def main(argv: list[str] | None = None) -> None:
         help="shut down when stdin closes (the launcher's parent-death guard)",
     )
     args = parser.parse_args(argv)
+    # Before any thread allocates (#516): large frees then return to the OS.
+    pin_mmap_threshold()
     listener = bind_listener(args.port)
     # One machine-readable line tells the launcher which port this process holds.
     print(f"{PORT_ANNOUNCEMENT}{listener.getsockname()[1]}", flush=True)

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

@@ -87,8 +87,8 @@ function measureBackups(mainSelector) {
 }
 
 const SCHEDULE_REASON = 'Daily and Weekly are not available yet: back up with Back up whenever you choose.';
-const SAFETY_DESCRIPTION = 'Keep a verified copy of the database on disk before maintenance, cleanups and LoRA imports change ' +
-    'records. A restore always keeps one.';
+const SAFETY_DESCRIPTION = 'Keep a verified copy of the database on disk before maintenance, cleanups, LoRA imports and ' +
+    'prompt deletes change records. A restore always keeps one.';
 
 /**
  * D103: "Back up" (the concept's "Simulate backup"), the status line from /backup/status, "Export JSON" (its "Export

tests/browser/system-concept.spec.mjs

@@ -165,6 +165,8 @@ const number = value => value.toLocaleString('en-US');
 
 /** The concept's shell and Overview with the recorded deviations applied, given the server's real overview. */
 function mapOverviewConcept(reference, overview) {
+    // D165: the discreet legacy-pages line follows the settings layout.
+    reference = { ...reference, tree: [...reference.tree, 'p.legacy-pages.small'] };
     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 = {
@@ -257,7 +259,7 @@ const UNMAPPED_PATHS = [
     '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',
+    'save.button.cursor', 'save.button.opacity', 'save.status.text', 'tree.3', 'tree.length',
 ].sort();
 
 test('system comparison detects mutations', async ({ page, request }) => {

tests/browser/workspace-collections.spec.mjs

@@ -5,6 +5,7 @@ import { test, expect } from './fixtures.mjs';
 // page `#/collection/<id>` with its Edit (D137, concept render a1186–1189) and saved views on a collection (D140).
 const workspace = '/prompt_manager/workspace';
 const API = '/prompt_manager/collections';
+const RESTORE_APPLY_URL = '/prompt_manager/restore/apply';
 const main = page => page.locator('#workspace-main');
 const heading = page => main(page).getByRole('heading', { level: 1 });
 const breadcrumb = page => page.locator('#workspace-breadcrumb');
@@ -305,7 +306,12 @@ test('a finished restore reads the collections again', async ({ page, request })
         const chooser = page.waitForEvent('filechooser');
         await page.getByRole('button', { name: 'Review restore…', exact: true }).click();
         await (await chooser).setFiles({ name: 'prompts_backup_20261027_093000.db', mimeType: 'application/octet-stream', buffer: bytes });
+        // Wait for the restore job itself, as workspace-system-backups.spec.mjs does: under load a restore outlasts the
+        // 5 s expect default, and a restore still running after this test replaces the next tests' database (#520).
+        const applied = page.waitForResponse(response => response.url().endsWith(RESTORE_APPLY_URL));
         await page.locator('dialog#modal[open]').getByRole('button', { name: 'Restore', exact: true }).click();
+        const { job } = await (await applied).json();
+        await expect(await request.get(`/prompt_manager/jobs/${job.id}/events`)).toBeOK();
         await expect(toast(page)).toHaveText(/^Database restore finished · /);
         // The list was read again without a reload.
         await expect(rows(page)).toHaveCount(2);
@@ -480,7 +486,7 @@ test('a rename that settles after its dialog closed leaves the next dialog open
 });
 
 test('a page that says a collection or view could not be opened takes focus after a route change (review L3)', async ({ page, request }) => {
-    await seed(request);
+    const manifest = await seed(request);
     await page.goto(`${workspace}#/images`);
     await expect(heading(page)).toHaveText('Images');
     await page.evaluate(() => { window.location.hash = '#/collection/999999'; });
@@ -499,7 +505,8 @@ test('a page that says a collection or view could not be opened takes focus afte
     await page.route('**/prompt_manager/saved-views', route => route.request().method() === 'GET'
         ? route.fulfill({ status: 500, contentType: 'application/json', body: '{"success":false,"error":"x"}' })
         : route.fallback());
-    await page.evaluate(() => { window.location.hash = '#/saved/5'; });
+    // An id the seed never made (its one view is manifest.saved_view), whatever ids earlier tests used (#520).
+    await page.evaluate(id => { window.location.hash = `#/saved/${id}`; }, manifest.saved_view.id + 1000);
     await expect(description(page)).toHaveText('Saved views could not be loaded. Your saved data has not changed.');
     await expect(heading(page)).toBeFocused();
 });
@@ -527,7 +534,7 @@ test('Add to collection creates a collection and adds to it ignoring case (CUJ 1
     await expect(imageCards(page)).toHaveCount(21);
     for (const file of ['loose.png', 'landscape_01.png', 'experiment_01.png']) await check(page, file);
     await expect(bar(page).locator('button')).toHaveText(['Add tags', 'Auto-tag selected', 'Set category', 'Add to collection',
-        'Export metadata', 'Clear']);
+        'Export metadata', 'Delete…', 'Clear']);
     await barButton(page, 'Add to collection').click();
     // The concept's simpleInput with Add (D138) and the existing names as suggestions.
     await expect(addDialog(page).locator('label')).toHaveText('Collection name');
@@ -578,7 +585,7 @@ test('Remove from collection takes the checked images off the open collection (C
     await check(page, 'landscape_01.png');
     await check(page, 'landscape_02.png');
     await expect(bar(page).locator('button')).toHaveText(['Add tags', 'Auto-tag selected', 'Set category', 'Add to collection',
-        'Remove from collection', 'Export metadata', 'Clear']);
+        'Remove from collection', 'Export metadata', 'Delete…', 'Clear']);
     await barButton(page, 'Remove from collection').click();
     await expect(toast(page)).toHaveText('Removed 2 images from “Landscapes”.');
     await expect(imageCards(page)).toHaveCount(10);
@@ -715,7 +722,8 @@ test('Collections… in the side panel adds, removes and creates for one image (
     // The newest image, landscape_01, is the panel's.
     await expect(panel(page).getByRole('heading', { level: 2 })).toHaveText('landscape_01.png');
     const open = panel(page).getByRole('button', { name: 'Collections…', exact: true });
-    await expect(panel(page).locator('.detail-footer > button').last()).toHaveText('Collections…');
+    // #480 D159: Delete… follows Collections… at the end of the panel's actions.
+    await expect(panel(page).locator('.detail-footer > button').nth(-2)).toHaveText('Collections…');
     await open.click();
     await expect(collectionsDialog(page)).toBeVisible();
     await expect(choice(page, 'Landscapes')).toBeChecked();

tests/browser/workspace-images-delete.spec.mjs

@@ -0,0 +1,184 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { seedConceptAt, openProduction } from './concept-inventory.mjs';
+
+// #480 (D159): Images › Delete…: the review asks every time (nothing preselected), "Remove from the library only"
+// hides the file and keeps it on disk, "Also move the files to the trash" moves it (the server's fake trash here).
+test.use({ locale: 'en-US', timezoneId: 'UTC' });
+
+const CARDS = '#workspace-main article[data-image-key]';
+const bar = page => page.locator('#workspace-main #bulkbar');
+const review = page => page.getByRole('dialog', { name: /^Delete \d+ images?$/ });
+const toast = page => page.locator('#workspace-toast');
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await seedConceptAt(page, request);
+    page.deleteErrors = [];
+    page.on('pageerror', error => page.deleteErrors.push(error.message));
+    page.on('dialog', dialog => { page.deleteErrors.push(`browser ${dialog.type()}`); dialog.dismiss().catch(() => {}); });
+});
+
+test.afterEach(async ({ page, browserName }) => {
+    await saveCoverage(page, browserName);
+    expect(page.deleteErrors).toEqual([]);
+});
+
+async function openImages(page) {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await openProduction(page, 'images', 'dark');
+    await expect(page.locator(CARDS).first()).toBeVisible();
+    return page.locator(CARDS).count();
+}
+
+async function check(page, index) {
+    const card = page.locator(CARDS).nth(index);
+    const key = await card.getAttribute('data-image-key');
+    await card.locator('.image-overlays input[type="checkbox"]').check();
+    return key;
+}
+
+async function deleteChecked(page, mode) {
+    await bar(page).getByRole('button', { name: 'Delete…', exact: true }).click();
+    const dialog = review(page);
+    await expect(dialog).toBeVisible();
+    const primary = dialog.locator('.dialog-actions button.danger');
+    // Ask every time: no mode is preselected and the primary waits for one.
+    await expect(dialog.getByRole('radio')).toHaveCount(2);
+    for (const radio of await dialog.getByRole('radio').all()) await expect(radio).not.toBeChecked();
+    await expect(primary).toHaveAttribute('aria-disabled', 'true');
+    await expect(dialog.locator('dl.meta-grid')).toBeHidden();
+    const label = mode === 'trash' ? 'Also move the files to the trash' : 'Remove from the library only';
+    await dialog.getByRole('radio', { name: new RegExp(`^${label}`) }).check();
+    await expect(dialog.locator('dl.meta-grid')).toBeVisible();
+    await expect(primary).not.toHaveAttribute('aria-disabled', 'true');
+    return { dialog, primary };
+}
+
+for (const mode of ['library', 'trash']) {
+    test(`${mode}: the deleted image leaves Images and stays gone after a reload`, async ({ page }) => {
+        const before = await openImages(page);
+        const key = await check(page, 0);
+        const { dialog, primary } = await deleteChecked(page, mode);
+        await expect(dialog.locator('dt', { hasText: 'Media on disk' })).toBeVisible();
+        await expect(primary).toHaveText(mode === 'trash' ? 'Move 1 image to the trash' : 'Remove 1 image from the library');
+        await primary.click();
+        await expect(toast(page)).toContainText(mode === 'trash' ? 'Moved 1 image to the trash.' : 'Removed 1 image from the library.');
+        await expect(page.locator(`${CARDS}[data-image-key="${key}"]`)).toHaveCount(0);
+        await expect(page.locator(CARDS)).toHaveCount(before - 1);
+        await expect(bar(page)).toBeEmpty();
+        await page.reload();
+        await expect(page.locator(CARDS).first()).toBeVisible();
+        await expect(page.locator(`${CARDS}[data-image-key="${key}"]`)).toHaveCount(0);
+    });
+}
+
+// #501: the sidebar's Images count (read once at mount) follows a finished delete without a reload.
+test('a finished delete re-reads the sidebar Images count', async ({ page }) => {
+    await openImages(page);
+    const badge = page.locator('#primary-nav a[data-route="images"] .nav-count');
+    await expect(badge).toHaveText(/^\d[\d,]*$/);
+    const before = Number((await badge.textContent()).replace(/,/g, ''));
+    await check(page, 0);
+    const { primary } = await deleteChecked(page, 'library');
+    await primary.click();
+    await expect(toast(page)).toContainText('Removed 1 image from the library.');
+    await expect(badge).toHaveText((before - 1).toLocaleString('en-US'));
+});
+
+test('Cancel changes nothing', async ({ page }) => {
+    const before = await openImages(page);
+    await check(page, 0);
+    const { dialog } = await deleteChecked(page, 'library');
+    await dialog.getByRole('button', { name: 'Cancel', exact: true }).click();
+    await expect(dialog).toBeHidden();
+    await expect(page.locator(CARDS)).toHaveCount(before);
+});
+
+test('switching modes redraws the rows from one review', async ({ page }) => {
+    await openImages(page);
+    await check(page, 0);
+    let previews = 0;
+    page.on('request', request => { if (request.url().endsWith('/images/delete/preview')) previews += 1; });
+    const { dialog, primary } = await deleteChecked(page, 'library');
+    await expect(dialog.locator('dd', { hasText: 'Files stay on disk, hidden from Images.' })).toBeVisible();
+    await dialog.getByRole('radio', { name: /^Also move the files to the trash/ }).check();
+    await expect(dialog.locator('dd', { hasText: 'Nothing is deleted permanently' })).toBeVisible();
+    await expect(primary).toHaveText('Move 1 image to the trash');
+    expect(previews).toBe(1);
+});
+
+test('Delete… in the inspector reviews that one image', async ({ page }) => {
+    const before = await openImages(page);
+    const card = page.locator(CARDS).first();
+    await card.getByRole('button', { name: /^Inspect / }).click();
+    const button = page.locator('#workspace-main .file-inspector button.danger', { hasText: 'Delete…' });
+    await expect(button).toBeVisible();
+    await button.click();
+    const dialog = review(page);
+    await expect(dialog).toBeVisible();
+    await dialog.getByRole('radio', { name: /^Remove from the library only/ }).check();
+    await dialog.locator('.dialog-actions button.danger').click();
+    await expect(page.locator(CARDS)).toHaveCount(before - 1);
+});
+
+test('Delete… in the viewer closes it after the delete', async ({ page }) => {
+    const before = await openImages(page);
+    await page.locator(CARDS).first().getByRole('button', { name: /^Open / }).click();
+    const viewer = page.locator('dialog#viewer-dialog[open]');
+    await expect(viewer).toBeVisible();
+    await viewer.getByRole('button', { name: 'Delete…', exact: true }).click();
+    const dialog = review(page);
+    await expect(dialog).toBeVisible();
+    await dialog.getByRole('radio', { name: /^Remove from the library only/ }).check();
+    await dialog.locator('.dialog-actions button.danger').click();
+    await expect(viewer).toBeHidden();
+    await expect(page.locator(CARDS)).toHaveCount(before - 1);
+});
+
+// The review never starts a delete without an explicit choice (live test 2026-10-29): every activation of the
+// aria-disabled primary is ignored, the dialog has no form to submit, and a chosen primary starts once.
+test('without a chosen mode nothing can start a delete', async ({ page }) => {
+    const before = await openImages(page);
+    await check(page, 0);
+    const applies = [];
+    page.on('request', request => { if (request.url().includes('/maintenance/apply')) applies.push(request.postDataJSON()); });
+    await bar(page).getByRole('button', { name: 'Delete…', exact: true }).click();
+    const dialog = review(page);
+    await expect(dialog).toBeVisible();
+    const primary = dialog.locator('.dialog-actions button.danger');
+    await expect(primary).toHaveAttribute('aria-disabled', 'true');
+    await expect(primary).toHaveText('Choose what happens to the files');
+    // Visibly dimmed while no mode is chosen.
+    await expect(primary).toHaveCSS('opacity', '0.55');
+    await expect(primary).toHaveCSS('cursor', 'not-allowed');
+    await primary.click({ force: true });
+    await primary.dblclick({ force: true });
+    await primary.focus();
+    await page.keyboard.press('Enter');
+    await page.keyboard.press('Space');
+    await dialog.locator('#modal-title').click();
+    await page.keyboard.press('Enter');
+    expect(await dialog.locator('form').count()).toBe(0);
+    await page.evaluate(() => document.querySelector('dialog#modal[open]')?.dispatchEvent(new Event('submit', { bubbles: true })));
+    await expect(dialog).toBeVisible();
+    expect(applies).toEqual([]);
+    for (const radio of await dialog.getByRole('radio').all()) await expect(radio).not.toBeChecked();
+    await dialog.getByRole('button', { name: 'Cancel', exact: true }).click();
+    await expect(page.locator(CARDS)).toHaveCount(before);
+    expect(applies).toEqual([]);
+});
+
+test('a chosen mode starts exactly one delete, with that mode, however often it is pressed', async ({ page }) => {
+    const before = await openImages(page);
+    await check(page, 0);
+    const applies = [];
+    page.on('request', request => { if (request.url().includes('/maintenance/apply')) applies.push(request.postDataJSON()); });
+    const { primary } = await deleteChecked(page, 'library');
+    await primary.dblclick();
+    await expect(toast(page)).toContainText('Removed 1 image from the library.');
+    await expect(page.locator(CARDS)).toHaveCount(before - 1);
+    expect(applies.length).toBe(1);
+    expect(applies[0].mode).toBe('library');
+    expect(Object.keys(applies[0]).sort()).toEqual(['mode', 'token']);
+});

tests/browser/workspace-images-removed.spec.mjs

@@ -0,0 +1,143 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { seedConceptAt, openProduction } from './concept-inventory.mjs';
+
+// #498 (D162): Images › Show removed images (N) lists the files "Remove from the library only" hid; Return to library
+// (bar or inspector) clears their marks and scans them again. Nothing is deleted or moved.
+test.use({ locale: 'en-US', timezoneId: 'UTC' });
+
+const CARDS = '#workspace-main article[data-image-key]';
+const bar = page => page.locator('#workspace-main #bulkbar');
+const toast = page => page.locator('#workspace-toast');
+const toggle = page => page.locator('.heading-actions').getByRole('button', { name: /^Show removed images/ });
+const imagesBadge = page => page.locator('#primary-nav a[data-route="images"] .nav-count');
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await seedConceptAt(page, request);
+    page.removedErrors = [];
+    page.on('pageerror', error => page.removedErrors.push(error.message));
+    page.on('dialog', dialog => { page.removedErrors.push(`browser ${dialog.type()}`); dialog.dismiss().catch(() => {}); });
+});
+
+test.afterEach(async ({ page, browserName }) => {
+    await saveCoverage(page, browserName);
+    expect(page.removedErrors).toEqual([]);
+});
+
+async function openImages(page) {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await openProduction(page, 'images', 'dark');
+    await expect(page.locator(CARDS).first()).toBeVisible();
+    return page.locator(CARDS).count();
+}
+
+async function check(page, index) {
+    const card = page.locator(CARDS).nth(index);
+    const key = await card.getAttribute('data-image-key');
+    await card.locator('.image-overlays input[type="checkbox"]').check();
+    return key;
+}
+
+/** Remove the first `count` cards from the library (library mode), then wait for the cards to leave. */
+async function removeFromLibrary(page, count) {
+    const keys = [];
+    for (let index = 0; index < count; index += 1) keys.push(await check(page, index));
+    await bar(page).getByRole('button', { name: 'Delete…', exact: true }).click();
+    const dialog = page.getByRole('dialog', { name: /^Delete \d+ images?$/ });
+    await dialog.getByRole('radio', { name: /^Remove from the library only/ }).check();
+    await dialog.locator('.dialog-actions button.danger').click();
+    await expect(toast(page)).toContainText(`Removed ${count} image${count === 1 ? '' : 's'} from the library.`);
+    for (const key of keys) await expect(page.locator(`${CARDS}[data-image-key="${key}"]`)).toHaveCount(0);
+    return keys;
+}
+
+test('without removed images there is no toggle', async ({ page }) => {
+    await openImages(page);
+    await expect(page.locator('#result-count')).toContainText(/images?/);
+    await expect(toggle(page)).toHaveCount(0);
+});
+
+test('Show removed images lists the removed files; Return to library brings them back', async ({ page }) => {
+    const before = await openImages(page);
+    const keys = await removeFromLibrary(page, 2);
+    await expect(toggle(page)).toHaveText('Show removed images (2)');
+    await expect(toggle(page)).toHaveAttribute('aria-pressed', 'false');
+    await toggle(page).click();
+    await expect(toggle(page)).toHaveAttribute('aria-pressed', 'true');
+    await expect(page.locator(CARDS)).toHaveCount(2);
+    await expect(page.locator('#result-count')).toHaveText('2 removed images · files on disk, hidden from Images');
+    for (const key of keys) {
+        const card = page.locator(`${CARDS}[data-image-key="${key}"]`);
+        await expect(card.locator('.chip', { hasText: 'Removed' })).toBeVisible();
+        // A removed file has no records: no star and no Tag action, which would write and show it again.
+        await expect(card.locator('.star-button')).toHaveCount(0);
+        await expect(card.locator('.image-card-actions button')).toHaveCount(1);
+    }
+    await check(page, 0);
+    await check(page, 1);
+    const actions = bar(page).locator('button');
+    await expect(actions).toHaveText(['Return to library', 'Clear']);
+    await bar(page).getByRole('button', { name: 'Return to library' }).click();
+    await expect(toast(page)).toContainText('Returned 2 images to the library');
+    await expect(toast(page)).toContainText('Tags, categories, collections and favorites do not come back.');
+    // The view emptied: it turns off and Images lists every file again.
+    await expect(toggle(page)).toHaveCount(0);
+    await expect(page.locator(CARDS)).toHaveCount(before);
+    for (const key of keys) await expect(page.locator(`${CARDS}[data-image-key="${key}"]`)).toHaveCount(1);
+    await expect(bar(page)).toBeEmpty();
+});
+
+test('Return to library from the inspector', async ({ page }) => {
+    await openImages(page);
+    const [key] = await removeFromLibrary(page, 1);
+    await toggle(page).click();
+    const card = page.locator(`${CARDS}[data-image-key="${key}"]`);
+    await card.getByRole('button', { name: /^Inspect / }).click();
+    const panel = page.locator('#image-inspector');
+    await expect(panel.getByRole('button', { name: 'Return to library' })).toBeVisible();
+    await expect(panel.getByRole('button', { name: 'Delete…' })).toHaveCount(0);
+    await expect(panel.locator('button[data-collections]')).toHaveCount(0);
+    await panel.getByRole('button', { name: 'Return to library' }).click();
+    await expect(toast(page)).toContainText('Returned 1 image to the library');
+    await expect(toggle(page)).toHaveCount(0);
+    await expect(page.locator(`${CARDS}[data-image-key="${key}"]`)).toHaveCount(1);
+});
+
+test('the sidebar Images count follows a remove and a return', async ({ page }) => {
+    await openImages(page);
+    await expect(imagesBadge(page)).toHaveText(/^\d[\d,]*$/);
+    const start = Number((await imagesBadge(page).textContent()).replace(/,/g, ''));
+    await removeFromLibrary(page, 1);
+    await expect(imagesBadge(page)).toHaveText((start - 1).toLocaleString('en-US'));
+    await toggle(page).click();
+    await check(page, 0);
+    await bar(page).getByRole('button', { name: 'Return to library' }).click();
+    await expect(toast(page)).toContainText('Returned 1 image to the library');
+    await expect(imagesBadge(page)).toHaveText(start.toLocaleString('en-US'));
+});
+
+test('the removed view is never saved and ends when the page is left', async ({ page }) => {
+    await openImages(page);
+    await removeFromLibrary(page, 1);
+    await toggle(page).click();
+    await expect(toggle(page)).toHaveAttribute('aria-pressed', 'true');
+    await page.locator('#primary-nav a[data-route="library"]').click();
+    await expect(page).toHaveURL(/#\/library/);
+    await page.locator('#primary-nav a[data-route="images"]').click();
+    await expect(page.locator(CARDS).first()).toBeVisible();
+    await expect(toggle(page)).toHaveAttribute('aria-pressed', 'false');
+    await expect(page.locator('#result-count')).not.toContainText('removed');
+});
+
+test('choosing a category in the removed view ends the view and lists the category', async ({ page }) => {
+    await openImages(page);
+    await removeFromLibrary(page, 1);
+    await toggle(page).click();
+    await expect(toggle(page)).toHaveAttribute('aria-pressed', 'true');
+    await page.getByRole('combobox', { name: 'Filter by category', exact: true }).selectOption('Landscapes');
+    // A removed file has no category: the view ends instead of refusing the listing.
+    await expect(toggle(page)).toHaveAttribute('aria-pressed', 'false');
+    await expect(page.locator(CARDS).first()).toBeVisible();
+    await expect(page.locator('#result-count')).not.toContainText('removed');
+});

tests/browser/workspace-images.spec.mjs

@@ -1376,6 +1376,61 @@ async function expectStar(button, favorite) {
     await expect(button).toHaveAttribute('aria-pressed', String(favorite));
 }
 
+// #494: the Favorites count is re-read 300 ms after a star changes. A page that has begun to leave starts no count read
+// (WebKit fails it with "Fetch API cannot load … due to access control checks.", reported as a page error; queue run
+// 40934368716). A leave that is called off counts again on the next input.
+for (const leave of ['beforeunload', 'pagehide']) {
+    test(`a star changed just before ${leave} starts no Favorites count read while the page leaves`, async ({ page }) => {
+        await page.clock.install();
+        const countReads = [];
+        page.on('request', item => {
+            const url = new URL(item.url());
+            if (url.pathname === '/prompt_manager/images/output' && url.searchParams.get('favorites') === '1' && url.searchParams.get('limit') === '1') countReads.push(url.search);
+        });
+        await page.goto(workspace);
+        const card = page.locator('article[data-image-key="0:shared/same.png"]');
+        await expectStar(star(card, 'same.png'), false);
+        await expect.poll(() => countReads.length).toBe(1);
+        await star(card, 'same.png').click();
+        await expectStar(star(card, 'same.png'), true);
+        await expect(toast(page)).toHaveText('Added to favorites.');
+        await page.evaluate(type => window.dispatchEvent(new Event(type)), leave);
+        await page.clock.runFor(1000);
+        // A read made after the clock ran is listed, so the listener saw every count read.
+        await page.evaluate(() => fetch('/prompt_manager/images/output?mode=workspace&favorites=1&limit=1&probe=1'));
+        await expect.poll(() => countReads.length).toBe(2);
+        expect(countReads.at(-1)).toContain('probe=1');
+        if (leave === 'beforeunload') {
+            // The leave was called off (the page is still here): the next input counts again, once, and the badge shows it.
+            await page.keyboard.press('Shift');
+            await expect.poll(() => countReads.length).toBe(3);
+            expect(countReads.at(-1)).not.toContain('probe=1');
+            await expect(page.locator('nav [data-route="favorites"] .nav-count')).toHaveText('1');
+            await page.clock.runFor(1000);
+            expect(countReads).toHaveLength(3);
+        }
+    });
+}
+
+test('a count read in flight when the page starts to leave is dropped, then read again if the page stays (#494)', async ({ page }) => {
+    const held = [];
+    // The page's first Library count read is held at the server boundary while the page starts to leave.
+    await page.route('**/prompt_manager/library?limit=1', route => { held.push(route); });
+    await page.goto(workspace);
+    await expect.poll(() => held.length).toBe(1);
+    const failed = page.waitForEvent('requestfailed', item => item.url().includes('/prompt_manager/library?limit=1'));
+    await page.evaluate(() => window.dispatchEvent(new Event('beforeunload')));
+    await failed;
+    await page.unroute('**/prompt_manager/library?limit=1');
+    await held[0].continue().catch(() => {});
+    await expect(page.locator('nav [data-route="library"] .nav-count')).toHaveCount(0);
+    // The page stayed: the next input reads the dropped count again.
+    const reread = page.waitForRequest(item => item.url().includes('/prompt_manager/library?limit=1'));
+    await page.keyboard.press('Shift');
+    await reread;
+    await expect(page.locator('nav [data-route="library"] .nav-count')).toHaveText(/^\d+$/);
+});
+
 test('favorite persists across reload', async ({ page, request }) => {
     await expect(await request.post('/__test__/reset', { data: { include_video: true } })).toBeOK();
     const sent = [];
@@ -1794,7 +1849,7 @@ test('card checkboxes select images into the concept bar and Clear empties it',
     await checkbox(first, 'same.png').check();
     await expect(bulkbar(page).locator('.bulkbar > strong')).toHaveText('1 selected');
     // D85: Add tags (the concept's) and Auto-tag selected lead the real actions.
-    await expect(barButtons(page)).toHaveText(['Add tags', 'Auto-tag selected', 'Set category', 'Add to collection', 'Export metadata', 'Clear']);
+    await expect(barButtons(page)).toHaveText(['Add tags', 'Auto-tag selected', 'Set category', 'Add to collection', 'Export metadata', 'Delete…', 'Clear']);
     // Toggling neither opens the viewer, nor inspects, nor moves focus.
     await expect(page.locator('dialog[open]')).toHaveCount(0);
     await expect(checkbox(first, 'same.png')).toBeFocused();

tests/browser/workspace-inspect.spec.mjs

@@ -704,6 +704,147 @@ test('a video replaced while still starting is reset once it settles', async ({
     }
 });
 
+test('a new selection while the viewer\'s own video is still starting leaves it until it settles (#483)', async ({ context, browserName }) => {
+    test.setTimeout(180000);
+    // D155 opens the viewer once the inline preview has settled; the viewer then starts a video of its own. A new
+    // selection from that video's own `loadstart` (readyState HAVE_NOTHING), or a few milliseconds after it, must not
+    // reset it or take it off the page while it starts (WebKit, GStreamer: TESTING.md D62; merge-queue run
+    // 40903238387). The viewer stays open until it reports metadata or an error, then closes; the URL goes last.
+    for (let attempt = 0; attempt < 10; attempt++) {
+        const page = await context.newPage();
+        try {
+            if (attempt === 0) await startCoverage(page, browserName);
+            await page.addInitScript(() => {
+                const load = HTMLMediaElement.prototype.load;
+                HTMLMediaElement.prototype.load = function () { if (!this.hasAttribute('src')) { this.__resets = (this.__resets ?? 0) + 1; this.__resetReadyState ??= this.readyState; } return load.call(this); };
+                const revoke = URL.revokeObjectURL;
+                URL.revokeObjectURL = url => {
+                    const starting = window.__starting;
+                    if (url === starting?.url) starting.revoked = { src: starting.node.hasAttribute('src'), connected: starting.node.isConnected, resets: starting.node.__resets ?? 0 };
+                    return revoke(url);
+                };
+            });
+            await openInspect(page);
+            await page.evaluate(() => {
+                const input = document.querySelector('#local-file');
+                new MutationObserver((records, observer) => {
+                    const video = document.querySelector('#viewer-dialog video');
+                    if (!video) return;
+                    observer.disconnect();
+                    const replace = () => {
+                        window.__starting = { node: video, url: video.getAttribute('src'), readyState: video.readyState };
+                        input.files = window.__pngFiles; input.dispatchEvent(new Event('change', { bubbles: true }));
+                        window.__starting.replaced = { connected: video.isConnected, src: video.hasAttribute('src'), resets: video.__resets ?? 0 };
+                    };
+                    video.addEventListener('loadstart', () => { if (window.__delay) setTimeout(replace, window.__delay); else replace(); }, { once: true });
+                }).observe(document.body, { childList: true, subtree: true });
+            });
+            const png = parityPng('f02.png');
+            await page.evaluate(bytes => {
+                const transfer = new DataTransfer();
+                transfer.items.add(new File([new Uint8Array(bytes)], 'f02.png', { type: 'image/png' }));
+                window.__pngFiles = transfer.files;
+            }, [...png.buffer]);
+            await page.evaluate(delay => { window.__delay = delay; }, attempt % 5);
+            await choose(page, localFixture('core-tags.webm', 'video/webm'));
+            await expect(preview(page).locator('img.local-file-preview')).toBeVisible({ timeout: 8000 });
+            await expect.poll(() => page.evaluate(() => window.__starting?.revoked ?? null)).toEqual({ src: false, connected: false, resets: 1 });
+            const { readyState, replaced } = await page.evaluate(() => ({ readyState: window.__starting.readyState, replaced: window.__starting.replaced }));
+            if (attempt % 5 === 0) expect(readyState).toBe(0);
+            // Starting when replaced: still on the page with its URL, never reset; settled: released at once.
+            expect(replaced).toEqual(readyState === 0 ? { connected: true, src: true, resets: 0 } : { connected: false, src: false, resets: 1 });
+            expect(await page.evaluate(() => window.__starting.node.__resets)).toBe(1);
+            // Its one reset came after it had metadata, never while it was starting.
+            expect(await page.evaluate(() => window.__starting.node.__resetReadyState)).toBeGreaterThanOrEqual(1);
+            // The new file's viewer opens after the old one closed, and the page still answers.
+            await expect(viewer(page).getByRole('img', { name: 'f02.png', exact: true })).toBeVisible({ timeout: 8000 });
+            await expect(viewer(page).locator('video')).toHaveCount(0);
+            if (attempt === 0) await saveCoverage(page, browserName);
+        } finally {
+            await page.close();
+        }
+    }
+});
+
+/** #483: holds the viewer's video in HAVE_NOTHING (its `loadedmetadata` never fires) so a hold can be driven by hand. */
+async function stallViewerVideo(page) {
+    await page.addInitScript(() => {
+        const describe = Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, 'readyState');
+        Object.defineProperty(HTMLMediaElement.prototype, 'readyState', { configurable: true, get() {
+            return this.closest?.('#viewer-dialog') && window.__stallViewer ? 0 : describe.get.call(this);
+        } });
+        window.addEventListener('loadedmetadata', event => {
+            if (window.__stallViewer && event.target.closest?.('#viewer-dialog')) event.stopImmediatePropagation();
+        }, true);
+    });
+}
+
+test('a held viewer closed by hand, or replaced twice, opens only the latest file\'s viewer at once (#483)', async ({ page }) => {
+    await stallViewerVideo(page);
+    await openInspect(page);
+    await page.evaluate(() => { window.__stallViewer = true; });
+    await choose(page, localFixture('core-tags.webm', 'video/webm'));
+    await expect(viewer(page).locator('video')).toBeAttached();
+    // Two selections while the viewer's video is (made to look) still starting: the viewer stays, untouched.
+    await chooser(page).setInputFiles(parityPng('f02.png', 'first.png'));
+    await chooser(page).setInputFiles(parityPng('f02.png', 'second.png'));
+    await expect(preview(page).locator('img.local-file-preview')).toBeVisible();
+    await expect(viewer(page).locator('video')).toBeAttached();
+    // Open file metadata pressed meanwhile (the page behind the viewer is inert, so by script): the latest request.
+    await action(page).evaluate(node => node.click());
+    // Closing it by hand ends the hold at once: the latest file's viewer opens, once, well before D62's 15 s.
+    await page.keyboard.press('Escape');
+    await expect(viewer(page).getByRole('img', { name: 'second.png', exact: true })).toBeVisible({ timeout: 5000 });
+    await expect(viewer(page).getByRole('img', { name: 'first.png', exact: true })).toHaveCount(0);
+    await expect(viewer(page).locator('video')).toHaveCount(0);
+    await expect(page.locator('dialog[open]')).toHaveCount(1);
+});
+
+test('a held viewer revokes its URL only once it is gone, drops a stale open, and ends on page leave (#483)', async ({ page }) => {
+    await stallViewerVideo(page);
+    await openInspect(page);
+    await trackReleases(page);
+    await page.evaluate(() => { window.__stallViewer = true; });
+    const videoUrl = () => page.evaluate(() => document.querySelector('#viewer-dialog video')?.getAttribute('src') ?? null);
+    const released = url => page.evaluate(url => window.__released.filter(item => item.url === url), url);
+    await choose(page, localFixture('core-tags.webm', 'video/webm'));
+    await expect(viewer(page).locator('video')).toBeAttached();
+    const first = await videoUrl();
+    await chooser(page).setInputFiles(parityPng('f02.png', 'held.png'));
+    await expect(preview(page).locator('img.local-file-preview')).toBeVisible();
+    // The session asked to revoke the video's URL; it waits while the held viewer still plays it.
+    expect(await released(first)).toEqual([]);
+    // An Open asked for during the hold, then an AVI (which never opens the viewer by itself): the open for the earlier
+    // file is stale and is dropped when the hold ends.
+    await action(page).evaluate(node => node.click());
+    const avi = { name: 'clip.avi', mimeType: 'video/x-msvideo', buffer: Buffer.concat([Buffer.from('RIFF'), Buffer.alloc(4), Buffer.from('AVI LIST'), Buffer.alloc(64)]) };
+    await chooser(page).setInputFiles(avi);
+    await expect(page.locator('#workspace-toast')).toHaveText(TOAST);
+    await page.keyboard.press('Escape');
+    await expect(page.locator('dialog[open]')).toHaveCount(0);
+    await expect.poll(() => released(first)).toEqual([{ url: first, live: 0 }]);
+    // Page leave while held: the viewer goes and the deferred URL is revoked with nothing holding it.
+    await choose(page, localFixture('core-tags.webm', 'video/webm'));
+    await expect(viewer(page).locator('video')).toBeAttached();
+    const second = await videoUrl();
+    await chooser(page).setInputFiles(parityPng('f02.png', 'leave.png'));
+    await expect(viewer(page).locator('video')).toBeAttached();
+    expect(await released(second)).toEqual([]);
+    await page.evaluate(() => window.dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true })));
+    await expect(page.locator('dialog[open]')).toHaveCount(0);
+    await expect.poll(() => released(second)).toEqual([{ url: second, live: 0 }]);
+    // Another route while held: the page's dispose ends the hold and revokes the URL with nothing holding it.
+    await page.evaluate(() => window.dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true })));
+    await choose(page, localFixture('core-tags.webm', 'video/webm'));
+    await expect(viewer(page).locator('video')).toBeAttached();
+    const third = await videoUrl();
+    await chooser(page).setInputFiles(parityPng('f02.png', 'route.png'));
+    await expect(viewer(page).locator('video')).toBeAttached();
+    await page.evaluate(() => { window.location.hash = '#/library'; });
+    await expect(main(page).getByRole('heading', { level: 1, name: 'Prompt library', exact: true })).toBeVisible();
+    await expect.poll(() => released(third)).toEqual([{ url: third, live: 0 }]);
+});
+
 test('leaving for another route while a video starts waits for it to settle', async ({ context, browserName }) => {
     test.setTimeout(180000);
     // A WebKit (GStreamer) video detached before its pipeline had started deadlocked the page (TESTING.md D62); a

tests/browser/workspace-library-delete.spec.mjs

@@ -0,0 +1,608 @@
+import {startCoverage,saveCoverage} from '../../tools/vendor/browser-coverage.mjs';
+import {test,expect} from './fixtures.mjs';
+import {armUnseenRestores,unseenRestore} from './unseen-restore.mjs';
+
+// #443 D152: Delete… on the Library bar deletes unpaired prompts, archives paired ones (restorable), keeps protected ones.
+const route='/prompt_manager/workspace#/library';
+const PREVIEW='/prompt_manager/library/delete/preview';
+const DELETE='/prompt_manager/library/delete';
+const cards=page=>page.locator('article[data-prompt-id]');
+const card=(page,id)=>page.locator(`article[data-prompt-id="${id}"]`);
+const box=(page,id)=>card(page,id).locator('.image-overlays input[type="checkbox"]');
+const bar=page=>page.locator('#library-bulkbar > .bulkbar');
+const toast=page=>page.locator('.toast');
+const review=page=>page.getByRole('dialog');
+const showArchived=page=>page.locator('#workspace-main .heading-actions').getByRole('button',{name:/^Show archived prompts/});
+// #482: on the archived shelf the same button reads the concept's way back (app.js 594 "← Prompt library").
+const backToLibrary=page=>page.locator('#workspace-main .heading-actions').getByRole('button',{name:'← Prompt library',exact:true});
+
+async function items(request,shelf='active') {
+    const query=shelf==='archived'?'&shelf=archived':'';
+    return (await(await request.get(`/prompt_manager/library?limit=100${query}`)).json()).items;
+}
+const byText=(list,text)=>list.find(item=>item.text===text);
+function recordPosts(page,path) {
+    const posts=[];
+    page.on('request',item=>{if(item.method()==='POST'&&new URL(item.url()).pathname===path)posts.push(item.postDataJSON());});
+    return posts;
+}
+async function openReview(page) {
+    await bar(page).getByRole('button',{name:'Delete…',exact:true}).click();
+    await expect(review(page)).toBeVisible();
+}
+
+test.beforeEach(async({page,request,browserName})=>{
+    await startCoverage(page,browserName);await expect(await request.post('/__test__/reset',{data:{native_library:true,extra_prompts:2}})).toBeOK();
+    page.libraryErrors=[];page.on('pageerror',error=>page.libraryErrors.push(error.message));
+});
+test.afterEach(async({page,browserName})=>{await saveCoverage(page,browserName);expect(page.libraryErrors).toEqual([]);});
+
+test('Delete… reviews the selection, deletes the unpaired, archives the paired and keeps the protected',async({page,request})=>{
+    const before=await items(request);
+    const dog=byText(before,'Dog landscape'),cat=byText(before,'Cat portrait'),guarded=byText(before,'Library extra 0000');
+    await expect(await request.post('/prompt_manager/bulk/tags',{data:{prompt_ids:[guarded.id],tags:['__protected__']}})).toBeOK();
+    const previews=recordPosts(page,PREVIEW),writes=recordPosts(page,DELETE);
+    await page.goto(route);await expect(cards(page)).toHaveCount(before.length);
+    for(const item of [dog,cat,guarded]) await box(page,item.id).check();
+    await expect(bar(page).getByRole('button')).toHaveText([`Select all ${before.length} loaded`,'Add tags','Set category','Delete…','Clear']);
+    await expect(bar(page).getByRole('button',{name:'Delete…',exact:true})).toHaveClass(/danger/);
+    await openReview(page);
+    await expect(review(page)).toHaveAccessibleName('Delete or archive selected prompts');
+    const grid=review(page).locator('dl.meta-grid > div');
+    await expect(grid.locator('dt')).toHaveText(['Delete permanently','Archive','Protected (kept)','Image links removed','Backup']);
+    // #512: Cat portrait is also another prompt's negative in the fixture, so the review says so.
+    await expect(grid.locator('dd')).toHaveText(['1 prompt not in a saved pair',"1 prompt used as another prompt's negative: hidden, restorable",
+        '1: Library extra 0000','0 images will no longer show these prompts (files stay on disk)','Create and verify before deleting']);
+    await expect(review(page).locator('p.small')).toHaveCount(3);
+    await expect(review(page).getByRole('button',{name:'Delete 1 and archive 1 prompt',exact:true})).toHaveClass(/danger/);
+    // Cancel writes nothing and releases the bar.
+    await review(page).getByRole('button',{name:'Cancel',exact:true}).click();
+    await expect(review(page)).toHaveCount(0);expect(writes).toEqual([]);
+    await expect(bar(page).getByRole('button',{name:'Delete…',exact:true})).not.toHaveAttribute('aria-disabled','true');
+    await openReview(page);
+    await review(page).getByRole('button',{name:'Delete 1 and archive 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText(/^Deleted 1 prompt\. Archived 1 prompt\. 1 protected prompt was kept\. Safety backup saved: \S+\.backup_\S+ \(System › Backup & export\)\.$/);
+    await expect(page.locator('#library-bulkbar')).toBeEmpty();
+    await expect(card(page,dog.id)).toHaveCount(0);await expect(card(page,cat.id)).toHaveCount(0);await expect(card(page,guarded.id)).toHaveCount(1);
+    const epoch=(await(await request.get('/prompt_manager/library/options')).json()).library_epoch;
+    // One preview per review opened (Cancel, then Delete…).
+    const reviewed={prompt_ids:[dog.id,cat.id,guarded.id],expected_epoch:epoch};
+    expect(previews).toEqual([reviewed,reviewed]);
+    expect(writes).toEqual([{archive_ids:[cat.id],delete_ids:[dog.id],expected_epoch:epoch,backup:'on'}]);
+    const after=await items(request);
+    expect(byText(after,'Dog landscape')).toBeUndefined();expect(byText(after,'Cat portrait')).toBeUndefined();
+    expect((await items(request,'archived')).map(item=>item.id)).toEqual([cat.id]);
+    await expect(showArchived(page)).toHaveText('Show archived prompts (1)');
+});
+
+test('Show archived prompts lists archived prompts, and Restore on its bar returns them',async({page,request})=>{
+    const before=await items(request);const cat=byText(before,'Cat portrait'),dual=byText(before,'Dual role portrait');
+    await page.goto(route);await expect(cards(page)).toHaveCount(before.length);
+    await box(page,cat.id).check();await box(page,dual.id).check();
+    await openReview(page);
+    await expect(review(page)).toHaveAccessibleName('Archive selected prompts');
+    // The archive reason is the saved pair, for one or many prompts (live note on #470): never negative variants.
+    await expect(review(page).locator('dl.meta-grid > div').filter({hasText:'Archive'}).locator('dd')).toHaveText("2 prompts in a saved pair (1 used as another prompt's negative): hidden, restorable");
+    await review(page).getByRole('button',{name:'Archive 2 prompts',exact:true}).click();
+    await expect(toast(page)).toHaveText('Archived 2 prompts.');
+    await expect(cards(page)).toHaveCount(before.length-2);
+    // #482: a plain button that names where it goes (no pressed state that its changing label would contradict).
+    await expect(showArchived(page)).not.toHaveAttribute('aria-pressed');
+    await showArchived(page).click();
+    await expect(backToLibrary(page)).toBeVisible();await expect(backToLibrary(page)).not.toHaveAttribute('aria-pressed');
+    await expect(showArchived(page)).toHaveCount(0);
+    await expect(cards(page)).toHaveCount(2);
+    await expect(page.locator('.section-caption > span').first()).toHaveText(/^2 archived prompts · \d+ negative variants? hidden with them$/);
+    await expect(card(page,cat.id).locator('.card-title .chip',{hasText:'Archived'})).toHaveCount(1);
+    await box(page,cat.id).check();
+    // #492: the archived shelf offers Delete… after Restore.
+    await expect(bar(page).getByRole('button')).toHaveText(['Select all 2 loaded','Restore','Delete…','Clear']);
+    await bar(page).getByRole('button',{name:'Restore',exact:true}).click();
+    await expect(toast(page)).toHaveText('Restored 1 prompt to the Prompt library.');
+    await expect(cards(page)).toHaveCount(1);
+    await backToLibrary(page).click();
+    await expect(showArchived(page)).toHaveText('Show archived prompts (1)');
+    await expect(cards(page)).toHaveCount(before.length-1);
+    await expect(card(page,cat.id)).toHaveCount(1);
+    expect((await items(request,'archived')).map(item=>item.id)).toEqual([dual.id]);
+    // An empty archived view says so.
+    await showArchived(page).click();await box(page,dual.id).check();
+    await bar(page).getByRole('button',{name:'Restore',exact:true}).click();
+    await expect(page.locator('.library-status')).toHaveText('No archived prompts.');
+});
+
+// #482 (D154): a prompt in a saved pair can be deleted permanently, with its own saved pairs; Archive stays the default.
+const choice=page=>review(page).getByRole('radiogroup',{name:'Prompts in a saved pair'});
+const row=(page,term)=>review(page).locator('dl.meta-grid > div').filter({has:page.locator('dt',{hasText:new RegExp(`^${term}$`)})}).locator('dd');
+test('Delete permanently removes a paired prompt with its own saved pair; its negative stays (#482)',async({page,request})=>{
+    const before=await items(request);const dual=byText(before,'Dual role portrait'),cat=byText(before,'Cat portrait');
+    const writes=recordPosts(page,DELETE);
+    await page.goto(route);await expect(cards(page)).toHaveCount(before.length);
+    await box(page,dual.id).check();await openReview(page);
+    // Archive is checked: the review is #443's.
+    await expect(choice(page).getByRole('radio',{name:'Archive (hidden, restorable)'})).toBeChecked();
+    // The D90 radio row (the auto-tag "How to apply"): each radio keeps its own size beside its label.
+    expect(await choice(page).evaluate(group=>{const label=group.querySelector('label'),radio=label.querySelector('input');
+        return {group:group.className,display:getComputedStyle(label).display,gap:getComputedStyle(label).columnGap,
+            margin:getComputedStyle(radio).marginLeft,full:radio.getBoundingClientRect().width>=label.getBoundingClientRect().width/2};}))
+        .toEqual({group:'field',display:'flex',gap:'8px',margin:'0px',full:false});
+    await expect(review(page).getByRole('button',{name:'Archive 1 prompt',exact:true})).toBeVisible();
+    await choice(page).getByRole('radio',{name:'Delete permanently, with their saved pairs'}).check();
+    await expect(review(page)).toHaveAccessibleName('Delete selected prompts');
+    await expect(row(page,'Delete permanently')).toHaveText('1 prompt in a saved pair');
+    await expect(row(page,'Saved pairs removed')).toHaveText('1 saved pair (1 with a negative prompt)');
+    await expect(row(page,'Negatives kept')).toHaveText('1 negative prompt is kept');
+    await expect(row(page,'Backup')).toHaveText('Create and verify before deleting');
+    await expect(review(page).locator('p.small').first()).toHaveText(/^Deleting a prompt in a saved pair also removes its saved pairs/);
+    // Back to Archive: the review is #443's again.
+    await choice(page).getByRole('radio',{name:'Archive (hidden, restorable)'}).check();
+    await expect(row(page,'Saved pairs removed')).toHaveCount(0);
+    await expect(review(page).getByRole('button',{name:'Archive 1 prompt',exact:true})).toBeVisible();
+    await choice(page).getByRole('radio',{name:'Delete permanently, with their saved pairs'}).check();
+    await review(page).getByRole('button',{name:'Delete 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText(/^Deleted 1 prompt\. Removed 1 saved pair\. Safety backup saved: /);
+    await expect(card(page,dual.id)).toHaveCount(0);
+    expect(writes).toHaveLength(1);
+    expect(writes[0].delete_paired_ids).toEqual([dual.id]);
+    expect(Object.keys(writes[0].paired_digests)).toEqual([String(dual.id)]);
+    const after=await items(request);
+    expect(byText(after,'Dual role portrait')).toBeUndefined();
+    // Its negative (Cat portrait) is kept, with its own variants.
+    expect(byText(after,'Cat portrait')?.id).toBe(cat.id);
+    expect((await items(request,'archived')).map(item=>item.id)).toEqual([]);
+});
+
+test('a prompt used as another prompt\'s negative is archived even when Delete permanently is chosen (#482)',async({page,request})=>{
+    const before=await items(request);const dual=byText(before,'Dual role portrait'),cat=byText(before,'Cat portrait');
+    await page.goto(route);await expect(cards(page)).toHaveCount(before.length);
+    await box(page,cat.id).check();await box(page,dual.id).check();await openReview(page);
+    await choice(page).getByRole('radio',{name:'Delete permanently, with their saved pairs'}).check();
+    await expect(row(page,'Archive')).toHaveText('1 prompt used as another prompt\'s negative: hidden, restorable');
+    await expect(review(page).locator('p.small',{hasText:'archived instead of deleted'})).toHaveCount(1);
+    await review(page).getByRole('button',{name:'Delete 1 and archive 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText(/^Deleted 1 prompt\. Removed 1 saved pair\. Archived 1 prompt\./);
+    expect((await items(request,'archived')).map(item=>item.id)).toEqual([cat.id]);
+});
+
+test('the choice resets to Archive on every Delete…, and a selection with no paired prompt has none (#482)',async({page,request})=>{
+    const before=await items(request);const dual=byText(before,'Dual role portrait'),dog=byText(before,'Dog landscape');
+    await page.goto(route);await box(page,dual.id).check();await openReview(page);
+    await choice(page).getByRole('radio',{name:'Delete permanently, with their saved pairs'}).check();
+    await review(page).getByRole('button',{name:'Cancel',exact:true}).click();
+    await openReview(page);
+    await expect(choice(page).getByRole('radio',{name:'Archive (hidden, restorable)'})).toBeChecked();
+    await review(page).getByRole('button',{name:'Cancel',exact:true}).click();
+    await bar(page).getByRole('button',{name:'Clear',exact:true}).click();
+    await box(page,dog.id).check();await openReview(page);
+    await expect(choice(page)).toHaveCount(0);
+});
+
+// #492: Delete… on the archived shelf deletes archived prompts permanently, with their own saved pairs; no choice.
+async function archiveByApi(request,ids) {
+    const epoch=(await(await request.get('/prompt_manager/library/options')).json()).library_epoch;
+    const preview=await(await request.post(PREVIEW,{data:{prompt_ids:ids,expected_epoch:epoch}})).json();
+    expect(preview.archive).toEqual(ids);
+    await expect(await request.post(DELETE,{data:{archive_ids:ids,delete_ids:[],expected_epoch:epoch,backup:'on'}})).toBeOK();
+    return epoch;
+}
+test('Delete… on the archived shelf deletes an archived prompt and its saved pair permanently (#492)',async({page,request})=>{
+    const dual=byText(await items(request),'Dual role portrait');
+    const epoch=await archiveByApi(request,[dual.id]);
+    const previews=recordPosts(page,PREVIEW),writes=recordPosts(page,DELETE);
+    await page.goto(route);await showArchived(page).click();await expect(card(page,dual.id)).toHaveCount(1);
+    await box(page,dual.id).check();
+    await openReview(page);
+    await expect(review(page)).toHaveAccessibleName('Delete archived prompts');
+    await expect(choice(page)).toHaveCount(0);
+    // A permanent delete only: the review opens on Cancel, and its copy says it cannot be undone and takes the pairs.
+    await expect(review(page).getByRole('button',{name:'Cancel',exact:true})).toBeFocused();
+    await expect(review(page).locator('p.small').first()).toHaveText(/^Deleting a prompt in a saved pair also removes its saved pairs/);
+    await expect(review(page).locator('p.small').nth(1)).toContainText('the only way back is to restore the safety backup taken first');
+    await expect(row(page,'Delete permanently')).toHaveText('1 prompt in a saved pair');
+    await expect(row(page,'Saved pairs removed')).toHaveText(/^1 saved pair/);
+    await expect(row(page,'Backup')).toHaveText('Create and verify before deleting');
+    expect(previews).toEqual([{prompt_ids:[dual.id],expected_epoch:epoch,shelf:'archived'}]);
+    // Cancel writes nothing and returns focus to Delete….
+    await review(page).getByRole('button',{name:'Cancel',exact:true}).click();
+    await expect(review(page)).toHaveCount(0);expect(writes).toEqual([]);
+    await expect(bar(page).getByRole('button',{name:'Delete…',exact:true})).toBeFocused();
+    await openReview(page);
+    await review(page).getByRole('button',{name:'Delete 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText(/^Deleted 1 prompt\. Removed 1 saved pair\. Safety backup saved: /);
+    expect(writes).toHaveLength(1);
+    expect(writes[0]).toMatchObject({archive_ids:[dual.id],delete_ids:[],delete_paired_ids:[dual.id],shelf:'archived'});
+    await expect(page.locator('.library-status')).toHaveText('No archived prompts.');
+    await backToLibrary(page).click();
+    await expect(showArchived(page)).toHaveText('Show archived prompts (0)');
+    expect(byText(await items(request),'Dual role portrait')).toBeUndefined();
+    expect(await items(request,'archived')).toEqual([]);
+});
+
+test('an archived prompt restored since the shelf was read is kept, in a close-only review (#492)',async({page,request})=>{
+    const dual=byText(await items(request),'Dual role portrait');
+    await archiveByApi(request,[dual.id]);
+    const epoch=(await(await request.get('/prompt_manager/library/options')).json()).library_epoch;
+    await page.goto(route);await showArchived(page).click();await expect(card(page,dual.id)).toHaveCount(1);
+    await box(page,dual.id).check();
+    // Restored elsewhere after the shelf was read: the review counts it and deletes nothing.
+    await expect(await request.post('/prompt_manager/library/restore',{data:{prompt_ids:[dual.id],expected_epoch:epoch}})).toBeOK();
+    await openReview(page);
+    await expect(review(page).locator('p.small').last()).toHaveText('None of the selected prompts can be deleted.');
+    await expect(row(page,'No longer archived \\(kept\\)')).toHaveText('1');
+    await expect(review(page).getByRole('button',{name:/^Delete \d/})).toHaveCount(0);
+    expect(byText(await items(request),'Dual role portrait')?.id).toBe(dual.id);
+});
+
+// #481 (D161): a prompt's own page deletes it from Edit metadata (the concept's recipe editor, app.js 976), through the
+// same review: "Delete prompt…" beside "Archive variant…" (the variant's archive, renamed so the two cannot be confused).
+const editMetadata=page=>page.locator('#workspace-main .heading-actions').getByRole('button',{name:'Edit metadata',exact:true});
+const editor=page=>page.locator('dialog.library-editor[open]');
+async function deleteFromPage(page,id){
+    await page.goto(`/prompt_manager/workspace#/library/${id}`);
+    await editMetadata(page).click();
+    await expect(editor(page).locator('.dialog-actions button')).toHaveText(['Create text revision','Archive variant…','Delete prompt…','Cancel','Save']);
+    await expect(editor(page).getByRole('button',{name:'Delete prompt…',exact:true})).toHaveClass(/\bdanger\b/);
+    await editor(page).getByRole('button',{name:'Delete prompt…',exact:true}).click();
+    await expect(editor(page)).toHaveCount(0);await expect(review(page)).toBeVisible();
+}
+test('Delete prompt… on a prompt\'s page archives it by default, and deletes it permanently when chosen (#481)',async({page,request})=>{
+    const dual=byText(await items(request),'Dual role portrait');
+    const previews=recordPosts(page,PREVIEW);
+    await deleteFromPage(page,dual.id);
+    expect(previews.map(body=>body.prompt_ids)).toEqual([[dual.id]]);
+    await expect(choice(page).getByRole('radio',{name:'Archive (hidden, restorable)'})).toBeChecked();
+    await review(page).getByRole('button',{name:'Archive 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText('Archived 1 prompt.');
+    // The page stays and shows its Archived notice.
+    await expect(page.locator('.library-archived-notice h2')).toHaveText('Archived');
+    await expect(page.locator('#workspace-main h1')).toBeFocused();
+    await page.locator('.library-archived-notice').getByRole('button',{name:'Restore this prompt to the Prompt library'}).click();
+    await expect(toast(page)).toHaveText('Restored 1 prompt to the Prompt library.');
+    // Delete permanently: back to the Prompt library, the prompt gone.
+    await editMetadata(page).click();await editor(page).getByRole('button',{name:'Delete prompt…',exact:true}).click();
+    await choice(page).getByRole('radio',{name:'Delete permanently, with their saved pairs'}).check();
+    await review(page).getByRole('button',{name:'Delete 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText(/^Deleted 1 prompt\. Removed 1 saved pair\. Safety backup saved: /);
+    await expect(page).toHaveURL(/#\/library$/);
+    await expect(card(page,dual.id)).toHaveCount(0);
+    expect(byText(await items(request),'Dual role portrait')).toBeUndefined();
+});
+
+test('Cancel on the page\'s review changes nothing and returns focus to Edit metadata (#481)',async({page,request})=>{
+    const dual=byText(await items(request),'Dual role portrait');
+    const writes=recordPosts(page,DELETE);
+    await deleteFromPage(page,dual.id);
+    await review(page).getByRole('button',{name:'Cancel',exact:true}).click();
+    await expect(review(page)).toHaveCount(0);await expect(editMetadata(page)).toBeFocused();
+    expect(writes).toEqual([]);
+    expect(byText(await items(request),'Dual role portrait')?.id).toBe(dual.id);
+});
+
+test('the page\'s delete holds one review at a time, Escape returns focus, and an archived page\'s review is close-only (#481)',async({page,request})=>{
+    const dual=byText(await items(request),'Dual role portrait');
+    const previews=recordPosts(page,PREVIEW);
+    let release;const held=new Promise(resolve=>{release=resolve;});
+    await page.route(`**${PREVIEW}`,async item=>{await held;await item.fallback();});
+    await page.goto(`/prompt_manager/workspace#/library/${dual.id}`);
+    await editMetadata(page).click();await editor(page).getByRole('button',{name:'Delete prompt…',exact:true}).click();
+    // While the preview is held, Edit metadata is held too: no second review and no save can race the delete.
+    await expect(editMetadata(page)).toHaveAttribute('aria-disabled','true');
+    await editMetadata(page).click({force:true});await expect(editor(page)).toHaveCount(0);
+    release();
+    await expect(review(page)).toBeVisible();
+    expect(previews).toHaveLength(1);
+    expect(previews[0].expected_epoch).toMatch(/\S/);
+    await page.keyboard.press('Escape');
+    await expect(review(page)).toHaveCount(0);await expect(editMetadata(page)).toBeFocused();
+    await expect(editMetadata(page)).not.toHaveAttribute('aria-disabled');
+    await page.unroute(`**${PREVIEW}`);
+    // Archived: its review has nothing to change and only closes.
+    await editMetadata(page).click();await editor(page).getByRole('button',{name:'Delete prompt…',exact:true}).click();
+    await review(page).getByRole('button',{name:'Archive 1 prompt',exact:true}).click();
+    await expect(page.locator('.library-archived-notice')).toBeVisible();
+    await editMetadata(page).click();await editor(page).getByRole('button',{name:'Delete prompt…',exact:true}).click();
+    // #512: the page's review names its one prompt.
+    await expect(review(page).locator('p.small').last()).toHaveText('This prompt cannot be deleted or archived.');
+    await expect(review(page).getByRole('button',{name:/^(Delete|Archive)/})).toHaveCount(0);
+});
+
+test('a failed review on the prompt\'s page says so, changes nothing and releases Edit metadata (#481)',async({page,request})=>{
+    const dual=byText(await items(request),'Dual role portrait');
+    const writes=recordPosts(page,DELETE);
+    await page.route(`**${PREVIEW}`,item=>item.fulfill({status:500,contentType:'application/json',body:JSON.stringify({success:false,code:'review-failed',error:'x'})}),{times:1});
+    await page.goto(`/prompt_manager/workspace#/library/${dual.id}`);
+    await editMetadata(page).click();await editor(page).getByRole('button',{name:'Delete prompt…',exact:true}).click();
+    await expect(toast(page)).toHaveText('The selected prompts could not be reviewed. Try again.');
+    await expect(review(page)).toHaveCount(0);await expect(editMetadata(page)).not.toHaveAttribute('aria-disabled');
+    expect(writes).toEqual([]);
+    await editMetadata(page).click();await expect(editor(page)).toBeVisible();
+});
+
+test('a delete answered after the page was left invalidates the shelf without a toast or a jump (#481)',async({page,request})=>{
+    const dual=byText(await items(request),'Dual role portrait');
+    let release;const held=new Promise(resolve=>{release=resolve;});
+    let answered;const done=new Promise(resolve=>{answered=resolve;});
+    await page.route(`**${DELETE}`,async item=>{await held;const response=await item.fetch();await item.fulfill({response});answered();});
+    await deleteFromPage(page,dual.id);
+    await review(page).getByRole('button',{name:'Archive 1 prompt',exact:true}).click();
+    await page.evaluate(()=>{window.location.hash='#/overview';});
+    await expect(page.locator('#workspace-main h1')).toHaveText('Overview');
+    // Every toast text shown from here on is recorded, so one shown and hidden again still counts.
+    await page.evaluate(()=>{window.seenToasts=[];new MutationObserver(()=>{for(const node of document.querySelectorAll('.toast'))
+        if(node.textContent.trim())window.seenToasts.push(node.textContent.trim());}).observe(document.body,{subtree:true,childList:true,characterData:true});});
+    release();await done;
+    // The answer lands on Overview: no navigation; the shelf reads again when opened; and no toast was ever shown.
+    await page.evaluate(()=>{window.location.hash='#/library';});
+    await expect(card(page,dual.id)).toHaveCount(0);
+    expect((await items(request,'archived')).map(item=>item.id)).toEqual([dual.id]);
+    expect(await page.evaluate(()=>window.seenToasts)).toEqual([]);
+});
+
+test('a restore since the prompt\'s page loaded is refused and the page reads the Library again (#481)',async({page,request})=>{
+    const dual=byText(await items(request),'Dual role portrait');
+    await armUnseenRestores(page);
+    await page.goto(`/prompt_manager/workspace#/library/${dual.id}`);
+    await editMetadata(page).click();await editor(page).getByRole('button',{name:'Delete prompt…',exact:true}).click();
+    const backup=await request.get('/prompt_manager/backup');await expect(backup).toBeOK();const buffer=await backup.body();
+    const restore=await unseenRestore(page,()=>request.post('/prompt_manager/restore',{multipart:{database_file:{name:'library.db',mimeType:'application/octet-stream',buffer}}}));
+    await expect(restore).toBeOK();
+    await review(page).getByRole('button',{name:'Archive 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText('The library was restored or moved since this page loaded. Nothing was deleted or archived.');
+    await expect(page.locator('#workspace-main h1')).toBeFocused();
+    expect((await items(request,'archived')).map(item=>item.id)).toEqual([]);
+});
+
+test('an archived prompt\'s page says so and restores it from its notice',async({page,request})=>{
+    const cat=byText(await items(request),'Cat portrait');
+    const epoch=(await(await request.get('/prompt_manager/library/options')).json()).library_epoch;
+    await expect(await request.post(DELETE,{data:{archive_ids:[cat.id],delete_ids:[],expected_epoch:epoch,backup:'off'}})).toBeOK();
+    await page.goto(`/prompt_manager/workspace#/library/${cat.id}`);
+    const notice=page.locator('.library-archived-notice');
+    await expect(notice.locator('h2')).toHaveText('Archived');
+    // The notice says why (the saved pair) and counts the prompt's negative variants (live note on #470).
+    expect(cat.variant_count).toBeGreaterThan(1);
+    await expect(notice.locator('p').first()).toHaveText(`This prompt is archived because it is in a saved pair. It and its ${cat.variant_count} negative variants are hidden from the Prompt library; nothing was removed.`);
+    await notice.getByRole('button',{name:'Restore this prompt to the Prompt library'}).click();
+    await expect(toast(page)).toHaveText('Restored 1 prompt to the Prompt library.');
+    await expect(notice).toHaveCount(0);
+    expect(byText(await items(request),'Cat portrait')?.id).toBe(cat.id);
+});
+
+// #443: a starved renderer (headless WebKit under CPU load, a background tab) can hold animation frames for
+// seconds; a loaded page of prompts is shown without waiting for one, on first load and after a delete.
+async function holdAnimationFrames(page) {
+    await page.addInitScript(()=>{
+        const request=window.requestAnimationFrame.bind(window),cancel=window.cancelAnimationFrame.bind(window);
+        const held=new Map(),real=new Map();let holding=true,next=0;
+        window.requestAnimationFrame=callback=>{const id=--next;if(holding)held.set(id,callback);else real.set(id,request(callback));return id;};
+        window.cancelAnimationFrame=id=>{held.delete(id);if(real.has(id))cancel(real.get(id));real.delete(id);};
+        window.__releaseAnimationFrames=()=>{holding=false;for(const [id,callback] of held)real.set(id,request(callback));held.clear();};
+    });
+}
+test('a held animation frame does not hide the loaded prompts, on first load or after a delete',async({page,request})=>{
+    const before=await items(request);const dog=byText(before,'Dog landscape');
+    await holdAnimationFrames(page);
+    await page.goto(route);await expect(cards(page)).toHaveCount(before.length);
+    await box(page,dog.id).check();await openReview(page);
+    await review(page).getByRole('button',{name:'Delete 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText(/^Deleted 1 prompt\./);
+    await expect(cards(page)).toHaveCount(before.length-1);await expect(card(page,dog.id)).toHaveCount(0);
+    await page.evaluate(()=>window.__releaseAnimationFrames());
+    await expect(cards(page)).toHaveCount(before.length-1);
+});
+
+test('a double press sends one preview, and the bar holds while it is reviewed',async({page,request})=>{
+    const dog=byText(await items(request),'Dog landscape');
+    const previews=recordPosts(page,PREVIEW);
+    let release;const held=new Promise(resolve=>{release=resolve;});
+    await page.route(`**${PREVIEW}`,async item=>{await held;await item.fallback();});
+    await page.goto(route);await box(page,dog.id).check();
+    const remove=bar(page).getByRole('button',{name:/^(Delete…|Reviewing…)$/});
+    await remove.click();
+    await expect(remove).toHaveText('Reviewing…');await expect(remove).toHaveAttribute('aria-disabled','true');
+    await expect(bar(page).getByRole('button',{name:'Clear',exact:true})).toHaveAttribute('aria-disabled','true');
+    await remove.click({force:true});
+    release();
+    await expect(review(page)).toHaveAccessibleName('Delete selected prompts');
+    expect(previews).toHaveLength(1);
+    await review(page).getByRole('button',{name:'Cancel',exact:true}).click();
+    await expect(bar(page).getByRole('button',{name:'Delete…',exact:true})).not.toHaveAttribute('aria-disabled','true');
+});
+
+test('a restore since the page loaded, a failed backup, a busy job and an unconfirmed answer each say what happened',async({page,request})=>{
+    const before=await items(request);const dog=byText(before,'Dog landscape');
+    await armUnseenRestores(page);
+    await page.goto(route);await expect(cards(page)).toHaveCount(before.length);
+    // Failed backup: nothing changed, the selection stays.
+    await page.route(`**${DELETE}`,item=>item.fulfill({status:500,contentType:'application/json',
+        body:JSON.stringify({success:false,code:'backup-failed',error:'The safety backup could not be taken and verified; nothing was changed.'})}));
+    await box(page,dog.id).check();await openReview(page);
+    await review(page).getByRole('button',{name:'Delete 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText('The safety backup failed. The safety backup could not be taken and verified; nothing was changed.');
+    await expect(box(page,dog.id)).toBeChecked();
+    // Busy: names the job, nothing changed.
+    await page.unroute(`**${DELETE}`);
+    await page.route(`**${DELETE}`,item=>item.fulfill({status:409,contentType:'application/json',
+        body:JSON.stringify({success:false,code:'busy',error:'busy',running:{id:'abc',title:'Scan'}})}));
+    await openReview(page);await review(page).getByRole('button',{name:'Delete 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText('Scan is running. Nothing was changed; try again when it finishes.');
+    // Unconfirmed: the shelf reloads.
+    await page.unroute(`**${DELETE}`);
+    await page.route(`**${DELETE}`,item=>item.abort());
+    await openReview(page);await review(page).getByRole('button',{name:'Delete 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText('The server did not confirm the change. The Library was reloaded: check the shelf and Show archived prompts.');
+    await expect(page.locator('#library-bulkbar')).toBeEmpty();
+    await page.unroute(`**${DELETE}`);
+    // A restore the page has not seen: the review opened before it is refused on the server.
+    await box(page,dog.id).check();await openReview(page);
+    const backup=await request.get('/prompt_manager/backup');await expect(backup).toBeOK();const buffer=await backup.body();
+    const restore=await unseenRestore(page,()=>request.post('/prompt_manager/restore',{multipart:{database_file:{name:'library.db',mimeType:'application/octet-stream',buffer}}}));
+    await expect(restore).toBeOK();
+    await review(page).getByRole('button',{name:'Delete 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText('The library was restored or moved since this page loaded. Nothing was deleted or archived.');
+    expect(byText(await items(request),'Dog landscape')).toBeDefined();
+});
+
+test('a failed review keeps the selection, and a selection nothing can change opens the close-only review',async({page,request})=>{
+    const before=await items(request);const guarded=byText(before,'Library extra 0000');
+    await expect(await request.post('/prompt_manager/bulk/tags',{data:{prompt_ids:[guarded.id],tags:['__protected__']}})).toBeOK();
+    await page.goto(route);await expect(cards(page)).toHaveCount(before.length);
+    await box(page,guarded.id).check();
+    await page.route(`**${PREVIEW}`,item=>item.fulfill({status:500,contentType:'application/json',body:JSON.stringify({success:false,code:'review-failed',error:'x'})}),{times:1});
+    await bar(page).getByRole('button',{name:'Delete…',exact:true}).click();
+    await expect(toast(page)).toHaveText('The selected prompts could not be reviewed. Try again.');
+    await expect(box(page,guarded.id)).toBeChecked();
+    await expect(bar(page).getByRole('button',{name:'Delete…',exact:true})).not.toHaveAttribute('aria-disabled','true');
+    await openReview(page);
+    await expect(review(page)).toHaveAccessibleName('Delete selected prompts');
+    await expect(review(page).locator('p.small').last()).toHaveText('None of the selected prompts can be deleted or archived.');
+    await expect(review(page).locator('.dialog-actions > button')).toHaveText(['Close']);
+    await review(page).getByRole('button',{name:'Close',exact:true}).click();
+    await expect(bar(page).getByRole('button',{name:'Delete…',exact:true})).not.toHaveAttribute('aria-disabled','true');
+    expect(byText(await items(request),'Library extra 0000')).toBeDefined();
+});
+
+// #512 (live test of #505/#507/#509): the prompt page's "⋯" More menu (D163), a gone prompt's page, single-prompt titles.
+const more=page=>page.locator('#workspace-main .heading-actions').getByRole('button',{name:'More actions for this prompt',exact:true});
+const moreMenu=page=>page.getByRole('menu',{name:'More actions for this prompt'});
+test('the prompt page\'s More menu opens Delete prompt…, by mouse and keyboard, and closes on Escape or outside (#512 D163)',async({page,request})=>{
+    const dual=byText(await items(request),'Dual role portrait');
+    await page.goto(`/prompt_manager/workspace#/library/${dual.id}`);
+    const heading=page.locator('#workspace-main .heading-actions > button, #workspace-main .heading-actions > .more-menu > button');
+    await expect(heading).toHaveText(['← Prompt library','Edit metadata','Send to ComfyUI','⋯']);
+    await expect(more(page)).toHaveAttribute('aria-haspopup','menu');await expect(more(page)).toHaveAttribute('aria-expanded','false');
+    await expect(moreMenu(page)).toBeHidden();
+    // Keyboard: Enter opens on the first item; Escape closes and returns focus.
+    await more(page).focus();await page.keyboard.press('Enter');
+    await expect(more(page)).toHaveAttribute('aria-expanded','true');
+    const item=moreMenu(page).getByRole('menuitem',{name:'Delete prompt…',exact:true});
+    await expect(item).toBeFocused();await expect(item).toHaveClass(/\bdanger\b/);
+    await page.keyboard.press('ArrowDown');await expect(item).toBeFocused();
+    await page.keyboard.press('Escape');
+    await expect(moreMenu(page)).toBeHidden();await expect(more(page)).toBeFocused();await expect(more(page)).toHaveAttribute('aria-expanded','false');
+    // ArrowUp opens on the last item; ArrowUp, Home and End move within it (one item here); Tab closes it.
+    await page.keyboard.press('ArrowUp');await expect(item).toBeFocused();
+    for(const key of ['ArrowUp','Home','End']) {await page.keyboard.press(key);await expect(item).toBeFocused();}
+    await page.keyboard.press('Tab');await expect(moreMenu(page)).toBeHidden();await expect(more(page)).toHaveAttribute('aria-expanded','false');
+    // Space opens too; an outside press closes it.
+    await more(page).focus();await page.keyboard.press(' ');await expect(item).toBeFocused();
+    await page.locator('#workspace-main h1').click();await expect(moreMenu(page)).toBeHidden();
+    // Choosing it opens the page's review, titled for this prompt; Cancel returns focus to ⋯.
+    await more(page).click();await item.click();
+    await expect(moreMenu(page)).toBeHidden();
+    await expect(review(page)).toHaveAccessibleName('Archive this prompt');
+    await expect(choice(page).getByRole('radio',{name:'Archive (hidden, restorable)'})).toBeChecked();
+    await choice(page).getByRole('radio',{name:'Delete permanently, with their saved pairs'}).check();
+    await expect(review(page).locator('#modal-title')).toHaveText('Delete this prompt');
+    await review(page).getByRole('button',{name:'Cancel',exact:true}).click();
+    await expect(review(page)).toHaveCount(0);await expect(more(page)).toBeFocused();
+    expect(byText(await items(request),'Dual role portrait')?.id).toBe(dual.id);
+});
+
+test('the More menu fits a 390px viewport and works by touch (#512 D163)',async({page,request})=>{
+    const dual=byText(await items(request),'Dual role portrait');
+    await page.setViewportSize({width:390,height:844});
+    await page.goto(`/prompt_manager/workspace#/library/${dual.id}`);
+    await more(page).click();
+    const item=moreMenu(page).getByRole('menuitem',{name:'Delete prompt…',exact:true});
+    await expect(item).toBeVisible();
+    const box=await moreMenu(page).boundingBox();
+    expect(box.x).toBeGreaterThanOrEqual(0);expect(box.x+box.width).toBeLessThanOrEqual(390);
+    await item.click();
+    await review(page).getByRole('button',{name:'Archive 1 prompt',exact:true}).click();
+    await expect(toast(page)).toHaveText('Archived 1 prompt.');
+    await expect(page.locator('.library-archived-notice')).toBeVisible();
+});
+
+test('a deleted prompt\'s page says it no longer exists, with the way back and no Retry (#512)',async({page,request})=>{
+    const dual=byText(await items(request),'Dual role portrait');
+    await deleteFromPage(page,dual.id);
+    await expect(review(page)).toHaveAccessibleName('Archive this prompt');
+    await choice(page).getByRole('radio',{name:'Delete permanently, with their saved pairs'}).check();
+    await review(page).getByRole('button',{name:'Delete 1 prompt',exact:true}).click();
+    await expect(page).toHaveURL(/#\/library$/);
+    await page.goto(`/prompt_manager/workspace#/library/${dual.id}`);
+    await expect(page.locator('#workspace-main .library-status')).toHaveText('This prompt no longer exists. It may have been deleted.');
+    await expect(page.getByRole('button',{name:'Retry prompt history'})).toHaveCount(0);
+    await expect(editMetadata(page)).toBeDisabled();await expect(more(page)).toBeDisabled();
+    await page.getByRole('button',{name:'Open the Prompt library',exact:true}).click();
+    await expect(page).toHaveURL(/#\/library$/);
+});
+
+// #524 (live test of #522): a long title clamps beside the heading actions, which stay on one row at desktop widths.
+const LONG_TITLE='masterpiece, high quality, very_awa, newest, absurdres, highres, depth_of_field, detailed eyes, realistic eyes, fake eyelashes, black eyes, white_nails, 1girl, solo, black bob_cut, upper body';
+async function openLongTitle(page,request,width) {
+    const dual=byText(await items(request),'Dual role portrait');
+    await page.route(new RegExp(`/prompt_manager/library/${dual.id}\\?`),async route=>{
+        const response=await route.fetch(),json=await response.json();
+        await route.fulfill({response,json:{...json,positive:{...json.positive,title:LONG_TITLE}}});
+    });
+    await page.setViewportSize({width,height:900});
+    await page.goto(`/prompt_manager/workspace#/library/${dual.id}`);
+    await expect(page.locator('#workspace-main h1')).toHaveText(LONG_TITLE);
+    expect(await page.evaluate(()=>document.documentElement.scrollWidth<=document.documentElement.clientWidth)).toBe(true);
+    return page.locator('#workspace-main .heading-actions > button, #workspace-main .heading-actions > .more-menu > button');
+}
+for(const width of [1440,951]) test(`a long title clamps and the heading actions stay on one row at ${width}px (#524)`,async({page,request})=>{
+    const actions=await openLongTitle(page,request,width);
+    await expect(actions).toHaveText(['← Prompt library','Edit metadata','Send to ComfyUI','⋯']);
+    const tops=await actions.evaluateAll(nodes=>nodes.map(node=>Math.round(node.getBoundingClientRect().top)));
+    expect(new Set(tops).size).toBe(1);
+    const h1=page.locator('#workspace-main h1');
+    const shape=await h1.evaluate(node=>({scroll:node.scrollHeight,client:node.clientHeight,line:parseFloat(getComputedStyle(node).lineHeight),title:node.title}));
+    expect(shape.scroll).toBeGreaterThan(shape.client);
+    expect(shape.client).toBeLessThanOrEqual(Math.ceil(shape.line*2));
+    // The clamp hides pixels only: the whole title stays the text and shows on hover.
+    expect(shape.title).toBe(LONG_TITLE);
+    // The buttons do not shrink: no label is cut or broken onto a second line.
+    const broken=await actions.evaluateAll(nodes=>nodes.filter(node=>node.scrollWidth>node.clientWidth||node.getBoundingClientRect().height>44).length);
+    expect(broken).toBe(0);
+    const [h1Box,firstBox]=[await h1.boundingBox(),await actions.first().boundingBox()];
+    expect(h1Box.x+h1Box.width).toBeLessThanOrEqual(firstBox.x);
+});
+
+test('a long title at 390px keeps the concept\'s stacked heading, not clamped, inside the viewport (#524)',async({page,request})=>{
+    const actions=await openLongTitle(page,request,390);
+    const h1=await page.locator('#workspace-main h1').evaluate(node=>({scroll:node.scrollHeight,client:node.clientHeight}));
+    expect(h1.scroll).toBeLessThanOrEqual(h1.client);
+    const right=await actions.evaluateAll(nodes=>Math.max(...nodes.map(node=>node.getBoundingClientRect().right)));
+    expect(right).toBeLessThanOrEqual(390);
+});
+
+test('a deleted prompt\'s page has no history subtitle, and a page that loads shows it (#524)',async({page,request})=>{
+    const list=await items(request),dual=byText(list,'Dual role portrait'),dog=byText(list,'Dog landscape');
+    const description=page.locator('#workspace-main > .heading p.muted');
+    await deleteFromPage(page,dual.id);
+    await choice(page).getByRole('radio',{name:'Delete permanently, with their saved pairs'}).check();
+    await review(page).getByRole('button',{name:'Delete 1 prompt',exact:true}).click();
+    await expect(page).toHaveURL(/#\/library$/);
+    await page.goto(`/prompt_manager/workspace#/library/${dual.id}`);
+    await expect(page.locator('#workspace-main .library-status')).toHaveText('This prompt no longer exists. It may have been deleted.');
+    await expect(description).toBeHidden();await expect(description).toHaveText('');
+    await page.goto(`/prompt_manager/workspace#/library/${dog.id}`);
+    await expect(description).toHaveText('Prompt history · one positive, one shared gallery');await expect(description).toBeVisible();
+});
+
+test('the archived shelf\'s heading count and its list agree under a remembered search (#512 item 5)',async({page,request})=>{
+    const all=await items(request);
+    const dual=byText(all,'Dual role portrait'),dog=byText(all,'Dog landscape');
+    await archiveByApi(request,[dual.id]);
+    await page.goto(route);
+    // A search that matches a shelf prompt but not the archived one.
+    await page.getByRole('searchbox').fill('landscape');
+    await expect(card(page,dog.id)).toHaveCount(1);await expect(card(page,dual.id)).toHaveCount(0);
+    const matching=(await(await request.get('/prompt_manager/library?limit=100&shelf=archived&text=landscape')).json()).items.length;
+    await expect(showArchived(page)).toHaveText(`Show archived prompts (${matching})`);
+    // Leave and come back: the remembered search is shown and still counts the same.
+    await page.goto('/prompt_manager/workspace#/overview');await page.goto(route);
+    await expect(page.getByRole('searchbox')).toHaveValue('landscape');
+    await expect(showArchived(page)).toHaveText(`Show archived prompts (${matching})`);
+    await showArchived(page).click();
+    await expect(backToLibrary(page)).toBeVisible();
+    if(matching) await expect(cards(page)).toHaveCount(matching);
+    else await expect(page.locator('.library-status')).toHaveText('No archived prompts match.');
+    await page.getByRole('searchbox').fill('');
+    await expect(card(page,dual.id)).toHaveCount(1);
+    await backToLibrary(page).click();
+    await expect(showArchived(page)).toHaveText('Show archived prompts (1)');
+});

tests/browser/workspace-library-editor.spec.mjs

@@ -8,7 +8,7 @@ import {inventoryOf,mapConcept,diffInventory} from './library-editor-canonical-c
 // Dialog-level contracts mount the editor through a page import; the user flows below use the real entry actions.
 test.use({locale:'en-US',timezoneId:'UTC',reducedMotion:'reduce'});
 const workspace='/prompt_manager/workspace';
-const ACTIONS={new:['Cancel','Save'],metadata:['Create text revision','Archive…','Cancel','Save'],revision:['Cancel','Save'],negative:['Cancel','Save']};
+const ACTIONS={new:['Cancel','Save'],metadata:['Create text revision','Archive variant…','Delete prompt…','Cancel','Save'],revision:['Cancel','Save'],negative:['Cancel','Save']};
 // D153 (#447): no Rating field; the fixture's positive stays stored with rating 4 through every workspace save.
 const LABELS=['Title','Positive prompt','Negative prompt (optional)','Category','Tags, separated by commas','Notes'];
 const UNAPPLIED='Saved as a new negative variant of an existing prompt. The title, category, tags and notes you entered were not applied.';
@@ -27,13 +27,15 @@ async function mountEditor(page,theme) {
     if(theme)await page.getByRole('combobox',{name:'Theme',exact:true}).selectOption(theme);
     await page.evaluate(async()=>{
         const trigger=document.createElement('button');trigger.type='button';trigger.id='editor-trigger';trigger.textContent='Open editor';document.body.append(trigger);
-        window.editorEvents={committed:[],reconciled:[]};
+        window.editorEvents={committed:[],reconciled:[],deletePrompt:[]};
         try {
             const {createLibraryEditor,showWorkspaceToast}=await import('/prompt_manager/js/workspace/library-editor.mjs');
             const {createScope}=await import('/prompt_manager/js/shared/toolkit/core.js');
             const scope=createScope();
             const editor=createLibraryEditor({api:window.ApiClient.createApiClient(),parentScope:scope,
-                onCommitted:commit=>window.editorEvents.committed.push(commit),onReconciled:result=>window.editorEvents.reconciled.push(result)});
+                onCommitted:commit=>window.editorEvents.committed.push(commit),onReconciled:result=>window.editorEvents.reconciled.push(result),
+                // As the prompt's page wires it (#481); the review itself is covered in workspace-library-delete.spec.mjs.
+                onDeletePrompt:request=>window.editorEvents.deletePrompt.push(request.positiveId)});
             window.editorHarness={scope,editor,showWorkspaceToast};
         } catch(error) {window.editorHarness={missing:String(error)};}
     });
@@ -52,7 +54,7 @@ const pairRead=async(request,id)=>(await(await request.get(`/prompt_manager/pair
 
 test('edit recipe metadata shows the concept fields with the selected saved negative read-only',async({page})=>{
     const f=page.fixture;await mountEditor(page);
-    const dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.pair_id});
+    let dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.pair_id});
     await expect(dialog.getByRole('heading',{name:'Edit recipe metadata',exact:true})).toBeVisible();
     expect(await dialog.evaluate(node=>node.matches(':modal'))).toBe(true);
     await expect(button(dialog,'Close dialog')).toBeFocused();await ready(dialog);
@@ -73,9 +75,14 @@ test('edit recipe metadata shows the concept fields with the selected saved nega
     await expect(dialog.locator('[placeholder]')).toHaveCount(0);
     await expect(dialog.locator('.demo-note')).toHaveCount(0);
     expect(await actionNames(dialog)).toEqual(ACTIONS.metadata);
-    await expect(button(dialog,'Archive…')).toHaveClass(/\bdanger\b/);await expect(button(dialog,'Save')).toHaveClass(/\bca-primary\b/);
+    await expect(button(dialog,'Archive variant…')).toHaveClass(/\bdanger\b/);await expect(button(dialog,'Save')).toHaveClass(/\bca-primary\b/);
     await page.keyboard.press('Escape');await expect(dialog).toHaveCount(0);
     await expect(page.locator('#editor-trigger')).toBeFocused();expect(page.writes).toHaveLength(0);
+    // D161 (#481): Delete prompt… closes the editor first and hands the prompt to the page's delete review.
+    dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.pair_id});await ready(dialog);
+    await expect(button(dialog,'Delete prompt…')).toHaveClass(/\bdanger\b/);await button(dialog,'Delete prompt…').click();
+    await expect(dialog).toHaveCount(0);
+    expect(await page.evaluate(()=>window.editorEvents.deletePrompt)).toEqual([f.positive_id]);expect(page.writes).toHaveLength(0);
 });
 
 test('editor modes persist through reload with selected saved negative',async({page,request})=>{
@@ -144,13 +151,13 @@ test('editor modes persist through reload with selected saved negative',async({p
 test('archive confirms the selected pair with fresh counts and writes only on confirm',async({page,request})=>{
     const f=page.fixture;await mountEditor(page);
     let dialog=await openEditor(page,{mode:'metadata',positiveId:f.standalone_id,pairId:null});await ready(dialog);
-    const archive=button(dialog,'Archive…');await expect(archive).toBeDisabled();
+    const archive=button(dialog,'Archive variant…');await expect(archive).toBeDisabled();
     await expect(archive).toHaveAccessibleDescription('Archive needs a selected saved negative variant.');
     await expect(note(dialog)).toHaveText('Archive needs a selected saved negative variant.');
     await button(dialog,'Cancel').click();await expect(dialog).toHaveCount(0);await expect(page.locator('#editor-trigger')).toBeFocused();
 
     dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.pair_id});await ready(dialog);
-    await button(dialog,'Archive…').click();
+    await button(dialog,'Archive variant…').click();
     await expect(dialog.getByRole('heading',{name:'Archive negative variant',exact:true})).toBeVisible();
     await expect(button(dialog,'Close dialog')).toBeFocused();
     const block=dialog.getByRole('region',{name:'Negative prompt',exact:true});
@@ -163,7 +170,7 @@ test('archive confirms the selected pair with fresh counts and writes only on co
     expect((await pairRead(request,f.pair_id)).archived).toBe(false);
 
     dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.pair_id});await ready(dialog);
-    await button(dialog,'Archive…').click();await expect(button(dialog,'Archive')).toBeEnabled();
+    await button(dialog,'Archive variant…').click();await expect(button(dialog,'Archive')).toBeEnabled();
     await button(dialog,'Archive').click();await expect(dialog).toHaveCount(0);
     expect(page.writes).toEqual([{method:'PATCH',url:`/prompt_manager/pairs/${f.pair_id}`,body:{archived:true}}]);
     expect((await pairRead(request,f.pair_id)).archived).toBe(true);
@@ -178,7 +185,7 @@ test('a failed archive keeps focus on the Archive confirmation inside the dialog
         failed=true;return route.fulfill({status:400,contentType:'application/json',body:'{"success":false,"error":"Cannot archive.","code":null}'});
     });
     const dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.pair_id});await ready(dialog);
-    await button(dialog,'Archive…').click();await expect(button(dialog,'Archive')).toBeEnabled();
+    await button(dialog,'Archive variant…').click();await expect(button(dialog,'Archive')).toBeEnabled();
     await button(dialog,'Archive').click();
     await expect(note(dialog)).toContainText('Cannot archive.');expect(page.writes).toHaveLength(1);
     await expect(button(dialog,'Archive')).toBeFocused();
@@ -192,7 +199,7 @@ test('an unconfirmed archive moves focus to Retry instead of dropping it out of
         await route.continue();
     });
     const dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.pair_id});await ready(dialog);
-    await button(dialog,'Archive…').click();await expect(button(dialog,'Archive')).toBeEnabled();
+    await button(dialog,'Archive variant…').click();await expect(button(dialog,'Archive')).toBeEnabled();
     await button(dialog,'Archive').click();
     await expect(note(dialog)).toHaveText('Archive could not be confirmed. Retry sends the same archive once.');
     await expect(button(dialog,'Archive')).toBeDisabled();await expect(button(dialog,'Retry')).toBeFocused();
@@ -209,7 +216,7 @@ test('an archive conflict offers an explicit Reload that re-reads and never repl
         conflicted=true;return route.fulfill({status:409,contentType:'application/json',body:'{"success":false,"error":"changed","code":"metadata-conflict"}'});
     });
     const dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.pair_id});await ready(dialog);
-    await button(dialog,'Archive…').click();await expect(button(dialog,'Archive')).toBeEnabled();
+    await button(dialog,'Archive variant…').click();await expect(button(dialog,'Archive')).toBeEnabled();
     await button(dialog,'Archive').click();
     await expect(note(dialog)).toHaveText('This negative variant changed since it was loaded. Reload it and review it before archiving.');
     await expect(button(dialog,'Archive')).toBeDisabled();expect(page.writes).toHaveLength(1);
@@ -237,7 +244,7 @@ test('cancel and busy submit have honest write counts',async({page})=>{
     dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.pair_id});await ready(dialog);
     await field(dialog,'Notes').fill('busy save');await button(dialog,'Save').click();
     await expect(note(dialog)).toHaveText('Saving… The dialog stays open until the server answers.');
-    for(const name of ['Save','Cancel','Close dialog','Create text revision','Archive…'])await expect(button(dialog,name)).toBeDisabled();
+    for(const name of ['Save','Cancel','Close dialog','Create text revision','Archive variant…','Delete prompt…'])await expect(button(dialog,name)).toBeDisabled();
     await field(dialog,'Title').press('Enter');await page.keyboard.press('Escape');
     await expect(dialog).toBeVisible();expect(page.writes).toHaveLength(1);
     release();await expect(dialog).toHaveCount(0);expect(page.writes).toHaveLength(1);
@@ -319,15 +326,15 @@ test('edge states keep drafts, explain disabled archive and clean up on dispose'
 
     dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.archived_pair_id});await ready(dialog);
     await expect(field(dialog,'Negative prompt (optional)')).toHaveValue(f.archived_negative);
-    await expect(button(dialog,'Archive…')).toBeDisabled();await expect(note(dialog)).toHaveText('This negative variant is already archived.');
-    await expect(button(dialog,'Archive…')).toHaveAccessibleDescription('This negative variant is already archived.');
+    await expect(button(dialog,'Archive variant…')).toBeDisabled();await expect(note(dialog)).toHaveText('This negative variant is already archived.');
+    await expect(button(dialog,'Archive variant…')).toHaveAccessibleDescription('This negative variant is already archived.');
     await button(dialog,'Cancel').click();
 
     let failed=true;
     await page.route(`**/prompt_manager/pairs/${f.empty_pair_id}`,route=>{if(!failed&&route.request().method()==='GET'){failed=true;return route.fulfill({status:500,contentType:'application/json',body:'{"success":false,"error":"down"}'});}return route.continue();});
     dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.empty_pair_id});await ready(dialog);
     await expect(field(dialog,'Negative prompt (optional)')).toHaveValue('');
-    failed=false;await button(dialog,'Archive…').click();
+    failed=false;await button(dialog,'Archive variant…').click();
     await expect(note(dialog)).toHaveText('Linked images and recorded runs could not be read. Nothing was archived.');
     await expect(button(dialog,'Archive')).toBeDisabled();
     await expect(dialog.getByRole('region',{name:'Negative prompt',exact:true})).toContainText('Empty negative prompt');
@@ -347,12 +354,12 @@ test('the archive confirmation does not inherit a failed or invalid Edit save me
     let dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.pair_id});await ready(dialog);
     await field(dialog,'Notes').fill('Rejected notes');await button(dialog,'Save').click();
     await expect(note(dialog)).toHaveText('Not saved: Notes are too long. Your entries are kept.');
-    await button(dialog,'Archive…').click();await expect(dialog).toContainText('1 image and 2 recorded runs stay linked.');
+    await button(dialog,'Archive variant…').click();await expect(dialog).toContainText('1 image and 2 recorded runs stay linked.');
     await expect(note(dialog)).toBeHidden();await expect(button(dialog,'Archive')).toBeEnabled();
     await button(dialog,'Cancel').click();await expect(dialog).toHaveCount(0);
     dialog=await openEditor(page,{mode:'metadata',positiveId:f.positive_id,pairId:f.pair_id});await ready(dialog);
     await field(dialog,'Title').fill('   ');await button(dialog,'Save').click();await expect(note(dialog)).toHaveText('Title is required');
-    await button(dialog,'Archive…').click();await expect(dialog).toContainText('1 image and 2 recorded runs stay linked.');
+    await button(dialog,'Archive variant…').click();await expect(dialog).toContainText('1 image and 2 recorded runs stay linked.');
     await expect(note(dialog)).toBeHidden();await expect(button(dialog,'Archive')).toBeEnabled();
     expect(page.writes).toHaveLength(1);
 });
@@ -493,13 +500,16 @@ test('a restore seen finishing keeps New prompt open and reloads the Library aft
 test('library heading offers Export then + New prompt, and New opens the saved prompt history',async({page,request})=>{
     await page.goto(`${workspace}#/library`);await expect(page.locator('article[data-prompt-id]').first()).toBeVisible();
     const actions=headingActions(page).locator('button');
-    expect(await visibleNames(actions)).toEqual(['Export','+ New prompt']);
+    // D152 (#443): Show archived prompts (N) comes first, a plain button (#482: no pressed state; on the archived shelf it
+    // reads "← Prompt library").
+    expect(await visibleNames(actions)).toEqual(['Show archived prompts (0)','Export','+ New prompt']);
+    await expect(actions.nth(0)).not.toHaveAttribute('aria-pressed');await expect(actions.nth(0)).not.toHaveClass(/ca-primary/);
     // One image is counted in the singular.
     const f=page.fixture;await expect(page.locator(`article[data-prompt-id="${f.positive_id}"]`).getByText('1 image',{exact:true})).toHaveCount(1);
-    await expect(actions.nth(0)).toHaveAccessibleName('Export full Library JSON');await expect(actions.nth(0)).not.toHaveClass(/ca-primary/);
-    await expect(actions.nth(1)).toHaveClass(/\bca-primary\b/);
-    for(const index of [0,1])expect((await actions.nth(index).boundingBox()).height).toBeGreaterThanOrEqual(32);
-    await actions.nth(1).click();const dialog=editorDialog(page);await expect(dialog.getByRole('heading',{name:'New prompt',exact:true})).toBeVisible();await ready(dialog);
+    await expect(actions.nth(1)).toHaveAccessibleName('Export full Library JSON');await expect(actions.nth(1)).not.toHaveClass(/ca-primary/);
+    await expect(actions.nth(2)).toHaveClass(/\bca-primary\b/);
+    for(const index of [0,1,2])expect((await actions.nth(index).boundingBox()).height).toBeGreaterThanOrEqual(32);
+    await actions.nth(2).click();const dialog=editorDialog(page);await expect(dialog.getByRole('heading',{name:'New prompt',exact:true})).toBeVisible();await ready(dialog);
     await field(dialog,'Title').fill('Harbor at dawn');await field(dialog,'Positive prompt').fill('A quiet harbor at dawn');await field(dialog,'Negative prompt (optional)').fill('fog, noise');
     await button(dialog,'Save').click();await expect(dialog).toHaveCount(0);
     const created=(await(await request.get('/prompt_manager/library?text=quiet%20harbor')).json()).items[0];
@@ -530,8 +540,9 @@ test('new from Images cancel preserves browse',async({page})=>{
 
 test('history heading follows the concept and sends the selected saved pair',async({page})=>{
     const f=page.fixture;await openHistory(page,f.positive_id);
-    const actions=headingActions(page).locator('button');
-    expect(await visibleNames(actions)).toEqual(['← Prompt library','Edit metadata','Send to ComfyUI']);
+    const actions=headingActions(page).locator('button:not([role="menuitem"])');
+    // D163 (#512): the More menu button follows Send to ComfyUI.
+    expect(await visibleNames(actions)).toEqual(['← Prompt library','Edit metadata','Send to ComfyUI','⋯']);
     await expect(page.getByRole('link',{name:'Back to library',exact:true})).toHaveCount(0);
     const send=actions.nth(2);await expect(send).toHaveClass(/\bsend\b/);await expect(send.locator('svg')).toHaveCount(1);
     await expect(send).toHaveAccessibleName(`Send prompt pair to ComfyUI: ${f.metadata.title}`);
@@ -633,16 +644,20 @@ test('restored storage after a confirmed save or before an archive offers an exp
         const response=await route.fetch();await expect(await restore()).toBeOK();return route.fulfill({response});
     });
     await page.getByRole('button',{name:'Edit metadata',exact:true}).click();let dialog=editorDialog(page);await ready(dialog);
-    await field(dialog,'Notes').fill('Lost to a restore');await button(dialog,'Save').click();
+    await field(dialog,'Notes').fill('Lost to a restore');
+    // The save's answer waits for a whole restore in the route above; wait for that answer, not the 5 s expect
+    // default (#501 merge queue: under load the restore outlasted it on WebKit).
+    const saved=page.waitForResponse(item=>item.request().method()==='PATCH'&&new URL(item.url()).pathname===`/prompt_manager/library/${f.positive_id}`);
+    await button(dialog,'Save').click();await saved;
     await expect(note(dialog)).toHaveText('Saved; Library refresh failed because prompt storage was restored. Reload the Library to see current data.');
-    expect(await actionNames(dialog)).toEqual(['Reload Library','Create text revision','Archive…','Cancel','Save']);
-    for(const name of ['Create text revision','Archive…'])await expect(button(dialog,name)).toBeDisabled();
+    expect(await actionNames(dialog)).toEqual(['Reload Library','Create text revision','Archive variant…','Delete prompt…','Cancel','Save']);
+    for(const name of ['Create text revision','Archive variant…','Delete prompt…'])await expect(button(dialog,name)).toBeDisabled();
     await button(dialog,'Reload Library').click();await expect(dialog).toHaveCount(0);
     await expect(variantsPanel(page)).toBeVisible();await expect(page.locator('#workspace-main h1')).toHaveText(f.metadata.title);
     await page.unroute(`**/prompt_manager/library/${f.positive_id}`);expect(page.writes).toHaveLength(1);
     await selectPair(page,'Select negative variant 2');
     await page.getByRole('button',{name:'Edit metadata',exact:true}).click();dialog=editorDialog(page);await ready(dialog);
-    await button(dialog,'Archive…').click();await expect(button(dialog,'Archive')).toBeEnabled();
+    await button(dialog,'Archive variant…').click();await expect(button(dialog,'Archive')).toBeEnabled();
     await expect(await restore()).toBeOK();await button(dialog,'Archive').click();
     await expect(note(dialog)).toHaveText('Prompt storage was restored since this dialog opened. Nothing was archived.');
     expect(await actionNames(dialog)).toEqual(['Reload Library','Cancel','Archive']);expect(page.writes).toHaveLength(1);
@@ -659,10 +674,10 @@ test('restored storage before an Edit or Add negative save offers only the Libra
     await expect(await restore()).toBeOK();
     await field(dialog,'Notes').fill('Typed before the restore');await button(dialog,'Save').click();
     await expect(note(dialog)).toHaveText(`Prompt storage was restored since this dialog opened. Nothing was saved. ${DISCARDS}`);
-    expect(await actionNames(dialog)).toEqual(['Reload Library','Create text revision','Archive…','Cancel','Save']);
+    expect(await actionNames(dialog)).toEqual(['Reload Library','Create text revision','Archive variant…','Delete prompt…','Cancel','Save']);
     await expect(button(dialog,'Reload Library state')).toHaveCount(0);await expect(button(dialog,'Save')).toBeDisabled();
     // Revise and archive would re-read the old numeric IDs, which may now name another prompt.
-    for(const name of ['Create text revision','Archive…'])await expect(button(dialog,name)).toBeDisabled();
+    for(const name of ['Create text revision','Archive variant…','Delete prompt…'])await expect(button(dialog,name)).toBeDisabled();
     await expect(button(dialog,'Reload Library')).toBeFocused();
     expect(page.writes).toHaveLength(1);// the refused save
     await button(dialog,'Reload Library').click();await expect(dialog).toHaveCount(0);await expect(variantsPanel(page)).toBeVisible();
@@ -729,7 +744,7 @@ test('archive hides a pair, Show archived finds it and Restore keeps it selected
     const before=await evidence();expect(before.counts).toEqual({images:1,runs:2});
     await openHistory(page,f.positive_id);await selectPair(page,'Select negative variant 2');
     await page.getByRole('button',{name:'Edit metadata',exact:true}).click();const dialog=editorDialog(page);await ready(dialog);
-    await button(dialog,'Archive…').click();await expect(button(dialog,'Archive')).toBeEnabled();await button(dialog,'Archive').click();await expect(dialog).toHaveCount(0);
+    await button(dialog,'Archive variant…').click();await expect(button(dialog,'Archive')).toBeEnabled();await button(dialog,'Archive').click();await expect(dialog).toHaveCount(0);
     await expect(toast(page)).toHaveText('Archived. Find it under Show archived in Negative variants.');await expect(page.locator('#workspace-main h1')).toBeFocused();
     await expect(variantsPanel(page).locator('.variant-lane')).toHaveCount(2);await expect(pressedVariant(page)).toHaveCount(1);
     await expect(savedTexts(page).getByRole('region',{name:'Negative prompt',exact:true})).not.toContainText(f.selected_negative);
@@ -872,7 +887,7 @@ test('turning Show archived on again after a hidden archive shows the newly arch
     await toggle().click();await expect(toggle()).toHaveAttribute('aria-pressed','false');await expect(variantsPanel(page).locator('.library-variant-archived')).toHaveCount(0);
     await selectPair(page,'Select negative variant 2');
     await page.getByRole('button',{name:'Edit metadata',exact:true}).click();const dialog=editorDialog(page);await ready(dialog);
-    await button(dialog,'Archive…').click();await expect(button(dialog,'Archive')).toBeEnabled();await button(dialog,'Archive').click();await expect(dialog).toHaveCount(0);
+    await button(dialog,'Archive variant…').click();await expect(button(dialog,'Archive')).toBeEnabled();await button(dialog,'Archive').click();await expect(dialog).toHaveCount(0);
     await expect(toggle()).toHaveText('Show archived (2)');await toggle().click();
     await expect(variantsPanel(page).locator('.library-variant-archived')).toHaveCount(2);
     await expect(laneLabel(page,'· 2 runs · Archived')).toHaveCount(1);await uniqueDotNames(page);

tests/browser/workspace-library-selection.spec.mjs

@@ -62,7 +62,8 @@ test('Set category writes the selected prompts on the server, reloads the shelf
     await box(page,first.id).check();await expect(bar(page).locator('strong')).toHaveText('1 selected');
     await box(page,second.id).check();await expect(bar(page).locator('strong')).toHaveText('2 selected');
     // Two of three loaded are checked, so Select all N loaded follows the count (D151, #444 ruling).
-    await expect(bar(page).getByRole('button')).toHaveText([`Select all ${items.length} loaded`,'Add tags','Set category','Clear']);
+    // D152 (#443) adds Delete… before Clear.
+    await expect(bar(page).getByRole('button')).toHaveText([`Select all ${items.length} loaded`,'Add tags','Set category','Delete…','Clear']);
     await setCategory(page,'  Studio set  ');
     await expect(toast(page)).toHaveText('Category “Studio set” set on 2 prompts.');
     await expect(dialog(page)).toHaveCount(0);
@@ -287,7 +288,7 @@ test('Ctrl/Cmd+A and Select all N loaded select every loaded prompt, windowed on
     let release;const held=new Promise(resolve=>{release=resolve;});
     await page.route('**/prompt_manager/bulk/tags',async route=>{await held;await route.continue();},{times:1});
     await addTags(page,'everyone');
-    for(const name of ['Add tags','Set category',`Select all ${all} loaded`]) await expect(bar(page).getByRole('button',{name,exact:true})).toHaveAttribute('aria-disabled','true');
+    for(const name of ['Add tags','Set category','Delete…','Clear',`Select all ${all} loaded`]) await expect(bar(page).getByRole('button',{name,exact:true})).toHaveAttribute('aria-disabled','true');
     release();
     await expect(toast(page)).toHaveText(`Added “everyone” to ${all-1} prompts.`);
     expect(writes).toHaveLength(1);expect(new Set(writes[0].prompt_ids).size).toBe(all-1);

tests/browser/workspace-review.spec.mjs

@@ -221,6 +221,33 @@ test('tag image from review saves tags and the item remains pending', async ({ p
     await expect(dialog).toHaveCount(0);
 });
 
+test('#515: tags typed before the image observation answers are saved', async ({ page, request }) => {
+    await seed(request, 1);
+    await open(page);
+    // Hold the dialog's observation so the typing lands while it is pending (a slow host or WebKit in CI).
+    let release;
+    const held = new Promise(resolve => { release = resolve; });
+    const matcher = '**/prompt_manager/image-annotations/observe';
+    let reachedObserve;
+    const reached = new Promise(resolve => { reachedObserve = resolve; });
+    await page.route(matcher, async route => { reachedObserve(); await held; await route.continue(); });
+    await panel(page).getByRole('button', { name: 'Tag image', exact: true }).click();
+    const dialog = page.getByRole('dialog', { name: 'Tag image', exact: true });
+    await reached;
+    const field = dialog.getByRole('textbox', { name: 'Image tags · edit manually', exact: true });
+    await field.fill('dunes');
+    const save = dialog.getByRole('button', { name: 'Save manual tags', exact: true });
+    await expect(save).toHaveAttribute('aria-disabled', 'true');
+    const answered = page.waitForResponse(item => item.url().endsWith('/image-annotations/observe'));
+    release();
+    await answered;
+    await expect(save).not.toHaveAttribute('aria-disabled', 'true');
+    await expect(field).toHaveValue('dunes');
+    await save.click();
+    await expect(toast(page)).toHaveText('1 tags saved for review_0000.png. Prompt association still awaits review.');
+    await page.unroute(matcher);
+});
+
 test('an empty queue shows the empty notice only', async ({ page, request }) => {
     await seed(request, 0);
     await page.goto(review);

tests/browser/workspace-stale-source.spec.mjs

@@ -37,6 +37,15 @@ test.afterEach(async ({ page, request, browserName }) => {
     await expect(await request.post('/__test__/tagging/reset', { data: {} })).toBeOK();
 });
 
+async function openSettled(page, url) {
+    // The page reads its selected file's details as soon as it lists. A source change before that read is answered
+    // makes the page find the file again on its own, so the test's old-numbering locators are gone before they are
+    // used (#484): every test changes sources only after the read was answered.
+    const inspected = page.waitForResponse(item => new URL(item.url()).pathname.startsWith('/prompt_manager/images/inspect/') &&
+        item.request().method() === 'GET');
+    await page.goto(url);
+    expect((await inspected).status()).toBe(200);
+}
 async function openTag(page, path = FIRST, root = 0) {
     const observed = answered(page, '/image-annotations/observe');
     await tagButton(page, path, root).click();
@@ -53,7 +62,7 @@ async function savedTags(request, path, root) {
 }
 
 test('renumbered sources under an open Tag dialog: it finds the file again, keeps the draft and Generate works', async ({ page, request }) => {
-    await page.goto(images);
+    await openSettled(page, images);
     await expect(card(page, FIRST)).toHaveClass(/\bselected\b/);
     expect((await openTag(page)).status()).toBe(200);
     await manual(page).fill('kept_draft');
@@ -91,7 +100,7 @@ test('renumbered sources under an open Tag dialog: it finds the file again, keep
 });
 
 test('the inspector finds a renumbered file again; checked files from the old numbering are cleared', async ({ page, request }) => {
-    await page.goto(images);
+    await openSettled(page, images);
     await expect(card(page, FIRST)).toHaveClass(/\bselected\b/);
     await card(page, FIRST).getByRole('checkbox', { name: /^Select / }).check();
     await expect(page.locator('.bulkbar')).toBeVisible();
@@ -113,7 +122,7 @@ test('the inspector finds a renumbered file again; checked files from the old nu
 });
 
 test('a scope that cannot be mapped: Generate and Save are visibly disabled, the reason and Refresh sit beside them', async ({ page }) => {
-    await page.goto(images);
+    await openSettled(page, images);
     await expect(card(page, FIRST)).toBeVisible();
     await expect(await page.request.post('/__test__/scope-key/rotate')).toBeOK();
     const rescoped = answered(page, '/images/rescope');
@@ -157,7 +166,7 @@ test('a scope that cannot be mapped: Generate and Save are visibly disabled, the
 });
 
 test('an unmappable inspector read keeps its visible Refresh, and Refresh recovers the panel', async ({ page }) => {
-    await page.goto(images);
+    await openSettled(page, images);
     await expect(card(page, FIRST)).toHaveClass(/\bselected\b/);
     await expect(await page.request.post('/__test__/scope-key/rotate')).toBeOK();
     const rescoped = answered(page, '/images/rescope');
@@ -173,7 +182,7 @@ test('an unmappable inspector read keeps its visible Refresh, and Refresh recove
 
 test('a Load more cursor the server cannot verify offers Refresh instead of a dead Retry', async ({ page, request }) => {
     await expect(await request.post('/__test__/tagging/reset', { data: { extra_images: 60 } })).toBeOK();
-    await page.goto(images);
+    await openSettled(page, images);
     await expect(cards(page).first()).toBeVisible();
     await expect(page.locator('#gallery-continuation')).toContainText('more load as you scroll');
     await expect(await request.post('/__test__/scope-key/rotate')).toBeOK();
@@ -191,7 +200,7 @@ test('a Load more cursor the server cannot verify offers Refresh instead of a de
 });
 
 test('a viewer whose media source was renumbered closes onto the file, kept selected', async ({ page, request }) => {
-    await page.goto(images);
+    await openSettled(page, images);
     await expect(card(page, FIRST)).toHaveClass(/\bselected\b/);
     await expect(await request.post('/__test__/sources/reverse')).toBeOK();
     const rescoped = answered(page, '/images/rescope');
@@ -217,7 +226,7 @@ test('a collection page finds a renumbered member again and stays on its members
     await expect(added).toBeOK();
     const collections = (await (await request.get('/prompt_manager/collections')).json()).collections;
     const { id } = collections.find(item => item.name === name);
-    await page.goto(`/prompt_manager/workspace#/collection/${id}`);
+    await openSettled(page, `/prompt_manager/workspace#/collection/${id}`);
     await expect(cards(page)).toHaveCount(1);
     await expect(card(page, FIRST)).toHaveClass(/\bselected\b/);
     await expect(await request.post('/__test__/sources/reverse')).toBeOK();

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

@@ -11,8 +11,8 @@ const STATUS_URL = '/prompt_manager/backup/status';
 const PREVIEW_URL = '/prompt_manager/restore/preview';
 const APPLY_URL = '/prompt_manager/restore/apply';
 const WHEN = { dateStyle: 'medium', timeStyle: 'short' };
-const SAFETY_DESCRIPTION = 'Keep a verified copy of the database on disk before maintenance, cleanups and LoRA imports change ' +
-    'records. A restore always keeps one.';
+const SAFETY_DESCRIPTION = 'Keep a verified copy of the database on disk before maintenance, cleanups, LoRA imports and ' +
+    'prompt deletes change records. A restore always keeps one.';
 
 test.use({ locale: 'en-US', timezoneId: 'UTC' });
 

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

@@ -274,11 +274,18 @@ test('level filter is minimum-level over all six choices', async ({ page, reques
     for (const line of (await lines(page).textContent()).split('\n')) expect(line).toMatch(/^\d\d:\d\d:\d\d [A-Z]+ +\S/);
     expect(urls.at(-1)).toBe('?limit=100');
     for (const minimum of LEVELS) {
+        // Wait for this level's answer: the previous level's lines also hold the CRITICAL line, so seeing it proved
+        // nothing, and under load the filtered answer painted after the check (#501 merge queue, firefox).
+        const answered = page.waitForResponse(item => new URL(item.url()).pathname === LOGS_URL
+            && new URL(item.url()).search === `?limit=100&level=${minimum}`);
         await level.selectOption(minimum);
+        await answered;
         await expect.poll(() => urls.at(-1)).toBe(`?limit=100&level=${minimum}`);
         await expect(lines(page)).toContainText('CRITICAL The database could not be opened');
-        const shown = await shownLevels(page);
-        expect(shown.every(name => LEVELS.indexOf(name) >= LEVELS.indexOf(minimum)), `${minimum}: ${shown}`).toBe(true);
+        await expect.poll(async () => {
+            const shown = await shownLevels(page);
+            return shown.every(name => LEVELS.indexOf(name) >= LEVELS.indexOf(minimum)) || `${minimum}: ${shown}`;
+        }).toBe(true);
         if (minimum === 'DEBUG') await expect(lines(page)).toContainText('DEBUG Thumbnail cache lookup');
         if (minimum === 'WARNING') {
             await expect(lines(page)).not.toContainText('Database backup verified');

tests/browser/workspace-tagging-bulk.spec.mjs

@@ -73,7 +73,7 @@ const jobStart = page => page.waitForRequest(item => item.method() === 'POST' &&
 
 test('selection bar shows Add tags then Auto-tag selected before Set category', async ({ page }) => {
     await select(page, FIRST);
-    await expect(bar(page).locator(':scope > *')).toHaveText(['1 selected', 'Add tags', 'Auto-tag selected', 'Set category', 'Add to collection', 'Export metadata', 'Clear']);
+    await expect(bar(page).locator(':scope > *')).toHaveText(['1 selected', 'Add tags', 'Auto-tag selected', 'Set category', 'Add to collection', 'Export metadata', 'Delete…', 'Clear']);
 });
 
 test('Add tags runs a job and the cards show the tags after it finishes', async ({ page, request }) => {

tests/browser/workspace.spec.mjs

@@ -11,12 +11,12 @@ const sidebarLink = (page, label) => page.locator('aside.sidebar nav').getByRole
 const sidebarLinks = page => page.locator('aside.sidebar nav a');
 const routes = [
     ['overview', 'Overview', null],
-    // D29: Images no longer links the legacy gallery; Overview's tool cards still do.
+    // D29: Images no longer links the legacy gallery.
     ['images', 'Images', null],
-    // #249 E3: the shelf no longer links the legacy Library; Overview's tool card still does.
+    // #249 E3: the shelf no longer links the legacy Library.
     ['library', 'Prompt library', null],
     ['tags', 'Tags & categories', null],
-    // #249 local Inspect: the native Inspect a file page; Overview's tool card still links the legacy metadata page.
+    // #249 local Inspect: the native Inspect a file page.
     ['inspect', 'Inspect a file', null],
     // #249 System S2: native System; every section native since S12 (D94 retired, asserted below).
     ['system', 'System', null],
@@ -93,20 +93,106 @@ test('all shell destinations deep-link, reload and expose working existing appli
         await page.reload();
         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.
+    // #525: Overview's cards open the native pages, and no workspace page links a legacy one.
+    for (const [action, hash, title] of [
+        ['Open Images', '#/images', 'Images'],
+        ['Open Prompt library', '#/library', 'Prompt library'],
+        ['Open Tags & categories', '#/tags', 'Tags & categories'],
+        ['Open Inspect a file', '#/inspect', 'Inspect a file'],
+        ['Open System', '#/system/overview', 'System'],
+    ]) {
+        await page.goto(`${workspace}#/overview`);
+        const main = page.locator('#workspace-main');
+        const card = main.getByRole('link', { name: action, exact: true });
+        await expect(card).toHaveAttribute('href', hash);
+        await card.click();
+        await expect(page).toHaveURL(new RegExp(`/prompt_manager/workspace${hash}$`));
+        await expect(main.getByRole('heading', { level: 1, name: title, exact: true })).toBeVisible();
+    }
     await page.goto(`${workspace}#/overview`);
-    const library = page.locator('#workspace-main').getByRole('link', { name: 'Open existing prompt library', exact: true });
-    await expect(library).toHaveAttribute('href', '/prompt_manager/admin');
-    await expect(await request.get('/prompt_manager/admin')).toBeOK();
-    // The legacy metadata page stays reachable from Overview beside the native Inspect page.
-    const metadata = page.locator('#workspace-main').getByRole('link', { name: 'Open existing metadata inspector', exact: true });
-    await expect(metadata).toHaveAttribute('href', '/prompt_manager/gallery.html');
-    await expect(await request.get('/prompt_manager/gallery.html')).toBeOK();
-    const gallery = page.locator('#workspace-main').getByRole('link', { name: 'Open existing image gallery', exact: true });
-    await expect(gallery).toHaveAttribute('href', '/prompt_manager/gallery');
-    await expect(await request.get('/prompt_manager/gallery')).toBeOK();
-    await gallery.click();
-    await expect(page).toHaveURL(/\/prompt_manager\/gallery$/);
+    await expect(page.locator('#workspace-main').getByRole('link', { name: 'Open Images', exact: true })).toBeVisible();
+    await expect(page.locator('a[href*="/prompt_manager/admin"], a[href*="/prompt_manager/gallery"]')).toHaveCount(0);
+    await expect(page.locator('#workspace-main').getByText('Your existing tools remain available')).toHaveCount(0);
+    // The legacy pages themselves stay at their URLs.
+    for (const legacy of ['/prompt_manager/admin', '/prompt_manager/gallery', '/prompt_manager/gallery.html']) {
+        await expect(await request.get(legacy)).toBeOK();
+    }
+});
+
+test('/prompt_manager/web lands on the workspace Library and Back does not bounce through it (#525)', async ({ page }) => {
+    await page.goto(`${workspace}#/overview`);
+    await page.evaluate(() => { location.href = '/prompt_manager/web'; });
+    await expect(page).toHaveURL(/\/prompt_manager\/workspace#\/library$/);
+    const main = page.locator('#workspace-main');
+    await expect(main.getByRole('heading', { level: 1, name: 'Prompt library', exact: true })).toBeVisible();
+    await page.goBack();
+    await expect(page).toHaveURL(/\/prompt_manager\/workspace#\/overview$/);
+    await expect(main.getByRole('heading', { level: 1, name: 'Overview', exact: true })).toBeVisible();
+});
+
+// D165 (#525, maintainer ruling): a discreet line under System is the workspace's only visible way to the legacy pages.
+test('System Overview links the legacy pages discreetly, and each one loads (#525)', async ({ page, context }) => {
+    await page.goto(`${workspace}#/system/overview`);
+    const line = page.locator('#workspace-main .legacy-pages');
+    await expect(line).toBeVisible();
+    await expect(line).toContainText('Legacy pages');
+    const links = line.getByRole('link');
+    await expect(links).toHaveCount(4);
+    for (const [name, url, ready] of [
+        ['Dashboard', '/prompt_manager/admin', '#addPromptBtn'],
+        ['Tags', '/prompt_manager/admin#/tags', '#addPromptBtn'],
+        ['Gallery', '/prompt_manager/gallery', 'body'],
+        ['Metadata viewer', '/prompt_manager/gallery.html', 'body'],
+    ]) {
+        const opened = context.waitForEvent('page');
+        await line.getByRole('link', { name, exact: true }).click();
+        const tab = await opened;
+        await tab.waitForLoadState('domcontentloaded');
+        const target = new URL(tab.url());
+        expect(target.pathname + target.hash).toBe(url);
+        await expect(tab.locator(ready).first()).toBeAttached();
+        await tab.close();
+    }
+    // Only on System's Overview section, and gone with the page.
+    await page.locator('#workspace-main .section-nav').getByRole('button', { name: 'Appearance', exact: true }).click();
+    await expect(line).toBeHidden();
+    await page.goto(`${workspace}#/library`);
+    await expect(page.locator('#workspace-main .legacy-pages')).toHaveCount(0);
+});
+
+const bootFailure = page => page.locator('#workspace-boot-failure');
+
+test('a healthy workspace never shows the load failure message (#525)', async ({ page }) => {
+    await page.goto(`${workspace}#/library`);
+    await expect(page.locator('#workspace-main h1')).toHaveText('Prompt library');
+    await page.waitForFunction(() => document.readyState === 'complete');
+    await expect(bootFailure(page)).toBeHidden();
+});
+
+for (const [label, pattern] of [['the entry module', '**/js/workspace/index.mjs*'], ['a dependency', '**/js/workspace/state.mjs*']]) {
+    test(`when ${label} fails to load the page still offers the legacy pages (#525)`, async ({ page }) => {
+        const pageErrors = [];
+        page.on('pageerror', error => pageErrors.push(error.message));
+        await page.route(pattern, route => route.abort());
+        await page.goto(`${workspace}#/library`);
+        const failure = bootFailure(page);
+        await expect(failure).toBeVisible();
+        await expect(failure).toHaveAttribute('role', 'alert');
+        const dashboard = failure.getByRole('link', { name: 'Dashboard', exact: true });
+        await expect(dashboard).toBeVisible();
+        await expect(failure.getByRole('link')).toHaveCount(4);
+        await dashboard.click();
+        await expect(page).toHaveURL(/\/prompt_manager\/admin$/);
+        expect(pageErrors).toEqual([]);
+    });
+}
+
+test('when a module throws while starting the page still offers the legacy pages (#525)', async ({ page }) => {
+    await page.route('**/js/workspace/state.mjs*', route => route.fulfill({ contentType: 'text/javascript', body: "throw new Error('boot failure');" }));
+    await page.goto(`${workspace}#/library`);
+    await expect(bootFailure(page).getByRole('link', { name: 'Dashboard', exact: true })).toBeVisible();
+    // The broken module's own error is this test's premise, not a failure of the page.
+    page.workspaceErrors.length = 0;
 });
 
 test('keyboard navigation, browser history and unknown routes remain usable', async ({ page }) => {
@@ -438,7 +524,7 @@ test('System is native: the concept shell, section navigation, sections and the
     // D92: no "Sample configuration" chip.
     await expect(main.locator('.heading .chip')).toHaveCount(0);
     expect(await main.evaluate(node => [...node.children].map(child => `${child.localName}.${child.className}`)))
-        .toEqual(['div.heading', 'div.section-nav', 'div.settings-layout']);
+        .toEqual(['div.heading', 'div.section-nav', 'div.settings-layout', 'p.small legacy-pages']);
     const nav = main.getByRole('group', { name: 'System sections', exact: true });
     await expect(nav.getByRole('button')).toHaveText(SYSTEM_SECTION_LABELS);
     await expect(nav.getByRole('button', { name: 'Overview', exact: true })).toHaveAttribute('aria-pressed', 'true');

tests/comfyui/focused-node.spec.mjs

@@ -210,14 +210,14 @@ test(`${label} follows actual ComfyUI light and dark palettes`, async ({ page },
     }
 });
 
-test(`${label} Web UI button opens actual standalone pages`, async ({ page }) => {
+test(`${label} Web UI button opens the workspace; legacy pages still load`, async ({ page }) => {
     await addEditor(page, type);
     const popupPromise = page.waitForEvent('popup');
     await page.locator('.pm-focused').getByRole('button', { name: 'Web UI ↗', exact: true }).click();
     const popup = await popupPromise;
     await popup.waitForLoadState('domcontentloaded');
-    await expect(popup).toHaveURL(/\/prompt_manager\/(web|admin)/);
-    await expect(popup.locator('body')).toContainText('Prompt');
+    await expect(popup).toHaveURL(/\/prompt_manager\/workspace#\/library$/);
+    await expect(popup.locator('#workspace-main h1')).toHaveText('Prompt library');
     await expect(page.locator('.pm-focused').getByRole('status').filter({ hasText: 'Web UI opened.' })).toHaveText('Web UI opened.');
     await popup.goto(new URL('/prompt_manager/gallery', page.url()).href);
     await expect(popup.locator('#addPromptBtn')).toBeVisible();

tests/comfyui/prompt-manager.spec.mjs

@@ -84,7 +84,7 @@ test('all node schemas and extension entrypoints load from the real host', async
 });
 
 for (const type of ['PromptManager', 'PromptManagerText']) {
-    test(`${type} Web UI button opens actual standalone pages`, async ({ page }) => {
+    test(`${type} Web UI button opens the workspace; legacy pages still load`, async ({ page }) => {
         await page.evaluate(async type => {
             const { app } = await import('/scripts/app.js');
             const node = LiteGraph.createNode(type);
@@ -95,14 +95,74 @@ for (const type of ['PromptManager', 'PromptManagerText']) {
         await page.getByRole('button', { name: '🌐 Web UI', exact: true }).click();
         const popup = await popupPromise;
         await popup.waitForLoadState('domcontentloaded');
-        await expect(popup).toHaveURL(/\/prompt_manager\/(web|admin)/);
-        await expect(popup.locator('body')).toContainText('Prompt');
+        await expect(popup).toHaveURL(/\/prompt_manager\/workspace#\/library$/);
+        await expect(popup.locator('#workspace-main h1')).toHaveText('Prompt library');
         await popup.goto(new URL('/prompt_manager/gallery', page.url()).href);
         await expect(popup.locator('#addPromptBtn')).toBeVisible();
         await popup.close();
     });
 }
 
+test('top-bar PM button opens the workspace in either renderer', async ({ page }) => {
+    const button = page.locator('.promptmanager-top-button-group button, #pm-toolbar-btn').first();
+    await expect(button).toBeVisible();
+    const popupPromise = page.waitForEvent('popup');
+    await button.click();
+    const popup = await popupPromise;
+    await expect(popup).toHaveURL(/\/prompt_manager\/workspace#\/library$/);
+    await expect(popup.locator('#workspace-main h1')).toHaveText('Prompt library');
+    await popup.close();
+});
+
+for (const [type, buttonName] of [['PromptManager', '🌐 Web UI'], ['PromptManagerFocused', 'Web UI ↗'], ['PromptManagerPair', 'Web UI ↗']]) {
+    test(`${type} and the PM button open the workspace after switching renderers both ways, a workflow reload and node removal`, async ({ page }, testInfo) => {
+        const id = await page.evaluate(async type => {
+            const { app } = await import('/scripts/app.js');
+            const node = LiteGraph.createNode(type);
+            app.graph.add(node);
+            node.setSize([900, 800]);
+            app.canvas.centerOnNode(node);
+            return node.id;
+        }, type);
+        const webUi = page.getByRole('button', { name: buttonName, exact: true });
+        const pm = page.locator('.promptmanager-top-button-group button, #pm-toolbar-btn').first();
+        const opensWorkspace = async button => {
+            await expect(button).toHaveCount(1);
+            await expect(button).toBeVisible();
+            const popupPromise = page.waitForEvent('popup');
+            await button.click();
+            const popup = await popupPromise;
+            await expect(popup).toHaveURL(/\/prompt_manager\/workspace#\/library$/);
+            await expect(popup.locator('#workspace-main h1')).toHaveText('Prompt library');
+            await popup.close();
+        };
+        await opensWorkspace(webUi);
+        for (const renderer of [!testInfo.project.metadata.initialRenderer, testInfo.project.metadata.initialRenderer]) {
+            await page.evaluate(async renderer => {
+                const { app } = await import('/scripts/app.js');
+                await app.ui.settings.setSettingValue('Comfy.VueNodes.Enabled', renderer);
+                app.canvas.ds.scale = .8;
+                app.canvas.centerOnNode(app.graph._nodes[0]);
+            }, renderer);
+            await expect.poll(() => page.evaluate(() => LiteGraph.vueNodesMode)).toBe(renderer);
+            await opensWorkspace(webUi);
+            await opensWorkspace(pm);
+        }
+        await page.evaluate(async () => {
+            const { app } = await import('/scripts/app.js');
+            await app.loadGraphData(app.graph.serialize());
+        });
+        await opensWorkspace(webUi);
+        await opensWorkspace(pm);
+        await page.evaluate(async id => {
+            const { app } = await import('/scripts/app.js');
+            app.graph.remove(app.graph.getNodeById(id));
+        }, id);
+        await expect(webUi).toHaveCount(0);
+        await opensWorkspace(pm);
+    });
+}
+
 test('Classic controls follow actual ComfyUI light and dark palettes', async ({ page }, testInfo) => {
     await page.evaluate(async () => {
         const { app } = await import('/scripts/app.js');

tests/comfyui/workspace.spec.mjs

@@ -37,11 +37,11 @@ test('workspace serves real library data beside either ComfyUI renderer', async
             await expect(workspace.getByText('No matching images · 0 images', { exact: true })).toBeVisible();
             await expect(workspace.locator('.gallery-body > .empty')).toHaveText('No matching images. Try another search or category.');
         }
-        // D29: Images no longer links the legacy gallery; Overview's "Open existing image gallery" card does.
+        // D29: Images no longer links the legacy gallery; #525: nor does Overview. The page stays at its URL.
         await expect(workspace.locator('#workspace-main a[href="/prompt_manager/gallery"]')).toHaveCount(0);
         await workspace.evaluate(() => { location.hash = '/overview'; });
-        const gallery = workspace.locator('#workspace-main').getByRole('link', { name: 'Open existing image gallery', exact: true });
-        await expect(gallery).toHaveAttribute('href', '/prompt_manager/gallery');
+        const imagesCard = workspace.locator('#workspace-main').getByRole('link', { name: 'Open Images', exact: true });
+        await expect(imagesCard).toHaveAttribute('href', '#/images');
         expect((await workspace.request.get('/prompt_manager/gallery')).ok()).toBe(true);
         await workspace.evaluate(() => { location.hash = '/images'; });
         await workspace.reload();

tests/fake_trash.py

@@ -0,0 +1,52 @@
+"""A fake system trash for tests (#480): renames into a folder outside every root.
+
+``install(folder)`` replaces ``utils.trash.BACKEND`` and returns the fake;
+``uninstall`` puts the real one back. ``refuse[path] = code`` refuses one
+file with that code. The fake never copies or unlinks; it records each call.
+The disposable browser server installs it when ``PM_TEST_FAKE_TRASH=1``, so
+no test touches a real trash.
+"""
+
+import os
+
+from utils import trash
+
+
+class FakeTrash:
+    def __init__(self, folder):
+        self.folder = str(folder)
+        os.makedirs(self.folder, exist_ok=True)
+        self.refuse = {}
+        self.moved = []  # (source, destination)
+        self.calls = []
+
+    def available(self, path, roots):
+        self.calls.append(("available", str(path)))
+        return self.refuse.get(str(path))
+
+    def move(self, path, roots):
+        self.calls.append(("move", str(path)))
+        code = self.refuse.get(str(path))
+        if code:
+            raise trash.TrashRefused(code)
+        destination = os.path.join(
+            self.folder, f"{len(self.moved)}-{os.path.basename(path)}"
+        )
+        if os.path.lexists(destination):
+            raise trash.TrashRefused(trash.FAILED)
+        os.rename(path, destination)
+        self.moved.append((str(path), destination))
+        return "fake trash"
+
+
+_ORIGINAL = trash.BACKEND
+
+
+def install(folder):
+    fake = FakeTrash(folder)
+    trash.BACKEND = fake
+    return fake
+
+
+def uninstall():
+    trash.BACKEND = _ORIGINAL

tests/fixtures/legacy_contract_snapshot.json

@@ -118,9 +118,11 @@
     "POST /prompt_manager/image-annotations/observe",
     "POST /prompt_manager/image-annotations/suggest",
     "POST /prompt_manager/images/clear-thumbnails",
+    "POST /prompt_manager/images/delete/preview",
     "POST /prompt_manager/images/generate-thumbnails",
     "POST /prompt_manager/images/generate-thumbnails/progress",
     "POST /prompt_manager/images/link",
+    "POST /prompt_manager/images/removed/return",
     "POST /prompt_manager/images/rescope",
     "POST /prompt_manager/images/reveal",
     "POST /prompt_manager/jobs/autotag",
@@ -131,6 +133,9 @@
     "POST /prompt_manager/jobs/thumbnails",
     "POST /prompt_manager/jobs/{job_id}/cancel",
     "POST /prompt_manager/library",
+    "POST /prompt_manager/library/delete",
+    "POST /prompt_manager/library/delete/preview",
+    "POST /prompt_manager/library/restore",
     "POST /prompt_manager/library/{positive_id}/variants",
     "POST /prompt_manager/logs/config",
     "POST /prompt_manager/logs/truncate",

tests/js/workspace-entry.test.js

@@ -0,0 +1,34 @@
+// #525: where the canvas buttons open PromptManager (web/js/workspace-entry.js).
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const source = import('../../web/js/workspace-entry.js');
+const state = import('../../web/js/workspace/state.mjs');
+
+test('the canvas entry route is the workspace Library, a native route', async () => {
+    const { WORKSPACE_ENTRY_ROUTE } = await source;
+    const { resolveRoute } = await state;
+    assert.equal(WORKSPACE_ENTRY_ROUTE, '/prompt_manager/workspace#/library');
+    const [pathname, hash] = WORKSPACE_ENTRY_ROUTE.split('#');
+    assert.equal(pathname, '/prompt_manager/workspace');
+    assert.equal(resolveRoute(`#${hash}`).id, 'library');
+});
+
+test('/prompt_manager/web redirects to the same route, under any mount prefix', async () => {
+    const { WORKSPACE_ENTRY_ROUTE } = await source;
+    const html = fs.readFileSync(path.join(__dirname, '../../web/index.html'), 'utf8');
+    const [, pattern, flags, replacement] = html.match(/location\.replace\(\s*window\.location\.pathname\.replace\(\/(.+)\/([a-z]*), '([^']+)'\)/);
+    const redirect = pathname => pathname.replace(new RegExp(pattern, flags), replacement);
+    assert.equal(redirect('/prompt_manager/web'), WORKSPACE_ENTRY_ROUTE);
+    assert.equal(redirect('/prompt_manager/web/'), WORKSPACE_ENTRY_ROUTE);
+    assert.equal(redirect('/prompt_manager/index.html'), WORKSPACE_ENTRY_ROUTE);
+    assert.equal(redirect('/sub/prompt_manager/web'), `/sub${WORKSPACE_ENTRY_ROUTE}`);
+});
+
+test('no canvas entry point still names a legacy page', () => {
+    for (const file of ['web/comfy/prompt_manager.js', 'web/js/focused-node.js', 'web/js/classic-node.js']) {
+        const code = fs.readFileSync(path.join(__dirname, '../..', file), 'utf8');
+        assert.doesNotMatch(code, /\/prompt_manager\/(?:admin|gallery|web)\b/, file);
+    }
+});

tests/js/workspace-image-tagging-state.test.js

@@ -876,3 +876,63 @@ test('retry after a changed storage, file or expired capture observes again and
     await settle();
     assert.equal(c.state.manual, 'Minimal, warm_light');
 });
+
+test('#515: text typed while the first observation is pending is kept, after the saved tags', async () => {
+    const { createImageTaggingController } = await load();
+    const answers = [deferred(), deferred()];
+    let n = 0;
+    const h = harness(defaultRoutes({ [`POST ${OBSERVE}`]: () => answers[n++].promise }));
+    // An untagged file: the typed text is the whole draft and Save sends it.
+    const bare = createImageTaggingController({ api: h.api, target: TARGET, source: 'review' });
+    const first = bare.open();
+    bare.setManual('dunes');
+    answers[0].resolve(response(200, observed({ tags: [], tag_revision: 0 })));
+    await first;
+    await settle();
+    assert.equal(bare.state.phase, 'ready');
+    assert.equal(bare.state.manual, 'dunes');
+    assert.equal(bare.state.statusText, '', 'nothing changed elsewhere');
+    await bare.save();
+    await settle();
+    assert.deepEqual(h.of('PUT', TAGS).at(-1).body.tags, ['dunes']);
+    // A tagged file: its saved tags lead, so a Save never drops tags the user had not seen yet.
+    const tagged = createImageTaggingController({ api: h.api, target: TARGET });
+    const second = tagged.open();
+    tagged.setManual('dunes, minimal');
+    answers[1].resolve(response(200, observed()));
+    await second;
+    await settle();
+    assert.equal(tagged.state.manual, 'Minimal, warm_light, dunes');
+    assert.equal(tagged.state.statusText, '');
+});
+
+test('#515: a kept draft takes the text typed while the reopen observes', async () => {
+    const { c } = await opened({ [`PUT ${TAGS}`]: () => fail(409, 'file-changed', 'The file changed.') });
+    c.setManual('kept draft');
+    await c.save();
+    await settle();
+    const reopened = c.retry();
+    c.setManual('kept draft, later');
+    await reopened;
+    await settle();
+    assert.equal(c.state.phase, 'ready');
+    assert.equal(c.state.manual, 'kept draft, later');
+});
+
+test('#515: text typed before Retry after a failed first observation follows the saved tags', async () => {
+    const { createImageTaggingController } = await load();
+    let n = 0;
+    const h = harness(defaultRoutes({
+        [`POST ${OBSERVE}`]: () => (n++ === 0 ? fail(500, 'internal', 'boom') : response(200, observed())),
+    }));
+    const c = createImageTaggingController({ api: h.api, target: TARGET });
+    await c.open();
+    await settle();
+    assert.equal(c.state.phase, 'observe-error');
+    c.setManual('dunes');
+    await c.retry();
+    await settle();
+    assert.equal(c.state.phase, 'ready');
+    assert.equal(c.state.manual, 'Minimal, warm_light, dunes');
+    assert.equal(c.state.statusText, '');
+});

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

@@ -0,0 +1,151 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+// #480 (D159): Images › Delete…: the review's rows, sentences, labels and outcome toasts.
+const loaded = await import('../../web/js/workspace/images-delete.mjs').catch(() => null);
+const module = () => { assert.ok(loaded, 'images-delete.mjs is not implemented'); return loaded; };
+const pageScope = () => {
+    const controller = new AbortController();
+    return { signal: controller.signal, cleanup: () => {}, abort: () => controller.abort() };
+};
+const plan = (over = {}) => ({
+    token: 't', library: { count: 3 }, trash: { count: 2 },
+    refused: { count: 1, counts: { 'not-listed': 1 }, rows: [{ path: 'sub/gone.png', code: 'not-listed', detail: 'No longer listed in Images.' }] },
+    trash_refused: { count: 1, counts: { 'no-trash': 1 }, rows: [{ path: 'b.png', code: 'no-trash', detail: 'This drive has no trash.' }] },
+    records: { prompt_links: 2, pair_links: 0, image_tags: 1, auto_tagged: 0, categories: 1, collections: 2, favorites: 0, review_items: 0 },
+    orphaned_prompts: { count: 1, titles: ['Red fox'] },
+    backup: { policy: 'on' }, disk: null, ...over,
+});
+
+test('the words of the review and its routes', () => {
+    const { PREVIEW_URL, MAX_DELETE, TOO_MANY, QUESTION, MODES } = module();
+    assert.equal(PREVIEW_URL, '/prompt_manager/images/delete/preview');
+    assert.equal(MAX_DELETE, 500);
+    assert.equal(TOO_MANY, 'Select at most 500 images.');
+    assert.equal(QUESTION, 'What should happen to the files?');
+    assert.deepEqual(MODES.map(mode => mode.label), ['Remove from the library only', 'Also move the files to the trash']);
+});
+
+test('library rows: scope, refusals, links, details, backup and media', () => {
+    const { deleteRows } = module();
+    const rows = Object.fromEntries(deleteRows(plan(), 'library'));
+    assert.equal(rows.Scope, '3 images');
+    assert.equal(rows['Not changed'], '1: gone.png. No longer listed in Images.');
+    assert.equal(rows['Prompt links'], '2 links. 1 prompt loses its last image: Red fox. The prompt stays on the Library page.');
+    assert.equal(rows['Image details'], '1 with image tags, 1 category, 2 collection memberships');
+    assert.equal(rows.Backup, 'Create and verify before changes (the database, not the files)');
+    assert.equal(rows['Media on disk'], 'Files stay on disk, hidden from Images.');
+});
+
+test('trash rows add the trash refusals and the trash media line', () => {
+    const { deleteRows } = module();
+    const rows = Object.fromEntries(deleteRows(plan({ backup: { policy: 'off' } }), 'trash'));
+    assert.equal(rows.Scope, '2 images');
+    assert.match(rows['Not changed'], /^2: gone\.png, b\.png\. No longer listed in Images\. This drive has no trash\.$/);
+    assert.equal(rows.Backup, 'Off: no safety backup (System › Backup & export › Recovery policy)');
+    assert.match(rows['Media on disk'], /Nothing is deleted permanently/);
+});
+
+test('rows leave out what is zero', () => {
+    const { deleteRows } = module();
+    const bare = plan({ refused: { count: 0, rows: [] }, trash_refused: { count: 0, rows: [] },
+        records: { prompt_links: 0 }, orphaned_prompts: { count: 0, titles: [] } });
+    assert.deepEqual(deleteRows(bare, 'library').map(([term]) => term), ['Scope', 'Backup', 'Media on disk']);
+    const many = plan({ orphaned_prompts: { count: 5, titles: ['A', 'B', 'C'] } });
+    assert.match(Object.fromEntries(deleteRows(many, 'library'))['Prompt links'],
+        /5 prompts lose their last image: A, B, C and 2 more\. The prompts stay on the Library page\./);
+    assert.equal(module().refusedValue({ count: 5, rows: [{ path: 'a.png' }] }), '5: a.png and 4 more');
+    assert.equal(module().refusedValue({ count: 0 }), null);
+});
+
+test('sentences follow the mode and the backup policy', () => {
+    const { deleteSentences, SENTENCES, USE_LIBRARY_ONLY, NO_TRASH_HERE } = module();
+    assert.deepEqual(deleteSentences(plan(), 'library'), [SENTENCES.libraryBackup]);
+    assert.deepEqual(deleteSentences(plan({ backup: { policy: 'off' } }), 'library'), [SENTENCES.libraryNoBackup]);
+    assert.deepEqual(deleteSentences(plan(), 'trash'), [SENTENCES.trash, USE_LIBRARY_ONLY]);
+    const nowhere = plan({ trash: { count: 0 }, trash_refused: { count: 3, rows: [] } });
+    assert.deepEqual(deleteSentences(nowhere, 'trash'), [SENTENCES.trash, NO_TRASH_HERE, USE_LIBRARY_ONLY]);
+    // #500: no "yet" (Windows is unavailable by design); each file's reason says why.
+    assert.equal(NO_TRASH_HERE, 'Moving to the trash is not available for these files; each one lists why.');
+    assert.deepEqual(deleteSentences(plan({ trash_refused: { count: 0 } }), 'trash'), [SENTENCES.trash]);
+});
+
+test('primary labels and the close-only reasons', () => {
+    const { primaryLabel, closeOnlyReason, NONE_DELETABLE } = module();
+    assert.equal(primaryLabel('library', 1), 'Remove 1 image from the library');
+    assert.equal(primaryLabel('trash', 4), 'Move 4 images to the trash');
+    assert.equal(closeOnlyReason(plan()), null);
+    assert.equal(closeOnlyReason(plan({ library: { count: 0 }, trash: { count: 0 } })), NONE_DELETABLE);
+    assert.equal(closeOnlyReason(plan({ disk: { sufficient: false, required_bytes: 2048, free_bytes: 1024 } })),
+        'There is not enough free space for the safety backup (needs 2,048 bytes, has 1,024).');
+});
+
+test('outcome toasts per mode and failure', () => {
+    const { outcomeToast } = module();
+    assert.equal(outcomeToast({ scope: { mode: 'library' }, counters: { removed: 3, not_changed: 0 }, total: 3 }),
+        'Removed 3 images from the library.');
+    assert.equal(outcomeToast({ scope: { mode: 'trash' }, counters: { trashed: 2, not_changed: 1 }, total: 3 }),
+        'Moved 2 images to the trash. 1 was not changed (see Activity).');
+    assert.equal(outcomeToast({ scope: { mode: 'trash' }, counters: { trashed: 0, not_changed: 2 }, total: 2 }),
+        'Moved 0 images to the trash. 2 were not changed (see Activity).');
+    assert.equal(outcomeToast({ scope: { mode: 'library', failure: 'records-failed' }, counters: { removed: 1 }, total: 4 }),
+        'Stopped after 1 of 4 images; the rest were not changed. See Activity.');
+    assert.equal(outcomeToast({ scope: { failure: 'backup-failed' } }), 'The safety backup failed; nothing was changed.');
+    assert.equal(outcomeToast({ scope: { failure: 'sources-changed' } }), 'The sources changed; nothing was changed.');
+});
+
+test('review failures name the cause', () => {
+    const { reviewFailure, SOURCE_CHANGED, STORAGE_CHANGED, TOO_MANY, REVIEW_FAILED } = module();
+    assert.equal(reviewFailure({ code: 'source-changed' }), SOURCE_CHANGED);
+    assert.equal(reviewFailure({ code: 'storage-changed' }), STORAGE_CHANGED);
+    assert.equal(reviewFailure({ code: 'too-many-images' }), TOO_MANY);
+    assert.equal(reviewFailure({ code: 'busy', message: 'Scan running' }), 'Scan running');
+    assert.equal(reviewFailure(new Error('boom')), REVIEW_FAILED);
+});
+
+test('over 500 refuses with the toast before any request', async () => {
+    const { openDeleteImages, TOO_MANY } = module();
+    const toasts = [];
+    const api = { post: () => assert.fail('no request') };
+    await openDeleteImages({ api, scope: pageScope(), images: [], filter: {}, count: 501, notify: text => toasts.push(text) });
+    assert.deepEqual(toasts, [TOO_MANY]);
+    await openDeleteImages({ api, scope: pageScope(), images: [], notify: text => toasts.push(text) });
+    assert.deepEqual(toasts, [TOO_MANY]);
+});
+
+test('a failed review toasts and releases its trigger', async () => {
+    const { openDeleteImages, SOURCE_CHANGED } = module();
+    const toasts = [], sent = [];
+    const attributes = new Map();
+    const trigger = { textContent: 'Delete…', getAttribute: name => attributes.get(name) ?? null,
+        setAttribute: (name, value) => attributes.set(name, value), removeAttribute: name => attributes.delete(name) };
+    const api = { post: async (url, body) => { sent.push([url, body]); throw Object.assign(new Error('x'), { code: 'source-changed' }); } };
+    await openDeleteImages({ api, scope: pageScope(), trigger, notify: text => toasts.push(text),
+        images: [{ root_index: 0, root_scope: 'a'.repeat(64), path: 'a.png', filename: 'a.png' }] });
+    assert.deepEqual(sent, [['/prompt_manager/images/delete/preview', { items: [{ root_index: 0, root_scope: 'a'.repeat(64), path: 'a.png' }] }]]);
+    assert.deepEqual(toasts, [SOURCE_CHANGED]);
+    assert.equal(trigger.textContent, 'Delete…');
+    assert.equal(trigger.getAttribute('aria-disabled'), null);
+});
+
+test('apply sends the token and the mode, and toasts that the job started', async () => {
+    const { applyDelete } = module();
+    const sent = [], toasts = [];
+    const api = { post: async (url, body) => { sent.push([url, body]); return { job: { id: 'j', title: 'Delete images (move to the trash)' } }; } };
+    const store = { track: job => job, load: () => {} };
+    const job = await applyDelete({ api, store, plan: plan(), mode: 'trash', notify: text => toasts.push(text) });
+    assert.equal(job.id, 'j');
+    assert.deepEqual(sent, [['/prompt_manager/maintenance/apply', { token: 't', mode: 'trash' }]]);
+    assert.deepEqual(toasts, ['Delete images (move to the trash) started.']);
+    const refused = await applyDelete({ api: { post: async () => { throw Object.assign(new Error('Busy'), { code: 'busy', running: null }); } },
+        store, plan: plan(), mode: 'library', notify: text => toasts.push(text) });
+    assert.equal(refused, null);
+});
+
+test('apply refuses to send a delete without an explicit mode', async () => {
+    const { applyDelete } = module();
+    const api = { post: () => assert.fail('no request without a mode') };
+    for (const mode of [undefined, null, '', 'TRASH', 'delete']) {
+        await assert.rejects(applyDelete({ api, store: null, plan: plan(), mode, notify: () => {} }), TypeError);
+    }
+});

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

@@ -0,0 +1,91 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+// #498 (D162): Images › Show removed images › Return to library: the words, the request and the toasts.
+const loaded = await import('../../web/js/workspace/images-return.mjs').catch(() => null);
+const module = () => { assert.ok(loaded, 'images-return.mjs is not implemented'); return loaded; };
+const pageScope = () => {
+    const controller = new AbortController();
+    return { signal: controller.signal, cleanup: () => {}, abort: () => controller.abort() };
+};
+const image = (path, root_index = 0) => ({ path, root_index, root_scope: 's0', filename: path });
+
+test('the toggle, the caption and the empty view', () => {
+    const { toggleLabel, removedCaption, removedEmpty, RETURN_LABEL } = module();
+    assert.equal(toggleLabel(null), 'Show removed images');
+    assert.equal(toggleLabel(1234), 'Show removed images (1,234)');
+    assert.equal(removedCaption(1), '1 removed image · files on disk, hidden from Images');
+    assert.equal(removedCaption(3), '3 removed images · files on disk, hidden from Images');
+    assert.equal(removedEmpty(false), 'No removed images.');
+    assert.equal(removedEmpty(true), 'No removed images match.');
+    assert.equal(RETURN_LABEL, 'Return to library');
+});
+
+test('the finished toast says what came back and what did not', () => {
+    const { finishedToast, startToast } = module();
+    assert.equal(startToast(2), 'Returning 2 images to the library…');
+    assert.equal(finishedToast({ state: 'finished', counters: { added: 1 } }, 2),
+        'Returned 2 images to the library; 1 image linked to its prompt. Tags, categories, collections and favorites do not come back.');
+    assert.equal(finishedToast({ state: 'finished', counters: { added: 3 } }, 3),
+        'Returned 3 images to the library; 3 images linked to their prompts. Tags, categories, collections and favorites do not come back.');
+    assert.equal(finishedToast({ state: 'finished', counters: {} }, 1),
+        'Returned 1 image to the library. Tags, categories, collections and favorites do not come back.');
+    assert.match(finishedToast({ state: 'failed', status_line: 'Disk error' }, 1), /^Returning images stopped: Disk error\.$/);
+    assert.match(finishedToast({ state: 'cancelled' }, 1), /cancelled/);
+});
+
+test('refusals name the cause', () => {
+    const { returnFailure, NONE_REMOVED, TOO_MANY, SOURCE_CHANGED, RETURN_FAILED } = module();
+    assert.equal(returnFailure({ code: 'no-images' }), NONE_REMOVED);
+    assert.equal(returnFailure({ code: 'too-many-images' }), TOO_MANY);
+    assert.equal(returnFailure({ code: 'source-changed' }), SOURCE_CHANGED);
+    assert.equal(returnFailure({ code: 'busy', message: 'Scan for metadata is running.' }), 'Scan for metadata is running.');
+    assert.equal(returnFailure(new Error('x')), RETURN_FAILED);
+});
+
+test('over 500 refuses with the toast before any request', async () => {
+    const { returnImages, TOO_MANY } = module();
+    const toasts = [], posts = [];
+    const api = { post: async (...args) => { posts.push(args); return {}; } };
+    await returnImages({ api, scope: pageScope(), filter: { q: '' }, count: 501, notify: text => toasts.push(text) });
+    assert.deepEqual(toasts, [TOO_MANY]);
+    assert.deepEqual(posts, []);
+});
+
+test('items post their identities; a filter posts the removed view; the job is tracked and followed', async () => {
+    const { returnImages, RETURN_URL } = module();
+    const toasts = [], posts = [], ended = [];
+    let listener = null;
+    const job = { id: 'j1', title: 'Return images to the library', state: 'running', counters: {} };
+    const store = {
+        track: started => started,
+        find: () => job,
+        subscribe: fn => { listener = fn; return () => { listener = null; }; },
+    };
+    const api = { post: async (url, body) => { posts.push([url, body]); return { job, returned: 2, not_removed: 0 }; } };
+    const started = await returnImages({ api, scope: pageScope(), store, images: [image('a.png'), image('b.png', 1)],
+        notify: text => toasts.push(text), onReturned: done => ended.push(done) });
+    assert.equal(started, job);
+    assert.deepEqual(posts[0], [RETURN_URL, { items: [
+        { root_index: 0, root_scope: 's0', path: 'a.png' }, { root_index: 1, root_scope: 's0', path: 'b.png' }] }]);
+    assert.deepEqual(toasts, ['Returning 2 images to the library…']);
+    job.state = 'finished'; job.counters = { added: 2 };
+    listener();
+    assert.deepEqual(ended, [job]);
+    assert.match(toasts[1], /^Returned 2 images to the library; 2 images linked/);
+    await returnImages({ api, scope: pageScope(), filter: { q: 'x' }, count: 2, notify: () => {} });
+    assert.deepEqual(posts[1][1], { filter: { q: 'x', removed: '1' } });
+});
+
+test('a refused return toasts, releases the trigger and changes nothing', async () => {
+    const { returnImages, NONE_REMOVED } = module();
+    const toasts = [];
+    const attributes = new Map();
+    const trigger = { getAttribute: name => attributes.get(name) ?? null, setAttribute: (name, value) => attributes.set(name, value),
+        removeAttribute: name => attributes.delete(name) };
+    const api = { post: async () => { throw Object.assign(new Error('no'), { code: 'no-images' }); } };
+    const result = await returnImages({ api, scope: pageScope(), images: [image('a.png')], trigger, notify: text => toasts.push(text) });
+    assert.equal(result, null);
+    assert.deepEqual(toasts, [NONE_REMOVED]);
+    assert.equal(trigger.getAttribute('aria-disabled'), null);
+});

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

@@ -0,0 +1,327 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+// #443 D152: the Prompt library's Delete… review (delete unpaired, archive paired, keep protected) and Restore.
+const source = import('../../web/js/workspace/library-delete.mjs');
+
+const preview = (patch = {}) => ({success: true, library_epoch: 'e', delete: [], archive: [], protected: [],
+    already_archived: 0, not_found: 0, image_links: 0, backup: 'on', disk: null, ...patch});
+
+test('the routes are the workspace ones, never the legacy bulk delete', async () => {
+    const {PREVIEW_URL, DELETE_URL, RESTORE_URL} = await source;
+    assert.equal(PREVIEW_URL, '/prompt_manager/library/delete/preview');
+    assert.equal(DELETE_URL, '/prompt_manager/library/delete');
+    assert.equal(RESTORE_URL, '/prompt_manager/library/restore');
+});
+
+test('the title, primary and body follow what the review will do', async () => {
+    const {reviewOf, reviewTitle, primaryLabel, deleteBody} = await source;
+    const both = reviewOf(preview({delete: [1, 2], archive: [3]}));
+    assert.equal(reviewTitle(both), 'Delete or archive selected prompts');
+    assert.equal(primaryLabel(both), 'Delete 2 and archive 1 prompt');
+    assert.deepEqual(deleteBody(both), {archive_ids: [3], delete_ids: [1, 2], expected_epoch: 'e', backup: 'on'});
+    const onlyDelete = reviewOf(preview({delete: [1]}));
+    assert.equal(reviewTitle(onlyDelete), 'Delete selected prompts');
+    assert.equal(primaryLabel(onlyDelete), 'Delete 1 prompt');
+    const onlyArchive = reviewOf(preview({archive: [4, 5]}));
+    assert.equal(reviewTitle(onlyArchive), 'Archive selected prompts');
+    assert.equal(primaryLabel(onlyArchive), 'Archive 2 prompts');
+});
+
+test('the grid shows each row only when it applies, with protected titles in selection order', async () => {
+    const {reviewOf, reviewGrid} = await source;
+    const names = {7: 'Seven', 8: 'Eight', 9: 'Nine', 10: 'Ten'};
+    const review = reviewOf(preview({delete: [1], archive: [2], protected: [7, 8, 9, 10], already_archived: 1,
+        not_found: 2, image_links: 3}));
+    assert.deepEqual(reviewGrid(review, id => names[id]), [
+        ['Delete permanently', '1 prompt not in a saved pair'],
+        ['Archive', '1 prompt in a saved pair: hidden, restorable'],
+        ['Protected (kept)', '4: Seven, Eight, Nine and 1 more'],
+        ['Already archived', '1'],
+        ['No longer exist', '2'],
+        ['Image links removed', '3 images will no longer show these prompts (files stay on disk)'],
+        ['Backup', 'Create and verify before deleting'],
+    ]);
+    // #512: a row with nothing in it is left out.
+    const archiveOnly = reviewOf(preview({archive: [2]}));
+    assert.deepEqual(reviewGrid(archiveOnly).map(([term]) => term), ['Archive']);
+    const deleteOnly = reviewOf(preview({delete: [1]}));
+    assert.deepEqual(reviewGrid(deleteOnly).map(([term]) => term), ['Delete permanently', 'Image links removed', 'Backup']);
+    const keptOnly = reviewOf(preview({protected: [7]}));
+    assert.deepEqual(reviewGrid(keptOnly, id => names[id]), [['Protected (kept)', '1: Seven']]);
+    const off = reviewOf(preview({delete: [1], backup: 'off'}));
+    assert.equal(reviewGrid(off).at(-1)[1], 'Off: no safety backup (System › Backup & export › Recovery policy)');
+});
+
+test('the Archive row names the saved pair, never negative variants, for one or many prompts', async () => {
+    const {reviewOf, reviewGrid} = await source;
+    // A saved-pair prompt with 0 negative variants (live prompt 7901) is archive-only for its pair, not for variants.
+    const one = reviewGrid(reviewOf(preview({archive: [2]}))).find(([term]) => term === 'Archive');
+    assert.deepEqual(one, ['Archive', '1 prompt in a saved pair: hidden, restorable']);
+    const many = reviewGrid(reviewOf(preview({archive: [2, 3, 4]}))).find(([term]) => term === 'Archive');
+    assert.deepEqual(many, ['Archive', '3 prompts in a saved pair: hidden, restorable']);
+    for (const [, value] of [one, many]) assert.doesNotMatch(value, /variant/);
+});
+
+test('the sentences explain archive, irreversibility per backup policy, re-creation and protection', async () => {
+    const {reviewOf, reviewSentences} = await source;
+    const [archive, remove, guarded] = reviewSentences(reviewOf(preview({delete: [1], archive: [2], protected: [3]})));
+    // Live test (#470): the archive reason is the saved pair, which a prompt with 0 negative variants has too.
+    assert.match(archive, /^Prompts in a saved pair, as its positive or its negative, are archived instead of deleted, so the pair and its runs stay intact\./);
+    assert.doesNotMatch(archive, /variant/);
+    // #492: the archived shelf deletes them too.
+    assert.match(archive, /stay intact\. To delete them later or bring them back, press Show archived prompts, select them and press Delete… or Restore\.$/);
+    assert.match(remove, /the only way back is to restore the safety backup taken first \(System › Backup & export\), which returns the whole library to that moment\. It is kept among the last 10 safety backups\./);
+    assert.match(remove, /A later scan, a new image or a node run with the same text adds it again as a new prompt\.$/);
+    assert.equal(guarded, 'Protected prompts are tagged __protected__; remove the tag to delete them.');
+    const [off] = reviewSentences(reviewOf(preview({delete: [1], backup: 'off'})));
+    assert.match(off, /Deleted prompts cannot be brought back\. Image files/);
+    assert.doesNotMatch(off, /safety backup/);
+});
+
+test('a review that cannot start says why: nothing to change, or no room for the backup', async () => {
+    const {reviewOf, blockedReason, COPY} = await source;
+    assert.equal(blockedReason(reviewOf(preview({protected: [1]}))), COPY.none);
+    assert.equal(blockedReason(reviewOf(preview({delete: [1], disk: {sufficient: false, message: 'Not enough. Nothing was changed.'}}))),
+        'Not enough. Nothing was changed.');
+    assert.match(blockedReason(reviewOf(preview({delete: [1], disk: {sufficient: false}}))), /not enough free space/);
+    assert.equal(blockedReason(reviewOf(preview({delete: [1], disk: {sufficient: true}}))), null);
+    assert.equal(blockedReason(reviewOf(preview({archive: [1]}))), null);
+});
+
+test('a delete outcome counts each part, singular and plural, and names the backup', async () => {
+    const {reviewOf, deleteOutcome} = await source;
+    const review = reviewOf(preview({delete: [1, 2], archive: [3], protected: [9]}));
+    assert.deepEqual(deleteOutcome({success: true, deleted: 2, archived: 3, already_archived: 0, not_found: 0, changed: 0,
+        backup: 'prompts.db.backup_x'}, null, review), {committed: true, reload: true,
+        toast: 'Deleted 2 prompts. Archived 3 prompts. 1 protected prompt was kept. Safety backup saved: prompts.db.backup_x (System › Backup & export).'});
+    assert.equal(deleteOutcome({success: true, deleted: 1, archived: 0, already_archived: 1, not_found: 1, changed: 1,
+        backup: null}, null, reviewOf(preview())).toast,
+    'Deleted 1 prompt. 1 was already archived. 1 no longer exists. 1 changed since the review and was not deleted.');
+    assert.equal(deleteOutcome({success: true, deleted: 0, archived: 0, already_archived: 2, not_found: 3, changed: 2,
+        backup: null}, null, reviewOf(preview({protected: [1, 2]}))).toast,
+    'Nothing was deleted or archived. 2 were already archived. 3 no longer exist. 2 changed since the review and were not deleted. 2 protected prompts were kept. The Library was reloaded.');
+    assert.equal(deleteOutcome({success: true, deleted: 0, archived: 0}, null, reviewOf(preview())).committed, false);
+});
+
+test('a failed delete says nothing changed, or that it may have, and keeps or reloads the selection', async () => {
+    const {deleteOutcome, COPY} = await source;
+    assert.deepEqual(deleteOutcome(null, {status: 409, code: 'storage-changed'}), {toast: COPY.storage, committed: false, reload: true});
+    assert.equal(COPY.storage, 'The library was restored or moved since this page loaded. Nothing was deleted or archived.');
+    assert.deepEqual(deleteOutcome(null, {status: 409, code: 'busy', running: {title: 'Scan'}}),
+        {toast: 'Scan is running. Nothing was changed; try again when it finishes.', committed: false, reload: false});
+    assert.deepEqual(deleteOutcome(null, {status: 500, code: 'backup-failed', message: 'The safety backup could not be taken and verified; nothing was changed.'}),
+        {toast: 'The safety backup failed. The safety backup could not be taken and verified; nothing was changed.', committed: false, reload: false});
+    assert.deepEqual(deleteOutcome(null, {status: 507, code: 'insufficient-space', message: 'Not enough free disk space. Nothing was changed.'}),
+        {toast: 'Not enough free disk space. Nothing was changed.', committed: false, reload: false});
+    for (const failure of [new TypeError('Failed to fetch'), {status: 502}, {status: 503}, {status: 504}]) {
+        assert.deepEqual(deleteOutcome(null, failure), {toast: COPY.unconfirmed, committed: true, reload: true});
+    }
+    assert.deepEqual(deleteOutcome(null, {status: 400}), {toast: COPY.failed, committed: false, reload: false});
+});
+
+test('a failed preview reloads only after a restore; Restore outcomes have their own words', async () => {
+    const {previewOutcome, restoreOutcome, COPY} = await source;
+    assert.deepEqual(previewOutcome({status: 409, code: 'storage-changed'}), {toast: COPY.storage, committed: false, reload: true});
+    assert.deepEqual(previewOutcome({status: 500}), {toast: COPY.reviewFailed, committed: false, reload: false});
+    assert.equal(previewOutcome({status: 409, code: 'busy', running: {title: 'Optimize'}}).toast,
+        'Optimize is running. Nothing was changed; try again when it finishes.');
+    assert.deepEqual(restoreOutcome({success: true, restored: 2, unchanged: 1, not_found: 1}, null),
+        {toast: 'Restored 2 prompts to the Prompt library. 1 was not archived. 1 no longer exists.', committed: true, reload: true});
+    assert.deepEqual(restoreOutcome({success: true, restored: 0, unchanged: 2, not_found: 0}, null),
+        {toast: 'No prompt was restored. 2 were not archived.', committed: false, reload: true});
+    assert.deepEqual(restoreOutcome(null, {status: 409, code: 'storage-changed'}), {toast: COPY.restoreStorage, committed: false, reload: true});
+    assert.deepEqual(restoreOutcome(null, {status: 503}), {toast: COPY.restoreUnconfirmed, committed: true, reload: true});
+    assert.deepEqual(restoreOutcome(null, {status: 400}), {toast: COPY.restoreFailed, committed: false, reload: false});
+});
+
+test('reviewOf keeps only well-formed ids and counts from an answer', async () => {
+    const {reviewOf} = await source;
+    const review = reviewOf({library_epoch: 3, delete: [1, 'x', -2, 2], archive: null, protected: [1.5], already_archived: -1,
+        not_found: 'x', image_links: 2, backup: 'maybe', not_archived: -3});
+    assert.deepEqual(review, {shelf: 'active', notArchived: 0, epoch: null, delete: [1, 2], archive: [], protected: [], alreadyArchived: 0, notFound: 0,
+        imageLinks: 2, backup: 'on', disk: null, deletable: [], digests: {},
+        pairedCounts: {pairs: 0, archivedPairs: 0, variants: 0, keptNegatives: 0}, pairedImageLinks: 0, choice: 'archive', archiveOnly: []});
+});
+
+test('the archived notice says why (the saved pair) and names negative variants only when there are any', async () => {
+    const {archivedNoticeText} = await source;
+    assert.equal(archivedNoticeText(0), 'This prompt is archived because it is in a saved pair. It is hidden from the Prompt ' +
+        'library; nothing was removed.');
+    assert.equal(archivedNoticeText(1), 'This prompt is archived because it is in a saved pair. It and its 1 negative variant ' +
+        'are hidden from the Prompt library; nothing was removed.');
+    assert.equal(archivedNoticeText(3), 'This prompt is archived because it is in a saved pair. It and its 3 negative variants ' +
+        'are hidden from the Prompt library; nothing was removed.');
+    // An unknown count (an older server) never claims variants.
+    assert.equal(archivedNoticeText(undefined), archivedNoticeText(0));
+});
+
+// #482 (D160): prompts in a saved pair can be deleted permanently, with their own saved pairs.
+const D1 = 'a'.repeat(64), D2 = 'b'.repeat(64);
+const paired = (patch = {}) => preview({archive: [3, 4, 5], deletable: [3, 4], review_digests: {3: D1, 4: D2},
+    paired_counts: {pairs: 3, archived_pairs: 1, variants: 2, kept_negatives: 2}, paired_image_links: 4, ...patch});
+
+test('reviewOf reads the deletable ids, their digests and the pair counts; the choice starts at Archive', async () => {
+    const {reviewOf, hasPairedChoice} = await source;
+    const review = reviewOf(paired({deletable: [3, 4, 99], review_digests: {3: D1, 4: 'short', 99: D1}}));
+    // Only reviewed archive ids with a well-formed digest can be deleted permanently.
+    assert.deepEqual(review.deletable, [3]);
+    assert.deepEqual(review.digests, {3: D1});
+    assert.deepEqual(review.pairedCounts, {pairs: 3, archivedPairs: 1, variants: 2, keptNegatives: 2});
+    assert.equal(review.pairedImageLinks, 4);
+    assert.equal(review.choice, 'archive');
+    assert.equal(hasPairedChoice(review), true);
+    assert.equal(hasPairedChoice(reviewOf(preview({archive: [5]}))), false);
+});
+
+test('Archive chosen keeps the #443 review; Delete permanently names the pairs, the kept negatives and archive-only', async () => {
+    const {reviewOf, withChoice, reviewGrid, reviewTitle, primaryLabel, deleteBody} = await source;
+    const review = reviewOf(paired({delete: [1], image_links: 2}));
+    assert.deepEqual(reviewGrid(review).map(([term]) => term), ['Delete permanently', 'Archive', 'Image links removed', 'Backup']);
+    assert.equal(primaryLabel(review), 'Delete 1 and archive 3 prompts');
+    assert.deepEqual(deleteBody(review), {archive_ids: [3, 4, 5], delete_ids: [1], expected_epoch: 'e', backup: 'on'});
+    const permanent = withChoice(review, 'delete');
+    assert.notEqual(permanent, review);
+    assert.equal(review.choice, 'archive');
+    assert.deepEqual(reviewGrid(permanent), [
+        ['Delete permanently', '3 prompts: 1 not in a saved pair, 2 in a saved pair'],
+        ['Saved pairs removed', '3 saved pairs (2 with a negative prompt, 1 archived)'],
+        ['Negatives kept', '2 negative prompts are kept'],
+        ['Archive', '1 prompt used as another prompt\'s negative: hidden, restorable'],
+        ['Image links removed', '6 images will no longer show these prompts (files stay on disk)'],
+        ['Backup', 'Create and verify before deleting'],
+    ]);
+    assert.equal(reviewTitle(permanent), 'Delete or archive selected prompts');
+    assert.equal(primaryLabel(permanent), 'Delete 3 and archive 1 prompt');
+    assert.deepEqual(deleteBody(permanent), {archive_ids: [3, 4, 5], delete_ids: [1], expected_epoch: 'e', backup: 'on',
+        delete_paired_ids: [3, 4], paired_digests: {3: D1, 4: D2}});
+});
+
+test('edge counts: one prompt, no negative, nothing archive-only', async () => {
+    const {reviewOf, withChoice, reviewGrid, reviewTitle, primaryLabel} = await source;
+    // Live prompt 7896: one pair with an explicitly empty negative.
+    const one = withChoice(reviewOf(preview({archive: [7], deletable: [7], review_digests: {7: D1},
+        paired_counts: {pairs: 1, archived_pairs: 0, variants: 0, kept_negatives: 0}, paired_image_links: 0})), 'delete');
+    assert.deepEqual(reviewGrid(one), [
+        ['Delete permanently', '1 prompt in a saved pair'],
+        ['Saved pairs removed', '1 saved pair'],
+        ['Image links removed', '0 images will no longer show these prompts (files stay on disk)'],
+        ['Backup', 'Create and verify before deleting'],
+    ]);
+    assert.equal(reviewTitle(one), 'Delete selected prompts');
+    assert.equal(primaryLabel(one), 'Delete 1 prompt');
+});
+
+test('Delete permanently sentences: what goes with the pairs, what stays, and how it comes back', async () => {
+    const {reviewOf, withChoice, reviewSentences} = await source;
+    const [pairs, remove, archive] = reviewSentences(withChoice(reviewOf(paired()), 'delete'));
+    assert.equal(pairs, 'Deleting a prompt in a saved pair also removes its saved pairs, with their titles, categories, ' +
+        'ratings, notes, tags, run counts and image links. Their negative prompts are kept. Recorded runs stay in History ' +
+        'and Activity, listed by their text.');
+    assert.match(remove, /the only way back is to restore the safety backup/);
+    assert.match(remove, /A pair node run with the same text saves a new pair\.$/);
+    assert.equal(archive, 'Prompts used as another prompt\'s negative are archived instead of deleted, so that ' +
+        'prompt\'s variant stays.');
+    const [, off] = reviewSentences(withChoice(reviewOf(paired({backup: 'off'})), 'delete'));
+    assert.match(off, /Deleted prompts cannot be brought back\./);
+});
+
+test('a short disk blocks only the permanent delete; the outcome names removed pairs', async () => {
+    const {reviewOf, withChoice, blockedReason, deleteOutcome} = await source;
+    const short = reviewOf(paired({disk: {sufficient: false, message: 'Not enough space. Nothing was changed.'}}));
+    assert.equal(blockedReason(short), null);
+    assert.equal(blockedReason(withChoice(short, 'delete')), 'Not enough space. Nothing was changed.');
+    const {toast} = deleteOutcome({success: true, deleted: 2, archived: 1, pairs_removed: 3, changed: 1}, null, short);
+    assert.equal(toast, 'Deleted 2 prompts. Removed 3 saved pairs. Archived 1 prompt. 1 changed since the review and ' +
+        'was not deleted.');
+});
+
+// #492: Delete… on the archived shelf: no choice, only the permanent delete; what cannot be deleted stays archived.
+const shelfPreview = (patch = {}) => preview({deletable: [], review_digests: {}, paired_counts: {pairs: 0, archived_pairs: 0,
+    variants: 0, kept_negatives: 0}, paired_image_links: 0, not_archived: 0, ...patch});
+
+test('the archived shelf review is the permanent delete, without the choice', async () => {
+    const {reviewOf, hasPairedChoice, withChoice, reviewTitle, primaryLabel, reviewGrid, deleteBody, blockedReason} = await source;
+    const review = reviewOf(shelfPreview({delete: [1], archive: [2, 3], deletable: [2], review_digests: {2: D1},
+        paired_counts: {pairs: 2, archived_pairs: 1, variants: 1, kept_negatives: 1}, paired_image_links: 1, image_links: 1,
+        not_archived: 1}), 'archived');
+    assert.equal(review.shelf, 'archived');
+    assert.equal(review.choice, 'delete');
+    assert.equal(hasPairedChoice(review), false);
+    assert.equal(withChoice(review, 'archive').choice, 'delete');
+    assert.equal(reviewTitle(review), 'Delete archived prompts');
+    assert.equal(primaryLabel(review), 'Delete 2 prompts');
+    assert.equal(blockedReason(review), null);
+    assert.deepEqual(reviewGrid(review), [
+        ['Delete permanently', '2 prompts: 1 not in a saved pair, 1 in a saved pair'],
+        ['Saved pairs removed', '2 saved pairs (1 with a negative prompt, 1 archived)'],
+        ['Negatives kept', '1 negative prompt is kept'],
+        ['Stays archived', "1 prompt used as another prompt's negative"],
+        ['No longer archived (kept)', '1'],
+        ['Image links removed', '2 images will no longer show these prompts (files stay on disk)'],
+        ['Backup', 'Create and verify before deleting'],
+    ]);
+    // Only what it deletes is sent: the stays-archived id is left out.
+    assert.deepEqual(deleteBody(review), {archive_ids: [2], delete_ids: [1], expected_epoch: 'e', backup: 'on',
+        delete_paired_ids: [2], paired_digests: {2: D1}, shelf: 'archived'});
+});
+
+test('the archived shelf: unpaired only, nothing deletable, and its sentences', async () => {
+    const {reviewOf, reviewGrid, reviewSentences, primaryLabel, blockedReason, COPY} = await source;
+    const loose = reviewOf(shelfPreview({delete: [1]}), 'archived');
+    assert.deepEqual(reviewGrid(loose).map(([term]) => term), ['Delete permanently', 'Image links removed', 'Backup']);
+    assert.equal(reviewGrid(loose)[0][1], '1 prompt not in a saved pair');
+    assert.equal(primaryLabel(loose), 'Delete 1 prompt');
+    const [remove] = reviewSentences(loose);
+    assert.match(remove, /^Deleting removes each prompt's text/);
+    assert.doesNotMatch(reviewSentences(loose).join(' '), /saved pair/);
+    const stays = reviewOf(shelfPreview({archive: [3], protected: [4]}), 'archived');
+    assert.equal(blockedReason(stays), COPY.noneArchived);
+    assert.equal(COPY.noneArchived, 'None of the selected prompts can be deleted.');
+    const paired = reviewOf(shelfPreview({archive: [2, 3], deletable: [2], review_digests: {2: D1},
+        paired_counts: {pairs: 1, archived_pairs: 0, variants: 0, kept_negatives: 0}}), 'archived');
+    const sentences = reviewSentences(paired);
+    assert.match(sentences[0], /^Deleting a prompt in a saved pair also removes its saved pairs/);
+    assert.equal(sentences.at(-1), "Prompts used as another prompt's negative stay archived, so that prompt's variant stays.");
+    // The active shelf is unchanged: a preview without a shelf is #482's.
+    assert.equal(reviewOf(shelfPreview({archive: [2], deletable: [2], review_digests: {2: D1}})).choice, 'archive');
+});
+
+test('the outcome names prompts restored since the review', async () => {
+    const {deleteOutcome} = await source;
+    const outcome = deleteOutcome({success: true, deleted: 1, archived: 0, not_archived: 2, changed: 0}, null, {protected: []});
+    assert.equal(outcome.toast, 'Deleted 1 prompt. 2 were restored since the review and kept.');
+    const none = deleteOutcome({success: true, deleted: 0, archived: 0, not_archived: 1, changed: 1}, null,
+        {protected: [], shelf: 'archived'});
+    assert.equal(none.toast, 'Nothing was deleted. 1 was restored since the review and kept. 1 changed since the review and ' +
+        'was not deleted. The Library was reloaded.');
+});
+
+// #512 (live test of #505/#507/#509): the review names a single prompt, and a negative selected without its positive.
+test('a review from a prompt\'s own page names that prompt', async () => {
+    const {reviewOf, reviewTitle, blockedReason} = await source;
+    const single = review => ({...review, single: true});
+    assert.equal(reviewTitle(single(reviewOf(preview({delete: [1]})))), 'Delete this prompt');
+    assert.equal(reviewTitle(single(reviewOf(preview({archive: [2]})))), 'Archive this prompt');
+    const kept = single(reviewOf(preview({protected: [3]})));
+    assert.equal(reviewTitle(kept), 'Delete this prompt');
+    assert.equal(blockedReason(kept), 'This prompt cannot be deleted or archived.');
+    assert.equal(reviewTitle(single(reviewOf(preview({archive: [2], deletable: [2], review_digests: {2: 'c'.repeat(64)}}),
+        'archived'))), 'Delete this prompt');
+});
+
+test('a negative used by another prompt is named as such when it is archived', async () => {
+    const {reviewOf, reviewGrid, reviewSentences} = await source;
+    const negative = reviewOf(preview({archive: [5], deletable: []}));
+    assert.deepEqual(reviewGrid(negative), [['Archive', "1 prompt used as another prompt's negative: hidden, restorable"]]);
+    assert.deepEqual(reviewSentences(negative), ["Prompts used as another prompt's negative are archived instead of deleted, so " +
+        "that prompt's variant stays. To bring them back, press Show archived prompts, select them and press Restore."]);
+    const mixed = reviewOf(preview({archive: [2, 5], deletable: [2], review_digests: {2: 'c'.repeat(64)}}));
+    assert.deepEqual(reviewGrid(mixed)[0], ['Archive', "2 prompts in a saved pair (1 used as another prompt's negative): hidden, restorable"]);
+    // A paired prompt whose review digest is missing is not called another prompt's negative (review M1).
+    const noDigest = reviewOf(preview({archive: [2], deletable: [2], review_digests: {}}));
+    assert.deepEqual(reviewGrid(noDigest), [['Archive', '1 prompt in a saved pair: hidden, restorable']]);
+    const sentences = reviewSentences(mixed);
+    assert.match(sentences[0], /^Prompts in a saved pair, as its positive or its negative, are archived instead of deleted/);
+    assert.match(sentences[1], /^Prompts used as another prompt's negative are archived instead of deleted, so that prompt's variant stays\.$/);
+});

tests/js/workspace-state.test.js

@@ -17,7 +17,7 @@ test('tags is a native route titled Tags; only unbuilt routes hand off to legacy
     const tags = resolveRoute('#/tags');
     assert.equal(tags.label, 'Tags & categories');
     assert.equal(routeTitle(tags), 'Tags');
-    assert.equal(tags.href, '/prompt_manager/admin#/tags', 'Overview keeps the existing tag manager card');
+    assert.equal(tags.href, '#/tags', 'Overview opens the native page (#525)');
     for (const id of ['images', 'library', 'inspect', 'overview', 'system']) {
         const route = resolveRoute(`#/${id}`);
         assert.equal(routeTitle(route), route.label);
@@ -48,7 +48,6 @@ test('system resolves its sections; #/overview stays the production hub', async
     // Q12: Overview's System card opens the native System Overview, with no legacy href or action.
     const card = routes.find(route => route.id === 'system');
     assert.equal(card.href, '#/system/overview');
-    assert.equal(card.native, true);
     assert.equal(card.action, 'Open System');
 });
 
@@ -77,9 +76,28 @@ test('inspect is the native Inspect a file page with the concept description', a
     // The concept's heading description (app.js renderMetadata 743).
     assert.equal(inspect.description, 'A standalone file uses the same image viewer and prompt actions.');
     assert.equal(isHandoff(inspect), false);
-    // Overview keeps its card for the legacy metadata page, which stays working.
-    assert.equal(inspect.href, '/prompt_manager/gallery.html');
-    assert.equal(inspect.action, 'Open existing metadata inspector');
+    // Overview's card opens the native page (#525); the legacy metadata page stays at its URL.
+    assert.equal(inspect.href, '#/inspect');
+    assert.equal(inspect.action, 'Open Inspect a file');
+});
+
+test('every Overview card opens its own native page, never a legacy one (#525)', async () => {
+    const { resolveRoute, routes } = await source;
+    const cards = routes.filter(route => route.href);
+    assert.deepEqual(cards.map(card => card.id), ['images', 'library', 'tags', 'inspect', 'system']);
+    for (const card of cards) {
+        assert.match(card.href, /^#\//, card.id);
+        assert.equal(resolveRoute(card.href).id, card.id);
+        assert.match(card.action, /^Open /, card.id);
+        assert.doesNotMatch(card.action, /existing/, card.id);
+    }
+});
+
+test('the legacy pages System links are the four that stay at their URLs (#525 D165)', async () => {
+    const { LEGACY_PAGES } = await source;
+    assert.deepEqual(LEGACY_PAGES.map(page => page.href), ['/prompt_manager/admin', '/prompt_manager/admin#/tags',
+        '/prompt_manager/gallery', '/prompt_manager/gallery.html']);
+    for (const page of LEGACY_PAGES) assert.ok(page.label);
 });
 
 test('a job of the Activity page is its own deep link', async () => {

tests/js/workspace-toolbar.test.js

@@ -859,6 +859,42 @@ test('backupNotice is the concept .notice with its copy and one Back up now acti
     }
 });
 
+test('openReviewDialog replaces its rows and its primary in place (#482)', async () => {
+    const { openReviewDialog, closeWorkspaceDialog } = await dialogsModule;
+    const { createScope } = await coreModule;
+    const dom = fakeDOM();
+    const scope = createScope();
+    try {
+        const started = [];
+        const review = openReviewDialog({ scope, title: 'Delete or archive', grid: [['Archive', '2 prompts']],
+            cancelLabel: 'Cancel', primary: { label: 'Archive 2 prompts', danger: true }, onStart: () => started.push('start') });
+        review.setRows([['Delete permanently', '2 prompts'], ['Saved pairs removed', '3 saved pairs']]);
+        const grid = byId(dom, 'modal-body').children[0];
+        assert.deepEqual(grid.children.map(entry => [entry.children[0].textContent, entry.children[1].textContent]),
+            [['Delete permanently', '2 prompts'], ['Saved pairs removed', '3 saved pairs']]);
+        // setValue reaches the new rows only.
+        review.setValue('Saved pairs removed', '4 saved pairs');
+        review.setValue('Archive', 'x');
+        assert.equal(grid.children[1].children[1].textContent, '4 saved pairs');
+        const start = button(byId(dom, 'modal-body'), 'Archive 2 prompts');
+        review.setPrimary({ label: 'Delete 2 prompts', disabled: true });
+        assert.equal(start.textContent, 'Delete 2 prompts');
+        assert.equal(start.getAttribute('aria-disabled'), 'true');
+        start.click();
+        assert.deepEqual(started, []);
+        assert.equal(modal(dom).open, true);
+        review.setPrimary({ label: 'Delete 2 prompts', disabled: false });
+        assert.equal(start.getAttribute('aria-disabled'), 'false');
+        start.click();
+        assert.deepEqual(started, ['start']);
+        assert.throws(() => review.setRows([['only a term']]), TypeError);
+    } finally {
+        scope.dispose();
+        closeWorkspaceDialog();
+        dom.restore();
+    }
+});
+
 test('openReviewDialog lays out heading, grid, options, sentence, backup box and actions', async () => {
     const { openReviewDialog, closeWorkspaceDialog } = await dialogsModule;
     const { createScope } = await coreModule;

tests/run_suite.py

@@ -28,6 +28,10 @@ stack shows which). A dump after the summary is a hang at interpreter exit
 
 A limit is a measurement, not a dial: change it only with new measurements
 written next to it (TESTING.md "Time limits and hangs").
+
+PM_TEST_SLOWEST=N (opt-in, #487) lists the N slowest tests after the summary.
+A test's time runs from its ``start:`` line to the next one, so it includes
+the class and module fixtures in between, like the hang limit.
 """
 
 import argparse
@@ -36,6 +40,7 @@ import os
 import shutil
 import sys
 import tempfile
+import time
 import unittest
 from pathlib import Path
 
@@ -63,23 +68,57 @@ def read_limit(name, default):
     return int(text)
 
 
-def make_result_class(stream, per_test_limit, shutdown_limit):
+class TestClock:
+    """Seconds from each test's start to the next start (or the run's end)."""
+
+    def __init__(self, clock=time.perf_counter):
+        self._clock = clock
+        self._current = None
+        self._started = 0.0
+        self.durations = []
+
+    def start(self, test_id):
+        self.stop()
+        self._current = test_id
+        self._started = self._clock()
+
+    def stop(self):
+        if self._current is not None:
+            self.durations.append((self._clock() - self._started, self._current))
+            self._current = None
+
+    def report(self, count):
+        """Return the lines that list the ``count`` slowest tests."""
+        slowest = sorted(self.durations, key=lambda item: item[0], reverse=True)
+        lines = [f"slowest {min(count, len(slowest))} of {len(slowest)} tests:"]
+        lines += [f"{seconds:8.2f}s {test_id}" for seconds, test_id in slowest[:count]]
+        return lines
+
+
+def make_result_class(stream, per_test_limit, shutdown_limit, slowest=0):
     """Build a TextTestResult that names each test and re-arms the watchdog."""
 
     def arm(seconds):
         faulthandler.dump_traceback_later(seconds, exit=True, file=stream)
 
+    clock = TestClock()
+
     class WatchdogResult(unittest.TextTestResult):
         def startTest(self, test):
             # At default verbosity the progress dots share a line; start ours.
             prefix = "\n" if self.dots else ""
             stream.write(f"{prefix}start: {test.id()}\n")
             stream.flush()
+            clock.start(test.id())
             super().startTest(test)
             arm(per_test_limit)
 
         def stopTestRun(self):
+            clock.stop()
             super().stopTestRun()
+            if slowest:
+                stream.write("\n".join(["", *clock.report(slowest), ""]))
+                stream.flush()
             arm(shutdown_limit)
 
     return WatchdogResult
@@ -138,6 +177,7 @@ def main(argv=None):
     try:
         per_test_limit = read_limit("PM_TEST_HANG_LIMIT", DEFAULT_PER_TEST_LIMIT)
         shutdown_limit = read_limit("PM_TEST_SHUTDOWN_LIMIT", DEFAULT_SHUTDOWN_LIMIT)
+        slowest = read_limit("PM_TEST_SLOWEST", 0)
     except LimitError as error:
         stream.write(f"{error}\n")
         return USAGE_EXIT
@@ -152,7 +192,9 @@ def main(argv=None):
             verbosity=args.verbosity,
             # As unittest.main does: show warnings unless -W/PYTHONWARNINGS set them.
             warnings=None if sys.warnoptions else "default",
-            resultclass=make_result_class(stream, per_test_limit, shutdown_limit),
+            resultclass=make_result_class(
+                stream, per_test_limit, shutdown_limit, slowest
+            ),
         )
         result = runner.run(suite)
     finally:

tests/test_api_core.py

@@ -684,6 +684,132 @@ class TestStaticRoutes(CoreRoutesTestCase):
         self.assertEqual(resp.status, 403)
 
 
+class TestRevalidatedCaching(CoreRoutesTestCase):
+    """Every served page and static file is revalidated on reload (#478).
+
+    ``Cache-Control: no-cache`` makes the browser ask before it reuses a copy,
+    and the ETag lets an unchanged file answer 304 without a body, so an update
+    reaches the browser on a normal reload and an unchanged reload stays cheap.
+    """
+
+    STATIC_PATHS = (
+        "/prompt_manager/js/workspace/index.mjs",
+        "/prompt_manager/js/admin.js",
+        "/prompt_manager/js/inspection-semantics.json",
+        "/prompt_manager/lib/viewerjs/viewer.min.css",
+    )
+
+    async def _assert_revalidated(self, path):
+        resp = await self.client.request("GET", path)
+        self.assertEqual(resp.status, 200, path)
+        self.assertEqual(resp.headers.get("Cache-Control"), "no-cache", path)
+        etag = resp.headers.get("ETag")
+        self.assertTrue(etag, path)
+        body = await resp.read()
+        self.assertTrue(body, path)
+
+        again = await self.client.request("GET", path, headers={"If-None-Match": etag})
+        self.assertEqual(again.status, 304, path)
+        self.assertEqual(again.headers.get("ETag"), etag, path)
+        self.assertEqual(again.headers.get("Cache-Control"), "no-cache", path)
+        self.assertEqual(await again.read(), b"", path)
+
+        stale = await self.client.request(
+            "GET", path, headers={"If-None-Match": 'W/"stale"'}
+        )
+        self.assertEqual(stale.status, 200, path)
+        self.assertEqual(await stale.read(), body, path)
+        return etag
+
+    async def test_static_files_are_revalidated(self):
+        for path in self.STATIC_PATHS:
+            await self._assert_revalidated(path)
+
+    async def test_pages_are_revalidated(self):
+        for path in UI_PATHS:
+            await self._assert_revalidated(path)
+
+    async def test_etag_matches_in_a_list_and_as_wildcard(self):
+        path = "/prompt_manager/js/workspace/index.mjs"
+        etag = (await self.client.request("GET", path)).headers["ETag"]
+        for header in (f'W/"other", {etag}', etag.removeprefix("W/"), "*"):
+            resp = await self.client.request(
+                "GET", path, headers={"If-None-Match": header}
+            )
+            self.assertEqual(resp.status, 304, header)
+
+    async def test_changed_file_gets_a_new_etag_and_its_new_body(self):
+        web_dir = self._fake_root()
+        module = web_dir / "js" / "m.mjs"
+        module.write_text("export const v = 1;")
+        path = "/prompt_manager/js/m.mjs"
+        first = await self.client.request("GET", path)
+        etag = first.headers["ETag"]
+        # Same size and, on coarse clocks, the same mtime: only the bytes differ.
+        module.write_text("export const v = 2;")
+        resp = await self.client.request("GET", path, headers={"If-None-Match": etag})
+        self.assertEqual(resp.status, 200)
+        self.assertNotEqual(resp.headers["ETag"], etag)
+        self.assertEqual(await resp.text(), "export const v = 2;")
+
+    async def test_gzipped_and_plain_bodies_share_a_weak_etag(self):
+        """The gzip middleware changes the bytes, so the tag must be weak."""
+        resp = await self.client.request("GET", "/prompt_manager/js/admin.js")
+        self.assertTrue(resp.headers["ETag"].startswith('W/"'))
+
+    async def test_errors_carry_no_validator(self):
+        resp = await self.client.request("GET", "/prompt_manager/js/nope.js")
+        self.assertEqual(resp.status, 404)
+        self.assertNotIn("ETag", resp.headers)
+
+
+@web.middleware
+async def _comfyui_cache_control(request, handler):
+    """ComfyUI's own middleware (middleware/cache_middleware.py), JS/CSS branch.
+
+    It only fills a missing Cache-Control, and ``.mjs`` is not ``.js``: that is
+    why the workspace modules went out with no header at all before #478.
+    """
+    response = await handler(request)
+    if request.path.endswith(".js") or request.path.endswith(".css"):
+        response.headers.setdefault("Cache-Control", "no-store")
+    return response
+
+
+class TestRevalidatedCachingBehindMiddlewares(CoreRoutesTestCase):
+    """The host's middlewares keep the header and the 304 intact."""
+
+    async def get_application(self):
+        app = await super().get_application()
+        app.middlewares.append(_comfyui_cache_control)
+        app.middlewares.append(api_module._gzip_middleware)
+        return app
+
+    async def test_gzipped_files_keep_no_cache_and_answer_304(self):
+        for path in (
+            "/prompt_manager/js/workspace/index.mjs",
+            "/prompt_manager/js/admin.js",
+            "/prompt_manager/lib/viewerjs/viewer.min.css",
+            "/prompt_manager/workspace",
+        ):
+            resp = await self.client.request(
+                "GET", path, headers={"Accept-Encoding": "gzip"}
+            )
+            self.assertEqual(resp.status, 200, path)
+            self.assertEqual(resp.headers.get("Content-Encoding"), "gzip", path)
+            self.assertEqual(resp.headers["Cache-Control"], "no-cache", path)
+            again = await self.client.request(
+                "GET",
+                path,
+                headers={
+                    "Accept-Encoding": "gzip",
+                    "If-None-Match": resp.headers["ETag"],
+                },
+            )
+            self.assertEqual(again.status, 304, path)
+            self.assertEqual(again.headers["Cache-Control"], "no-cache", path)
+
+
 # ── instance helpers ──────────────────────────────────────────────────
 
 

tests/test_api_diagnostics_report.py

@@ -45,7 +45,9 @@ SEEDED_PATHS = (
     "/srv/someone/renders",
     "C:\\Users\\someone\\Documents\\renders",
     "D:/Users/someone/prompts.db",
-    "\\\\nas\\share\\someone\\renders",
+    # A share on this machine: on Windows the report resolves every source,
+    # and an unknown server name made that wait about 2.9 s (#487).
+    "\\\\localhost\\pm-no-such-share\\someone\\renders",
 )
 _WINDOWS_ABSOLUTE = re.compile(r"^[A-Za-z]:[\\/]")
 TOP_KEYS = {

tests/test_api_history.py

@@ -25,6 +25,7 @@ try:
 except ImportError:
     from tests.test_api_images import ImageAPITestCase
 
+from database import restore_stage
 from database.operations import PromptDatabase
 from py.api.library import _encode, _scope
 from tests.test_execution_context_database import bundle, snapshot
@@ -43,6 +44,21 @@ OTHER_SESSION = "aaaaaaaa-3333-4333-8333-333333333333"
 MISSING_RUN = "bbbbbbbb-4444-4444-8444-444444444444"
 
 
+@contextmanager
+def no_wal_truncate_wait():
+    """Restore with the restore notification held back, as these tests need.
+
+    The read under test keeps its snapshot open across the restore, so the
+    publish's WAL truncate can never succeed; without the short wait it would
+    sit out the full CHECKPOINT_BUSY_MS (30 s) each time (#487).
+    """
+    with (
+        patch("database.execution_history.notify_history_restore"),
+        patch.object(restore_stage, "CHECKPOINT_BUSY_MS", 50),
+    ):
+        yield
+
+
 class HistoryAPITests(ImageAPITestCase):
     async def tearDownAsync(self):
         if hasattr(self.api, "close_history_reads"):
@@ -346,7 +362,7 @@ class HistoryAPITests(ImageAPITestCase):
 
         def during_snapshot(*args, **kwargs):
             result = original(*args, **kwargs)
-            with patch("database.execution_history.notify_history_restore"):
+            with no_wal_truncate_wait():
                 writer.model.restore_from_file(source)
             return result
 
@@ -890,7 +906,7 @@ class HistoryAPITests(ImageAPITestCase):
 
                 def during_snapshot(*args, **kwargs):
                     result = original(*args, **kwargs)
-                    with patch("database.execution_history.notify_history_restore"):
+                    with no_wal_truncate_wait():
                         writer.model.restore_from_file(source)
                     return result
 

tests/test_api_images.py

@@ -3020,6 +3020,8 @@ class TestSharedListing(ImageAPITestCase):
                 "limit",
                 "has_more",
                 "next_cursor",
+                # #498: Show removed images (N).
+                "removed_total",
             },
         )
         _, folders = await self._json("GET", "/prompt_manager/gallery/subfolders")

tests/test_autotag_engine.py

@@ -8,6 +8,7 @@ import contextlib
 import csv
 import os
 import shutil
+import subprocess
 import sys
 import tempfile
 import types
@@ -15,7 +16,18 @@ import unittest
 from pathlib import Path
 from unittest.mock import MagicMock, patch
 
-sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, _REPO_ROOT)
+
+# Run in a child interpreter: import py.autotag with a stub ComfyUI ``server``
+# and print every ML backend that the import pulled in.
+_IMPORT_AUTOTAG_REPORT_BACKENDS = """
+import sys
+from unittest.mock import MagicMock
+sys.modules["server"] = MagicMock()
+import py.autotag
+print(*sorted({"onnxruntime", "llama_cpp"} & set(sys.modules)))
+"""
 
 from PIL import Image
 
@@ -142,17 +154,26 @@ class TestModelInjection(EngineTestCase):
         self.assertEqual(service._model_loader, service._load_model)
 
     def test_importing_autotag_does_not_import_ml_backends(self):
-        for heavy in ("onnxruntime", "llama_cpp"):
-            self.assertNotIn(heavy, sys.modules)
+        # A fresh interpreter: earlier tests in this process may have imported
+        # an installed backend, so only a clean import can prove this (#472).
+        result = subprocess.run(
+            [sys.executable, "-c", _IMPORT_AUTOTAG_REPORT_BACKENDS],
+            cwd=_REPO_ROOT,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(result.stdout.split(), [])
 
     def test_default_wd14_loader_reports_missing_onnxruntime(self):
         _touch_model_files(self.models_dir, "wd14-vit")
         service = AutoTagService(models_dir=self.models_dir)
-        if "onnxruntime" in sys.modules:
-            self.skipTest("onnxruntime is installed in this environment")
 
-        with self.assertRaises(RuntimeError) as ctx:
-            service.load_model("wd14-vit")
+        # A None entry makes onnxruntime unimportable even where it is installed.
+        with _patch_modules({"onnxruntime": None}):
+            with self.assertRaises(RuntimeError) as ctx:
+                service.load_model("wd14-vit")
 
         self.assertIn("onnxruntime", str(ctx.exception))
         self.assertFalse(service.is_model_loaded())

tests/test_autotag_packages.py

@@ -1,6 +1,7 @@
 """#424: each tagging backend reports the Python packages it cannot import.
 
-``find_spec`` is patched throughout: no ML backend is installed or imported.
+``find_spec`` is patched throughout, and a backend an earlier test imported is
+hidden where it matters, so these pass with or without the ML packages (#472).
 """
 
 import os
@@ -75,8 +76,13 @@ class TestMissingPackages(unittest.TestCase):
     def test_find_spec_errors_count_as_missing(self):
         for error in (ValueError("no spec"), ImportError("broken"), OSError("io")):
             with self.subTest(error=type(error).__name__):
-                with patch.object(
-                    autotag.importlib.util, "find_spec", side_effect=error
+                # Hide an onnxruntime an earlier test imported, so the check
+                # reaches find_spec (#472).
+                with (
+                    _patch_modules({"onnxruntime": None}),
+                    patch.object(
+                        autotag.importlib.util, "find_spec", side_effect=error
+                    ),
                 ):
                     self.assertEqual(missing_packages("wd14-vit"), ["onnxruntime"])
 

tests/test_browser_malloc_tuning.py

@@ -0,0 +1,92 @@
+"""#516: the browser test server pins glibc's mmap threshold.
+
+Large frees then go back to the OS instead of fragmenting per-thread arenas.
+"""
+
+import ctypes
+import sys
+import unittest
+from unittest import mock
+
+from tests.browser import malloc_tuning
+
+
+class FakeLibc:
+    def __init__(self, result=1):
+        self.calls = []
+        self.result = result
+
+    def mallopt(self, option, value):
+        self.calls.append((option, value))
+        return self.result
+
+
+class PinMmapThresholdTests(unittest.TestCase):
+    def test_sets_a_fixed_threshold_through_mallopt(self):
+        libc = FakeLibc()
+        with mock.patch.object(sys, "platform", "linux"):
+            self.assertTrue(malloc_tuning.pin_mmap_threshold(libc))
+        # M_MMAP_THRESHOLD is -3; setting it also turns off glibc's dynamic
+        # raising of the threshold.
+        self.assertEqual(libc.calls, [(-3, 128 * 1024)])
+
+    def test_reports_a_refused_setting(self):
+        with mock.patch.object(sys, "platform", "linux"):
+            self.assertFalse(malloc_tuning.pin_mmap_threshold(FakeLibc(result=0)))
+
+    def test_skips_a_libc_without_mallopt(self):
+        with mock.patch.object(sys, "platform", "linux"):
+            self.assertFalse(malloc_tuning.pin_mmap_threshold(object()))
+
+    def test_skips_other_platforms_without_loading_a_libc(self):
+        for name in ("win32", "darwin"):
+            with (
+                self.subTest(name),
+                mock.patch.object(sys, "platform", name),
+                mock.patch.object(
+                    ctypes, "CDLL", side_effect=AssertionError("no libc load")
+                ),
+            ):
+                self.assertFalse(malloc_tuning.pin_mmap_threshold())
+
+    def test_skips_when_the_process_libc_cannot_be_loaded(self):
+        with (
+            mock.patch.object(sys, "platform", "linux"),
+            mock.patch.object(ctypes, "CDLL", side_effect=OSError("no libc")),
+        ):
+            self.assertFalse(malloc_tuning.pin_mmap_threshold())
+
+    @unittest.skipUnless(
+        sys.platform.startswith("linux")
+        and hasattr(ctypes.CDLL(None), "gnu_get_libc_version"),
+        "glibc only",
+    )
+    def test_glibc_accepts_the_setting(self):
+        # This pins the threshold for the rest of this test process too; the
+        # test server does the same at start, so nothing here depends on it.
+        self.assertTrue(malloc_tuning.pin_mmap_threshold())
+
+
+class ServerMainTests(unittest.TestCase):
+    def test_main_pins_the_threshold_before_it_starts_serving(self):
+        from tests.browser import server
+
+        order = []
+
+        def bind(port):
+            order.append("bind")
+            raise RuntimeError("stop before serving")
+
+        with (
+            mock.patch.object(
+                server, "pin_mmap_threshold", side_effect=lambda: order.append("pin")
+            ),
+            mock.patch.object(server, "bind_listener", side_effect=bind),
+        ):
+            with self.assertRaises(RuntimeError):
+                server.main(["--port", "0"])
+        self.assertEqual(order, ["pin", "bind"])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_bulk_library_delete.py

@@ -0,0 +1,889 @@
+"""#443 (D152): delete selected Library prompts; paired ones are archived.
+
+The DB commands, and what every reader does with an archived parent.
+"""
+
+import re
+import sqlite3
+import tempfile
+import unittest
+from pathlib import Path
+
+from database.execution_history_schema import rotate_history_epoch
+from database.library_commands import LibraryCommandError
+from database.library_folders import folder_prefixes
+from database.operations import PromptDatabase
+from database.prompt_archive import TABLE as ARCHIVE
+from utils.hashing import generate_prompt_hash
+
+
+def save(db, text, **metadata):
+    return db.save_prompt(text, prompt_hash=generate_prompt_hash(text), **metadata)
+
+
+def rows(db, sql, params=()):
+    with db.model.get_connection() as conn:
+        return [tuple(row) for row in conn.execute(sql, params).fetchall()]
+
+
+def archived_ids(db):
+    return sorted(row[0] for row in rows(db, f"SELECT prompt_id FROM {ARCHIVE}"))
+
+
+def prompt_ids(db):
+    return sorted(row[0] for row in rows(db, "SELECT id FROM prompts"))
+
+
+_STAMP = re.compile(r"^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}")
+
+
+def _stable(value):
+    return "<time>" if isinstance(value, str) and _STAMP.match(value) else value
+
+
+def table_dump(db):
+    """Every row of every table (times masked), to compare two databases."""
+    tables = [
+        row[0]
+        for row in rows(
+            db,
+            "SELECT name FROM sqlite_master WHERE type='table' "
+            "AND name NOT LIKE 'sqlite_%' AND name!='execution_history_metadata' "
+            "ORDER BY name",
+        )
+    ]
+    dump = {}
+    for table in tables:
+        dump[table] = sorted(
+            (tuple(map(_stable, row)) for row in rows(db, f"SELECT * FROM {table}")),
+            key=repr,
+        )
+    return dump
+
+
+class LibraryDeleteCase(unittest.TestCase):
+    maxDiff = None
+
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        # Cleanups run last-in first-out and after every cleanup a test adds,
+        # so a database a test opens (and closes via addCleanup) is closed
+        # before the folder goes; Windows cannot delete an open file (#510).
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+        self.db = PromptDatabase(str(self.root / "delete.db"))
+        self.addCleanup(self.db.close_all)
+        self.epoch = self.db.get_library_options()["library_epoch"]
+
+    def paired(self, positive, negative="blur"):
+        pair = self.db.save_prompt_pair(positive, negative)
+        found = self.db.get_prompt_pair(pair)
+        return found["positive_prompt_id"], found["negative_prompt_id"], pair
+
+    def image(self, prompt_id, name):
+        path = self.root / name
+        path.write_bytes(b"png")
+        return self.db.link_image_to_prompt(prompt_id, str(path))
+
+    def apply(self, ids, epoch=None, review=None):
+        """Review ``ids`` (or use ``review``), then write what was reviewed."""
+        review = review or self.classify(ids)
+        return self.db.archive_or_delete_library_prompts(
+            review["archive"],
+            review["delete"],
+            expected_epoch=epoch or self.epoch,
+            candidates=review["fingerprints"],
+        )
+
+    def classify(self, ids, epoch=None):
+        return self.db.classify_library_delete(ids, expected_epoch=epoch or self.epoch)
+
+    def restore(self, ids, epoch=None):
+        return self.db.restore_library_prompts(ids, expected_epoch=epoch or self.epoch)
+
+
+class TestClassifyAndApply(LibraryDeleteCase):
+    def test_each_class_in_order(self):
+        plain = save(self.db, "Plain")
+        protected = save(self.db, "Guarded", tags=["__protected__"])
+        protected_paired, _neg, _pair = self.paired("Guarded pair")
+        self.db.bulk_add_tags([protected_paired], ["__protected__"])
+        positive, negative_only, _pair = self.paired("Cat", "only negative")
+        both = save(self.db, "Both roles")
+        self.image(both, "both.png")  # a parent through its image
+        self.db.save_prompt_pair("Other", "Both roles")
+        archived_pair_positive, _n, old_pair = self.paired("Old")
+        self.db.archive_prompt_pair(old_pair, True)
+        already, _n2, _p2 = self.paired("Already")
+        self.apply([already])
+        self.image(plain, "plain.png")
+        ids = [
+            plain,
+            protected,
+            protected_paired,
+            positive,
+            negative_only,
+            both,
+            archived_pair_positive,
+            already,
+            99999,
+        ]
+        result = self.classify(ids)
+        self.assertEqual(
+            result,
+            {
+                "library_epoch": self.epoch,
+                "delete": [plain],
+                "archive": [positive, both, archived_pair_positive],
+                "protected": [protected, protected_paired],
+                "already_archived": [already],
+                "not_archived": [],
+                "not_found": [negative_only, 99999],
+                "image_links": 1,
+                "fingerprints": result["fingerprints"],
+                # #482: the archive ids Delete permanently could remove (with pairs).
+                "deletable": [positive, archived_pair_positive],
+                "review_digests": result["review_digests"],
+                "paired_counts": {
+                    "pairs": 2,
+                    "archived_pairs": 1,
+                    "variants": 2,
+                    # "only negative" is itself selected; only "blur" is kept.
+                    "kept_negatives": 1,
+                },
+                "paired_image_links": 0,
+            },
+        )
+        self.assertEqual(list(result["fingerprints"]), [plain])
+        self.assertEqual(
+            list(result["review_digests"]), [positive, archived_pair_positive]
+        )
+
+    def test_apply_archives_paired_deletes_unpaired_and_skips_protected(self):
+        plain = save(self.db, "Plain", tags=["red"])
+        protected = save(self.db, "Guarded", tags=["__protected__"])
+        positive, negative, pair = self.paired("Cat")
+        self.image(plain, "a.png")
+        self.image(positive, "b.png")
+        before = rows(self.db, "SELECT updated_at FROM prompts WHERE id=?", (positive,))
+        result = self.apply([plain, protected, positive, 99999])
+        self.assertEqual(
+            result,
+            {
+                "library_epoch": self.epoch,
+                "deleted": 1,
+                "archived": 1,
+                "already_archived": 0,
+                "not_archived": 0,
+                "not_found": 0,
+                "changed": 0,
+                "image_links": 1,
+                "pairs_removed": 0,
+            },
+        )
+        self.assertEqual(prompt_ids(self.db), sorted([protected, positive, negative]))
+        self.assertEqual(archived_ids(self.db), [positive])
+        # Archive keeps everything: the pair, its image link and the prompt row.
+        self.assertEqual(
+            len(rows(self.db, "SELECT 1 FROM prompt_pairs WHERE id=?", (pair,))), 1
+        )
+        self.assertEqual(
+            len(
+                rows(
+                    self.db,
+                    "SELECT 1 FROM generated_images WHERE prompt_id=?",
+                    (positive,),
+                )
+            ),
+            1,
+        )
+        after = rows(self.db, "SELECT updated_at FROM prompts WHERE id=?", (positive,))
+        self.assertNotEqual(before, after)
+        # The image file stays on disk.
+        self.assertTrue((self.root / "a.png").exists())
+
+    def test_delete_has_exactly_the_legacy_row_effects(self):
+        twin = PromptDatabase(str(self.root / "twin.db"))
+        self.addCleanup(twin.close_all)
+        twin_epoch = twin.get_library_options()["library_epoch"]
+        for db in (self.db, twin):
+            a = save(db, "Alpha", tags=["x", "y"], category="c")
+            save(db, "Beta")
+            path = self.root / "shared.png"
+            path.write_bytes(b"png")
+            db.link_image_to_prompt(a, str(path), {"workflow": {"nodes": []}})
+        self.db.bulk_delete_prompts([a])
+        twin.archive_or_delete_library_prompts(
+            [], [a], expected_epoch=twin_epoch, candidates=None
+        )
+        self.assertEqual(table_dump(self.db), table_dump(twin))
+
+    def test_already_archived_and_restore(self):
+        positive, _neg, _pair = self.paired("Cat")
+        self.apply([positive])
+        again = self.classify([positive])
+        self.assertEqual(
+            (again["archive"], again["already_archived"]), ([], [positive])
+        )
+        # Archived between the review and the write: counted, not archived twice.
+        other, _n, _p = self.paired("Dog")
+        review = self.classify([other])
+        self.apply([other])
+        late = self.apply([], review=review)
+        self.assertEqual((late["archived"], late["already_archived"]), (0, 1))
+        plain = save(self.db, "Plain")
+        result = self.restore([positive, plain, 99999])
+        self.assertEqual(
+            result,
+            {
+                "library_epoch": self.epoch,
+                "restored": 1,
+                "unchanged": 1,
+                "not_found": 1,
+            },
+        )
+        self.assertEqual(archived_ids(self.db), [other])
+
+    def test_the_write_executes_only_what_was_reviewed(self):
+        plain = save(self.db, "Plain")
+        guarded = save(self.db, "Guarded later")
+        touched = save(self.db, "Touched later")
+        review = self.classify([plain, guarded, touched])
+        # Between the review and the write: one becomes protected, one is used.
+        self.db.bulk_add_tags([guarded], ["__protected__"])
+        self.db.record_prompt_use(touched)
+        result = self.apply([], review=review)
+        self.assertEqual((result["deleted"], result["changed"]), (1, 2))
+        self.assertEqual(prompt_ids(self.db), sorted([guarded, touched]))
+        self.assertEqual(archived_ids(self.db), [])
+
+    def test_a_new_image_link_after_the_review_keeps_the_prompt(self):
+        plain = save(self.db, "Plain")
+        review = self.classify([plain])
+        self.image(plain, "late.png")
+        self.assertEqual(self.apply([], review=review)["changed"], 1)
+        self.assertIn(plain, prompt_ids(self.db))
+
+    def test_reviewed_deletes_without_a_backup_are_kept(self):
+        plain = save(self.db, "Plain")
+        review = self.classify([plain])
+        result = self.db.archive_or_delete_library_prompts(
+            [], [plain], expected_epoch=self.epoch, candidates={}
+        )
+        self.assertEqual((result["deleted"], result["changed"]), (0, 1))
+        self.assertEqual(review["delete"], [plain])
+
+    def test_a_reviewed_delete_that_became_paired_is_archived(self):
+        plain = save(self.db, "Plain")
+        review = self.classify([plain])
+        self.db.save_prompt_pair("Plain", "late negative")
+        result = self.apply([], review=review)
+        self.assertEqual((result["deleted"], result["archived"]), (0, 1))
+
+    def test_a_reviewed_archive_that_lost_its_pair_is_archived_not_deleted(self):
+        positive, _negative, pair = self.paired("Cat")
+        review = self.classify([positive])
+        self.db.delete_prompt_pair(pair)
+        result = self.apply([], review=review)
+        self.assertEqual((result["deleted"], result["archived"]), (0, 1))
+        self.assertEqual(archived_ids(self.db), [positive])
+
+    def test_one_id_in_both_lists_or_no_ids_is_refused(self):
+        plain = save(self.db, "Plain")
+        for archive, delete in (([plain], [plain]), ([], [])):
+            with self.subTest(archive=archive, delete=delete):
+                with self.assertRaises(ValueError):
+                    self.db.archive_or_delete_library_prompts(
+                        archive, delete, expected_epoch=self.epoch, candidates=None
+                    )
+
+    def test_archiving_repairs_a_missing_or_stale_hash(self):
+        missing, _n1, _p1 = self.paired("Hashless")
+        stale, _n2, _p2 = self.paired("Stale hash")
+        with self.db.model.get_connection() as conn:
+            conn.execute("UPDATE prompts SET hash=NULL WHERE id=?", (missing,))
+            conn.execute("UPDATE prompts SET hash='stale' WHERE id=?", (stale,))
+        self.apply([missing, stale])
+        for pid, text in ((missing, "Hashless"), (stale, "Stale hash")):
+            self.assertEqual(
+                rows(self.db, "SELECT hash FROM prompts WHERE id=?", (pid,)),
+                [(generate_prompt_hash(text),)],
+            )
+            # So every ingestion lookup finds the archived row.
+            self.assertEqual(save(self.db, text), pid)
+
+    def test_a_canonical_hash_another_row_holds_is_left_alone(self):
+        stale, _n, _p = self.paired("Twin text")
+        with self.db.model.get_connection() as conn:
+            conn.execute("UPDATE prompts SET hash='stale' WHERE id=?", (stale,))
+        twin = save(self.db, "twin text")
+        self.apply([stale])
+        self.assertEqual(
+            rows(self.db, "SELECT hash FROM prompts WHERE id=?", (stale,)), [("stale",)]
+        )
+        self.assertEqual(save(self.db, "Twin text"), twin)
+
+    def test_restore_unhides_protected_and_non_parent_archived_prompts(self):
+        guarded, _n, _p = self.paired("Guarded")
+        self.apply([guarded])
+        self.db.bulk_add_tags([guarded], ["__protected__"])
+        negative_only = save(self.db, "Only a negative")
+        self.db.save_prompt_pair("Owner", "Only a negative")
+        with self.db.model.get_connection() as conn:
+            conn.execute(
+                f"INSERT INTO {ARCHIVE} VALUES (?, '2026-10-28T00:00:00+00:00')",
+                (negative_only,),
+            )
+        result = self.restore([guarded, negative_only])
+        self.assertEqual(result["restored"], 2)
+        self.assertEqual(archived_ids(self.db), [])
+
+    def test_restored_storage_changes_nothing(self):
+        plain = save(self.db, "Plain")
+        positive, _neg, _pair = self.paired("Cat")
+        rotate_history_epoch(self.db.model.get_connection())
+        for call in (
+            lambda: self.apply([plain, positive]),
+            lambda: self.classify([plain]),
+            lambda: self.restore([positive]),
+        ):
+            with self.assertRaises(LibraryCommandError) as caught:
+                call()
+            self.assertEqual(caught.exception.code, "storage-changed")
+        self.assertIn(plain, prompt_ids(self.db))
+        self.assertEqual(archived_ids(self.db), [])
+
+    def test_a_failure_mid_write_rolls_everything_back(self):
+        plain = save(self.db, "Plain")
+        positive, _neg, _pair = self.paired("Cat")
+        with self.db.model.get_connection() as conn:
+            conn.execute(
+                "CREATE TRIGGER fail_delete BEFORE DELETE ON prompts "
+                "BEGIN SELECT RAISE(ABORT, 'boom'); END"
+            )
+        with self.assertRaises(sqlite3.DatabaseError):
+            self.apply([positive, plain])
+        self.assertIn(plain, prompt_ids(self.db))
+        self.assertEqual(archived_ids(self.db), [])
+
+    def test_many_ids_are_handled_in_batches(self):
+        ids = [save(self.db, f"Many {i}") for i in range(1000)]
+        result = self.apply(ids)
+        self.assertEqual(result["deleted"], 1000)
+
+    def test_rejects_invalid_arguments(self):
+        plain = save(self.db, "Plain")
+        for ids, epoch in (([], self.epoch), ([True], self.epoch), ([plain], "x")):
+            for call in (self.apply, self.classify, self.restore):
+                with self.subTest(ids=ids, epoch=epoch, call=call.__name__):
+                    with self.assertRaises(ValueError):
+                        call(ids, epoch)
+
+
+class TestArchivedReaders(LibraryDeleteCase):
+    """What each reader does with an archived parent (design §4.4)."""
+
+    def setUp(self):
+        super().setUp()
+        self.kept, _kn, _kp = self.paired("Kept cat", "kept blur")
+        self.gone, _gn, _gp = self.paired("Gone cat", "gone blur")
+        for pid, category, tag in ((self.kept, "keep", "k"), (self.gone, "gone", "g")):
+            self.db.update_prompt_metadata(pid, category=category, tags=[tag])
+        self.apply([self.gone])
+
+    def ids_of(self, page):
+        return [item["id"] for item in page["items"]]
+
+    def test_listing_search_and_totals(self):
+        active = self.db.list_library()
+        self.assertEqual(self.ids_of(active), [self.kept])
+        self.assertEqual(
+            (active["total"], active["variant_total"], active["archived_total"]),
+            (1, 1, 1),
+        )
+        archived = self.db.list_library(shelf="archived")
+        self.assertEqual(self.ids_of(archived), [self.gone])
+        self.assertEqual((archived["total"], archived["variant_total"]), (1, 1))
+        self.assertEqual(self.ids_of(self.db.list_library(text="Gone")), [])
+        self.assertEqual(
+            self.ids_of(self.db.list_library(text="Gone", shelf="archived")),
+            [self.gone],
+        )
+        self.assertEqual(self.ids_of(self.db.list_library(tags=["g"])), [])
+        self.assertEqual(self.db.list_library(category="gone")["archived_total"], 1)
+        with self.assertRaises(ValueError):
+            self.db.list_library(shelf="all")
+
+    def test_the_444_filters_and_tag_counts_hide_it(self):
+        # #444's folder filter, tag match and tag ranking keep #443's shelves.
+        bare, _bn, _bp = self.paired("Bare cat", "bare blur")
+        self.apply([bare])
+        folder = self.root / "out" / "cats"
+        folder.mkdir(parents=True)
+        for pid, name in ((self.kept, "kept.png"), (self.gone, "gone.png")):
+            self.image(pid, str(Path("out") / "cats" / name))
+        prefixes = folder_prefixes([str(self.root / "out")], "cats")
+        self.assertEqual(
+            self.ids_of(self.db.list_library(folder_prefixes=prefixes)), [self.kept]
+        )
+        self.assertEqual(
+            self.ids_of(
+                self.db.list_library(folder_prefixes=prefixes, shelf="archived")
+            ),
+            [self.gone],
+        )
+        self.assertEqual(
+            self.ids_of(self.db.list_library(tags=["k", "g"], tag_mode="any")),
+            [self.kept],
+        )
+        self.assertEqual(self.ids_of(self.db.list_library(tag_mode="untagged")), [])
+        self.assertEqual(
+            self.ids_of(self.db.list_library(tag_mode="untagged", shelf="archived")),
+            [bare],
+        )
+        tags = self.db.list_vocabulary_tags(sort="prompts")
+        self.assertEqual(
+            {row["name"]: row["prompt_count"] for row in tags["tags"]},
+            {"k": 1, "g": 0},
+        )
+        self.assertEqual(tags["untagged_count"], 0)
+        self.assertEqual(
+            self.db.list_vocabulary_tags(search="g", sort="prompts")["tags"][0][
+                "prompt_count"
+            ],
+            0,
+        )
+
+    def test_detail_and_options(self):
+        self.assertTrue(self.db.get_library_positive(self.gone)["positive"]["archived"])
+        self.assertFalse(
+            self.db.get_library_positive(self.kept)["positive"]["archived"]
+        )
+        # Suggestions keep archived parents' categories: the archived view
+        # filters by them.
+        self.assertEqual(self.db.get_library_options()["categories"], ["gone", "keep"])
+
+    def test_counts(self):
+        self.assertEqual(self.db.library_counts()["positive_prompts"], 1)
+        self.assertEqual(self.db.library_counts()["negative_variants"], 1)
+        tags = {
+            row["name"]: row["prompt_count"]
+            for row in self.db.list_vocabulary_tags()["tags"]
+        }
+        self.assertEqual((tags["k"], tags["g"]), (1, 0))
+        categories = {
+            row["value"]: row["prompt_count"]
+            for row in self.db.list_vocabulary_categories()["categories"]
+        }
+        # A value only archived parents hold stays listed with 0, as a tag does.
+        self.assertEqual(categories, {"keep": 1, "gone": 0})
+
+    def test_restore_summary_and_export(self):
+        from database.restore_stage import library_summary
+
+        summary = library_summary(self.db.model.get_connection())
+        self.assertEqual(summary["positives"], 1)
+        exported = {
+            item["positive_text"]: item["archived"]
+            for item in self.db.export_library()["positives"]
+        }
+        self.assertEqual(exported, {"Kept cat": False, "Gone cat": True})
+
+    def test_usage_statistics_keep_archived_runs(self):
+        self.db.record_prompt_use(self.gone, 3)
+        runs = {row["category"]: row["runs"] for row in self.db.usage_by_category()}
+        self.assertEqual(runs["gone"], 3)
+
+    def test_runs_node_saves_and_new_prompt_find_the_archived_row(self):
+        count = len(prompt_ids(self.db))
+        self.assertTrue(self.db.record_prompt_use(self.gone, 2))
+        existing = self.db.get_prompt_by_hash(generate_prompt_hash("Gone cat"))
+        self.assertEqual(existing["id"], self.gone)
+        self.assertEqual(save(self.db, "Gone cat"), self.gone)
+        self.db.save_prompt_pair("Gone cat", "new blur")
+        self.assertEqual(len(prompt_ids(self.db)), count + 1)  # only the new negative
+        self.assertEqual(archived_ids(self.db), [self.gone])
+
+    def test_legacy_reads_still_list_it_and_legacy_delete_still_refuses(self):
+        from database.pairs import PairDependencyError
+
+        texts = [p["text"] for p in self.db.get_recent_prompts(limit=50)["prompts"]]
+        self.assertIn("Gone cat", texts)
+        with self.assertRaises(PairDependencyError):
+            self.db.bulk_delete_prompts([self.gone])
+
+    def test_as_another_parents_negative_it_stays_a_visible_variant(self):
+        owner, _neg, pair = self.paired("Owner cat", "Gone cat")
+        detail = self.db.get_library_positive(owner)
+        self.assertEqual([v["id"] for v in detail["variants"]], [pair])
+        self.assertEqual(self.ids_of(self.db.list_library(text="Gone")), [owner])
+
+    def test_maintenance_never_prunes_an_archived_prompt(self):
+        lonely = save(self.db, "Lonely")
+        with self.db.model.get_connection() as conn:
+            conn.execute(
+                f"INSERT INTO {ARCHIVE} VALUES (?, '2026-10-28T00:00:00+00:00')",
+                (lonely,),
+            )
+            orphaned = [row[0] for row in conn.execute(self.orphaned_sql()).fetchall()]
+        self.assertNotIn(lonely, orphaned)
+
+    @staticmethod
+    def orphaned_sql():
+        from database.maintenance import ORPHANED_PROMPTS_SQL
+
+        return ORPHANED_PROMPTS_SQL
+
+    def test_bulk_metadata_writes_still_reach_an_archived_parent(self):
+        result = self.db.bulk_set_library_category(
+            [self.gone], "moved", expected_epoch=self.epoch
+        )
+        self.assertEqual(result["updated"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main()
+
+
+class TestPairedDelete(LibraryDeleteCase):
+    """#482 (D160): Delete permanently also removes a prompt's own saved pairs."""
+
+    def pair_rows(self, positive):
+        return rows(
+            self.db,
+            "SELECT id FROM prompt_pairs WHERE positive_prompt_id=? ORDER BY id",
+            (positive,),
+        )
+
+    def pair_link(self, pair, image):
+        return self.db.link_image_to_pair(pair, image, {"resolver_version": 1})
+
+    def delete_paired(self, ids, review, archive=None, epoch=None):
+        """Write ``ids`` as Delete permanently, with the digests ``review`` gave."""
+        archive = review["archive"] if archive is None else archive
+        return self.db.archive_or_delete_library_prompts(
+            archive,
+            review["delete"],
+            expected_epoch=epoch or self.epoch,
+            candidates=review["fingerprints"],
+            delete_paired={pid: review["review_digests"][pid] for pid in ids},
+        )
+
+    def test_classify_marks_deletable_and_archive_only_with_pair_counts(self):
+        cat, cat_negative, _pair = self.paired("Cat", "blur")
+        self.db.save_prompt_pair("Cat", "grain")
+        archived_pair = self.db.save_prompt_pair("Cat", "noise")
+        self.db.archive_prompt_pair(archived_pair, True)
+        shared = save(self.db, "Shared")
+        self.image(shared, "shared.png")
+        self.db.save_prompt_pair("Dog", "Shared")  # used as another positive's negative
+        review = self.classify([cat, shared])
+        self.assertEqual(review["archive"], [cat, shared])
+        self.assertEqual(review["deletable"], [cat])
+        self.assertEqual(list(review["review_digests"]), [cat])
+        self.assertRegex(review["review_digests"][cat], r"^[0-9a-f]{64}$")
+        self.assertEqual(
+            review["paired_counts"],
+            {"pairs": 3, "archived_pairs": 1, "variants": 3, "kept_negatives": 3},
+        )
+        self.assertEqual(review["paired_image_links"], 0)
+
+    def test_an_empty_negative_pair_is_deleted_with_its_prompt(self):
+        # Live prompt 7896: an auto-created pair with an explicitly empty negative.
+        pair = self.db.save_prompt_pair("été", "")
+        prompt = self.db.get_prompt_pair(pair)["positive_prompt_id"]
+        review = self.classify([prompt])
+        self.assertEqual(review["deletable"], [prompt])
+        self.assertEqual(
+            review["paired_counts"],
+            {"pairs": 1, "archived_pairs": 0, "variants": 0, "kept_negatives": 0},
+        )
+        result = self.delete_paired([prompt], review)
+        self.assertEqual((result["deleted"], result["archived"]), (1, 0))
+        self.assertEqual(result["pairs_removed"], 1)
+        self.assertNotIn(prompt, prompt_ids(self.db))
+        self.assertEqual(self.pair_rows(prompt), [])
+        self.assertEqual(rows(self.db, "PRAGMA foreign_key_check"), [])
+
+    def test_rows_removed_are_the_legacy_pair_deletes_then_the_prompt_delete(self):
+        twin = PromptDatabase(str(self.root / "twin.db"))
+        self.addCleanup(twin.close_all)
+        twin_epoch = twin.get_library_options()["library_epoch"]
+        made = {}
+        for db in (self.db, twin):
+            plain = db.save_prompt_pair("Owl", "", tags=["night"], title="Owl")
+            with_negative = db.save_prompt_pair("Owl", "dark", rating=4)
+            hidden = db.save_prompt_pair("Owl", "fog")
+            db.archive_prompt_pair(hidden, True)
+            owl = db.get_prompt_pair(plain)["positive_prompt_id"]
+            path = self.root / "owl.png"
+            path.write_bytes(b"png")
+            image = db.link_image_to_prompt(owl, str(path), {"workflow": {"nodes": []}})
+            db.link_image_to_pair(with_negative, image, {"resolver_version": 1})
+            save(db, "Bystander", tags=["night"])
+            made[id(db)] = (owl, [plain, with_negative, hidden])
+        owl, pairs = made[id(self.db)]
+        review = self.classify([owl])
+        self.delete_paired([owl], review)
+        twin_owl, twin_pairs = made[id(twin)]
+        with twin.model.get_connection() as conn:
+            conn.execute(
+                "DELETE FROM image_prompt_pairs WHERE pair_id IN (SELECT id FROM "
+                "prompt_pairs WHERE positive_prompt_id=?)",
+                (twin_owl,),
+            )
+            conn.commit()
+        for pair in twin_pairs:
+            self.assertTrue(twin.delete_prompt_pair(pair))
+        twin.archive_or_delete_library_prompts(
+            [], [twin_owl], expected_epoch=twin_epoch, candidates=None
+        )
+        self.assertEqual(table_dump(self.db), table_dump(twin))
+        # The negatives stay, and the image file stays on disk.
+        self.assertTrue((self.root / "owl.png").exists())
+        texts = [row[0] for row in rows(self.db, "SELECT text FROM prompts")]
+        self.assertTrue({"dark", "fog", "Bystander"} <= set(texts))
+
+    def test_a_negative_used_by_another_positive_is_archived_never_deleted(self):
+        shared = save(self.db, "Shared")
+        self.image(shared, "s.png")
+        self.db.save_prompt_pair("Dog", "Shared")
+        review = self.classify([shared])
+        self.assertEqual(review["deletable"], [])
+        result = self.db.archive_or_delete_library_prompts(
+            [shared],
+            [],
+            expected_epoch=self.epoch,
+            candidates={},
+            delete_paired={shared: "0" * 64},
+        )
+        self.assertEqual((result["deleted"], result["archived"]), (0, 1))
+        self.assertEqual(result["changed"], 1)
+        self.assertEqual(archived_ids(self.db), [shared])
+
+    def test_a_positive_and_its_own_negative_selected_together(self):
+        cat, blur, _pair = self.paired("Cat", "blur")
+        self.image(blur, "blur.png")  # the negative is a Library prompt too
+        review = self.classify([cat, blur])
+        self.assertEqual(review["deletable"], [cat])
+        result = self.delete_paired([cat], review)
+        self.assertEqual((result["deleted"], result["archived"]), (1, 1))
+        self.assertEqual(archived_ids(self.db), [blur])
+        self.assertNotIn(cat, prompt_ids(self.db))
+
+    def test_a_self_pair_is_deleted(self):
+        pair = self.db.save_prompt_pair("Same", "Same")
+        same = self.db.get_prompt_pair(pair)["positive_prompt_id"]
+        review = self.classify([same])
+        self.assertEqual(review["deletable"], [same])
+        self.assertEqual(review["paired_counts"]["kept_negatives"], 0)
+        self.assertEqual(self.delete_paired([same], review)["deleted"], 1)
+        self.assertNotIn(same, prompt_ids(self.db))
+
+    def test_drift_after_the_review_archives_and_counts_changed(self):
+        cases = {
+            "pair added": lambda p: self.db.save_prompt_pair("Fox", "new"),
+            "pair edited": lambda p: self.db.update_prompt_pair_metadata(
+                self.pair_rows(p)[0][0], title="Renamed"
+            ),
+            "pairs gone": lambda p: self.db.delete_prompt_pair(self.pair_rows(p)[0][0]),
+            "now another's negative": lambda p: self.db.save_prompt_pair("Hen", "Fox"),
+        }
+        for name, change in cases.items():
+            with self.subTest(name):
+                fox, _neg, _pair = self.paired("Fox", "mist " + name)
+                review = self.classify([fox])
+                self.assertEqual(review["deletable"], [fox])
+                change(fox)
+                result = self.delete_paired([fox], review)
+                self.assertEqual(
+                    (result["deleted"], result["archived"], result["changed"]),
+                    (0, 1, 1),
+                )
+                self.assertIn(fox, archived_ids(self.db))
+                self.restore([fox])
+                with self.db.model.get_connection() as conn:
+                    conn.execute(
+                        "DELETE FROM prompt_pairs WHERE positive_prompt_id IN "
+                        "(SELECT id FROM prompts WHERE text IN ('Hen','Fox'))"
+                    )
+                    conn.commit()
+
+    def test_delete_paired_must_name_reviewed_archive_ids(self):
+        fox, _neg, _pair = self.paired("Fox")
+        review = self.classify([fox])
+        with self.assertRaises(ValueError):
+            self.db.archive_or_delete_library_prompts(
+                [],
+                [],
+                expected_epoch=self.epoch,
+                candidates={},
+                delete_paired={fox: review["review_digests"][fox]},
+            )
+        with self.assertRaises(ValueError):
+            self.db.archive_or_delete_library_prompts(
+                [fox],
+                [],
+                expected_epoch=self.epoch,
+                candidates={},
+                delete_paired={fox: "not a digest"},
+            )
+
+
+class TestArchivedShelfDelete(LibraryDeleteCase):
+    """#492: Delete… on the archived shelf deletes archived prompts permanently."""
+
+    def archive(self, *ids):
+        with self.db.model.get_connection() as conn:
+            conn.executemany(
+                f"INSERT INTO {ARCHIVE}(prompt_id, archived_at) VALUES (?, ?)",
+                [(pid, "2026-10-29T00:00:00Z") for pid in ids],
+            )
+            conn.commit()
+
+    def shelf_classify(self, ids):
+        return self.db.classify_library_delete(
+            ids, expected_epoch=self.epoch, shelf="archived"
+        )
+
+    def shelf_write(self, review, deletes=None, paired=None):
+        """What the archived shelf's client sends: only what it deletes."""
+        deletes = review["delete"] if deletes is None else deletes
+        paired = review["deletable"] if paired is None else paired
+        return self.db.archive_or_delete_library_prompts(
+            list(paired),
+            list(deletes),
+            expected_epoch=self.epoch,
+            candidates=review["fingerprints"],
+            delete_paired={pid: review["review_digests"][pid] for pid in paired},
+            shelf="archived",
+        )
+
+    def test_classify_on_the_archived_shelf(self):
+        owl, _neg, _pair = self.paired("Owl", "dark")
+        shared = save(self.db, "Shared")
+        self.image(shared, "shared.png")
+        self.db.save_prompt_pair("Dog", "Shared")  # another positive's negative
+        loose = save(self.db, "Loose")
+        self.image(loose, "loose.png")
+        guarded = save(self.db, "Guarded", tags=["__protected__"])
+        self.image(guarded, "guarded.png")
+        shown = save(self.db, "Shown")
+        self.image(shown, "shown.png")
+        self.archive(owl, shared, loose, guarded)
+        review = self.shelf_classify([owl, shared, loose, guarded, shown, 999999])
+        self.assertEqual(review["archive"], [owl, shared])
+        self.assertEqual(review["deletable"], [owl])
+        self.assertEqual(review["delete"], [loose])
+        self.assertEqual(review["protected"], [guarded])
+        self.assertEqual(review["not_archived"], [shown])
+        self.assertEqual(review["already_archived"], [])
+        self.assertEqual(review["not_found"], [999999])
+        self.assertEqual(review["image_links"], 1)
+        # The active shelf is unchanged: archived prompts are only counted there.
+        active = self.classify([owl, loose, shown])
+        self.assertEqual(active["already_archived"], [owl, loose])
+        self.assertEqual(active["not_archived"], [])
+        self.assertEqual(active["delete"], [shown])
+
+    def test_the_write_deletes_archived_prompts_and_their_pairs(self):
+        owl, owl_negative, pair = self.paired("Owl", "dark")
+        loose = save(self.db, "Loose")
+        self.image(loose, "loose.png")
+        self.archive(owl, loose)
+        result = self.shelf_write(self.shelf_classify([owl, loose]))
+        self.assertEqual(
+            (result["deleted"], result["archived"], result["changed"]), (2, 0, 0)
+        )
+        self.assertEqual((result["pairs_removed"], result["not_archived"]), (1, 0))
+        self.assertNotIn(owl, prompt_ids(self.db))
+        self.assertNotIn(loose, prompt_ids(self.db))
+        self.assertIn(owl_negative, prompt_ids(self.db))
+        self.assertIsNone(self.db.get_prompt_pair(pair))
+        self.assertEqual(archived_ids(self.db), [])
+        self.assertEqual(rows(self.db, "PRAGMA foreign_key_check"), [])
+
+    def test_drift_leaves_the_prompt_archived_and_untouched(self):
+        owl, _neg, pair = self.paired("Owl", "dark")
+        hen, _hen_negative, hen_pair = self.paired("Hen", "fog")
+        loose = save(self.db, "Loose")
+        self.image(loose, "loose.png")
+        self.archive(owl, hen, loose)
+        review = self.shelf_classify([owl, hen, loose])
+        before = rows(self.db, "SELECT id,hash,updated_at FROM prompts ORDER BY id")
+        self.db.update_prompt_pair_metadata(pair, notes="edited after the review")
+        # Reviewed as unpaired, it gains a pair before the write.
+        self.db.save_prompt_pair("Loose", "grain")
+        # A pair removed since: no longer what the review promised.
+        with self.db.model.get_connection() as conn:
+            conn.execute("DELETE FROM prompt_pairs WHERE id=?", (hen_pair,))
+            conn.commit()
+        result = self.shelf_write(review)
+        self.assertEqual(
+            (result["deleted"], result["archived"], result["changed"]), (0, 0, 3)
+        )
+        self.assertEqual(archived_ids(self.db), sorted([owl, hen, loose]))
+        self.assertEqual(
+            rows(self.db, "SELECT id,hash,updated_at FROM prompts ORDER BY id")[
+                : len(before)
+            ],
+            before,
+        )
+
+    def test_a_prompt_restored_since_the_review_is_kept(self):
+        owl, _neg, _pair = self.paired("Owl", "dark")
+        self.archive(owl)
+        review = self.shelf_classify([owl])
+        self.restore([owl])
+        result = self.shelf_write(review)
+        self.assertEqual((result["deleted"], result["not_archived"]), (0, 1))
+        self.assertIn(owl, prompt_ids(self.db))
+        self.assertEqual(archived_ids(self.db), [])
+
+    def test_the_negative_of_a_deleted_positive_stays_archived(self):
+        # #482's rule, kept on this shelf: X is only Dog's negative.
+        dog, shared, _pair = self.paired("Dog", "Shared")
+        self.image(shared, "shared.png")
+        self.archive(dog, shared)
+        review = self.shelf_classify([dog, shared])
+        self.assertEqual(review["deletable"], [dog])
+        self.assertEqual(review["archive"], [dog, shared])
+        result = self.shelf_write(review)
+        self.assertEqual((result["deleted"], result["pairs_removed"]), (1, 1))
+        self.assertEqual(archived_ids(self.db), [shared])
+
+    def test_mixed_outcomes_are_each_counted_once(self):
+        owl, _neg, _pair = self.paired("Owl", "dark")
+        hen, _neg2, hen_pair = self.paired("Hen", "fog")
+        loose = save(self.db, "Loose")
+        self.image(loose, "loose.png")
+        guarded = save(self.db, "Guarded", tags=["__protected__"])
+        self.image(guarded, "guarded.png")
+        gone = save(self.db, "Gone")
+        self.image(gone, "gone.png")
+        self.archive(owl, hen, loose, guarded, gone)
+        review = self.shelf_classify([owl, hen, loose, guarded, gone])
+        self.db.update_prompt_pair_metadata(hen_pair, notes="drifted")
+        self.restore([loose])
+        with self.db.model.get_connection() as conn:
+            conn.execute("DELETE FROM generated_images WHERE prompt_id=?", (gone,))
+            conn.execute("DELETE FROM prompts WHERE id=?", (gone,))
+            conn.commit()
+        result = self.shelf_write(review, deletes=[loose, gone])
+        self.assertEqual(
+            {k: result[k] for k in ("deleted", "changed", "not_found", "not_archived")},
+            {"deleted": 1, "changed": 1, "not_found": 1, "not_archived": 1},
+        )
+        self.assertNotIn(owl, prompt_ids(self.db))
+        self.assertEqual(archived_ids(self.db), sorted([hen, guarded]))
+
+    def test_shelf_must_be_active_or_archived(self):
+        owl, _neg, _pair = self.paired("Owl")
+        with self.assertRaises(ValueError):
+            self.db.classify_library_delete(
+                [owl], expected_epoch=self.epoch, shelf="trash"
+            )
+        with self.assertRaises(ValueError):
+            self.db.archive_or_delete_library_prompts(
+                [owl], [], expected_epoch=self.epoch, candidates={}, shelf="trash"
+            )

tests/test_history_read_fence.py

@@ -7,6 +7,7 @@ from contextlib import closing
 from pathlib import Path
 from unittest.mock import patch
 
+from database import restore_stage
 from database.execution_history import HistoryEpochChanged, notify_history_restore
 from tests import test_execution_history_database as history_tests
 
@@ -41,7 +42,12 @@ class HistoryReadFenceTests(unittest.TestCase):
         generation = fence.begin()
         with reader.recorded_history_snapshot() as epoch:
             original = reader.get_history_run(start.run_id)
-            with patch("database.execution_history.notify_history_restore"):
+            # The open snapshot keeps the WAL from being truncated; do not
+            # sit out the full 30 s checkpoint wait for it (#487).
+            with (
+                patch("database.execution_history.notify_history_restore"),
+                patch.object(restore_stage, "CHECKPOINT_BUSY_MS", 50),
+            ):
                 writer.model.restore_from_file(source)
             self.assertEqual(reader.get_execution_epoch(), epoch)
             self.assertEqual(original["run"]["storage_epoch"], epoch)

tests/test_history_reads.py

@@ -400,6 +400,32 @@ class HistoryReadTests(unittest.TestCase):
                 pass
         self.assertFalse(conn.in_transaction)
 
+    def test_a_deleted_negative_is_unavailable_and_a_negative_only_one_is_not(self):
+        # #443: a Library delete can remove an unpaired prompt a run used as
+        # its negative. The run's prompt ids are live hints, so a deleted one
+        # reads unavailable; a negative-only prompt stays available.
+        db = self.database()
+        self.saved(db)
+        self.saved(db, "negative", 2)
+        start = self.capture(db)
+        with db.recorded_history_snapshot():
+            context = db.get_history_run(start.run_id)["contexts"][0]
+        self.assertTrue(context["navigation"]["negative_available"])
+        with db.model.get_connection() as conn:
+            conn.execute(
+                "INSERT INTO prompt_pairs(id,positive_prompt_id,negative_prompt_id) "
+                "VALUES(9,1,2)"
+            )
+        with db.recorded_history_snapshot():
+            context = db.get_history_run(start.run_id)["contexts"][0]
+        self.assertTrue(context["navigation"]["negative_available"])
+        with db.model.get_connection() as conn:
+            conn.execute("DELETE FROM prompt_pairs WHERE id=9")
+            conn.execute("DELETE FROM prompts WHERE id=2")
+        with db.recorded_history_snapshot():
+            context = db.get_history_run(start.run_id)["contexts"][0]
+        self.assertFalse(context["navigation"]["negative_available"])
+
     def test_detail_preserves_full_text_snapshots_hints_and_archive(self):
         db = self.database()
         self.saved(db)

tests/test_image_delete_routes.py

@@ -0,0 +1,409 @@
+"""Delete selected images: the review and the apply job (#480).
+
+``POST /prompt_manager/images/delete/preview`` reviews both modes;
+``POST /prompt_manager/maintenance/apply {token, mode}`` removes the files'
+records (library mode, with a removal mark) or moves the files to the trash
+first (trash mode, the fake trash here). No path unlinks a media file.
+"""
+
+import asyncio
+import os
+import sys
+import sqlite3
+from pathlib import Path
+from unittest.mock import patch
+
+try:
+    from tests import fake_trash
+    from tests.disk_waits import DISK_BOUND_SECONDS
+    from tests.test_api_duplicate_files import DuplicateFilesTestCase
+except ImportError:  # discovered with tests/ as the top-level directory
+    import fake_trash
+    from disk_waits import DISK_BOUND_SECONDS
+    from test_api_duplicate_files import DuplicateFilesTestCase
+
+from py.api import image_delete
+from py.api.image_delete import file_check, lexical_problem
+
+PREVIEW = "/prompt_manager/images/delete/preview"
+APPLY = "/prompt_manager/maintenance/apply"
+LISTING = "/prompt_manager/images/output"
+
+
+class ImageDeleteTestCase(DuplicateFilesTestCase):
+    async def get_application(self):
+        app = await super().get_application()
+        self.fake = fake_trash.install(Path(self.tmpdir) / "fake-trash")
+        self.addCleanup(fake_trash.uninstall)
+        return app
+
+    def target(self, path, index=0):
+        roots = self.api._get_all_output_dirs()
+        return {
+            "root_index": index,
+            "root_scope": self.api._gallery_root_scope(roots[index], index),
+            "path": path,
+        }
+
+    async def review(self, paths, status=200):
+        items = [p if isinstance(p, dict) else self.target(p) for p in paths]
+        return await self.post(PREVIEW, {"items": items}, status)
+
+    async def delete(self, paths, mode):
+        plan = await self.review(paths)
+        body = await self.post(APPLY, {"token": plan["token"], "mode": mode}, 202)
+        job = self.api._jobs.get(body["job"]["id"])
+        await asyncio.wait_for(asyncio.shield(job.task), DISK_BOUND_SECONDS)
+        return plan, job
+
+    async def listed(self):
+        response = await self.client.get(LISTING, params={"mode": "workspace"})
+        page = await response.json()
+        return [image["path"] for image in page["images"]]
+
+    def link(self, name, text="a prompt"):
+        prompt_id = self.save(text)
+        return self.api.db.link_image_to_prompt(
+            str(prompt_id), str(self.output_dir / name)
+        )
+
+    def count(self, sql):
+        conn = sqlite3.connect(self.api.db.model.db_path)
+        try:
+            return conn.execute(sql).fetchone()[0]
+        finally:
+            conn.close()
+
+    @staticmethod
+    def details(job, group):
+        return [row["detail"] for row in job.detail()["outcomes"][group]]
+
+
+class TestReview(ImageDeleteTestCase):
+    async def test_review_counts_records_and_refuses_what_it_cannot_delete(self):
+        self.write("a.png", b"aaa", mtime=1_000_000)
+        self.write("b.png", b"bbb", mtime=2_000_000)
+        self.link("a.png", "only a")
+        self.fake.refuse[str(self.output_dir / "b.png")] = "no-trash"
+        plan = await self.review(["a.png", "b.png", "missing.png"])
+        self.assertEqual(plan["library"], {"count": 2})
+        self.assertEqual(plan["trash"], {"count": 1})
+        self.assertEqual(plan["refused"]["counts"], {"not-listed": 1})
+        self.assertEqual(plan["trash_refused"]["counts"], {"no-trash": 1})
+        self.assertEqual(plan["records"]["prompt_links"], 1)
+        self.assertEqual(plan["orphaned_prompts"]["count"], 1)
+        self.assertIn(plan["backup"]["policy"], ("on", "off"))
+        self.assertNotIn(self.tmpdir, str(plan))
+        # The review wrote nothing.
+        self.assertEqual(self.count("SELECT COUNT(*) FROM generated_images"), 1)
+        self.assertEqual(self.fake.moved, [])
+
+    async def test_body_shapes_and_the_cap(self):
+        await self.post(PREVIEW, {}, 400)
+        await self.post(PREVIEW, {"items": [], "mode": "trash"}, 400)
+        too_many = [self.target(f"{n}.png") for n in range(501)]
+        await self.post(PREVIEW, {"items": too_many}, 400)
+
+    async def test_mode_is_required_and_only_for_this_plan(self):
+        self.write("a.png", b"aaa")
+        self.link("a.png")
+        plan = await self.review(["a.png"])
+        # No explicit, exact mode: refused, never a default (least of all trash).
+        for body in (
+            {"token": plan["token"]},
+            {"token": plan["token"], "mode": None},
+            {"token": plan["token"], "mode": ""},
+            {"token": plan["token"], "mode": "TRASH"},
+            {"token": plan["token"], "mode": "delete"},
+            {"token": plan["token"], "mode": ["trash"]},
+            {"token": plan["token"], "mode": True},
+        ):
+            with self.subTest(body=body):
+                await self.post(APPLY, body, 400)
+        self.assertTrue((self.output_dir / "a.png").exists())
+        self.assertEqual(self.fake.moved, [])
+        self.assertEqual(self.count("SELECT COUNT(*) FROM generated_images"), 1)
+        # The refusals left the token usable: an explicit mode still applies.
+        body = await self.post(APPLY, {"token": plan["token"], "mode": "library"}, 202)
+        job = self.api._jobs.get(body["job"]["id"])
+        await asyncio.wait_for(asyncio.shield(job.task), DISK_BOUND_SECONDS)
+        self.assertEqual(job.scope["mode"], "library")
+        self.assertTrue((self.output_dir / "a.png").exists())
+        self.assertEqual(self.fake.moved, [])
+
+    async def test_mode_on_another_plan_is_refused(self):
+        plan = await self.post(
+            "/prompt_manager/maintenance/preview",
+            {"operation": "missing_links", "options": {}},
+            200,
+        )
+        await self.post(APPLY, {"token": plan["token"], "mode": "trash"}, 400)
+
+
+class TestLibraryMode(ImageDeleteTestCase):
+    async def test_records_go_and_the_file_stays_hidden(self):
+        self.write("a.png", b"aaa", mtime=1_000_000)
+        self.write("b.png", b"bbb", mtime=2_000_000)
+        self.link("a.png")
+        self.assertEqual(sorted(await self.listed()), ["a.png", "b.png"])
+        before = os.stat(self.output_dir / "a.png")
+        _plan, job = await self.delete(["a.png"], "library")
+        self.assertEqual(job.state, "finished", job.summary())
+        self.assertEqual(self.count("SELECT COUNT(*) FROM generated_images"), 0)
+        after = os.stat(self.output_dir / "a.png")
+        self.assertEqual(
+            (before.st_size, before.st_mtime_ns), (after.st_size, after.st_mtime_ns)
+        )
+        self.assertEqual(await self.listed(), ["b.png"])
+        # A later scan or link never brings it back.
+        self.assertEqual(self.link("a.png", "rescanned"), 0)
+        self.assertEqual(
+            self.api._removed_paths([self.output_dir / "a.png"]),
+            {str(self.output_dir / "a.png")},
+        )
+        self.assertEqual(self.fake.moved, [])
+
+    async def test_a_modified_file_shows_again(self):
+        self.write("a.png", b"aaa", mtime=1_000_000)
+        await self.delete(["a.png"], "library")
+        self.assertEqual(await self.listed(), [])
+        self.write("a.png", b"new and longer", mtime=3_000_000)
+        self.api.invalidate_gallery_cache()
+        self.assertEqual(await self.listed(), ["a.png"])
+
+    async def test_a_safety_backup_is_taken_first(self):
+        self.write("a.png", b"aaa")
+        with patch.object(self.api, "_safety_backup_policy", return_value="on"):
+            await self.delete(["a.png"], "library")
+        self.assertEqual(len(self.backups()), 1)
+
+
+class TestTrashMode(ImageDeleteTestCase):
+    async def test_the_file_moves_first_then_its_records_go(self):
+        self.write("a.png", b"aaa")
+        self.link("a.png")
+        seen = {}
+        original = self.fake.move
+
+        def move(path, roots):
+            # The records still exist while the file moves.
+            seen["links"] = self.count("SELECT COUNT(*) FROM generated_images")
+            return original(path, roots)
+
+        self.fake.move = move
+        _plan, job = await self.delete(["a.png"], "trash")
+        self.assertEqual(job.state, "finished", job.summary())
+        self.assertEqual(seen["links"], 1)
+        self.assertFalse((self.output_dir / "a.png").exists())
+        [(source, destination)] = self.fake.moved
+        self.assertTrue(os.path.exists(destination))
+        self.assertEqual(self.count("SELECT COUNT(*) FROM generated_images"), 0)
+        self.assertEqual(self.api.db.removal_marks(), {})
+
+    async def test_a_refused_move_changes_nothing(self):
+        self.write("a.png", b"aaa")
+        self.link("a.png")
+        plan = await self.review(["a.png"])
+        self.fake.refuse[str(self.output_dir / "a.png")] = "locked"
+        body = await self.post(APPLY, {"token": plan["token"], "mode": "trash"}, 202)
+        job = self.api._jobs.get(body["job"]["id"])
+        await asyncio.wait_for(asyncio.shield(job.task), DISK_BOUND_SECONDS)
+        self.assertTrue((self.output_dir / "a.png").exists())
+        self.assertEqual(self.count("SELECT COUNT(*) FROM generated_images"), 1)
+        self.assertEqual(self.api.db.removal_marks(), {})
+        self.assertEqual(job.counters["not_changed"], 1)
+        self.assertEqual(
+            self.details(job, "not_changed"), [image_delete.REASONS["locked"]]
+        )
+
+    async def test_a_file_changed_after_the_review_is_not_changed(self):
+        self.write("a.png", b"aaa", mtime=1_000_000)
+        plan = await self.review(["a.png"])
+        self.write("a.png", b"changed bytes", mtime=2_000_000)
+        body = await self.post(APPLY, {"token": plan["token"], "mode": "trash"}, 202)
+        job = self.api._jobs.get(body["job"]["id"])
+        await asyncio.wait_for(asyncio.shield(job.task), DISK_BOUND_SECONDS)
+        self.assertTrue((self.output_dir / "a.png").exists())
+        self.assertEqual(self.fake.moved, [])
+        self.assertEqual(
+            self.details(job, "not_changed"), [image_delete.REASONS["changed"]]
+        )
+
+    async def test_a_records_failure_stops_the_job(self):
+        self.write("a.png", b"aaa", mtime=1_000_000)
+        self.write("b.png", b"bbb", mtime=2_000_000)
+        with patch.object(
+            type(self.api.db),
+            "remove_image_records",
+            side_effect=sqlite3.OperationalError("locked"),
+        ):
+            _plan, job = await self.delete(["a.png", "b.png"], "library")
+        self.assertEqual(job.state, "failed")
+        self.assertEqual(job.scope.get("failure"), "records-failed")
+        self.assertEqual(job.counters["errors"], 1)
+        self.assertEqual(
+            self.details(job, "not_changed"), [image_delete.REASONS["not-attempted"]]
+        )
+
+    async def test_nothing_is_ever_unlinked(self):
+        self.write("a.png", b"aaa")
+        self.write("b.png", b"bbb")
+        media = str(self.output_dir)
+        real_remove, real_unlink = os.remove, os.unlink
+
+        def guard(real):
+            def call(path, *args, **kwargs):
+                text = os.path.realpath(str(path))
+                if (
+                    text.startswith(os.path.realpath(media))
+                    and "thumbnails" not in text
+                ):
+                    raise AssertionError(f"unlinked a media file: {path}")
+                return real(path, *args, **kwargs)
+
+            return call
+
+        with (
+            patch("os.remove", guard(real_remove)),
+            patch("os.unlink", guard(real_unlink)),
+        ):
+            await self.delete(["a.png"], "trash")
+            await self.delete(["b.png"], "library")
+        self.assertTrue((self.output_dir / "b.png").exists())
+
+
+class TestFileCheck(ImageDeleteTestCase):
+    def test_lexical_codes(self):
+        self.assertEqual(lexical_problem("thumbnails/a.png"), "thumbnail")
+        self.assertEqual(lexical_problem(".Trash-1000/files/a.png"), "trash-folder")
+        self.assertEqual(lexical_problem("x/$RECYCLE.BIN/a.png"), "trash-folder")
+        self.assertEqual(lexical_problem("a.txt"), "not-media")
+        self.assertIsNone(lexical_problem(".Trashy/a.png"))
+        self.assertIsNone(lexical_problem("sub/a.png"))
+
+    def test_links_and_folders_leading_outside_are_refused(self):
+        root = str(self.output_dir)
+        outside = Path(self.tmpdir) / "elsewhere"
+        outside.mkdir()
+        (outside / "x.png").write_bytes(b"x")
+        try:
+            os.symlink(outside / "x.png", self.output_dir / "link.png")
+            os.symlink(outside, self.output_dir / "linked", target_is_directory=True)
+        except OSError:
+            self.skipTest("symlinks are not permitted here")
+        self.assertEqual(
+            file_check(str(self.output_dir / "link.png"), root, "link.png")[0], "link"
+        )
+        self.assertEqual(
+            file_check(str(self.output_dir / "linked/x.png"), root, "linked/x.png")[0],
+            "outside",
+        )
+        self.assertEqual(
+            file_check(str(self.output_dir / "gone.png"), root, "gone.png")[0], "gone"
+        )
+        self.write("ok.png", b"ok")
+        self.assertIsNone(
+            file_check(str(self.output_dir / "ok.png"), root, "ok.png")[0]
+        )
+
+    def test_windows_reason_says_why_plainly(self):
+        self.assertEqual(
+            image_delete.REASONS["windows-recycle"],
+            "Moving files to the Recycle Bin isn't available on Windows: files "
+            "larger than the bin's capacity would be deleted permanently.",
+        )
+
+    def test_reasons_cover_every_code(self):
+        from utils import trash
+
+        for code in trash.CODES:
+            self.assertIn(code, image_delete.REASONS)
+
+
+class TestMacOSOutcomes(ImageDeleteTestCase):
+    """The codes and the unconfirmed outcome the macOS backend adds (#499)."""
+
+    async def test_permission_and_cloud_refusals_show_their_sentences(self):
+        self.write("a.png", b"aaa")
+        self.write("b.png", b"bbb")
+        self.fake.refuse[str(self.output_dir / "a.png")] = "no-permission"
+        self.fake.refuse[str(self.output_dir / "b.png")] = "cloud-sync"
+        plan = await self.review(["a.png", "b.png"])
+        self.assertEqual(plan["trash"], {"count": 0})
+        self.assertEqual(
+            plan["trash_refused"]["counts"], {"no-permission": 1, "cloud-sync": 1}
+        )
+        details = {row["detail"] for row in plan["trash_refused"]["rows"]}
+        self.assertEqual(
+            details,
+            {image_delete.REASONS["no-permission"], image_delete.REASONS["cloud-sync"]},
+        )
+
+    async def test_an_unconfirmed_move_keeps_records_and_stops_the_job(self):
+        from utils import trash
+
+        self.write("a.png", b"aaa", mtime=1_000_000)
+        self.write("b.png", b"bbb", mtime=2_000_000)
+        self.link("a.png")
+        original = self.fake.move
+
+        def move(path, roots):
+            if path.endswith("a.png"):
+                original(path, roots)  # the file did leave its folder
+                raise trash.TrashUnconfirmed("resultingItemURL=None")
+            return original(path, roots)
+
+        self.fake.move = move
+        _plan, job = await self.delete(["a.png", "b.png"], "trash")
+        self.assertEqual(job.state, "failed")
+        self.assertEqual(job.scope.get("failure"), "records-failed")
+        self.assertEqual(
+            self.details(job, "errors"), [image_delete.REASONS["trash-unconfirmed"]]
+        )
+        self.assertEqual(self.count("SELECT COUNT(*) FROM generated_images"), 1)
+        self.assertEqual(
+            self.details(job, "not_changed"), [image_delete.REASONS["not-attempted"]]
+        )
+        self.assertTrue((self.output_dir / "b.png").exists())
+
+    async def test_a_refusal_detail_is_logged(self):
+        from utils import trash
+
+        self.write("a.png", b"aaa")
+
+        def move(path, roots):
+            raise trash.TrashRefused("no-permission", "NSCocoaErrorDomain 513")
+
+        self.fake.move = move
+        with self.assertLogs("prompt_manager.api", level="INFO") as logs:
+            _plan, job = await self.delete(["a.png"], "trash")
+        self.assertEqual(
+            self.details(job, "not_changed"), [image_delete.REASONS["no-permission"]]
+        )
+        self.assertTrue(any("NSCocoaErrorDomain 513" in line for line in logs.output))
+        self.assertTrue((self.output_dir / "a.png").exists())
+
+
+class TestNativeBackend(ImageDeleteTestCase):
+    """The real backend of this OS: Windows has no trash yet (#500).
+
+    Only library mode is applied, so even on macOS and Linux no file reaches
+    a real trash.
+    """
+
+    async def test_library_only_works_and_the_trash_is_unavailable_here(self):
+        fake_trash.uninstall()
+        self.write("a.png", b"aaa")
+        self.link("a.png")
+        plan = await self.review(["a.png"])
+        native_trash = sys.platform != "win32"
+        if not native_trash:
+            self.assertEqual(plan["trash"], {"count": 0})
+            self.assertEqual(plan["trash_refused"]["counts"], {"windows-recycle": 1})
+        body = await self.post(APPLY, {"token": plan["token"], "mode": "library"}, 202)
+        job = self.api._jobs.get(body["job"]["id"])
+        await asyncio.wait_for(asyncio.shield(job.task), DISK_BOUND_SECONDS)
+        self.assertEqual(job.counters["removed"], 1, job.summary())
+        self.assertTrue((self.output_dir / "a.png").exists())
+        self.assertEqual(self.count("SELECT COUNT(*) FROM generated_images"), 0)
+        self.assertEqual(await self.listed(), [])

tests/test_image_removal.py

@@ -0,0 +1,319 @@
+"""Removing one file's records from the library, and removal marks (#480)."""
+
+import hashlib
+import os
+import sqlite3
+import tempfile
+import unittest
+from pathlib import Path
+
+try:
+    from tests.open_handles import assert_closed
+except ImportError:  # discovered with tests/ as the top-level directory
+    from open_handles import assert_closed
+
+from database.image_removal_schema import (
+    image_removals_schema_error,
+    migrate_image_removals,
+)
+from database.models import PromptModel
+from database.operations import PromptDatabase
+
+
+def _locator(path):
+    return os.path.normcase(os.path.realpath(str(path)))
+
+
+class _RemovalCase(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.addCleanup(assert_closed, self, self.temp.name)
+        self.addCleanup(PromptModel.reset_schema_cache)
+        base = Path(self.temp.name)
+        self.root = base / "output"
+        self.root.mkdir()
+        # A second spelling of the folder (a symlink); Windows without the
+        # privilege has none, and the records then carry one spelling.
+        self.alias = base / "alias"
+        try:
+            self.alias.symlink_to(self.root, target_is_directory=True)
+        except OSError:
+            self.alias = None
+        self.db = PromptDatabase(str(base / "prompts.db"))
+        self.addCleanup(self.db.close_all)
+        self.epoch = self.db.get_execution_epoch()
+
+    def file(self, name, data=b"image-bytes"):
+        path = self.root / name
+        path.write_bytes(data)
+        return path
+
+    def removal(self, path):
+        root_key = os.path.normcase(os.path.realpath(str(self.root)))
+        return {
+            "spellings": [str(path)]
+            + ([str(self.alias / path.name)] if self.alias else []),
+            "locator": _locator(path),
+            "favorites": [(root_key, path.name.lower())],
+            "category": (root_key, path.name.lower()),
+        }
+
+    def link(self, path, text="a prompt", spelled=None):
+        prompt_id = self.db.save_prompt(text)
+        image_id = self.db.link_image_to_prompt(str(prompt_id), str(spelled or path))
+        self.assertTrue(image_id)
+        return prompt_id, image_id
+
+    def tag(self, path, tags):
+        data = path.read_bytes()
+        info = os.stat(path)
+        return self.db.replace_image_tags(
+            locator=_locator(path),
+            sha256=hashlib.sha256(data).hexdigest(),
+            size=info.st_size,
+            mtime_ns=info.st_mtime_ns,
+            expected_epoch=self.epoch,
+            expected_tag_revision=0,
+            tags=tags,
+        )
+
+    def queue(self, path):
+        data = path.read_bytes()
+        info = os.stat(path)
+        return self.db.record_review_item(
+            locator=_locator(path),
+            spelled_path=os.path.realpath(str(path)),
+            sha256=hashlib.sha256(data).hexdigest(),
+            size=info.st_size,
+            mtime_ns=info.st_mtime_ns,
+            epoch=self.epoch,
+            resolver_version=1,
+            evidence={"candidates": []},
+            candidate_count=0,
+            limited=True,
+        )
+
+    def count(self, sql, *params):
+        conn = sqlite3.connect(self.db.model.db_path)
+        try:
+            return conn.execute(sql, params).fetchone()[0]
+        finally:
+            conn.close()
+
+    def decorate(self, path):
+        """Give *path* one record of every kind."""
+        removal = self.removal(path)
+        root_key, relative = removal["favorites"][0]
+        self.tag(path, ["portrait"])
+        self.db.set_image_favorite(root_key, relative)
+        self.db.set_image_categories([removal["category"]], "keepers")
+        self.db.add_to_collection(items=[(root_key, relative)], name="Set")
+        return removal
+
+
+class ImageRemovalRecordsTests(_RemovalCase):
+    def test_counts_and_removes_every_record_under_every_spelling(self):
+        path = self.file("a.png")
+        other = self.file("b.png", b"other")
+        orphan, _ = self.link(path, "only this image")
+        shared, _ = self.link(path, "two images")
+        self.db.link_image_to_prompt(str(shared), str(other))
+        # A record under the symlinked folder spelling (or a third prompt).
+        self.link(path, "aliased", spelled=(self.alias or self.root) / "a.png")
+        removal = self.decorate(path)
+        self.assertTrue(self.queue(path))
+
+        counted = self.db.count_removal_records([removal])
+        self.assertEqual(
+            counted["records"],
+            {
+                "prompt_links": 3,
+                "pair_links": 0,
+                "image_tags": 1,
+                "auto_tagged": 0,
+                "categories": 1,
+                "collections": 1,
+                "favorites": 1,
+                "review_items": 1,
+            },
+        )
+        self.assertEqual(counted["orphaned_prompts"]["count"], 2)
+
+        removed = self.db.remove_image_records(removal)
+        self.assertEqual(removed["prompt_links"], 3)
+        self.assertEqual(removed["review_items"], 1)
+        self.assertEqual(self.count("SELECT COUNT(*) FROM generated_images"), 1)
+        for table in (
+            "media_image_tags",
+            "media_annotation_files",
+            "media_review_items",
+            "image_favorites",
+            "image_categories",
+            "image_collection_items",
+        ):
+            with self.subTest(table=table):
+                self.assertEqual(self.count(f"SELECT COUNT(*) FROM {table}"), 0)
+        # Prompts and the collection itself stay.
+        self.assertEqual(self.count("SELECT COUNT(*) FROM prompts"), 3)
+        self.assertEqual(self.count("SELECT COUNT(*) FROM image_collections"), 1)
+        self.assertTrue(path.exists())
+        self.assertIsNotNone(self.db.get_prompt_by_id(orphan))
+
+    def test_a_kept_review_item_keeps_the_annotation_rows(self):
+        path = self.file("a.png")
+        removal = self.decorate(path)
+        self.assertTrue(self.queue(path))
+        conn = sqlite3.connect(self.db.model.db_path)
+        try:
+            # A revised item is not settled; it still cites the bytes, whose
+            # foreign key is ON DELETE RESTRICT.
+            conn.execute("UPDATE media_review_items SET revision=1")
+            conn.commit()
+        finally:
+            conn.close()
+        removed = self.db.remove_image_records(removal)
+        self.assertEqual(removed["review_items"], 0)
+        self.assertEqual(removed["image_tags"], 1)
+        self.assertEqual(self.count("SELECT COUNT(*) FROM media_image_tags"), 0)
+        self.assertEqual(self.count("SELECT COUNT(*) FROM media_review_items"), 1)
+        self.assertEqual(self.count("SELECT COUNT(*) FROM media_annotation_files"), 1)
+
+    def test_mark_is_written_with_the_records_and_bumps_the_revision(self):
+        path = self.file("a.png")
+        self.link(path)
+        before = self.db.removal_revision()
+        info = os.stat(path)
+        self.db.remove_image_records(
+            self.removal(path), mark=(info.st_size, info.st_mtime_ns)
+        )
+        self.assertEqual(
+            self.db.removal_marks(),
+            {_locator(path): (info.st_size, info.st_mtime_ns)},
+        )
+        self.assertEqual(self.db.removal_revision(), before + 1)
+        self.assertEqual(self.db.clear_removal_marks([_locator(path)]), 1)
+        self.assertEqual(self.db.removal_marks(), {})
+        self.assertEqual(self.db.removal_revision(), before + 2)
+        self.assertEqual(self.db.clear_removal_marks([_locator(path)]), 0)
+
+    def test_a_failure_rolls_back_everything(self):
+        path = self.file("a.png")
+        self.link(path)
+        removal = self.decorate(path)
+        broken = {**removal, "category": ("only-one-value",)}
+        with self.assertRaises(sqlite3.Error):
+            self.db.remove_image_records(broken, mark=(1, 1))
+        self.assertEqual(self.count("SELECT COUNT(*) FROM generated_images"), 1)
+        self.assertEqual(self.count("SELECT COUNT(*) FROM media_image_tags"), 1)
+        self.assertEqual(self.db.removal_marks(), {})
+
+    def test_parity_with_the_legacy_single_delete(self):
+        path = self.file("a.png")
+        _prompt, image_id = self.link(path)
+        twin = PromptDatabase(str(Path(self.temp.name) / "twin.db"))
+        try:
+            twin_prompt = twin.save_prompt("a prompt")
+            twin_image = twin.link_image_to_prompt(str(twin_prompt), str(path))
+            self.assertTrue(twin.delete_image(twin_image))
+            self.db.remove_image_records(self.removal(path))
+            for table in (
+                "generated_images",
+                "image_prompt_pairs",
+                "workflow_documents",
+            ):
+                with self.subTest(table=table):
+                    conn = sqlite3.connect(twin.model.db_path)
+                    try:
+                        legacy = conn.execute(
+                            f"SELECT COUNT(*) FROM {table}"
+                        ).fetchone()[0]
+                    finally:
+                        conn.close()
+                    self.assertEqual(
+                        self.count(f"SELECT COUNT(*) FROM {table}"), legacy
+                    )
+        finally:
+            twin.close_all()
+        self.assertIsNotNone(image_id)
+
+
+class RemovalMarkGateTests(_RemovalCase):
+    """A marked file is never linked again; any record write shows it again."""
+
+    def hide(self, path):
+        info = os.stat(path)
+        self.db.remove_image_records(
+            self.removal(path), mark=(info.st_size, info.st_mtime_ns)
+        )
+
+    def test_a_marked_file_is_not_linked_again(self):
+        path = self.file("a.png")
+        self.hide(path)
+        prompt_id = self.db.save_prompt("scanned again")
+        self.assertEqual(self.db.link_image_to_prompt(str(prompt_id), str(path)), 0)
+        self.assertEqual(self.count("SELECT COUNT(*) FROM generated_images"), 0)
+        self.assertIn(_locator(path), self.db.removal_marks())
+
+    def test_a_changed_file_drops_its_stale_mark_and_links(self):
+        path = self.file("a.png")
+        self.hide(path)
+        path.write_bytes(b"new bytes, new size")
+        prompt_id = self.db.save_prompt("a new image at the same path")
+        self.assertTrue(self.db.link_image_to_prompt(str(prompt_id), str(path)))
+        self.assertEqual(self.db.removal_marks(), {})
+
+    def test_explicit_record_writes_clear_the_mark(self):
+        writers = {
+            "favorite": lambda path, key: self.db.set_image_favorite(*key),
+            "category": lambda path, key: self.db.set_image_categories([key], "c"),
+            "collection": lambda path, key: self.db.add_to_collection(
+                items=[key], name="Set"
+            ),
+            "tags": lambda path, key: self.tag(path, ["t"]),
+        }
+        for kind, write in writers.items():
+            with self.subTest(kind=kind):
+                path = self.file(f"{kind}.png", kind.encode())
+                self.hide(path)
+                self.assertIn(_locator(path), self.db.removal_marks())
+                write(path, self.removal(path)["favorites"][0])
+                self.assertNotIn(_locator(path), self.db.removal_marks())
+
+
+class ImageRemovalSchemaTests(unittest.TestCase):
+    def setUp(self):
+        self.conn = sqlite3.connect(":memory:")
+        self.addCleanup(self.conn.close)
+
+    def test_missing_is_allowed_only_for_old_backups(self):
+        self.assertIsNone(image_removals_schema_error(self.conn))
+        self.assertIsNotNone(
+            image_removals_schema_error(self.conn, allow_missing=False)
+        )
+
+    def test_install_is_valid_and_idempotent(self):
+        migrate_image_removals(self.conn)
+        migrate_image_removals(self.conn)
+        self.assertIsNone(image_removals_schema_error(self.conn, allow_missing=False))
+        self.assertEqual(
+            self.conn.execute("SELECT revision FROM image_removals_meta").fetchall(),
+            [(0,)],
+        )
+
+    def test_invalid_values_and_objects_are_refused(self):
+        migrate_image_removals(self.conn)
+        self.conn.execute("INSERT INTO image_removals VALUES ('', 1, 1, 'now')")
+        self.assertIn("invalid values", image_removals_schema_error(self.conn))
+        self.conn.execute("DELETE FROM image_removals")
+        self.conn.execute("CREATE INDEX extra ON image_removals(size)")
+        self.assertIn("unsupported", image_removals_schema_error(self.conn))
+
+    def test_a_foreign_table_definition_is_refused(self):
+        self.conn.execute("CREATE TABLE image_removals (locator TEXT)")
+        with self.assertRaises(sqlite3.DatabaseError):
+            migrate_image_removals(self.conn)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_image_removal_gaps.py

@@ -0,0 +1,261 @@
+"""Removal-mark gaps after #480, and trash folders inside output roots (#501).
+
+- Thumbnail jobs and the legacy auto-tag listing skip a library-removed file.
+- Missing-file links also forgets the marks of files that are gone (only under
+  a source that can be read now).
+- Every walker skips a trash folder that sits inside an output root.
+"""
+
+import asyncio
+import os
+import shutil
+import sqlite3
+from pathlib import Path
+from unittest.mock import patch
+
+try:
+    from tests.disk_waits import DISK_BOUND_SECONDS
+    from tests.test_image_delete_routes import ImageDeleteTestCase
+except ImportError:  # discovered with tests/ as the top-level directory
+    from disk_waits import DISK_BOUND_SECONDS
+    from test_image_delete_routes import ImageDeleteTestCase
+
+from py.api import images as images_module
+from py.api.admin import _collect_media_files
+from py.api.autotag_routes import AutotagRoutesMixin
+from utils.image_monitor import ImageGenerationHandler
+
+MAINTENANCE_PREVIEW = "/prompt_manager/maintenance/preview"
+MAINTENANCE_APPLY = "/prompt_manager/maintenance/apply"
+
+
+class _GapCase(ImageDeleteTestCase):
+    def marks(self):
+        conn = sqlite3.connect(self.api.db.model.db_path)
+        try:
+            return [
+                row[0] for row in conn.execute("SELECT locator FROM image_removals")
+            ]
+        finally:
+            conn.close()
+
+    def revision(self):
+        conn = sqlite3.connect(self.api.db.model.db_path)
+        try:
+            return conn.execute(
+                "SELECT revision FROM image_removals_meta WHERE singleton_id=1"
+            ).fetchone()[0]
+        finally:
+            conn.close()
+
+
+class TestThumbnailJobsSkipHiddenFiles(_GapCase):
+    async def test_missing_and_rebuild_plans_leave_a_removed_file_out(self):
+        self.write("hidden.png", b"hidden bytes", mtime=1_000_000)
+        self.write("shown.png", b"shown bytes", mtime=2_000_000)
+        await self.delete(["hidden.png"], "library")
+        thumbs = self.output_dir / "thumbnails"
+        for mode in ("missing", "rebuild"):
+            with self.subTest(mode=mode):
+                plan = self.api._plan_thumbnails(self.output_dir, thumbs, mode=mode)
+                sources = [src.name for src, _dst, _video in plan["targets"]]
+                self.assertEqual(sources, ["shown.png"])
+                self.assertEqual(plan["missing"], 1)
+
+    async def test_a_changed_file_gets_its_preview_again(self):
+        self.write("hidden.png", b"hidden bytes", mtime=1_000_000)
+        await self.delete(["hidden.png"], "library")
+        self.write("hidden.png", b"new and longer bytes", mtime=3_000_000)
+        plan = self.api._plan_thumbnails(
+            self.output_dir, self.output_dir / "thumbnails"
+        )
+        self.assertEqual([t[0].name for t in plan["targets"]], ["hidden.png"])
+
+
+class TestLegacyAutotagListing(_GapCase):
+    async def test_scan_output_dir_leaves_a_removed_file_out(self):
+        self.write("hidden.png", b"hidden bytes", mtime=1_000_000)
+        self.write("shown.png", b"shown bytes", mtime=2_000_000)
+        await self.delete(["hidden.png"], "library")
+        with patch.object(
+            self.api, "_find_comfyui_output_dir", return_value=str(self.output_dir)
+        ):
+            response = await self.client.get("/prompt_manager/scan_output_dir")
+            body = await response.json()
+        self.assertEqual([image["filename"] for image in body["images"]], ["shown.png"])
+
+
+class TestMissingFileLinksPrunesMarks(_GapCase):
+    async def links_review(self, status=200):
+        return await self.post(
+            MAINTENANCE_PREVIEW, {"operation": "missing_links", "options": {}}, status
+        )
+
+    async def apply(self, token, status=202):
+        body = await self.post(MAINTENANCE_APPLY, {"token": token}, status)
+        if status != 202:
+            return body
+        job = self.api._jobs.get(body["job"]["id"])
+        await asyncio.wait_for(asyncio.shield(job.task), DISK_BOUND_SECONDS)
+        return job
+
+    async def removed(self, name):
+        self.write("other.png", b"another output")  # the source lists something
+        self.write(name, f"bytes of {name}".encode(), mtime=1_000_000)
+        await self.delete([name], "library")
+        self.assertEqual(len(self.marks()), 1)
+
+    async def test_the_mark_of_a_gone_file_is_counted_and_forgotten(self):
+        await self.removed("gone.png")
+        # Not an unlink by PromptManager: the user deleted it elsewhere.
+        os.remove(self.output_dir / "gone.png")
+        plan = await self.links_review()
+        self.assertEqual(plan["scope"]["count"], 1)
+        self.assertEqual(
+            plan["scope"]["label"], "1 removed image whose file is gone or changed"
+        )
+        before = self.revision()
+        job = await self.apply(plan["token"])
+        self.assertEqual(job.state, "finished", job.summary())
+        self.assertEqual(self.marks(), [])
+        self.assertGreater(self.revision(), before)
+
+    async def test_the_mark_of_a_present_file_stays(self):
+        await self.removed("kept.png")
+        plan = await self.links_review()
+        self.assertEqual(plan["scope"]["count"], 0)
+        self.assertEqual(plan["scope"]["label"], "No links to missing files")
+        self.assertEqual(len(self.marks()), 1)
+
+    async def test_a_mark_under_an_unreadable_source_stays(self):
+        await self.removed("away.png")
+        os.remove(self.output_dir / "away.png")
+        with patch(
+            "database.maintenance.readable_roots",
+            side_effect=lambda r: [False] * len(r),
+        ):
+            plan = await self.links_review()
+            self.assertEqual(plan["scope"]["count"], 0)
+        self.assertEqual(len(self.marks()), 1)
+
+    async def test_the_mark_of_a_changed_file_is_forgotten(self):
+        await self.removed("changed.png")
+        self.write("changed.png", b"other and longer bytes", mtime=4_000_000)
+        plan = await self.links_review()
+        self.assertEqual(plan["scope"]["count"], 1)
+        job = await self.apply(plan["token"])
+        self.assertEqual(job.state, "finished", job.summary())
+        self.assertEqual(self.marks(), [])
+
+    async def test_marks_under_an_empty_source_stay(self):
+        # An unplugged drive leaves its mount point: an empty, readable folder.
+        await self.removed("mounted.png")
+        for child in list(self.output_dir.iterdir()):
+            if child.is_dir():
+                shutil.rmtree(child)
+            else:
+                os.remove(child)
+        plan = await self.links_review()
+        self.assertEqual(plan["scope"]["count"], 0)
+        self.assertEqual(len(self.marks()), 1)
+
+    async def test_a_name_the_folder_still_lists_is_not_gone(self):
+        # A case-sensitive NTFS folder: lstat of the normcased locator fails.
+        await self.removed("Listed.png")
+        real_lstat = os.lstat
+        locator = self.marks()[0]
+
+        def lstat(path, *args, **kwargs):
+            if os.fspath(path) == locator:
+                raise FileNotFoundError(path)
+            return real_lstat(path, *args, **kwargs)
+
+        with (
+            patch("database.maintenance.os.lstat", side_effect=lstat),
+            patch("database.maintenance.os.path.normcase", side_effect=str.lower),
+        ):
+            from database.maintenance import _stale_marks
+
+            stale = _stale_marks([(locator, 1, 1)], [str(self.output_dir)])
+        self.assertEqual(stale, [])
+
+    async def test_a_file_back_before_the_apply_changes_the_plan(self):
+        await self.removed("back.png")
+        path = self.output_dir / "back.png"
+        saved = Path(self.tmpdir) / "saved.png"
+        shutil.copy2(path, saved)
+        os.remove(path)
+        plan = await self.links_review()
+        shutil.copy2(saved, path)
+        job = await self.apply(plan["token"])
+        self.assertEqual(job.state, "failed", job.summary())
+        self.assertEqual(len(self.marks()), 1)
+
+
+class TestWalkersSkipTrashFolders(_GapCase):
+    def seed(self):
+        self.write("kept.png", b"kept")
+        self.write(
+            "x.png", b"trashed x", folder=self.output_dir / ".Trash-1000" / "files"
+        )
+        self.write(
+            "y.png", b"trashed y", folder=self.output_dir / "sub" / "$RECYCLE.BIN"
+        )
+        self.write("z.png", b"trashed z", folder=self.output_dir / ".Trashes")
+
+    def test_walk_media_and_the_settled_entry(self):
+        self.seed()
+        walked = sorted(
+            Path(entry.path).name
+            for entry in images_module._walk_media(self.output_dir, 100)
+        )
+        self.assertEqual(walked, ["kept.png"])
+        for relative in (
+            os.path.join(".Trash-1000", "files", "x.png"),
+            os.path.join("sub", "$RECYCLE.BIN", "y.png"),
+        ):
+            with self.subTest(relative=relative):
+                self.assertIsNone(
+                    images_module._settled_entry(self.output_dir, relative)
+                )
+
+    def test_scan_duplicate_and_autotag_walkers(self):
+        self.seed()
+        collected = [
+            Path(p).name for p in _collect_media_files([self.output_dir], [".png"])
+        ]
+        self.assertEqual(collected, ["kept.png"])
+        found, _truncated = AutotagRoutesMixin._collect_scan_files(self.output_dir)
+        self.assertEqual([p.name for p in found], ["kept.png"])
+
+    def test_the_image_monitor(self):
+        monitor = ImageGenerationHandler.__new__(ImageGenerationHandler)
+        monitor.supported_extensions = (".png",)
+        base = str(self.output_dir)
+        self.assertTrue(monitor.is_image_file(os.path.join(base, "a.png")))
+        for folder in (".Trash-1000", "$Recycle.Bin", ".Trashes", ".trash"):
+            with self.subTest(folder=folder):
+                self.assertFalse(
+                    monitor.is_image_file(os.path.join(base, folder, "files", "a.png"))
+                )
+
+    def test_the_image_monitor_watches_a_root_named_like_a_trash_folder(self):
+        monitor = ImageGenerationHandler.__new__(ImageGenerationHandler)
+        monitor.supported_extensions = (".png",)
+        root = os.path.join(str(self.output_dir), ".Trash-1000")
+        monitor.watched_roots = (root,)
+        self.assertTrue(monitor.is_image_file(os.path.join(root, "sub", "a.png")))
+        self.assertFalse(
+            monitor.is_image_file(os.path.join(root, "sub", ".Trashes", "a.png"))
+        )
+
+    async def test_the_workspace_listing(self):
+        self.seed()
+        self.assertEqual(await self.listed(), ["kept.png"])
+
+    def test_a_root_named_like_a_trash_folder_still_lists(self):
+        root = Path(self.tmpdir) / ".Trash-1000"
+        (root / "inner").mkdir(parents=True)
+        (root / "inner" / "a.png").write_bytes(b"a")
+        walked = [Path(e.path).name for e in images_module._walk_media(root, 10)]
+        self.assertEqual(walked, ["a.png"])

tests/test_image_return.py

@@ -0,0 +1,244 @@
+"""Show removed images and Return to library (#498).
+
+``GET /prompt_manager/images/output?mode=workspace&removed=1`` lists only the
+files a removal mark hides; every workspace page carries ``removed_total``.
+``POST /prompt_manager/images/removed/return {items | filter}`` starts a
+``scan`` job titled "Return images to the library": it deletes the marks of
+the files that are still hidden, then scans exactly those files, so their
+prompt links come back from their metadata. Image tags, category,
+collections and favorites do not come back.
+"""
+
+import asyncio
+import hashlib
+import os
+import sqlite3
+from unittest.mock import patch
+
+try:
+    from tests.disk_waits import DISK_BOUND_SECONDS
+    from tests.test_api_admin import _write_png
+    from tests.test_image_delete_routes import LISTING, ImageDeleteTestCase
+except ImportError:  # discovered with tests/ as the top-level directory
+    from disk_waits import DISK_BOUND_SECONDS
+    from test_api_admin import _write_png
+    from test_image_delete_routes import LISTING, ImageDeleteTestCase
+
+RETURN = "/prompt_manager/images/removed/return"
+
+
+class _ReturnCase(ImageDeleteTestCase):
+    async def page(self, status=200, **query):
+        params = {"mode": "workspace", **query}
+        response = await self.client.get(LISTING, params=params)
+        self.assertEqual(response.status, status, await response.text())
+        return await response.json()
+
+    async def removed_paths(self):
+        page = await self.page(removed="1")
+        return [image["path"] for image in page["images"]]
+
+    async def give_back(self, body, status=202):
+        answer = await self.post(RETURN, body, status)
+        if status != 202:
+            return answer
+        job = self.api._jobs.get(answer["job"]["id"])
+        await asyncio.wait_for(asyncio.shield(job.task), DISK_BOUND_SECONDS)
+        job.answer = answer
+        return job
+
+    def png(self, name, text):
+        path = self.output_dir / name
+        _write_png(path, text)
+        return path
+
+    def marks(self):
+        conn = sqlite3.connect(self.api.db.model.db_path)
+        try:
+            return conn.execute("SELECT COUNT(*) FROM image_removals").fetchone()[0]
+        finally:
+            conn.close()
+
+
+class TestRemovedView(_ReturnCase):
+    async def test_the_view_lists_only_hidden_files_and_both_views_count_them(self):
+        self.write("a.png", b"aaa", mtime=1_000_000)
+        self.write("b.png", b"bbb", mtime=2_000_000)
+        self.write("c.png", b"ccc", mtime=3_000_000)
+        await self.delete(["a.png", "b.png"], "library")
+        shown = await self.page()
+        self.assertEqual([i["path"] for i in shown["images"]], ["c.png"])
+        self.assertEqual(shown["removed_total"], 2)
+        removed = await self.page(removed="1")
+        self.assertEqual(
+            sorted(i["path"] for i in removed["images"]), ["a.png", "b.png"]
+        )
+        self.assertEqual(removed["total"], 2)
+        self.assertEqual(removed["removed_total"], 2)
+        # A search applies inside the view.
+        self.assertEqual(
+            [i["path"] for i in (await self.page(removed="1", q="b."))["images"]],
+            ["b.png"],
+        )
+
+    async def test_no_marks_count_zero(self):
+        self.write("a.png", b"aaa")
+        self.assertEqual((await self.page())["removed_total"], 0)
+        self.assertEqual((await self.page(removed="1"))["images"], [])
+
+    async def test_refused_combinations(self):
+        for query in (
+            {"removed": "2"},
+            {"removed": "1", "favorites": "1"},
+            {"removed": "1", "collection": "1"},
+            {"removed": "1", "category": "x"},
+            {"removed": "1", "tags": "x"},
+            {"removed": "1", "sort": "rating"},
+        ):
+            with self.subTest(query=query):
+                await self.page(status=400, **query)
+
+
+class TestReturn(_ReturnCase):
+    async def test_return_shows_the_file_and_rescans_its_links_but_not_its_tags(self):
+        path = self.png("linked.png", "a returned prompt")
+        prompt_id = self.save("a returned prompt")
+        self.api.db.link_image_to_prompt(str(prompt_id), str(path))
+        target = self.target("linked.png")
+        info = os.stat(path)
+        self.api.db.add_image_tags(
+            locator=os.path.normcase(os.path.realpath(path)),
+            sha256=hashlib.sha256(path.read_bytes()).hexdigest(),
+            size=info.st_size,
+            mtime_ns=info.st_mtime_ns,
+            expected_epoch=self.api.db.get_execution_epoch(),
+            tags=["kept-before"],
+        )
+        self.assertEqual(self.count("SELECT COUNT(*) FROM media_image_tags"), 1)
+        await self.delete(["linked.png"], "library")
+        self.assertEqual(await self.removed_paths(), ["linked.png"])
+        before = os.stat(path)
+        job = await self.give_back({"items": [target]})
+        self.assertEqual(job.state, "finished", job.summary())
+        self.assertEqual(self.marks(), 0)
+        self.assertEqual(await self.listed(), ["linked.png"])
+        self.assertEqual(await self.removed_paths(), [])
+        # The links come back from the file's metadata; the tags do not.
+        self.assertEqual(
+            self.count(
+                "SELECT COUNT(*) FROM generated_images WHERE prompt_id IS NOT NULL"
+            ),
+            1,
+        )
+        self.assertEqual(self.count("SELECT COUNT(*) FROM media_image_tags"), 0)
+        after = os.stat(path)
+        self.assertEqual(
+            (before.st_size, before.st_mtime_ns), (after.st_size, after.st_mtime_ns)
+        )
+        self.assertEqual(self.fake.moved, [])
+        self.assertEqual(job.kind, "scan")
+        self.assertEqual(job.title, "Return images to the library")
+        self.assertEqual(job.answer["returned"], 1)
+
+    async def test_a_file_that_is_not_hidden_is_not_changed(self):
+        self.write("shown.png", b"shown")
+        self.write("hidden.png", b"hidden", mtime=1_000_000)
+        await self.delete(["hidden.png"], "library")
+        job = await self.give_back(
+            {"items": [self.target("shown.png"), self.target("hidden.png")]}
+        )
+        self.assertEqual(job.state, "finished", job.summary())
+        self.assertEqual(job.answer["returned"], 1)
+        self.assertEqual(job.answer["not_removed"], 1)
+        self.assertEqual(self.marks(), 0)
+
+    async def test_nothing_hidden_is_refused(self):
+        self.write("shown.png", b"shown")
+        body = await self.give_back({"items": [self.target("shown.png")]}, 400)
+        self.assertEqual(body["code"], "no-images")
+
+    async def test_return_after_a_cancelled_scan_links_the_file(self):
+        path = self.png("again.png", "linked again")
+        await self.delete(["again.png"], "library")
+        cancelled = self.api._start_scan_job()
+        self.api._jobs.cancel(cancelled.id)
+        await asyncio.wait_for(asyncio.shield(cancelled.task), DISK_BOUND_SECONDS)
+        self.assertTrue(cancelled.cancelled)
+        job = await self.give_back({"items": [self.target("again.png")]})
+        self.assertEqual(job.state, "finished", job.summary())
+        self.assertEqual(
+            self.count(
+                "SELECT COUNT(*) FROM generated_images "
+                "WHERE image_path LIKE '%again.png'"
+            ),
+            1,
+        )
+        del path
+
+    async def test_other_bulk_routes_refuse_the_removed_filter(self):
+        self.write("hidden.png", b"hidden", mtime=1_000_000)
+        await self.delete(["hidden.png"], "library")
+        await self.post(
+            "/prompt_manager/images/delete/preview", {"filter": {"removed": "1"}}, 400
+        )
+        self.assertEqual(self.marks(), 1)
+
+    async def test_select_all_matching_in_the_view(self):
+        for n in range(3):
+            self.write(f"{n}.png", f"bytes {n}".encode(), mtime=1_000_000 + n)
+        await self.delete(["0.png", "1.png"], "library")
+        job = await self.give_back({"filter": {"removed": "1"}})
+        self.assertEqual(job.state, "finished", job.summary())
+        self.assertEqual(sorted(await self.listed()), ["0.png", "1.png", "2.png"])
+
+    async def test_busy_beside_a_scan_changes_nothing(self):
+        self.write("hidden.png", b"hidden", mtime=1_000_000)
+        await self.delete(["hidden.png"], "library")
+        gate = asyncio.Event()
+
+        async def held(job):
+            await gate.wait()
+            job.finish("finished")
+
+        running = self.api._jobs.start(
+            "scan", "Scan for metadata", record_changing=True, runner=held
+        )
+        try:
+            body = await self.give_back({"items": [self.target("hidden.png")]}, 409)
+            self.assertEqual(body["code"], "busy")
+            self.assertEqual(self.marks(), 1)
+        finally:
+            gate.set()
+            await asyncio.wait_for(asyncio.shield(running.task), DISK_BOUND_SECONDS)
+
+    async def test_body_shapes(self):
+        await self.post(RETURN, {}, 400)
+        await self.post(RETURN, {"items": []}, 400)
+        too_many = [self.target(f"{n}.png") for n in range(501)]
+        await self.post(RETURN, {"items": too_many}, 400)
+
+
+class TestMarksCacheRace(_ReturnCase):
+    async def test_a_listing_read_during_the_clear_does_not_keep_the_file_hidden(self):
+        from database import image_removal, image_removal_schema
+
+        self.write("raced.png", b"raced", mtime=1_000_000)
+        await self.delete(["raced.png"], "library")
+        real_clear = image_removal_schema.clear_marks
+        stale = dict(self.api.db.removal_marks())
+
+        def clear_then_read(conn, locators):
+            removed = real_clear(conn, locators)
+            # Another thread's connection reads the marks before this
+            # transaction commits: it still sees them, under the new generation.
+            key = (
+                self.api._database_identity(self.api.db),
+                image_removal_schema.generation(),
+            )
+            self.api._marks_cache = (key, stale)
+            return removed
+
+        with patch.object(image_removal, "clear_marks", side_effect=clear_then_read):
+            job = await self.give_back({"items": [self.target("raced.png")]})
+        self.assertEqual(job.state, "finished", job.summary())
+        self.assertEqual(await self.listed(), ["raced.png"])

tests/test_library.py

@@ -345,7 +345,8 @@ class TestLibrary(unittest.TestCase):
         self.assertEqual(
             (parent["title"], parent["notes"]), ("Portrait", "keep\nnotes")
         )
-        self.assertNotIn("archived", parent)
+        # The parent's own archive state (#443), never a pair's.
+        self.assertIs(parent["archived"], False)
         self.assertRegex(parent["edit_token"], r"^[0-9a-f]{64}$")
         self.assertEqual(page["items"][1]["title"], " \t\u00a0\u3000")
         self.assertEqual(self.db.list_library(text="Portrait")["total"], 1)
@@ -1520,6 +1521,7 @@ class TestLibrary(unittest.TestCase):
                     "tags",
                     "rating",
                     "notes",
+                    "archived",
                     "variants",
                 },
             )

tests/test_library_delete_routes.py

@@ -0,0 +1,538 @@
+"""#443 (D152): the Library delete, archive and restore routes, and ingestion after."""
+
+import json
+import os
+from unittest.mock import patch
+
+from tests.test_api_admin import AdminAPITestCase  # first: it stubs ComfyUI
+from database.execution_history_schema import rotate_history_epoch  # noqa: E402
+from database.prompt_archive import TABLE as ARCHIVE  # noqa: E402
+from database.safety_backup import SafetyBackupFailed  # noqa: E402
+from py.config import PromptManagerConfig  # noqa: E402
+from utils.hashing import generate_prompt_hash  # noqa: E402
+
+PREVIEW = "/prompt_manager/library/delete/preview"
+DELETE = "/prompt_manager/library/delete"
+RESTORE = "/prompt_manager/library/restore"
+
+
+def graph(positive, negative="blur"):
+    return {
+        "1": {"class_type": "CLIPTextEncode", "inputs": {"text": positive}},
+        "2": {"class_type": "CLIPTextEncode", "inputs": {"text": negative}},
+        "3": {
+            "class_type": "KSampler",
+            "inputs": {"positive": ["1", 0], "negative": ["2", 0]},
+        },
+    }
+
+
+class LibraryDeleteRouteCase(AdminAPITestCase):
+    def epoch(self):
+        return self.api.db.get_library_options()["library_epoch"]
+
+    def save(self, text, **metadata):
+        return self.api.db.save_prompt(
+            text, prompt_hash=generate_prompt_hash(text), **metadata
+        )
+
+    def paired(self, positive, negative="blur"):
+        pair = self.api.db.save_prompt_pair(positive, negative)
+        return self.api.db.get_prompt_pair(pair)["positive_prompt_id"]
+
+    def rows(self, sql, params=()):
+        with self.api.db.model.get_connection() as conn:
+            return [tuple(row) for row in conn.execute(sql, params).fetchall()]
+
+    def ids(self):
+        return sorted(row[0] for row in self.rows("SELECT id FROM prompts"))
+
+    def archived(self):
+        return sorted(row[0] for row in self.rows(f"SELECT prompt_id FROM {ARCHIVE}"))
+
+    def backups(self):
+        folder = os.path.dirname(self.api.db.model.db_path)
+        return sorted(name for name in os.listdir(folder) if ".backup_" in name)
+
+    async def post(self, url, body):
+        response = await self.client.request("POST", url, json=body)
+        return response.status, await response.json()
+
+    async def review(self, ids):
+        status, body = await self.post(
+            PREVIEW, {"prompt_ids": ids, "expected_epoch": self.epoch()}
+        )
+        self.assertEqual(status, 200, body)
+        return body
+
+    async def confirm(self, review, backup=None):
+        return await self.post(
+            DELETE,
+            {
+                "archive_ids": review["archive"],
+                "delete_ids": review["delete"],
+                "expected_epoch": review["library_epoch"],
+                "backup": backup or review["backup"],
+            },
+        )
+
+    def policy(self, on):
+        previous = PromptManagerConfig.SAFETY_BACKUP
+        PromptManagerConfig.SAFETY_BACKUP = on
+        self.addCleanup(setattr, PromptManagerConfig, "SAFETY_BACKUP", previous)
+
+
+class TestLibraryDeleteRoutes(LibraryDeleteRouteCase):
+    async def test_preview_then_delete_archives_deletes_and_backs_up(self):
+        self.policy(True)
+        plain = self.save("Plain")
+        guarded = self.save("Guarded", tags=["__protected__"])
+        positive = self.paired("Cat")
+        review = await self.review([plain, guarded, positive, 99999])
+        self.assertEqual(
+            {
+                key: review[key]
+                for key in ("delete", "archive", "protected", "not_found")
+            },
+            {
+                "delete": [plain],
+                "archive": [positive],
+                "protected": [guarded],
+                "not_found": 1,
+            },
+        )
+        self.assertEqual(review["backup"], "on")
+        self.assertTrue(review["disk"]["sufficient"])
+        status, body = await self.confirm(review)
+        self.assertEqual(status, 200, body)
+        self.assertEqual(
+            (body["deleted"], body["archived"], body["changed"]), (1, 1, 0)
+        )
+        self.assertEqual(self.backups(), [body["backup"]])
+        self.assertNotIn(os.sep, body["backup"])
+        self.assertNotIn(plain, self.ids())
+        self.assertEqual(self.archived(), [positive])
+        # The backup still holds the deleted prompt.
+        import sqlite3
+
+        path = os.path.join(os.path.dirname(self.api.db.model.db_path), body["backup"])
+        with sqlite3.connect(path) as copy:
+            self.assertEqual(
+                copy.execute(
+                    "SELECT COUNT(*) FROM prompts WHERE id=?", (plain,)
+                ).fetchone()[0],
+                1,
+            )
+        copy.close()
+        # The hold ended: nothing is listed as running.
+        self.assertEqual(self.api._jobs.running(), [])
+
+    async def test_archive_only_takes_no_backup(self):
+        self.policy(True)
+        positive = self.paired("Cat")
+        shared = self.save("Shared")
+        self.api.db.save_prompt_pair("Dog", "Shared")  # archive-only (#482)
+        self.api.db.link_image_to_prompt(shared, "/tmp/shared-443.png")
+        # Nothing could be deleted: no disk plan. (#482: a deletable prompt has one.)
+        self.assertIsNone((await self.review([shared]))["disk"])
+        review = await self.review([positive])
+        self.assertIsNotNone(review["disk"])
+        status, body = await self.confirm(review)
+        self.assertEqual((status, body["archived"], body["backup"]), (200, 1, None))
+        self.assertEqual(self.backups(), [])
+
+    async def test_policy_off_takes_none_unless_the_review_promised_one(self):
+        plain = self.save("Plain")
+        other = self.save("Other")
+        self.policy(False)
+        review = await self.review([plain])
+        self.assertEqual((review["backup"], review["disk"]), ("off", None))
+        status, body = await self.confirm(review)
+        self.assertEqual((status, body["deleted"], body["backup"]), (200, 1, None))
+        # Reviewed with the policy on, turned off before the confirm: kept.
+        review = await self.review([other])
+        status, body = await self.confirm(review, backup="on")
+        self.assertEqual(status, 200)
+        self.assertIsNotNone(body["backup"])
+
+    async def test_a_failed_backup_changes_nothing(self):
+        self.policy(True)
+        plain = self.save("Plain")
+        positive = self.paired("Cat")
+        review = await self.review([plain, positive])
+        with patch(
+            "py.api.maintenance.take_safety_backup",
+            side_effect=SafetyBackupFailed("x"),
+        ):
+            status, body = await self.confirm(review)
+        self.assertEqual((status, body["code"]), (500, "backup-failed"))
+        self.assertIn("nothing was changed", body["error"])
+        self.assertIn(plain, self.ids())
+        self.assertEqual(self.archived(), [])
+
+    async def test_a_short_disk_refuses_before_any_change(self):
+        self.policy(True)
+        plain = self.save("Plain")
+        from py.api import maintenance
+
+        with patch.object(maintenance, "_free_bytes", return_value=0):
+            review = await self.review([plain])
+            self.assertFalse(review["disk"]["sufficient"])
+            self.assertIn("Nothing was changed", review["disk"]["message"])
+            status, body = await self.confirm(review)
+        self.assertEqual((status, body["code"]), (507, "insufficient-space"))
+        self.assertIn(plain, self.ids())
+
+    async def test_busy_beside_a_record_changing_job(self):
+        plain = self.save("Plain")
+        review = await self.review([plain])
+        async with self.api._jobs.hold("scan", "Scan", admission="records"):
+            status, body = await self.confirm(review)
+        self.assertEqual((status, body["code"]), (409, "busy"))
+        self.assertEqual(body["running"]["title"], "Scan")
+        self.assertIn(plain, self.ids())
+
+    async def test_restored_storage_answers_409_on_every_route(self):
+        plain = self.save("Plain")
+        review = await self.review([plain])
+        rotate_history_epoch(self.api.db.model.get_connection())
+        status, body = await self.confirm(review)
+        self.assertEqual((status, body["code"]), (409, "storage-changed"))
+        for url in (PREVIEW, RESTORE):
+            status, body = await self.post(
+                url, {"prompt_ids": [plain], "expected_epoch": review["library_epoch"]}
+            )
+            self.assertEqual((status, body["code"]), (409, "storage-changed"))
+        self.assertIn(plain, self.ids())
+
+    async def test_restore_route(self):
+        positive = self.paired("Cat")
+        await self.confirm(await self.review([positive]))
+        status, body = await self.post(
+            RESTORE, {"prompt_ids": [positive, 99999], "expected_epoch": self.epoch()}
+        )
+        self.assertEqual(status, 200)
+        self.assertEqual((body["restored"], body["not_found"]), (1, 1))
+        self.assertEqual(self.archived(), [])
+
+    async def test_bodies_are_validated(self):
+        plain = self.save("Plain")
+        epoch = self.epoch()
+        selection = {"prompt_ids": [plain], "expected_epoch": epoch}
+        for url, body in (
+            (PREVIEW, {**selection, "extra": 1}),
+            (PREVIEW, {"prompt_ids": [], "expected_epoch": epoch}),
+            (PREVIEW, {"prompt_ids": [True], "expected_epoch": epoch}),
+            (PREVIEW, {"prompt_ids": list(range(1, 1002)), "expected_epoch": epoch}),
+            (PREVIEW, {"prompt_ids": [plain], "expected_epoch": "nope"}),
+            (RESTORE, {"prompt_ids": [plain]}),
+            (DELETE, {**selection}),
+            (
+                DELETE,
+                {
+                    "archive_ids": [],
+                    "delete_ids": [],
+                    "expected_epoch": epoch,
+                    "backup": "on",
+                },
+            ),
+            (
+                DELETE,
+                {
+                    "archive_ids": [plain],
+                    "delete_ids": [plain],
+                    "expected_epoch": epoch,
+                    "backup": "on",
+                },
+            ),
+            (
+                DELETE,
+                {
+                    "archive_ids": [],
+                    "delete_ids": [plain],
+                    "expected_epoch": epoch,
+                    "backup": "maybe",
+                },
+            ),
+            (
+                DELETE,
+                {
+                    "archive_ids": list(range(1, 600)),
+                    "delete_ids": list(range(600, 1100)),
+                    "expected_epoch": epoch,
+                    "backup": "off",
+                },
+            ),
+        ):
+            with self.subTest(url=url, body=body):
+                status, answer = await self.post(url, body)
+                self.assertEqual(status, 400, answer)
+                self.assertFalse(answer["success"])
+        for url in (PREVIEW, DELETE, RESTORE):
+            response = await self.client.request(
+                "POST", url, data="[1]", headers={"Content-Type": "application/json"}
+            )
+            self.assertEqual(response.status, 400)
+        self.assertIn(plain, self.ids())
+
+    async def test_the_legacy_bulk_delete_is_unchanged(self):
+        plain = self.save("Plain")
+        positive = self.paired("Cat")
+        response = await self.client.request(
+            "POST", "/prompt_manager/bulk/delete", json={"prompt_ids": [positive]}
+        )
+        self.assertEqual(response.status, 409)
+        response = await self.client.request(
+            "POST", "/prompt_manager/bulk/delete", json={"prompt_ids": [plain]}
+        )
+        self.assertEqual((await response.json())["deleted_count"], 1)
+        self.assertEqual(self.archived(), [])
+
+    async def test_shelf_parameter_and_cursor_scope(self):
+        kept = [self.paired(f"Kept {i}") for i in range(3)]
+        gone = [self.paired(f"Gone {i}") for i in range(3)]
+        await self.confirm(await self.review(gone))
+        response = await self.client.request(
+            "GET", "/prompt_manager/library?limit=2&shelf=active"
+        )
+        page = await response.json()
+        self.assertEqual(page["archived_total"], 3)
+        self.assertTrue(set(item["id"] for item in page["items"]) <= set(kept))
+        response = await self.client.request(
+            "GET",
+            "/prompt_manager/library?limit=2&shelf=archived"
+            f"&cursor={page['next_cursor']}",
+        )
+        self.assertEqual(response.status, 400)
+        response = await self.client.request(
+            "GET", "/prompt_manager/library?shelf=archived"
+        )
+        archived = await response.json()
+        self.assertEqual(sorted(item["id"] for item in archived["items"]), gone)
+        self.assertTrue(all(item["archived"] for item in archived["items"]))
+        response = await self.client.request("GET", "/prompt_manager/library?shelf=all")
+        self.assertEqual(response.status, 400)
+
+
+class TestPairedDeleteRoutes(LibraryDeleteRouteCase):
+    """#482 (D160): Delete permanently with a prompt's own saved pairs."""
+
+    async def confirm_paired(self, review, ids, backup=None, digests=None):
+        return await self.post(
+            DELETE,
+            {
+                "archive_ids": review["archive"],
+                "delete_ids": review["delete"],
+                "expected_epoch": review["library_epoch"],
+                "backup": backup or review["backup"],
+                "delete_paired_ids": ids,
+                "paired_digests": digests
+                or {str(pid): review["review_digests"][str(pid)] for pid in ids},
+            },
+        )
+
+    async def test_preview_reports_deletable_and_a_paired_only_delete_backs_up(self):
+        self.policy(True)
+        cat = self.paired("Cat")
+        shared = self.save("Shared")
+        self.api.db.save_prompt_pair("Dog", "Shared")
+        self.api.db.link_image_to_prompt(shared, "/tmp/shared-482.png")
+        review = await self.review([cat, shared])
+        self.assertEqual(review["archive"], [cat, shared])
+        self.assertEqual(review["deletable"], [cat])
+        self.assertEqual(list(review["review_digests"]), [str(cat)])
+        self.assertEqual(
+            review["paired_counts"],
+            {"pairs": 1, "archived_pairs": 0, "variants": 1, "kept_negatives": 1},
+        )
+        self.assertEqual(review["paired_image_links"], 0)
+        # A selection with nothing in the delete class still checks the disk.
+        self.assertTrue(review["disk"]["sufficient"])
+        status, body = await self.confirm_paired(review, [cat])
+        self.assertEqual(status, 200, body)
+        self.assertEqual(
+            (body["deleted"], body["archived"], body["pairs_removed"]), (1, 1, 1)
+        )
+        self.assertEqual(self.backups(), [body["backup"]])
+        self.assertNotIn(cat, self.ids())
+        self.assertEqual(self.archived(), [shared])
+
+    async def test_a_body_without_the_new_keys_is_the_443_delete(self):
+        cat = self.paired("Cat")
+        review = await self.review([cat])
+        status, body = await self.confirm(review)
+        self.assertEqual(status, 200, body)
+        self.assertEqual((body["deleted"], body["archived"]), (0, 1))
+        self.assertIn(cat, self.ids())
+
+    async def test_paired_bodies_are_validated(self):
+        cat = self.paired("Cat")
+        plain = self.save("Plain")
+        review = await self.review([cat, plain])
+        digest = review["review_digests"][str(cat)]
+        base = {
+            "archive_ids": review["archive"],
+            "delete_ids": review["delete"],
+            "expected_epoch": review["library_epoch"],
+            "backup": "off",
+        }
+        cases = [
+            {"delete_paired_ids": [cat]},  # without its digests
+            {"delete_paired_ids": [plain], "paired_digests": {str(plain): digest}},
+            {"delete_paired_ids": [cat], "paired_digests": {}},
+            {"delete_paired_ids": [cat], "paired_digests": {str(cat): "x"}},
+            {"delete_paired_ids": "all", "paired_digests": {}},
+        ]
+        for extra in cases:
+            with self.subTest(extra=extra):
+                status, body = await self.post(DELETE, {**base, **extra})
+                self.assertEqual((status, body["code"]), (400, "invalid-request"))
+        self.assertIn(cat, self.ids())
+
+    async def test_a_short_disk_refuses_a_paired_only_delete(self):
+        self.policy(True)
+        cat = self.paired("Cat")
+        from py.api import maintenance
+
+        with patch.object(maintenance, "_free_bytes", return_value=0):
+            review = await self.review([cat])
+            self.assertFalse(review["disk"]["sufficient"])
+            status, body = await self.confirm_paired(review, [cat])
+        self.assertEqual((status, body["code"]), (507, "insufficient-space"))
+        self.assertIn(cat, self.ids())
+
+
+class TestArchivedShelfDeleteRoutes(LibraryDeleteRouteCase):
+    """#492: Delete… on the archived shelf (``shelf: "archived"``)."""
+
+    def archive(self, *ids):
+        with self.api.db.model.get_connection() as conn:
+            conn.executemany(
+                f"INSERT INTO {ARCHIVE}(prompt_id, archived_at) VALUES (?, ?)",
+                [(pid, "2026-10-29T00:00:00Z") for pid in ids],
+            )
+            conn.commit()
+
+    async def shelf_review(self, ids):
+        status, body = await self.post(
+            PREVIEW,
+            {"prompt_ids": ids, "expected_epoch": self.epoch(), "shelf": "archived"},
+        )
+        self.assertEqual(status, 200, body)
+        return body
+
+    async def shelf_confirm(self, review):
+        paired = review["deletable"]
+        return await self.post(
+            DELETE,
+            {
+                "archive_ids": paired,
+                "delete_ids": review["delete"],
+                "expected_epoch": review["library_epoch"],
+                "backup": review["backup"],
+                "delete_paired_ids": paired,
+                "paired_digests": {
+                    str(pid): review["review_digests"][str(pid)] for pid in paired
+                },
+                "shelf": "archived",
+            },
+        )
+
+    async def test_an_archived_paired_prompt_is_deleted_after_a_backup(self):
+        self.policy(True)
+        cat = self.paired("Cat")
+        shown = self.save("Shown")
+        self.api.db.link_image_to_prompt(shown, "/tmp/shown-492.png")
+        self.archive(cat)
+        review = await self.shelf_review([cat, shown])
+        self.assertEqual(
+            (review["deletable"], review["delete"], review["not_archived"]),
+            ([cat], [], 1),
+        )
+        self.assertTrue(review["disk"]["sufficient"])
+        status, body = await self.shelf_confirm(review)
+        self.assertEqual(status, 200, body)
+        self.assertEqual(
+            (body["deleted"], body["archived"], body["pairs_removed"]), (1, 0, 1)
+        )
+        # The held write classified the archived shelf too, so it backed up.
+        self.assertEqual(self.backups(), [body["backup"]])
+        self.assertNotIn(cat, self.ids())
+        self.assertEqual(self.archived(), [])
+
+    async def test_an_archived_unpaired_prompt_is_deleted_after_a_backup(self):
+        self.policy(True)
+        loose = self.save("Loose")
+        self.api.db.link_image_to_prompt(loose, "/tmp/loose-492.png")
+        self.archive(loose)
+        review = await self.shelf_review([loose])
+        self.assertEqual(review["delete"], [loose])
+        status, body = await self.shelf_confirm(review)
+        self.assertEqual(status, 200, body)
+        self.assertEqual((body["deleted"], body["changed"]), (1, 0))
+        self.assertEqual(self.backups(), [body["backup"]])
+
+    async def test_the_shelf_is_validated_and_optional(self):
+        cat = self.paired("Cat")
+        status, body = await self.post(
+            PREVIEW,
+            {"prompt_ids": [cat], "expected_epoch": self.epoch(), "shelf": "trash"},
+        )
+        self.assertEqual((status, body["code"]), (400, "invalid-request"))
+        review = await self.review([cat])
+        base = {
+            "archive_ids": review["archive"],
+            "delete_ids": review["delete"],
+            "expected_epoch": review["library_epoch"],
+            "backup": "off",
+        }
+        status, body = await self.post(DELETE, {**base, "shelf": 1})
+        self.assertEqual((status, body["code"]), (400, "invalid-request"))
+        # The active shelf named explicitly is #443's delete.
+        status, body = await self.post(DELETE, {**base, "shelf": "active"})
+        self.assertEqual(status, 200, body)
+        self.assertEqual(self.archived(), [cat])
+
+
+class TestIngestionAfterArchive(LibraryDeleteRouteCase):
+    def scan(self, name, positive, negative="blur"):
+        meta = {"prompt": json.dumps(graph(positive, negative))}
+        path = self.output_dir / name
+        path.write_bytes(b"png")
+        return self.api._ingest_scanned_file(path, meta)
+
+    async def test_a_scan_after_archive_creates_no_duplicate_and_keeps_it_archived(
+        self,
+    ):
+        self.assertEqual(self.scan("first.png", "Sunset"), "added")
+        positive = self.api.db.get_prompt_by_hash(generate_prompt_hash("Sunset"))["id"]
+        await self.confirm(await self.review([positive]))
+        before = self.ids()
+        self.scan("second.png", "Sunset")
+        self.scan("third.png", "  sunset ", "other negative")
+        self.assertEqual(
+            [i for i in self.ids() if i not in before],
+            [
+                self.api.db.get_prompt_by_hash(generate_prompt_hash("other negative"))[
+                    "id"
+                ]
+            ],
+        )
+        self.assertEqual(self.archived(), [positive])
+        linked = self.rows(
+            "SELECT COUNT(*) FROM generated_images WHERE prompt_id=?", (positive,)
+        )
+        self.assertEqual(linked, [(3,)])
+        response = await self.client.request("GET", "/prompt_manager/library")
+        self.assertNotIn(
+            positive, [item["id"] for item in (await response.json())["items"]]
+        )
+
+    async def test_a_scan_after_delete_creates_the_prompt_again(self):
+        plain = self.save("Lonely sunset")
+        await self.confirm(await self.review([plain]))
+        self.assertEqual(self.scan("again.png", "Lonely sunset"), "added")
+        again = self.api.db.get_prompt_by_hash(generate_prompt_hash("Lonely sunset"))
+        self.assertIsNotNone(again)
+        self.assertNotEqual(again["id"], plain)
+        self.assertEqual(self.archived(), [])

tests/test_lora_manager_layout.py

@@ -14,6 +14,7 @@ import sys
 import tempfile
 import unittest
 from pathlib import Path
+from types import SimpleNamespace
 from unittest.mock import patch
 
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
@@ -753,6 +754,17 @@ class LocalMediaTests(LayoutTestCase):
         self.assertEqual(layout_module.VIDEO_SUFFIXES, frozenset(VIDEO_EXTENSIONS))
 
 
+# Windows path rules without the filesystem. On Windows ntpath.realpath asks
+# the network for \\server\share and waits seconds for a host that does not
+# exist (#487); elsewhere ntpath.realpath already is ntpath.abspath.
+LEXICAL_NT = SimpleNamespace(
+    normcase=ntpath.normcase,
+    realpath=ntpath.abspath,
+    dirname=ntpath.dirname,
+    sep=ntpath.sep,
+)
+
+
 class FolderGuardTests(unittest.TestCase):
     """Portable path-flavor controls (TESTING.md Windows portability preflight)."""
 
@@ -762,7 +774,7 @@ class FolderGuardTests(unittest.TestCase):
 
     def guard_nt(self, path, home="C:\\Users\\Vito"):
         return layout_module._guard_folder(
-            path, home, pathmod=ntpath, isdir=lambda _p: True
+            path, home, pathmod=LEXICAL_NT, isdir=lambda _p: True
         )
 
     def test_filesystem_roots_and_home_are_rejected(self):
@@ -832,8 +844,12 @@ class FolderGuardTests(unittest.TestCase):
 
     def test_missing_folders_add_nothing(self):
         self.assertIsNone(layout_module._guard_folder(str(self.tmp / "x"), "/home"))
+        # A missing share on this machine: an unknown server name made
+        # Windows wait about 2.8 s for the network (#487).
         self.assertIsNone(
-            layout_module._guard_folder("\\\\server\\share\\loras", str(self.tmp))
+            layout_module._guard_folder(
+                "\\\\localhost\\pm-no-such-share\\loras", str(self.tmp)
+            )
         )
         self.assertEqual(
             layout_module._guard_folder(str(self.tmp), "/nonexistent-home"),
@@ -843,17 +859,17 @@ class FolderGuardTests(unittest.TestCase):
     def test_windows_model_path_matches_a_lower_case_root(self):
         self.assertTrue(
             layout_module._inside(
-                "C:/Models/Loras/A.safetensors", ("c:\\models\\loras",), ntpath
+                "C:/Models/Loras/A.safetensors", ("c:\\models\\loras",), LEXICAL_NT
             )
         )
         self.assertFalse(
             layout_module._inside(
-                "C:/Models/LorasX/A.safetensors", ("c:\\models\\loras",), ntpath
+                "C:/Models/LorasX/A.safetensors", ("c:\\models\\loras",), LEXICAL_NT
             )
         )
         self.assertFalse(
             layout_module._inside(
-                "\\\\other\\share\\A.safetensors", ("c:\\models\\loras",), ntpath
+                "\\\\other\\share\\A.safetensors", ("c:\\models\\loras",), LEXICAL_NT
             )
         )
 

tests/test_lora_utils.py

@@ -9,6 +9,7 @@ import email
 import json
 import os
 import shutil
+import ssl
 import sys
 import tempfile
 import threading
@@ -669,6 +670,15 @@ class TestStaleDownloadSweep(unittest.TestCase):
         self.assertTrue(old.exists())
 
 
+def _unused_tls_context():
+    """A TLS context for the fake handlers, which never open a connection.
+
+    HTTPSHandler() builds a default context, and on Windows that reads the
+    system certificate store: about 0.14 s per handler (#487).
+    """
+    return ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+
+
 class _FakeHTTPSHandler(urllib.request.HTTPSHandler):
     """Serves canned responses through a real urllib opener, recording requests.
 
@@ -677,7 +687,7 @@ class _FakeHTTPSHandler(urllib.request.HTTPSHandler):
     """
 
     def __init__(self, redirect_to):
-        super().__init__()
+        super().__init__(context=_unused_tls_context())
         self.redirect_to = redirect_to
         self.requests = []
 
@@ -745,7 +755,7 @@ class _ChainHTTPSHandler(urllib.request.HTTPSHandler):
     urllib opener, recording every request; an unknown URL answers 404."""
 
     def __init__(self, routes):
-        super().__init__()
+        super().__init__(context=_unused_tls_context())
         self.routes = routes
         self.requests = []
 

tests/test_media_folders.py

@@ -0,0 +1,41 @@
+"""The shared folder skip every media walker uses (#501)."""
+
+import unittest
+
+from utils.media_folders import in_skipped_folder, is_skipped_folder, is_trash_folder
+
+
+class TrashFolderNameTests(unittest.TestCase):
+    def test_trash_folder_names_in_any_case(self):
+        for name in (
+            ".Trash",
+            ".trash",
+            ".Trash-1000",
+            ".trash-0",
+            ".Trashes",
+            "$RECYCLE.BIN",
+            "$Recycle.Bin",
+        ):
+            with self.subTest(name=name):
+                self.assertTrue(is_trash_folder(name))
+                self.assertTrue(is_skipped_folder(name))
+
+    def test_other_names_are_not_trash(self):
+        for name in (".Trash-abc", ".Trash-", "trash", "Recycle", "RECYCLE.BIN", "x"):
+            with self.subTest(name=name):
+                self.assertFalse(is_trash_folder(name))
+
+    def test_thumbnails_is_skipped_exactly(self):
+        self.assertTrue(is_skipped_folder("thumbnails"))
+        self.assertFalse(is_skipped_folder("Thumbnails"))
+        self.assertFalse(is_trash_folder("thumbnails"))
+
+    def test_folder_parts(self):
+        self.assertTrue(in_skipped_folder(("a", ".Trash-1000", "files")))
+        self.assertTrue(in_skipped_folder(("thumbnails",)))
+        self.assertFalse(in_skipped_folder(("a", "b")))
+        self.assertFalse(in_skipped_folder(()))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_prompt_archive_schema.py

@@ -0,0 +1,196 @@
+"""#443: the Library parent archive table, its migration and its validation."""
+
+import shutil
+import sqlite3
+import tempfile
+import unittest
+from pathlib import Path
+
+from database.models import PromptModel
+from database.operations import PromptDatabase
+from database.prompt_archive import (
+    TABLE,
+    migrate_prompt_archive,
+    prompt_archive_schema_error,
+)
+from utils.hashing import generate_prompt_hash
+
+
+def _tables(conn):
+    return {
+        row[0]
+        for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")
+    }
+
+
+class TestPromptArchiveSchema(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.path = str(Path(self.temp.name) / "archive.db")
+        self.db = PromptDatabase(self.path)
+
+    def tearDown(self):
+        self.db.close_all()
+        self.temp.cleanup()
+
+    def conn(self):
+        return self.db.model.get_connection()
+
+    def save(self, text):
+        return self.db.save_prompt(text, prompt_hash=generate_prompt_hash(text))
+
+    def test_startup_creates_the_table_and_it_validates(self):
+        self.assertIn(TABLE, _tables(self.conn()))
+        self.assertIsNone(prompt_archive_schema_error(self.conn(), allow_missing=False))
+
+    def test_migration_is_idempotent(self):
+        conn = self.conn()
+        migrate_prompt_archive(conn)
+        migrate_prompt_archive(conn)
+        self.assertIsNone(prompt_archive_schema_error(conn, allow_missing=False))
+
+    def test_a_missing_table_is_accepted_only_when_allowed(self):
+        conn = sqlite3.connect(":memory:")
+        self.addCleanup(conn.close)
+        self.assertIsNone(prompt_archive_schema_error(conn))
+        self.assertEqual(
+            prompt_archive_schema_error(conn, allow_missing=False),
+            "Missing prompt archive schema",
+        )
+
+    def test_deleting_a_prompt_drops_its_archive_row(self):
+        pid = self.save("Archived then deleted")
+        conn = self.conn()
+        conn.execute(
+            f"INSERT INTO {TABLE}(prompt_id, archived_at) VALUES (?, ?)",
+            (pid, "2026-10-28T00:00:00+00:00"),
+        )
+        conn.commit()
+        self.db.delete_prompt(pid)
+        self.assertEqual(conn.execute(f"SELECT COUNT(*) FROM {TABLE}").fetchone()[0], 0)
+
+    def _broken(self, *statements):
+        conn = sqlite3.connect(":memory:")
+        self.addCleanup(conn.close)
+        conn.execute("CREATE TABLE prompts (id INTEGER PRIMARY KEY)")
+        for statement in statements:
+            conn.execute(statement)
+        return conn
+
+    def test_unsupported_structures_are_refused(self):
+        good = (
+            f"CREATE TABLE {TABLE} (prompt_id INTEGER PRIMARY KEY, "
+            "archived_at TEXT NOT NULL, "
+            "FOREIGN KEY(prompt_id) REFERENCES prompts(id) ON DELETE CASCADE)"
+        )
+        cases = {
+            "other definition": (
+                f"CREATE TABLE {TABLE} (prompt_id INTEGER PRIMARY KEY, "
+                "archived_at TEXT)",
+            ),
+            "no cascade": (
+                f"CREATE TABLE {TABLE} (prompt_id INTEGER PRIMARY KEY, "
+                "archived_at TEXT NOT NULL, "
+                "FOREIGN KEY(prompt_id) REFERENCES prompts(id))",
+            ),
+            "extra index": (good, f"CREATE INDEX x ON {TABLE}(archived_at)"),
+            "trigger": (
+                good,
+                f"CREATE TRIGGER t AFTER INSERT ON {TABLE} BEGIN SELECT 1; END",
+            ),
+            "view name": (f"CREATE VIEW {TABLE} AS SELECT 1",),
+        }
+        for name, statements in cases.items():
+            with self.subTest(name):
+                self.assertIsNotNone(
+                    prompt_archive_schema_error(self._broken(*statements))
+                )
+
+    def test_invalid_values_and_dangling_rows_are_refused(self):
+        good = (
+            f"CREATE TABLE {TABLE} (prompt_id INTEGER PRIMARY KEY, "
+            "archived_at TEXT NOT NULL, "
+            "FOREIGN KEY(prompt_id) REFERENCES prompts(id) ON DELETE CASCADE)"
+        )
+        for name, row in {
+            "number": "(1, 5)",
+            "blob": "(1, x'00')",
+            "long": f"(1, '{'x' * 65}')",
+            "dangling": "(99, '2026-10-28T00:00:00+00:00')",
+        }.items():
+            with self.subTest(name):
+                conn = self._broken(good, "INSERT INTO prompts(id) VALUES (1)")
+                conn.execute(f"INSERT INTO {TABLE} VALUES {row}")
+                self.assertIsNotNone(prompt_archive_schema_error(conn))
+
+    def test_a_refused_structure_stops_the_migration_without_changes(self):
+        conn = self._broken(
+            f"CREATE TABLE {TABLE} (prompt_id INTEGER PRIMARY KEY, archived_at TEXT)"
+        )
+        with self.assertRaises(sqlite3.DatabaseError):
+            migrate_prompt_archive(conn)
+        sql = conn.execute(
+            "SELECT sql FROM sqlite_master WHERE name=?", (TABLE,)
+        ).fetchone()[0]
+        self.assertNotIn("NOT NULL", sql)
+
+
+class TestPromptArchiveBackups(unittest.TestCase):
+    """Restore validation accepts an older backup and refuses a damaged table."""
+
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.root = Path(self.temp.name)
+        self.db = PromptDatabase(str(self.root / "live.db"))
+
+    def tearDown(self):
+        self.db.close_all()
+        self.temp.cleanup()
+
+    def copy(self, name):
+        target = self.root / name
+        self.db.model.backup_database(str(target))
+        return str(target)
+
+    def test_a_backup_without_the_table_verifies_and_migrates(self):
+        path = self.copy("old.db")
+        with sqlite3.connect(path) as conn:
+            conn.execute(f"DROP TABLE {TABLE}")
+        conn.close()
+        ok, reason = self.db.model.verify_database_file(path)
+        self.assertTrue(ok, reason)
+        model = PromptModel(path)
+        try:
+            self.assertIn(TABLE, _tables(model.get_connection()))
+        finally:
+            model.close_all()
+
+    def test_a_backup_with_a_damaged_table_is_refused(self):
+        path = self.copy("bad.db")
+        with sqlite3.connect(path) as conn:
+            conn.execute(f"DROP TABLE {TABLE}")
+            conn.execute(f"CREATE TABLE {TABLE} (prompt_id INTEGER, archived_at TEXT)")
+        conn.close()
+        ok, reason = self.db.model.verify_database_file(path)
+        self.assertFalse(ok)
+        self.assertIn("archive", reason.lower())
+
+    def test_an_archived_prompt_survives_a_backup_copy(self):
+        pid = self.db.save_prompt("Kept", prompt_hash=generate_prompt_hash("Kept"))
+        conn = self.db.model.get_connection()
+        conn.execute(
+            f"INSERT INTO {TABLE}(prompt_id, archived_at) VALUES (?, ?)",
+            (pid, "2026-10-28T00:00:00+00:00"),
+        )
+        conn.commit()
+        path = self.copy("copy.db")
+        shutil.copy(path, path + ".2")
+        with sqlite3.connect(path + ".2") as other:
+            self.assertEqual(
+                other.execute(f"SELECT prompt_id FROM {TABLE}").fetchall(), [(pid,)]
+            )
+        other.close()
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_run_suite.py

@@ -18,11 +18,13 @@ from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parent.parent
 SUBPROCESS_TIMEOUT = 60
 WATCHDOG_ENV = ("PM_TEST_HANG_LIMIT", "PM_TEST_SHUTDOWN_LIMIT")
+# Integer settings the runner reads; a bad value is a usage error.
+RUNNER_ENV = (*WATCHDOG_ENV, "PM_TEST_SLOWEST")
 
 
 def run_suite(folder, extra_env=None, *args, verbosity=("-v",)):
     """Run the runner on ``folder`` and return the completed process."""
-    env = {k: v for k, v in os.environ.items() if k not in WATCHDOG_ENV}
+    env = {k: v for k, v in os.environ.items() if k not in RUNNER_ENV}
     # Windows writes a piped stderr in the ANSI codepage; ask for the UTF-8
     # this helper decodes, so non-ASCII values and paths survive.
     env["PYTHONIOENCODING"] = "utf-8"
@@ -269,8 +271,57 @@ class RunSuiteTests(unittest.TestCase):
         self.assertIn("ok", result.stderr, detail)
         self.assertIn("Timeout (", result.stderr, detail)
 
+    def test_slowest_tests_are_listed_when_asked(self):
+        self.write(
+            "test_probe_slowest.py",
+            """
+            import time
+            import unittest
+
+            class Probe(unittest.TestCase):
+                def test_fast(self):
+                    pass
+
+                def test_slow(self):
+                    time.sleep(0.3)
+
+                def test_slower(self):
+                    time.sleep(0.6)
+            """,
+        )
+        result = run_suite(self.folder, {"PM_TEST_SLOWEST": "2"})
+        self.assertEqual(result.returncode, 0, result.stderr)
+        report = result.stderr.split("slowest 2 of 3 tests:\n", 1)
+        self.assertEqual(len(report), 2, result.stderr)
+        lines = [line.split() for line in report[1].strip().splitlines()[:2]]
+        self.assertEqual(
+            [line[1] for line in lines],
+            [
+                "test_probe_slowest.Probe.test_slower",
+                "test_probe_slowest.Probe.test_slow",
+            ],
+            result.stderr,
+        )
+        self.assertGreaterEqual(float(lines[0][0].rstrip("s")), 0.6)
+        self.assertNotIn("test_fast", report[1])
+
+    def test_slowest_tests_are_not_listed_by_default(self):
+        self.write(
+            "test_probe_quiet.py",
+            """
+            import unittest
+
+            class Probe(unittest.TestCase):
+                def test_ok(self):
+                    pass
+            """,
+        )
+        result = run_suite(self.folder)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertNotIn("slowest", result.stderr)
+
     def test_invalid_limit_is_a_usage_error(self):
-        for name in WATCHDOG_ENV:
+        for name in RUNNER_ENV:
             for value in ("abc", "0", "-3", "1.5", "\u00b2"):
                 with self.subTest(name=name, value=value):
                     result = run_suite(self.folder, {name: value})

tests/test_thumbnail_jobs.py

@@ -490,16 +490,25 @@ class TestThumbnailJob(ThumbnailJobCase):
         real_write = images_module._write_image_thumbnail
         job_ids = []
         written = []
+        # #504: the worker can write its first preview before the response
+        # carrying the job id is read. The first write waits until the test
+        # has stored the id, so the cancel always lands after exactly one write.
+        first_written, id_stored = threading.Event(), threading.Event()
+        self.addCleanup(id_stored.set)
 
         def counting(src, dst, *args, **kwargs):
             real_write(src, dst, *args, **kwargs)
             written.append(dst)
             if len(written) == 1:
+                first_written.set()
+                id_stored.wait(10)
                 self.api._jobs.cancel(job_ids[0])
 
         with patch.object(images_module, "_write_image_thumbnail", counting):
             _, body = await self._start()
+            await self._wait(first_written)
             job_ids.append(body["job"]["id"])
+            id_stored.set()
             job = await self._finished(body["job"]["id"])
         self.assertEqual(job.state, "cancelled")
         self.assertEqual(job.status_line, "Cancelled · 1 preview written")

tests/test_trash_freedesktop.py

@@ -0,0 +1,310 @@
+"""The freedesktop trash backend (#480): rename into a trash or refuse, never unlink.
+
+Every test builds a disposable tree: a fake ``XDG_DATA_HOME`` and, through the
+backend's ``mounts`` seam, a fake "drive" mount point, so the real trash of the
+user running the tests is never touched. Moves are real renames on one
+filesystem.
+"""
+
+import os
+import shutil
+import stat
+import sys
+import tempfile
+import unittest
+from unittest import mock
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from utils import trash  # noqa: E402
+
+POSIX = os.name == "posix" and sys.platform != "darwin"
+
+
+@unittest.skipUnless(POSIX, "freedesktop trash is the Linux/BSD backend")
+class FreedesktopTrashTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp(prefix="pm-trash-")
+        self.addCleanup(shutil.rmtree, self.tmp, True)
+        self.data_home = os.path.join(self.tmp, "xdg")
+        self.drive = os.path.join(self.tmp, "drive")
+        self.root = os.path.join(self.drive, "output")
+        self.home_root = os.path.join(self.tmp, "home-output")
+        for folder in (self.data_home, self.root, self.home_root):
+            os.makedirs(folder)
+        self.mounts = ["/", os.path.realpath(self.drive)]
+        self.backend = trash.FreedesktopBackend(
+            data_home=self.data_home, mounts=lambda: list(self.mounts)
+        )
+
+    def _file(self, folder, name="a.png", content=b"png-bytes"):
+        path = os.path.join(folder, name)
+        with open(path, "wb") as handle:
+            handle.write(content)
+        return path
+
+    def _info(self, trash_dir, name):
+        with open(os.path.join(trash_dir, "info", name + ".trashinfo")) as handle:
+            return handle.read()
+
+    # ── choosing the trash ────────────────────────────────────────────
+
+    def test_file_on_the_home_mount_goes_to_the_home_trash(self):
+        path = self._file(self.home_root)
+        label = self.backend.move(path, [self.home_root])
+        home_trash = os.path.join(self.data_home, "Trash")
+        self.assertEqual(label, trash.HOME_TRASH_LABEL)
+        self.assertFalse(os.path.exists(path))
+        with open(os.path.join(home_trash, "files", "a.png"), "rb") as handle:
+            self.assertEqual(handle.read(), b"png-bytes")
+        info = self._info(home_trash, "a.png")
+        self.assertIn("[Trash Info]\n", info)
+        self.assertIn("Path=" + os.path.realpath(path) + "\n", info)
+        self.assertRegex(info, r"DeletionDate=\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\n")
+
+    def test_file_on_another_mount_uses_its_trash_dash_uid(self):
+        path = self._file(self.root, "b c%.png")
+        self.backend.move(path, [self.root])
+        top = os.path.join(self.drive, f".Trash-{os.getuid()}")
+        info_mode = stat.S_IMODE(os.lstat(top).st_mode)
+        self.assertEqual(info_mode, 0o700)
+        self.assertTrue(os.path.exists(os.path.join(top, "files", "b c%.png")))
+        # A top-directory trash records the path relative to its top folder,
+        # percent-encoded.
+        self.assertIn("Path=output/b%20c%25.png\n", self._info(top, "b c%.png"))
+
+    def test_sticky_dot_trash_folder_is_used(self):
+        shared = os.path.join(self.drive, ".Trash")
+        os.mkdir(shared)
+        os.chmod(shared, 0o1777)
+        path = self._file(self.root)
+        self.backend.move(path, [self.root])
+        self.assertTrue(
+            os.path.exists(os.path.join(shared, str(os.getuid()), "files", "a.png"))
+        )
+
+    def test_dot_trash_without_sticky_bit_is_skipped(self):
+        shared = os.path.join(self.drive, ".Trash")
+        os.mkdir(shared, 0o777)
+        os.chmod(shared, 0o777)
+        path = self._file(self.root)
+        self.backend.move(path, [self.root])
+        self.assertFalse(os.path.exists(os.path.join(shared, str(os.getuid()))))
+        top = os.path.join(self.drive, f".Trash-{os.getuid()}")
+        self.assertTrue(os.path.exists(os.path.join(top, "files", "a.png")))
+
+    def test_dot_trash_that_is_a_link_is_skipped(self):
+        elsewhere = os.path.join(self.tmp, "elsewhere")
+        os.mkdir(elsewhere)
+        os.chmod(elsewhere, 0o1777)
+        os.symlink(elsewhere, os.path.join(self.drive, ".Trash"))
+        path = self._file(self.root)
+        self.backend.move(path, [self.root])
+        self.assertEqual(os.listdir(elsewhere), [])
+
+    def test_trash_dash_uid_that_is_a_link_is_refused(self):
+        elsewhere = os.path.join(self.tmp, "elsewhere")
+        os.mkdir(elsewhere)
+        os.symlink(elsewhere, os.path.join(self.drive, f".Trash-{os.getuid()}"))
+        path = self._file(self.root)
+        with self.assertRaises(trash.TrashRefused) as caught:
+            self.backend.move(path, [self.root])
+        self.assertEqual(caught.exception.code, trash.NO_TRASH)
+        self.assertTrue(os.path.exists(path))
+        self.assertEqual(os.listdir(elsewhere), [])
+
+    def test_trash_inside_an_output_root_is_refused(self):
+        # The drive's top folder is itself an output root: its .Trash-uid
+        # would be listed as images.
+        path = self._file(self.root)
+        with self.assertRaises(trash.TrashRefused) as caught:
+            self.backend.move(path, [self.drive])
+        self.assertEqual(caught.exception.code, trash.TRASH_IN_ROOT)
+        self.assertTrue(os.path.exists(path))
+        self.assertFalse(
+            os.path.exists(os.path.join(self.drive, f".Trash-{os.getuid()}"))
+        )
+
+    def test_home_trash_inside_an_output_root_is_refused(self):
+        path = self._file(self.home_root)
+        with self.assertRaises(trash.TrashRefused) as caught:
+            self.backend.move(path, [self.home_root, self.tmp])
+        self.assertEqual(caught.exception.code, trash.TRASH_IN_ROOT)
+        self.assertTrue(os.path.exists(path))
+
+    def test_read_only_top_folder_is_no_trash(self):
+        path = self._file(self.root)
+        os.chmod(self.drive, 0o555)
+        self.addCleanup(os.chmod, self.drive, 0o755)
+        if os.access(self.drive, os.W_OK):
+            self.skipTest("running as root: permissions are not enforced")
+        self.assertEqual(self.backend.available(path, [self.root]), trash.NO_TRASH)
+        with self.assertRaises(trash.TrashRefused) as caught:
+            self.backend.move(path, [self.root])
+        self.assertEqual(caught.exception.code, trash.NO_TRASH)
+        self.assertTrue(os.path.exists(path))
+
+    def test_available_reports_without_writing(self):
+        path = self._file(self.root)
+        self.assertIsNone(self.backend.available(path, [self.root]))
+        self.assertEqual(
+            self.backend.available(path, [self.drive]), trash.TRASH_IN_ROOT
+        )
+        self.assertEqual(os.listdir(self.drive), ["output"])
+
+    # ── names and the no-replace rename ───────────────────────────────
+
+    def test_existing_name_in_the_trash_is_never_replaced(self):
+        top = os.path.join(self.drive, f".Trash-{os.getuid()}")
+        os.makedirs(os.path.join(top, "files"), mode=0o700)
+        os.makedirs(os.path.join(top, "info"), mode=0o700)
+        os.chmod(top, 0o700)
+        # A stray trashed file with no info file (another tool crashed).
+        stray = self._file(os.path.join(top, "files"), "a.png", b"older-file")
+        path = self._file(self.root)
+        self.backend.move(path, [self.root])
+        with open(stray, "rb") as handle:
+            self.assertEqual(handle.read(), b"older-file")
+        self.assertTrue(os.path.exists(os.path.join(top, "files", "a.1.png")))
+        self.assertTrue(os.path.exists(os.path.join(top, "info", "a.1.png.trashinfo")))
+        self.assertFalse(os.path.exists(os.path.join(top, "info", "a.png.trashinfo")))
+
+    def test_existing_info_name_is_skipped(self):
+        path = self._file(self.root)
+        self.backend.move(path, [self.root])
+        second = self._file(self.root)
+        self.backend.move(second, [self.root])
+        top = os.path.join(self.drive, f".Trash-{os.getuid()}")
+        self.assertEqual(
+            sorted(os.listdir(os.path.join(top, "files"))), ["a.1.png", "a.png"]
+        )
+
+    def test_missing_no_replace_rename_is_no_trash(self):
+        path = self._file(self.root)
+        for error in (38, 22):  # ENOSYS, EINVAL
+            with self.subTest(error=error):
+                backend = trash.FreedesktopBackend(
+                    data_home=self.data_home,
+                    mounts=lambda: list(self.mounts),
+                    rename=mock.Mock(side_effect=OSError(error, "no")),
+                )
+                with self.assertRaises(trash.TrashRefused) as caught:
+                    backend.move(path, [self.root])
+                self.assertEqual(caught.exception.code, trash.NO_TRASH)
+                self.assertTrue(os.path.exists(path))
+                top = os.path.join(self.drive, f".Trash-{os.getuid()}")
+                self.assertEqual(os.listdir(os.path.join(top, "info")), [])
+
+    def test_cross_device_rename_is_no_trash_and_never_copies(self):
+        path = self._file(self.root)
+        backend = trash.FreedesktopBackend(
+            data_home=self.data_home,
+            mounts=lambda: list(self.mounts),
+            rename=mock.Mock(side_effect=OSError(18, "EXDEV")),
+        )
+        with mock.patch("shutil.move") as move, mock.patch("shutil.copy2") as copy:
+            with self.assertRaises(trash.TrashRefused) as caught:
+                backend.move(path, [self.root])
+        self.assertEqual(caught.exception.code, trash.NO_TRASH)
+        move.assert_not_called()
+        copy.assert_not_called()
+        self.assertTrue(os.path.exists(path))
+
+    def test_other_rename_failure_is_failed_and_removes_only_our_info(self):
+        path = self._file(self.root)
+        backend = trash.FreedesktopBackend(
+            data_home=self.data_home,
+            mounts=lambda: list(self.mounts),
+            rename=mock.Mock(side_effect=OSError(5, "EIO")),
+        )
+        with self.assertRaises(trash.TrashRefused) as caught:
+            backend.move(path, [self.root])
+        self.assertEqual(caught.exception.code, trash.FAILED)
+        top = os.path.join(self.drive, f".Trash-{os.getuid()}")
+        self.assertEqual(os.listdir(os.path.join(top, "info")), [])
+        self.assertTrue(os.path.exists(path))
+
+    def test_never_removes_or_moves_the_source(self):
+        path = self._file(self.root)
+        real_unlink = os.unlink
+
+        def guarded_unlink(target, *args, **kwargs):
+            # Only our own .trashinfo may ever be removed.
+            self.assertTrue(str(target).endswith(".trashinfo"), target)
+            return real_unlink(target, *args, **kwargs)
+
+        backend = trash.FreedesktopBackend(
+            data_home=self.data_home,
+            mounts=lambda: list(self.mounts),
+            rename=mock.Mock(side_effect=OSError(5, "EIO")),
+        )
+        with (
+            mock.patch("os.unlink", guarded_unlink),
+            mock.patch("os.remove", guarded_unlink),
+            mock.patch("shutil.move") as move,
+            mock.patch("os.rename") as rename,
+        ):
+            with self.assertRaises(trash.TrashRefused):
+                backend.move(path, [self.root])
+        move.assert_not_called()
+        rename.assert_not_called()
+        self.assertTrue(os.path.exists(path))
+
+    def test_mountinfo_parsing_decodes_escapes(self):
+        text = (
+            "36 35 98:0 / / rw - ext4 /dev/root rw\n"
+            "37 36 98:1 / /mnt/my\\040drive rw - ext4 /dev/sdb1 rw\n"
+        )
+        self.assertEqual(trash.parse_mountinfo(text), ["/", "/mnt/my drive"])
+
+    def test_mount_of_picks_the_longest_containing_mount(self):
+        mounts = ["/", "/mnt", "/mnt/data"]
+        self.assertEqual(trash.mount_of("/mnt/data/x/y.png", mounts), "/mnt/data")
+        self.assertEqual(trash.mount_of("/mnt/datax/y.png", mounts), "/mnt")
+        self.assertEqual(trash.mount_of("/home/u/y.png", mounts), "/")
+
+
+class UnavailableBackendTests(unittest.TestCase):
+    def test_reports_no_trash_and_leaves_the_file(self):
+        backend = trash.UnavailableBackend()
+        with tempfile.TemporaryDirectory() as folder:
+            path = os.path.join(folder, "a.png")
+            with open(path, "wb") as handle:
+                handle.write(b"x")
+            self.assertEqual(backend.available(path, [folder]), trash.NO_TRASH)
+            with self.assertRaises(trash.TrashRefused) as caught:
+                backend.move(path, [folder])
+            self.assertEqual(caught.exception.code, trash.NO_TRASH)
+            self.assertTrue(os.path.exists(path))
+
+    def test_each_platform_gets_its_backend(self):
+        from utils import trash_macos
+
+        self.assertIsInstance(trash.default_backend("win32"), trash.UnavailableBackend)
+        self.assertIsInstance(
+            trash.default_backend("darwin"), trash_macos.MacTrashBackend
+        )
+        self.assertIsInstance(trash.default_backend("linux"), trash.FreedesktopBackend)
+
+    def test_windows_says_why_the_recycle_bin_is_not_used(self):
+        # #500 ruling (a): the Recycle Bin can delete permanently, so it is never used.
+        backend = trash.default_backend("win32")
+        self.assertEqual(
+            backend.available("C:/x/a.png", ["C:/x"]), trash.WINDOWS_RECYCLE
+        )
+        with self.assertRaises(trash.TrashRefused) as caught:
+            backend.move("C:/x/a.png", ["C:/x"])
+        self.assertEqual(caught.exception.code, trash.WINDOWS_RECYCLE)
+        self.assertIn(trash.WINDOWS_RECYCLE, trash.CODES)
+
+    def test_module_functions_use_the_replaceable_backend(self):
+        fake = mock.Mock()
+        fake.available.return_value = "network"
+        fake.move.return_value = "label"
+        with mock.patch.object(trash, "BACKEND", fake):
+            self.assertEqual(trash.trash_available("/x/a.png", ["/x"]), "network")
+            self.assertEqual(trash.move_to_trash("/x/a.png", ["/x"]), "label")
+
+
+if __name__ == "__main__":
+    unittest.main()