Merge branch 'feat/444-tags-page-search' into feat/444-library-folder-or

# Conflicts:
#	TESTING.md
#	web/js/workspace/library.mjs

tests/browser/fast_reset.py

@@ -28,6 +28,11 @@ import weakref
 from pathlib import Path
 from typing import Any, Callable, TypeVar
 
+try:
+    import fcntl
+except ImportError:  # Windows: no flock, and no /dev/shm to share
+    fcntl = None
+
 T = TypeVar("T")
 
 # Set to 1 to run seeders on the live database as before #384 (the equivalence
@@ -43,8 +48,13 @@ MEMORY_ROOT = Path("/dev/shm")
 # the browsers and the other workers; with less free than this, the scratch
 # copy goes on disk instead.
 MEMORY_FREE_BYTES = 32 * 1024 * 1024
-# Scratch folders are named <prefix><owner pid>-<random>.
+# Scratch folders are created as <prefix>new-<owner pid>-<random>, locked, then
+# renamed to <prefix>held-<owner pid>-<random>. The pid is for people only:
+# ownership is the flock on OWNER_LOCK, which every PID namespace sees (#419).
 SCRATCH_PREFIX = "pm-reset-"
+STAGING_PREFIX = f"{SCRATCH_PREFIX}new-"
+HELD_PREFIX = f"{SCRATCH_PREFIX}held-"
+OWNER_LOCK = "owner.lock"
 
 
 def _quote(name: str) -> str:
@@ -96,29 +106,40 @@ def table_digests(conn: sqlite3.Connection, schema: str = "main") -> dict[str, s
     return result
 
 
-def _process_alive(pid: int) -> bool:
+def _hold(folder: Path, *, create: bool) -> int:
+    """Take ``folder``'s owner lock without waiting; the open descriptor."""
+    flags = os.O_RDWR | (os.O_CREAT if create else 0)
+    fd = os.open(folder / OWNER_LOCK, flags, 0o600)
     try:
-        os.kill(pid, 0)
-    except ProcessLookupError:
-        return False
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
     except OSError:
-        return True  # it exists but belongs to someone else
-    return True
+        os.close(fd)
+        raise
+    return fd
 
 
 def remove_orphaned_scratch(root: Path) -> None:
     """Remove scratch folders of servers that died without cleaning up.
 
     A server killed outright (SIGKILL, a crash) never runs ``close``, and
-    tmpfs keeps its folder in memory until reboot. The folder name carries
-    the owner's process id; a folder whose process is gone is removed.
+    tmpfs keeps its folder in memory until reboot. A live owner holds the
+    flock on the folder's owner lock; the kernel drops it when the owner
+    dies, in whatever PID namespace it ran (a container with ``--ipc=host``
+    shares /dev/shm but not the pids, #419). A folder whose lock is free is
+    removed. Folders without a lock (staging, or named before #419) cannot
+    be proven orphaned and are left alone.
     """
-    if os.name != "posix":
-        return  # os.kill(pid, 0) would terminate the process on Windows
-    for folder in root.glob(f"{SCRATCH_PREFIX}*-*"):
-        pid = folder.name[len(SCRATCH_PREFIX) :].split("-", 1)[0]
-        if pid.isdigit() and not _process_alive(int(pid)):
+    if fcntl is None:
+        return
+    for folder in root.glob(f"{HELD_PREFIX}*"):
+        try:
+            fd = _hold(folder, create=False)
+        except OSError:
+            continue  # held by its owner, no lock to judge by, or gone
+        try:
             shutil.rmtree(folder, ignore_errors=True)
+        finally:
+            os.close(fd)
 
 
 class _SeedApi:
@@ -162,6 +183,7 @@ class ScratchSeeder:
         self._fallback = Path(directory)
         self._memory_root = memory_root
         self._directory: Path | None = None
+        self._owner_lock: int | None = None
         self._on_live = on_live
         self._scratch = None
         self._unsynced: "weakref.WeakSet[sqlite3.Connection]" = weakref.WeakSet()
@@ -266,6 +288,9 @@ class ScratchSeeder:
         if self._directory is not None:
             shutil.rmtree(self._directory, ignore_errors=True)
             self._directory = None
+        if self._owner_lock is not None:
+            os.close(self._owner_lock)  # after the removal: never a free lock
+            self._owner_lock = None
 
     def _scratch_directory(self) -> Path:
         """A folder in memory (tmpfs) where there is one, else ``directory``.
@@ -274,10 +299,35 @@ class ScratchSeeder:
         kernel is writing back the pages they rewrite.
         """
         root = self._memory_root
-        if root is not None and root.is_dir() and os.access(root, os.W_OK):
+        if (
+            fcntl is not None
+            and root is not None
+            and root.is_dir()
+            and os.access(root, os.W_OK)
+        ):
             remove_orphaned_scratch(root)
             if shutil.disk_usage(root).free >= MEMORY_FREE_BYTES:
-                prefix = f"{SCRATCH_PREFIX}{os.getpid()}-"
-                return Path(tempfile.mkdtemp(prefix=prefix, dir=root))
+                held = self._held_memory_directory(root)
+                if held is not None:
+                    return held
         self._fallback.mkdir(parents=True, exist_ok=True)
         return self._fallback
+
+    def _held_memory_directory(self, root: Path) -> Path | None:
+        """A new folder under ``root`` that this seeder holds the lock of.
+
+        It is locked under the staging name, which no cleaner judges, and
+        only then renamed: no cleaner ever sees it held-named and unlocked.
+        """
+        staging = Path(
+            tempfile.mkdtemp(prefix=f"{STAGING_PREFIX}{os.getpid()}-", dir=root)
+        )
+        try:
+            fd = _hold(staging, create=True)
+        except OSError:
+            shutil.rmtree(staging, ignore_errors=True)
+            return None  # no locks on this filesystem: use the disk
+        held = root / (HELD_PREFIX + staging.name[len(STAGING_PREFIX) :])
+        os.rename(staging, held)
+        self._owner_lock = fd
+        return held

tests/browser/library-concept.spec.mjs

@@ -30,6 +30,9 @@ export function mapLibraryConcept(reference) {
     // A shorter toolbar moves what follows it up by as much.
     const rise=library.toolbar.height-toolbar.height;
     const cards=library.cards.map((card,index)=>({...card,
+        // D148 (#437): each card leads with the concept's Images `.image-overlays` selection checkbox, placed absolutely
+        // over the art, so nothing else moves; it is compared with the concept's own overlay below.
+        children:['image-overlays',...card.children],
         // D23: "− N negative variants" uses the singular for one; that row is the concept's own, measured so (`oracle`).
         meta:card.meta.items[0]?.text===PLURAL_ONE?reference.oracle.meta[index]:card.meta,
         // D23: a long title wraps inside the title row, so the title button may shrink below its text (`min-width: 0`).
@@ -311,6 +314,56 @@ for(const [width,height] of SIZES)for(const theme of THEMES)test(`library geomet
     } finally {await host.evaluate(()=>window.conceptHost.dispose());await host.close();}
 });
 
+/**
+ * D148 (#437): the selection checkbox overlay of `card` and the `.bulkbar` row inside `main`, with one item checked,
+ * measured alike in the concept's Images page and production's Library: the overlay's inset in its card, the checkbox,
+ * and the bar's box, tokens and the two actions both bars have (Set category, Clear).
+ */
+const measureSelection=(page,{card,main})=>page.evaluate(({card,main})=>{
+    const css=(node,...keys)=>{const style=getComputedStyle(node);return Object.fromEntries(keys.map(key=>[key,style[key]]));};
+    const rect=node=>node.getBoundingClientRect(),px=value=>Math.round(value*100)/100;
+    const font=node=>css(node,'fontFamily','fontSize','fontWeight','lineHeight','color');
+    const edges=node=>css(node,'paddingTop','paddingRight','paddingBottom','paddingLeft','marginBottom','borderTopWidth','borderTopStyle',
+        'borderTopColor','borderTopLeftRadius','backgroundColor');
+    const host=document.querySelector(card),overlay=host.querySelector('.image-overlays'),label=overlay.querySelector(':scope > label');
+    const input=label.querySelector('input'),root=document.querySelector(main),bar=root.querySelector('.bulkbar');
+    const shared=['Set category','Clear'];
+    return {
+        overlay:{left:px(rect(overlay).left-rect(host).left),top:px(rect(overlay).top-rect(host).top),right:px(rect(host).right-rect(overlay).right),
+            ...css(overlay,'position','display','justifyContent','pointerEvents')},
+        label:css(label,'pointerEvents'),checkbox:{width:px(rect(input).width),height:px(rect(input).height),checked:input.checked,...css(input,'accentColor')},
+        bar:{left:px(rect(bar).left-rect(root).left),...css(bar,'display','alignItems','columnGap','rowGap','flexWrap'),...edges(bar),...font(bar),
+            count:{text:bar.querySelector(':scope > strong').textContent,...font(bar.querySelector(':scope > strong'))},
+            buttons:[...bar.querySelectorAll(':scope > button')].filter(button=>shared.includes(button.textContent.trim()))
+                .map(button=>({text:button.textContent.trim(),height:px(rect(button).height),...font(button),...edges(button)}))},
+    };
+},{card,main});
+async function conceptSelection(page,theme) {
+    await openConcept(page,'images',theme);
+    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);await settle(page);
+    return measureSelection(page,{card:'#image-grid .media-card',main:'#main'});
+}
+async function productionSelection(page,theme) {
+    await openProductionLibrary(page,theme,'no-preference');
+    await page.locator(CARDS).first().locator('.image-overlays input').check();
+    await expect(page.locator('#library-bulkbar .bulkbar')).toBeVisible();await page.mouse.move(0,0);await settle(page);
+    return measureSelection(page,{card:CARDS,main:'#workspace-main'});
+}
+for(const [width,height] of SIZES)for(const theme of THEMES)test(`the Library selection checkbox and bar match the concept's Images ones ${width}x${height} ${theme}`,async({page},testInfo)=>{
+    await page.setViewportSize({width,height});
+    const reference=await conceptSelection(page,theme);
+    await captureCanonicalState(page,testInfo,`concept-images-selection-${width}-${theme}`);
+    const actual=await productionSelection(page,theme);
+    await captureCanonicalState(page,testInfo,`production-library-selection-${width}-${theme}`);
+    await testInfo.attach('library-selection',{body:JSON.stringify({reference,actual},null,2),contentType:'application/json'});
+    expect(reference.bar.buttons.map(button=>button.text),'the concept bar has both actions').toEqual(['Set category','Clear']);
+    expect(actual).toEqual(reference);
+    // The comparison notices a moved checkbox (spec §7 mutation check).
+    await mutate(page,{css:'.prompt-card .image-overlays { inset: 20px 9px auto }'});
+    expect((await measureSelection(page,{card:CARDS,main:'#workspace-main'})).overlay.top).not.toBe(reference.overlay.top);
+});
+
 // The grid and cards at the concept's three-column breakpoint (style.css 1274–1276).
 for(const theme of THEMES)test(`library grid and cards match the concept 1800x1100 ${theme}`,async({page},testInfo)=>{
     await page.setViewportSize({width:1800,height:1100});

tests/browser/unseen-restore.mjs

@@ -52,3 +52,43 @@ export async function unseenRestore(page, restoring) {
         open();
     }
 }
+
+// A restore the open page does see run and finish (#415), driven by the test instead of the 15 s poll's timing. The
+// job is shaped as the server's (py/api/backup_restore.py: kind `restore`, one `errors` group, not cancellable).
+const RESTORE_JOB_ID = '415415415415415415415415415415ab';
+const restoreJob = state => ({ id: RESTORE_JOB_ID, kind: 'restore', title: 'Database restore', state, started_at: 1,
+    finished_at: state === 'running' ? null : 2, progress: 0, status_line: state === 'running' ? '' : 'Restored the test snapshot.',
+    processed: 0, total: 0, counters: { errors: 0 }, scope: {}, listed: { errors: 0 }, log_length: 0, cancellable: false });
+/** The Activity pill's link while the page follows that restore. */
+export const SEEN_RESTORE_PILL = `#/activity/${RESTORE_JOB_ID}`;
+/** The toast the page shows when it sees that restore finish (activity-kinds.mjs `restore.finishToast`). */
+export const SEEN_RESTORE_TOAST = 'Database restore finished · Restored the test snapshot.';
+
+/**
+ * Call before the page's first navigation, after `armUnseenRestores(page)` (a later route wins). The page's first
+ * job-list read lists a restore job running, so its Activity store follows it; its job stream is refused, so the store
+ * reads the list again, and every later read is held until `finish()`, which answers them with the job finished and
+ * resolves once one of those answers reached the page. The real restore the test runs meanwhile goes through the API.
+ */
+export async function followRestore(page) {
+    let release;
+    const released = new Promise(resolve => { release = resolve; });
+    let first = true;
+    await page.route(`${JOBS}/*/events`, route => route.abort().catch(() => {}));
+    await page.route(JOBS, async route => {
+        if (first) {
+            first = false;
+            return route.fulfill({ json: { success: true, jobs: [restoreJob('running')] } }).catch(() => {});
+        }
+        await released;
+        // A read the page has aborted since (a newer read supersedes it) can no longer be answered.
+        return route.fulfill({ json: { success: true, jobs: [restoreJob('finished')] } }).catch(() => {});
+    });
+    return {
+        async finish() {
+            const answered = page.waitForResponse(response => new URL(response.url()).pathname === '/prompt_manager/jobs');
+            release();
+            await answered;
+        },
+    };
+}

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

@@ -1,7 +1,7 @@
 import {writeFile} from 'node:fs/promises';
 import {startCoverage,saveCoverage} from '../../tools/vendor/browser-coverage.mjs';
 import {test,expect} from './fixtures.mjs';
-import {armUnseenRestores,unseenRestore} from './unseen-restore.mjs';
+import {armUnseenRestores,unseenRestore,followRestore,SEEN_RESTORE_PILL,SEEN_RESTORE_TOAST} from './unseen-restore.mjs';
 import {captureCanonicalState} from './history-canonical-comparison.mjs';
 import {inventoryOf,mapConcept,diffInventory} from './library-editor-canonical-comparison.mjs';
 
@@ -454,6 +454,37 @@ async function leaveAndReturn(page,id) {
 }
 const laneLabel=(page,text)=>variantsPanel(page).locator('.variant-lane').filter({hasText:text});
 
+// #415: a restore the page sees finish while New prompt is open keeps the dialog and its entries; the Library is shown
+// again from the restored data only once the dialog has closed.
+test('a restore seen finishing keeps New prompt open and reloads the Library after it closes',async({page,request})=>{
+    const f=page.fixture;const snapshot=await request.get('/__test__/library-editor/snapshot');await expect(snapshot).toBeOK();
+    const buffer=await snapshot.body();
+    const current=await detail(request,f.positive_id,'active');
+    await expect(await request.patch(`/prompt_manager/library/${f.positive_id}`,{data:{expected_epoch:current.library_epoch,if_match:current.positive.edit_token,metadata:{title:'Retitled elsewhere'}}})).toBeOK();
+    const restoreRun=await followRestore(page);
+    await page.goto(`${workspace}#/library`);const card=page.locator(`article[data-prompt-id="${f.positive_id}"]`);
+    await expect(card).toContainText('Retitled elsewhere');
+    await expect(page.locator('#activity-pill')).toHaveAttribute('href',SEEN_RESTORE_PILL);
+    await headingActions(page).getByRole('button',{name:'+ New prompt',exact:true}).click();
+    const dialog=editorDialog(page);await expect(dialog.getByRole('heading',{name:'New prompt',exact:true})).toBeVisible();await ready(dialog);
+    await field(dialog,'Title').fill('Typed before restore');await field(dialog,'Positive prompt').fill('A prompt typed while storage was restored');
+    await expect(await request.post('/prompt_manager/restore',{multipart:{database_file:{name:'editor.db',mimeType:'application/octet-stream',buffer}}})).toBeOK();
+    page.writes.length=0;
+    await restoreRun.finish();
+    await expect(toast(page)).toHaveText(SEEN_RESTORE_TOAST);
+    await expect(dialog).toBeVisible();
+    await expect(field(dialog,'Title')).toHaveValue('Typed before restore');
+    await expect(field(dialog,'Positive prompt')).toHaveValue('A prompt typed while storage was restored');
+    await expect(card).toContainText('Retitled elsewhere');
+    await button(dialog,'Save').click();
+    await expect(note(dialog)).toHaveText('Prompt storage was restored since this dialog opened. Nothing was saved.');
+    await expect(button(dialog,'Save')).toBeDisabled();expect(page.writes).toHaveLength(1);
+    await button(dialog,'Cancel').click();await expect(dialog).toHaveCount(0);
+    await expect(card).not.toContainText('Retitled elsewhere');await expect(card).toContainText('Editor portrait');
+    await expect(page.locator('#workspace-main h1')).toBeFocused();
+    expect(page.writes).toHaveLength(1);
+});
+
 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');

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

@@ -0,0 +1,177 @@
+import {startCoverage,saveCoverage} from '../../tools/vendor/browser-coverage.mjs';
+import {test,expect} from './fixtures.mjs';
+import {armUnseenRestores,unseenRestore} from './unseen-restore.mjs';
+
+// #437 D148: select prompts on the Library shelf and set their category in one step (the legacy admin's Set Category).
+const route='/prompt_manager/workspace#/library';
+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 dialog=page=>page.getByRole('dialog',{name:'Categorize selected prompts',exact:true});
+const toast=page=>page.locator('.toast');
+const heading=page=>page.locator('#workspace-main h1');
+
+async function shelf(request) {
+    const body=await(await request.get('/prompt_manager/library?limit=100')).json();
+    return body.items;
+}
+/** Every POST to the bulk category route, with its body. */
+function recordWrites(page) {
+    const writes=[];
+    page.on('request',item=>{if(item.method()==='POST'&&new URL(item.url()).pathname==='/prompt_manager/bulk/category')writes.push(item.postDataJSON());});
+    return writes;
+}
+/** The first mounted card's index once two frames in a row agree (the shelf's window follows scrolling a frame later). */
+async function stableFirstIndex(page) {
+    return page.evaluate(()=>new Promise(resolve=>{
+        const first=()=>document.querySelector('article[data-prompt-id]')?.dataset.index;
+        let previous=first();
+        const check=()=>requestAnimationFrame(()=>requestAnimationFrame(()=>{const now=first();if(now===previous)resolve(Number(now));else{previous=now;check();}}));
+        check();
+    }));
+}
+async function setCategory(page,value) {
+    await bar(page).getByRole('button',{name:'Set category',exact:true}).click();
+    await expect(dialog(page)).toBeVisible();
+    await dialog(page).locator('#action-input').fill(value);
+    await dialog(page).getByRole('button',{name:'Apply',exact:true}).click();
+}
+
+test.beforeEach(async({page,request,browserName})=>{
+    await startCoverage(page,browserName);await expect(await request.post('/__test__/reset',{data:{native_library:true}})).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('Set category writes the selected prompts on the server, reloads the shelf and clears the selection',async({page,request})=>{
+    const items=await shelf(request);const [first,second,third]=items;
+    const writes=recordWrites(page);
+    await page.goto(route);await expect(cards(page)).toHaveCount(items.length);
+    await expect(page.locator('#library-bulkbar')).toBeEmpty();
+    // The checkbox is named after the card's title, as the Images overlay names its file.
+    await expect(box(page,first.id)).toHaveAccessibleName(new RegExp(`^Select `));
+    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');
+    await expect(bar(page).getByRole('button')).toHaveText(['Set category','Clear']);
+    await setCategory(page,'  Studio set  ');
+    await expect(toast(page)).toHaveText('Category “Studio set” set on 2 prompts.');
+    await expect(dialog(page)).toHaveCount(0);
+    await expect(page.locator('#library-bulkbar')).toBeEmpty();
+    for(const item of [first,second]) await expect(card(page,item.id).locator('.card-title .chip')).toHaveText('Studio set');
+    await expect(card(page,third.id).locator('.card-title .chip')).toHaveText(third.category || 'Uncategorized');
+    await expect(box(page,first.id)).not.toBeChecked();
+    const after=await shelf(request);
+    expect(after.filter(item=>item.category==='Studio set').map(item=>item.id).sort()).toEqual([first.id,second.id].sort());
+    const epoch=(await(await request.get('/prompt_manager/library/options')).json()).library_epoch;
+    expect(writes).toEqual([{prompt_ids:[first.id,second.id],category:'Studio set',expected_epoch:epoch}]);
+    // The toolbar's category list now offers the new value, and so does the next dialog.
+    await expect(page.locator('#category-filter option',{hasText:'Studio set'})).toHaveCount(1);
+    await box(page,third.id).check();
+    await bar(page).getByRole('button',{name:'Set category',exact:true}).click();
+    await expect(dialog(page).locator('datalist option[value="Studio set"]')).toHaveCount(1);
+    await dialog(page).getByRole('button',{name:'Cancel',exact:true}).click();await expect(dialog(page)).toHaveCount(0);
+    expect(writes).toHaveLength(1);
+});
+
+test('a blank or control-character category keeps the dialog open; Clear and Escape clear the selection',async({page,request})=>{
+    const items=await shelf(request);const writes=recordWrites(page);
+    await page.goto(route);await expect(cards(page)).toHaveCount(items.length);
+    await box(page,items[0].id).check();
+    await bar(page).getByRole('button',{name:'Set category',exact:true}).click();
+    const field=dialog(page).locator('#action-input');
+    await field.fill('   ');await dialog(page).getByRole('button',{name:'Apply',exact:true}).click();
+    await expect(dialog(page)).toBeVisible();await expect(field).toBeFocused();
+    await field.fill('bad\tvalue');await dialog(page).getByRole('button',{name:'Apply',exact:true}).click();
+    await expect(dialog(page)).toBeVisible();
+    expect(await field.evaluate(node=>node.validationMessage)).toBe('A category cannot contain control characters.');
+    await dialog(page).getByRole('button',{name:'Cancel',exact:true}).click();await expect(dialog(page)).toHaveCount(0);
+    expect(writes).toHaveLength(0);
+    await bar(page).getByRole('button',{name:'Clear',exact:true}).click();
+    await expect(page.locator('#library-bulkbar')).toBeEmpty();await expect(heading(page)).toBeFocused();
+    await expect(box(page,items[0].id)).not.toBeChecked();
+    await box(page,items[1].id).check();
+    await bar(page).getByRole('button',{name:'Set category',exact:true}).focus();await page.keyboard.press('Escape');
+    await expect(page.locator('#library-bulkbar')).toBeEmpty();await expect(heading(page)).toBeFocused();
+    // A filter change replaces the shelf and clears the selection too.
+    await box(page,items[1].id).check();await expect(bar(page)).toBeVisible();
+    await page.locator('#search').fill('portrait');
+    await expect(page.locator('#library-bulkbar')).toBeEmpty();
+});
+
+test('Shift+click selects a range across windowed cards, Tab reaches the checkbox at the window edge, and a return keeps the fence',async({page,request,isMobile})=>{
+    await expect(await request.post('/__test__/reset',{data:{native_library:true,extra_prompts:200}})).toBeOK();
+    if(!isMobile)await page.setViewportSize({width:1600,height:1100});
+    const writes=recordWrites(page);
+    await page.goto(route);await expect(cards(page).first()).toBeVisible();
+    const more=page.getByRole('button',{name:'Load more prompts',exact:true});
+    for(let index=0;index<3;index++) {
+        await expect(more).toHaveAttribute('aria-disabled','false');
+        const response=page.waitForResponse(item=>{const url=new URL(item.url());return url.pathname==='/prompt_manager/library'&&url.searchParams.has('cursor');});
+        await more.evaluate(node=>node.click());await response;
+    }
+    await expect(more).toHaveAttribute('aria-disabled','false');
+    const firstId=Number(await cards(page).first().getAttribute('data-prompt-id'));
+    await box(page,firstId).check();
+    // Windowed: fewer cards are mounted than are loaded.
+    expect(await cards(page).count()).toBeLessThan(160);
+    // Tab from the last mounted card's last control lands on the next (unmounted) card's checkbox.
+    const last=cards(page).last();const lastIndex=Number(await last.getAttribute('data-index'));
+    await last.locator('button').last().focus();await page.keyboard.press('Tab');
+    const next=page.locator(`article[data-index="${lastIndex+1}"]`);
+    await expect(next.locator('.image-overlays input')).toBeFocused();
+    // Shift+click that card's checkbox: every card from the first to it is selected, mounted or not.
+    await next.locator('.image-overlays > label').click({modifiers:['Shift']});
+    await expect(bar(page).locator('strong')).toHaveText(`${lastIndex+2} selected`);
+    // Shift+Tab from a checkbox whose previous card is unmounted lands on that card's last control.
+    // Halfway down the loaded cards (short of the continuation, so no page loads), once the window stops moving.
+    await page.evaluate(()=>{const grid=document.querySelector('.library-grid');scrollTo(0,grid.getBoundingClientRect().top+scrollY+grid.offsetHeight/2);});
+    await expect.poll(()=>page.locator('article[data-index="0"]').count()).toBe(0);
+    const topIndex=await stableFirstIndex(page);
+    await page.locator(`article[data-index="${topIndex}"] .image-overlays input`).focus();await page.keyboard.press('Shift+Tab');
+    await expect(page.locator(`article[data-index="${topIndex-1}"] .card-footer .row-actions > button`).last()).toBeFocused();
+    // Leaving for a prompt's history and coming back restores the shelf without a read; its epoch still fences.
+    await page.locator(`article[data-index="${topIndex}"]`).getByRole('button',{name:'Explore history',exact:true}).click();
+    await page.getByRole('button',{name:'← Prompt library',exact:true}).click();
+    await expect(cards(page).first()).toBeVisible();await expect(page.locator('#library-bulkbar')).toBeEmpty();
+    const visible=Number(await cards(page).first().getAttribute('data-prompt-id'));
+    await box(page,visible).check();await setCategory(page,'Returned');
+    await expect(toast(page)).toHaveText('Category “Returned” set on 1 prompt.');
+    const epoch=(await(await request.get('/prompt_manager/library/options')).json()).library_epoch;
+    expect(writes).toEqual([{prompt_ids:[visible],category:'Returned',expected_epoch:epoch}]);
+});
+
+test('a restore the page did not see refuses the write, changes nothing and reloads the shelf',async({page,request})=>{
+    await armUnseenRestores(page);
+    const items=await shelf(request);
+    await page.goto(route);await expect(cards(page)).toHaveCount(items.length);
+    await box(page,items[0].id).check();
+    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();
+    const reload=page.waitForResponse(item=>{const url=new URL(item.url());return url.pathname==='/prompt_manager/library'&&!url.searchParams.has('cursor');});
+    await setCategory(page,'After restore');
+    await expect(toast(page)).toHaveText('Prompt storage was restored since this page loaded. No category was changed.');
+    await reload;await expect(page.locator('#library-bulkbar')).toBeEmpty();
+    expect((await shelf(request)).filter(item=>item.category==='After restore')).toEqual([]);
+    // The reloaded shelf reads the new epoch: the next write goes through.
+    await box(page,items[0].id).check();await setCategory(page,'After reload');
+    await expect(toast(page)).toHaveText('Category “After reload” set on 1 prompt.');
+});
+
+test('an answer that may follow a committed write says so and reloads; a refused write keeps the selection',async({page,request})=>{
+    const items=await shelf(request);
+    await page.goto(route);await expect(cards(page)).toHaveCount(items.length);
+    await box(page,items[0].id).check();
+    await page.route('**/prompt_manager/bulk/category',route=>route.fulfill({status:500,contentType:'application/json',body:'{"success":false,"error":"boom"}'}),{times:1});
+    await setCategory(page,'Refused');
+    await expect(toast(page)).toHaveText('Category could not be set. Try again.');
+    await expect(bar(page).locator('strong')).toHaveText('1 selected');
+    let sent=false;
+    await page.route('**/prompt_manager/bulk/category',async route=>{sent=true;await route.fetch();await route.abort('failed');},{times:1});
+    await setCategory(page,'Unconfirmed');
+    await expect(toast(page)).toHaveText('The category change could not be confirmed. The Library was reloaded.');
+    expect(sent).toBe(true);
+    await expect(page.locator('#library-bulkbar')).toBeEmpty();
+    await expect(card(page,items[0].id).locator('.card-title .chip')).toHaveText('Unconfirmed');
+});

tests/browser/workspace-library.spec.mjs

@@ -619,7 +619,8 @@ test('card matches the concept and never wraps the category mid-word',async({pag
         const card=page.locator(`article[data-prompt-id="${cat.id}"]`);
         // app.js renderLibrary a586: article.prompt-card > .card-art, .card-content, .card-footer.
         await expect(card).toHaveClass('prompt-card');
-        expect(await card.evaluate(node=>[...node.children].map(child=>child.className))).toEqual(['card-art','card-content','card-footer']);
+        // D148 (#437): the concept's Images selection overlay leads the card.
+        expect(await card.evaluate(node=>[...node.children].map(child=>child.className))).toEqual(['image-overlays','card-art','card-content','card-footer']);
         expect(await card.locator('.card-art').evaluate(node=>[...node.children].map(child=>child.tagName))).toEqual(['IMG','IMG']);
         expect(await card.locator('.card-content').evaluate(node=>[...node.children].map(child=>child.className))).toEqual(['card-title','prompt-inspector','card-meta','tags']);
         expect(await card.locator('.card-title').evaluate(node=>[...node.children].map(child=>`${child.tagName}.${child.className}`))).toEqual(['BUTTON.','SPAN.chip']);

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

@@ -1,6 +1,7 @@
 import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
 import { test, expect } from './fixtures.mjs';
 import { seedConcept } from './concept-inventory.mjs';
+import { followRestore, SEEN_RESTORE_PILL, SEEN_RESTORE_TOAST } from './unseen-restore.mjs';
 
 // System › Backup & export (#249 System S9 Task 24) on the S8 backend and the concept-shaped fixture: Back up and its
 // status line (D103), the restore review (D105) and its job, the exports, Import / inspect and the recovery policy
@@ -265,6 +266,24 @@ test('a finished restore shows the open page again from the restored data', asyn
     expect(await libraryTotal(request)).toBe(restoredTotal);
 });
 
+// #415: an open dialog waits out a finished restore, except a review: the plan it staged no longer describes storage,
+// so it closes as dismissed (its stage discarded), as before.
+test('a restore seen finishing elsewhere closes an open restore review and discards its stage', async ({ page, request }) => {
+    const bytes = await backupBytes(request);
+    const restoreRun = await followRestore(page);
+    await openBackups(page);
+    await expect(page.locator('#activity-pill')).toHaveAttribute('href', SEEN_RESTORE_PILL);
+    await chooseBackup(page, bytes);
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Restore preview');
+    expect((await serverJson(request, '/__test__/system/backups')).stages).toBe(1);
+    const discarded = page.waitForResponse(response => response.url().includes(`${PREVIEW_URL}/`) && response.request().method() === 'DELETE');
+    await restoreRun.finish();
+    await expect(toast(page)).toHaveText(SEEN_RESTORE_TOAST);
+    expect((await discarded).status()).toBe(200);
+    await expect(dialog(page)).toHaveCount(0);
+    expect((await serverJson(request, '/__test__/system/backups')).stages).toBe(0);
+});
+
 test('invalid file shows the validator message; nothing is staged', async ({ page, request }) => {
     const before = await serverJson(request, '/__test__/system/digest');
     await openBackups(page);

tests/browser/workspace-vocabulary.spec.mjs

@@ -1,7 +1,7 @@
 import {startCoverage,saveCoverage} from '../../tools/vendor/browser-coverage.mjs';
 import {writeFile} from 'node:fs/promises';
 import {test,expect} from './fixtures.mjs';
-import {armUnseenRestores,unseenRestore} from './unseen-restore.mjs';
+import {armUnseenRestores,unseenRestore,followRestore,SEEN_RESTORE_PILL,SEEN_RESTORE_TOAST} from './unseen-restore.mjs';
 import {captureCanonicalState} from './history-canonical-comparison.mjs';
 import {pageInventoryOf,inventoryOf,diffInventory,mapVocabularyConcept,mapVocabularyDialog,d149Of,toolbarInventoryOf} from './vocabulary-canonical-comparison.mjs';
 
@@ -552,6 +552,31 @@ test('conflict and restore states keep the dialog and write nothing',async({page
     expect(writes.filter(write=>write.url==='/prompt_manager/vocabulary/tags')).toHaveLength(1);
 });
 
+// #415: a restore the page sees finish while Create tag is open keeps the dialog and its entries; the page is shown
+// again from the restored data only once the dialog has closed.
+test('a restore seen finishing keeps an open dialog and reloads the page after it closes',async({page,request})=>{
+    const saved=await backup(request);
+    await expect(await request.put('/prompt_manager/tags/mist',{data:{new_name:'fog'}})).toBeOK();
+    const restoreRun=await followRestore(page);const writes=trackWrites(page);await openPage(page);
+    await expect(page.locator('#activity-pill')).toHaveAttribute('href',SEEN_RESTORE_PILL);
+    await expect(tagRow(page,'fog')).toHaveCount(1);
+    const box=await openDialog(page,main(page).getByRole('button',{name:'+ Create tag',exact:true}),'Create tag');
+    await field(box,'Tag name').fill('sunrise');
+    await expect(await request.post('/prompt_manager/restore',{multipart:{database_file:{name:'vocabulary.db',mimeType:'application/octet-stream',buffer:saved}}})).toBeOK();
+    await restoreRun.finish();
+    await expect(toast(page)).toHaveText(SEEN_RESTORE_TOAST);
+    await expect(box).toBeVisible();await expect(field(box,'Tag name')).toHaveValue('sunrise');
+    await expect(tagRow(page,'fog')).toHaveCount(1);
+    await button(box,'Apply').click();
+    await expect(note(box)).toHaveText('Prompt storage was restored since this dialog opened. Nothing was changed.');
+    expect(await actionNames(box)).toEqual(['Reload','Cancel','Apply']);
+    expect(tagNames(await snapshot(request))).not.toContain('sunrise');
+    await button(box,'Cancel').click();await expect(box).toHaveCount(0);
+    await expect(tagRow(page,'mist')).toHaveCount(1);await expect(tagRow(page,'fog')).toHaveCount(0);
+    await expect(main(page).getByRole('heading',{level:1})).toBeFocused();
+    expect(writes.filter(write=>write.url==='/prompt_manager/vocabulary/tags')).toHaveLength(1);
+});
+
 test('lost response is outcome-unknown',async({page,request})=>{
     const writes=trackWrites(page);await openPage(page);
     await page.route('**/prompt_manager/vocabulary/tags/*',async route=>{

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

@@ -59,3 +59,9 @@ test('the toolbar list merges prompt and image categories once each', async () =
     assert.deepEqual(mergeCategories(['A', '', '  ', 7], null), ['A']);
     assert.deepEqual(mergeCategories(undefined, ['landscapes', 'Landscapes']), ['landscapes', 'Landscapes']);
 });
+
+test('the outcome names what was set: images by default, prompts for the Library bar (#437)', async () => {
+    const {setOutcome} = await source;
+    assert.equal(setOutcome({updated:1, unchanged:0, not_found:0}, 'A', 'prompt'), 'Category “A” set on 1 prompt.');
+    assert.equal(setOutcome({updated:2, unchanged:0, not_found:0}, 'A', 'prompt'), 'Category “A” set on 2 prompts.');
+});

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

@@ -0,0 +1,44 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+// #437 D148: the Prompt library's selection bar sets one category on the selected prompts, fenced by the storage epoch.
+const source = import('../../web/js/workspace/library-selection.mjs');
+
+test('the dialog is the shared simpleInput with the prompt title, and the route and cap are the legacy ones', async () => {
+    const {PROMPT_CATEGORY_DIALOG, CATEGORY_URL, MAX_CATEGORY_PROMPTS, TOO_MANY_PROMPTS} = await source;
+    assert.deepEqual({...PROMPT_CATEGORY_DIALOG}, {title:'Categorize selected prompts', label:'Category', action:'Apply'});
+    assert.equal(CATEGORY_URL, '/prompt_manager/bulk/category');
+    assert.equal(MAX_CATEGORY_PROMPTS, 1000);
+    assert.equal(TOO_MANY_PROMPTS, 'Select at most 1,000 prompts.');
+});
+
+test('a confirmed write toasts the shared outcome with "prompt", invalidates and reloads', async () => {
+    const {writeOutcome} = await source;
+    assert.deepEqual(writeOutcome({success:true, category:'Studio', updated:2, unchanged:1, not_found:0}, null),
+        {toast:'Category “Studio” set on 3 prompts.', committed:true, reload:true});
+    assert.deepEqual(writeOutcome({success:true, category:'Studio', updated:1, unchanged:0, not_found:2}, null),
+        {toast:'Category “Studio” set on 1 prompt. 2 could not be found.', committed:true, reload:true});
+});
+
+test('none found, a restored storage, an unconfirmed answer and a refused write each say what happened', async () => {
+    const {writeOutcome, NONE_FOUND, STORAGE_CHANGED, UNCONFIRMED, CATEGORY_FAILED} = await source;
+    assert.deepEqual(writeOutcome({success:true, category:'X', updated:0, unchanged:0, not_found:3}, null),
+        {toast:NONE_FOUND, committed:false, reload:true});
+    assert.deepEqual(writeOutcome(null, {status:409, code:'storage-changed'}), {toast:STORAGE_CHANGED, committed:false, reload:true});
+    for (const failure of [new TypeError('Failed to fetch'), {status:502}, {status:503}, {status:504}]) {
+        assert.deepEqual(writeOutcome(null, failure), {toast:UNCONFIRMED, committed:true, reload:true});
+    }
+    assert.deepEqual(writeOutcome(null, null), {toast:UNCONFIRMED, committed:true, reload:true});
+    for (const status of [400, 500]) {
+        assert.deepEqual(writeOutcome(null, {status}), {toast:CATEGORY_FAILED, committed:false, reload:false});
+    }
+    assert.equal(STORAGE_CHANGED, 'Prompt storage was restored since this page loaded. No category was changed.');
+});
+
+test('the field refuses control characters as validate_category does', async () => {
+    const {categoryProblem, CONTROL_CHARACTERS} = await source;
+    assert.equal(categoryProblem('Studio portraits'), null);
+    assert.equal(categoryProblem('tab\there'), CONTROL_CHARACTERS);
+    assert.equal(categoryProblem('nul\u0000'), CONTROL_CHARACTERS);
+    assert.equal(categoryProblem('unicode ✓ é'), null);
+});

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

@@ -129,3 +129,13 @@ test('tag mode untagged is sent, echoed and never combined with tags (#444)',asy
  await assert.rejects(s.reset({tagMode:'untagged',tags:['a']}),TypeError);await assert.rejects(s.reset({tagMode:'or'}),TypeError);
  assert.equal(calls.length,3);s.dispose();
 });
+test('the stream keeps the first page\'s storage epoch and refuses a later page from another one (#437)',async()=>{
+ const {createLibraryStream}=await source;const A='11111111-1111-4111-8111-111111111111',B='22222222-2222-4222-8222-222222222222';
+ const pending=[{...page([item(1)],'next'),library_epoch:A},{...page([item(2)],'more'),library_epoch:A},{...page([item(3)]),library_epoch:B}];
+ const s=createLibraryStream({api:{get:async()=>pending.shift()}});assert.equal(s.state.epoch,null);
+ await s.reset();assert.equal(s.state.epoch,A);await s.loadMore();assert.equal(s.state.epoch,A);assert.equal(s.state.items.length,2);
+ await s.loadMore();assert.ok(s.state.error);assert.equal(s.state.items.length,2);assert.equal(s.state.epoch,A);
+ const restored=createLibraryStream({api:{},restore:{filters:{},state:s.state}});assert.equal(restored.state.epoch,A);restored.dispose();
+ const fresh=[{...page([item(4)]),library_epoch:B}];const reset=s.reset({text:'x'});assert.equal(s.state.epoch,null);
+ s.dispose();const next=createLibraryStream({api:{get:async()=>fresh.shift()}});await next.reset();assert.equal(next.state.epoch,B);next.dispose();await reset;
+});

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

@@ -192,6 +192,71 @@ test('views reload once after a restore this page saw finish; a failed restore c
     assert.equal(listeners.size, 0);
 });
 
+// #415: a fake document whose open dialogs the test sets, and a MutationObserver stand-in it triggers.
+function dialogPage() {
+    const page = { open: 0, observers: new Set() };
+    page.doc = { documentElement: {}, querySelector: selector => (selector === 'dialog[open]' && page.open > 0 ? {} : null) };
+    page.Observer = class {
+        constructor(callback) { this.callback = callback; }
+        observe(target, options) { this.target = target; this.options = options; page.observers.add(this); }
+        disconnect() { page.observers.delete(this); }
+    };
+    page.mutate = open => { page.open = open; for (const observer of [...page.observers]) observer.callback([]); };
+    return page;
+}
+
+test('the restore reload runs at once when no dialog is open', async () => {
+    const { createRestoreReload } = await backups;
+    const page = dialogPage();
+    let reloads = 0;
+    const reload = createRestoreReload(() => { reloads += 1; }, { doc: page.doc, Observer: page.Observer });
+    reload.request();
+    assert.equal(reloads, 1);
+    assert.equal(page.observers.size, 0, 'nothing waits');
+    reload.request();
+    assert.equal(reloads, 2);
+});
+
+test('the restore reload waits for every open dialog to close, then runs once (#415)', async () => {
+    const { createRestoreReload } = await backups;
+    const page = dialogPage();
+    page.open = 1;
+    let reloads = 0;
+    const reload = createRestoreReload(() => { reloads += 1; }, { doc: page.doc, Observer: page.Observer });
+    reload.request();
+    reload.request();
+    assert.equal(reloads, 0, 'an open dialog holds the reload');
+    assert.equal(page.observers.size, 1, 'one observer for repeated requests');
+    const [observer] = page.observers;
+    assert.equal(observer.target, page.doc.documentElement);
+    assert.deepEqual(observer.options, { subtree: true, childList: true, attributes: true, attributeFilter: ['open'] });
+    page.mutate(1);
+    assert.equal(reloads, 0, 'a dialog swapped for another keeps it waiting');
+    page.mutate(0);
+    assert.equal(reloads, 1);
+    assert.equal(page.observers.size, 0, 'the observer stops once it ran');
+    page.mutate(0);
+    assert.equal(reloads, 1);
+    page.open = 1;
+    reload.request();
+    page.mutate(0);
+    assert.equal(reloads, 2, 'a later restore waits again');
+});
+
+test('disposing drops a waiting restore reload', async () => {
+    const { createRestoreReload } = await backups;
+    const page = dialogPage();
+    page.open = 1;
+    let reloads = 0;
+    const reload = createRestoreReload(() => { reloads += 1; }, { doc: page.doc, Observer: page.Observer });
+    reload.request();
+    reload.dispose();
+    assert.equal(page.observers.size, 0);
+    page.mutate(0);
+    assert.equal(reloads, 0);
+    reload.dispose();
+});
+
 test('a downloaded backup the server could not verify says so', async () => {
     const { downloadDatabaseBackup, BACKUP_DONE, backupUnverified } = await scan;
     const toasts = [];

tests/js/workspace-toolbar.test.js

@@ -908,6 +908,34 @@ test('openReviewDialog lays out heading, grid, options, sentence, backup box and
     }
 });
 
+// #415: a finished restore ends an open review (its reviewed plan no longer describes storage) as a dismissal, and
+// leaves any other dialog, with what was typed in it, open.
+test('closeReviewDialog closes only an open review, as dismissed', async () => {
+    const { openReviewDialog, openInputDialog, closeReviewDialog, closeWorkspaceDialog } = await dialogsModule;
+    const { createScope } = await coreModule;
+    const dom = fakeDOM();
+    const scope = createScope();
+    try {
+        closeReviewDialog();
+        const outcomes = [];
+        openInputDialog({ scope, title: 'Save view', label: 'Name', value: 'typed', action: 'Save', onApply() {} });
+        closeReviewDialog();
+        assert.equal(modal(dom).open, true, 'an input dialog stays');
+        assert.equal(byId(dom, 'action-input').value, 'typed');
+        openReviewDialog({ scope, title: 'Restore preview', grid: [['Integrity', 'Verified']], cancelLabel: 'Cancel',
+            primary: { label: 'Restore', danger: true }, onStart: () => outcomes.push('start'), onDismiss: () => outcomes.push('dismiss') });
+        closeReviewDialog();
+        assert.deepEqual(outcomes, ['dismiss']);
+        assert.equal(modal(dom), undefined, 'the shell is gone');
+        closeReviewDialog();
+        assert.deepEqual(outcomes, ['dismiss']);
+    } finally {
+        scope.dispose();
+        closeWorkspaceDialog();
+        dom.restore();
+    }
+});
+
 test('review dialog backup box keeps the dialog open and toasts the outcome', async () => {
     const { openReviewDialog, closeWorkspaceDialog, SCAN_BACKUP_COPY } = await dialogsModule;
     const { downloadDatabaseBackup, BACKUP_DONE, BACKUP_FAILED } = await scanModule;

tests/test_browser_fast_reset.py

@@ -22,6 +22,9 @@ from database.operations import PromptDatabase
 from tests.browser import fast_reset
 from tests.browser.fast_reset import ScratchSeeder, table_digests
 
+# The owner lock of /dev/shm scratch folders needs POSIX flock (#419).
+HAS_FLOCK = unittest.skipUnless(os.name == "posix", "needs POSIX flock")
+
 
 def digests(db: PromptDatabase) -> dict:
     return table_digests(db.model.get_connection())
@@ -275,6 +278,7 @@ class TestScratchSeeder(unittest.TestCase):
         self.assertEqual(digests(self.live), expected)
         self.assertFalse((self.root / "unused").exists())
 
+    @HAS_FLOCK
     def test_the_scratch_lives_under_the_memory_root_when_there_is_one(self):
         memory = self.root / "memory"
         memory.mkdir()
@@ -288,6 +292,16 @@ class TestScratchSeeder(unittest.TestCase):
         seeder.close()
         self.assertEqual(list(memory.iterdir()), [])
 
+    @unittest.skipIf(os.name == "posix", "without flock the memory root is unused")
+    def test_without_flock_the_scratch_stays_on_disk(self):
+        memory = self.root / "memory"
+        memory.mkdir()
+        seeder = ScratchSeeder(self.api, self.root / "fallback", memory_root=memory)
+        self.addCleanup(seeder.close)
+        seeder.run(reseed)
+        self.assertEqual(list(memory.iterdir()), [])
+        self.assertTrue((self.root / "fallback" / "seed.db").exists())
+
     def test_a_full_memory_root_puts_the_scratch_on_disk(self):
         memory = self.root / "memory"
         memory.mkdir()
@@ -303,26 +317,32 @@ class TestScratchSeeder(unittest.TestCase):
         self.assertEqual(list(memory.iterdir()), [])
         self.assertTrue((self.root / "fallback" / "seed.db").exists())
 
-    @unittest.skipUnless(os.name == "posix", "process probe is POSIX only")
-    def test_scratch_folders_of_dead_servers_are_removed(self):
+    @HAS_FLOCK
+    def test_the_scratch_folder_is_held_by_a_lock_until_close(self):
         memory = self.root / "memory"
         memory.mkdir()
-        dead = subprocess.Popen([sys.executable, "-c", "pass"])
-        dead.wait()
-        orphan = memory / f"pm-reset-{dead.pid}-abc"
-        alive = memory / f"pm-reset-{os.getpid()}-def"
-        other = memory / "pm-reset-notapid"
-        for folder in (orphan, alive, other):
-            folder.mkdir()
-            (folder / "seed.db").write_bytes(b"x")
         seeder = ScratchSeeder(self.api, self.root / "fallback", memory_root=memory)
         self.addCleanup(seeder.close)
         seeder.run(reseed)
-        self.assertFalse(orphan.exists())
-        self.assertTrue(alive.exists())
-        self.assertTrue(other.exists())
-        own = [p for p in memory.glob(f"pm-reset-{os.getpid()}-*") if p != alive]
-        self.assertEqual(len(own), 1)
+        (folder,) = memory.iterdir()
+        self.assertTrue(folder.name.startswith(f"pm-reset-held-{os.getpid()}-"))
+        self.assertFalse(lock_is_free(folder / "owner.lock"))
+        seeder.close()
+        self.assertEqual(list(memory.iterdir()), [])
+
+    @HAS_FLOCK
+    def test_a_lock_that_cannot_be_taken_puts_the_scratch_on_disk(self):
+        memory = self.root / "memory"
+        memory.mkdir()
+        seeder = ScratchSeeder(self.api, self.root / "fallback", memory_root=memory)
+        self.addCleanup(seeder.close)
+        refuse = mock.patch.object(
+            fast_reset.fcntl, "flock", side_effect=OSError("no locks here")
+        )
+        with refuse:
+            seeder.run(reseed)
+        self.assertEqual(list(memory.iterdir()), [])
+        self.assertTrue((self.root / "fallback" / "seed.db").exists())
 
     def test_close_releases_the_scratch_files(self):
         self.seeder.run(reseed)
@@ -331,5 +351,95 @@ class TestScratchSeeder(unittest.TestCase):
         self.seeder.close()  # idempotent
 
 
+# A process that takes the owner lock of a folder, says so, and waits.
+HOLDER = """
+import fcntl, os, sys, time
+fd = os.open(os.path.join(sys.argv[1], "owner.lock"), os.O_RDWR | os.O_CREAT)
+fcntl.flock(fd, fcntl.LOCK_EX)
+print("held", flush=True)
+time.sleep(600)
+"""
+
+
+def lock_is_free(path: Path) -> bool:
+    fd = os.open(path, os.O_RDWR)
+    try:
+        fast_reset.fcntl.flock(fd, fast_reset.fcntl.LOCK_EX | fast_reset.fcntl.LOCK_NB)
+    except BlockingIOError:
+        return False
+    finally:
+        os.close(fd)
+    return True
+
+
+@HAS_FLOCK
+class TestOrphanedScratch(unittest.TestCase):
+    """Only folders whose owner lock is free are orphans (#419)."""
+
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.memory = Path(self.tmp.name)
+
+    def folder(self, name: str) -> Path:
+        folder = self.memory / name
+        folder.mkdir()
+        (folder / "seed.db").write_bytes(b"x")
+        return folder
+
+    def hold(self, folder: Path) -> subprocess.Popen:
+        holder = subprocess.Popen(
+            [sys.executable, "-c", HOLDER, str(folder)],
+            stdout=subprocess.PIPE,
+            text=True,
+        )
+        self.addCleanup(holder.wait)
+        self.addCleanup(holder.stdout.close)
+        self.addCleanup(holder.kill)
+        self.assertEqual(holder.stdout.readline().strip(), "held")
+        return holder
+
+    def test_a_folder_whose_owner_was_killed_is_removed(self):
+        folder = self.folder("pm-reset-held-123-abc")
+        holder = self.hold(folder)
+        holder.kill()
+        holder.wait()
+        fast_reset.remove_orphaned_scratch(self.memory)
+        self.assertFalse(folder.exists())
+
+    def test_a_held_folder_is_kept_whatever_pid_its_name_carries(self):
+        # Under --ipc=host the owner's pid is from another PID namespace: it
+        # does not exist here, but its lock does.
+        dead = subprocess.Popen([sys.executable, "-c", "pass"])
+        dead.wait()
+        folder = self.folder(f"pm-reset-held-{dead.pid}-abc")
+        self.hold(folder)
+        fast_reset.remove_orphaned_scratch(self.memory)
+        self.assertTrue(folder.exists())
+        self.assertTrue((folder / "seed.db").exists())
+
+    def test_folders_without_an_owner_lock_are_kept(self):
+        dead = subprocess.Popen([sys.executable, "-c", "pass"])
+        dead.wait()
+        legacy = self.folder(f"pm-reset-{dead.pid}-abc")
+        staging = self.folder(f"pm-reset-new-{dead.pid}-def")
+        unlocked = self.folder(f"pm-reset-held-{dead.pid}-ghi")
+        fast_reset.remove_orphaned_scratch(self.memory)
+        for folder in (legacy, staging, unlocked):
+            self.assertTrue(folder.exists(), folder.name)
+
+    def test_a_folder_held_by_another_seeder_in_this_process_is_kept(self):
+        api = types.SimpleNamespace(db=PromptDatabase(str(self.memory / "live.db")))
+        self.addCleanup(api.db.close_all)
+        root = self.memory / "shm"
+        root.mkdir()
+        other = ScratchSeeder(api, self.memory / "fallback", memory_root=root)
+        self.addCleanup(other.close)
+        other.run(reseed)
+        (folder,) = root.iterdir()
+        fast_reset.remove_orphaned_scratch(root)
+        self.assertTrue(folder.exists())
+
+
 if __name__ == "__main__":
     unittest.main()

tests/test_bulk_library_category.py

@@ -0,0 +1,255 @@
+"""#437: the workspace Library's fenced bulk "Set category" (DB command and route)."""
+
+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.operations import PromptDatabase
+from utils.hashing import generate_prompt_hash
+
+try:
+    from test_api_prompts import RouteCoverageCase
+except ImportError:
+    from tests.test_api_prompts import RouteCoverageCase
+
+URL = "/prompt_manager/bulk/category"
+
+
+def save(db, text, **metadata):
+    return db.save_prompt(text, prompt_hash=generate_prompt_hash(text), **metadata)
+
+
+def row(db, prompt_id):
+    with db.model.get_connection() as conn:
+        found = conn.execute(
+            "SELECT category, updated_at FROM prompts WHERE id=?", (prompt_id,)
+        ).fetchone()
+    return tuple(found) if found else None
+
+
+class TestBulkLibraryCategory(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.db = PromptDatabase(str(Path(self.temp.name) / "bulk.db"))
+        self.epoch = self.db.get_library_options()["library_epoch"]
+
+    def tearDown(self):
+        self.db.close_all()
+        self.temp.cleanup()
+
+    def run_bulk(self, ids, category, epoch=None):
+        return self.db.bulk_set_library_category(
+            ids, category, expected_epoch=epoch or self.epoch
+        )
+
+    def test_sets_changed_rows_and_counts_unchanged_and_missing(self):
+        a = save(self.db, "Alpha", category="Old")
+        b = save(self.db, "Beta", category="New")
+        c = save(self.db, "Gamma")
+        before_b = row(self.db, b)
+        result = self.run_bulk([a, b, c, 99999], "  New ")
+        self.assertEqual(
+            result,
+            {
+                "library_epoch": self.epoch,
+                "category": "New",
+                "updated": 2,
+                "unchanged": 1,
+                "not_found": 1,
+            },
+        )
+        self.assertEqual(row(self.db, a)[0], "New")
+        self.assertEqual(row(self.db, c)[0], "New")
+        # An unchanged row keeps its timestamp (and so its edit token).
+        self.assertEqual(row(self.db, b), before_b)
+
+    def test_changed_category_rotates_the_edit_token_only_for_changed_rows(self):
+        a = save(self.db, "Alpha", category="Old")
+        b = save(self.db, "Beta", category="New")
+        tokens = {
+            pid: self.db.get_library_positive(pid)["positive"]["edit_token"]
+            for pid in (a, b)
+        }
+        self.run_bulk([a, b], "New")
+        self.assertNotEqual(
+            self.db.get_library_positive(a)["positive"]["edit_token"], tokens[a]
+        )
+        self.assertEqual(
+            self.db.get_library_positive(b)["positive"]["edit_token"], tokens[b]
+        )
+
+    def test_changed_rows_become_registered_library_parents_like_the_editor(self):
+        a = save(self.db, "Alpha", category="Old")
+        b = save(self.db, "Beta", category="Same")
+
+        def registered(pid):
+            with self.db.model.get_connection() as conn:
+                return bool(
+                    conn.execute(
+                        "SELECT 1 FROM prompt_library_state WHERE prompt_id=?", (pid,)
+                    ).fetchone()
+                )
+
+        self.assertEqual((registered(a), registered(b)), (False, False))
+        self.run_bulk([a, b], "Same")
+        self.assertEqual((registered(a), registered(b)), (True, False))
+
+    def test_updated_at_is_utc_iso_text(self):
+        a = save(self.db, "Alpha")
+        self.run_bulk([a], "Utc")
+        self.assertTrue(row(self.db, a)[1].endswith("+00:00"))
+
+    def test_negative_only_prompts_are_not_library_parents(self):
+        pair = self.db.save_prompt_pair("Cat", "Blur")
+        negative = self.db.get_prompt_pair(pair)["negative_prompt_id"]
+        positive = self.db.get_prompt_pair(pair)["positive_prompt_id"]
+        result = self.run_bulk([positive, negative], "Animals")
+        self.assertEqual((result["updated"], result["not_found"]), (1, 1))
+        self.assertIsNone(row(self.db, negative)[0])
+
+    def test_restored_storage_writes_nothing(self):
+        a = save(self.db, "Alpha", category="Old")
+        new_epoch = rotate_history_epoch(self.db.model.get_connection())
+        with self.assertRaises(LibraryCommandError) as caught:
+            self.run_bulk([a], "New")
+        self.assertEqual(caught.exception.code, "storage-changed")
+        self.assertEqual(caught.exception.epoch, new_epoch)
+        self.assertEqual(row(self.db, a)[0], "Old")
+
+    def test_a_failure_mid_write_leaves_every_row_as_it_was(self):
+        ids = [save(self.db, f"P{i}", category="Old") for i in range(3)]
+        with self.db.model.get_connection() as conn:
+            conn.execute(
+                "CREATE TRIGGER fail_third BEFORE UPDATE OF category ON prompts "
+                f"WHEN OLD.id={ids[2]} BEGIN SELECT RAISE(ABORT, 'boom'); END"
+            )
+        with self.assertRaises(sqlite3.DatabaseError):
+            self.run_bulk(ids, "New")
+        self.assertEqual([row(self.db, pid)[0] for pid in ids], ["Old"] * 3)
+
+    def test_many_ids_are_read_in_chunks(self):
+        ids = [save(self.db, f"Many {i}") for i in range(1000)]
+        result = self.run_bulk(ids, "Bulk")
+        self.assertEqual(result["updated"], 1000)
+
+    def test_rejects_invalid_arguments(self):
+        a = save(self.db, "Alpha")
+        for ids, category, epoch in (
+            ([a], "", self.epoch),
+            ([a], "   ", self.epoch),
+            ([a], None, self.epoch),
+            ([a], "x" * 101, self.epoch),
+            ([a], "bad\x01", self.epoch),
+            ([a], "ok", "not-a-uuid"),
+            ([], "ok", self.epoch),
+        ):
+            with self.subTest(category=category, epoch=epoch, ids=ids):
+                with self.assertRaises(ValueError):
+                    self.run_bulk(ids, category, epoch)
+
+
+class TestBulkLibraryCategoryRoute(RouteCoverageCase):
+    def epoch(self):
+        return self.api.db.get_library_options()["library_epoch"]
+
+    async def test_fenced_form_sets_categories_and_reports_counts(self):
+        ids = [self._save_prompt(f"route {i}", category="Old") for i in range(2)]
+        status, body = await self._json(
+            "POST",
+            URL,
+            json={
+                "prompt_ids": ids,
+                "category": "Fresh",
+                "expected_epoch": self.epoch(),
+            },
+        )
+        self.assertEqual(status, 200)
+        self.assertEqual(
+            body,
+            {
+                "success": True,
+                "library_epoch": self.epoch(),
+                "category": "Fresh",
+                "updated": 2,
+                "unchanged": 0,
+                "not_found": 0,
+            },
+        )
+        self.assertEqual(self.api.db.get_prompt_by_id(ids[1])["category"], "Fresh")
+
+    async def test_restored_storage_answers_409_storage_changed(self):
+        pid = self._save_prompt("route restore", category="Old")
+        stale = self.epoch()
+        new_epoch = rotate_history_epoch(self.api.db.model.get_connection())
+        status, body = await self._json(
+            "POST",
+            URL,
+            json={"prompt_ids": [pid], "category": "Fresh", "expected_epoch": stale},
+        )
+        self.assertEqual((status, body["code"]), (409, "storage-changed"))
+        self.assertFalse(body["success"])
+        self.assertEqual(body["library_epoch"], new_epoch)
+        self.assertIsInstance(body["error"], str)
+        self.assertEqual(self.api.db.get_prompt_by_id(pid)["category"], "Old")
+
+    async def test_fenced_form_validates_its_body(self):
+        pid = self._save_prompt("route validate")
+        epoch = self.epoch()
+        for body in (
+            {"prompt_ids": [pid], "category": "", "expected_epoch": epoch},
+            {"prompt_ids": [pid], "category": "  ", "expected_epoch": epoch},
+            {"prompt_ids": [pid], "category": 5, "expected_epoch": epoch},
+            {"prompt_ids": [pid], "category": "x" * 101, "expected_epoch": epoch},
+            {"prompt_ids": [pid], "category": "ok", "expected_epoch": "nope"},
+            {"prompt_ids": [pid], "category": "ok", "expected_epoch": 7},
+            {"prompt_ids": [], "category": "ok", "expected_epoch": epoch},
+            {"prompt_ids": [True], "category": "ok", "expected_epoch": epoch},
+            {
+                "prompt_ids": list(range(1, 1002)),
+                "category": "ok",
+                "expected_epoch": epoch,
+            },
+            {"prompt_ids": [pid], "expected_epoch": epoch},
+            {
+                "prompt_ids": [pid],
+                "category": "ok",
+                "expected_epoch": epoch,
+                "extra": 1,
+            },
+        ):
+            with self.subTest(body=body):
+                status, answer = await self._json("POST", URL, json=body)
+                self.assertEqual(status, 400)
+                self.assertFalse(answer["success"])
+        self.assertIsNone(self.api.db.get_prompt_by_id(pid)["category"])
+
+    async def test_fenced_form_reports_an_unexpected_failure(self):
+        pid = self._save_prompt("route failure")
+        self._break("bulk_set_library_category")
+        status, body = await self._json(
+            "POST",
+            URL,
+            json={
+                "prompt_ids": [pid],
+                "category": "ok",
+                "expected_epoch": self.epoch(),
+            },
+        )
+        self.assertEqual(status, 500)
+        self.assertFalse(body["success"])
+
+    async def test_legacy_form_is_unchanged(self):
+        pid = self._save_prompt("route legacy", category="Old")
+        status, body = await self._json(
+            "POST", URL, json={"prompt_ids": [pid], "category": "Legacy"}
+        )
+        self.assertEqual((status, body["updated_count"]), (200, 1))
+        self.assertNotIn("library_epoch", body)
+        self.assertEqual(self.api.db.get_prompt_by_id(pid)["category"], "Legacy")
+
+
+if __name__ == "__main__":
+    unittest.main()