tumwater 0.2.0 → 0.3.0

package/dist/src/inbox/inbox-attachments.js

@@ -1,7 +1,6 @@
-// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
-import { removeQuiet, unlinkAllMissingTolerant } from "../files/files.js";
+import { dirEntryNames, removeQuiet, unlinkAllMissingTolerant } from "../files/files.js";
 import { isJsonObject } from "../files/json-object.js";
 import { roleInboxDir } from "../paths.js";
 import { errorMessage, isNonBlankString } from "../text/text.js";
@@ -10,7 +9,7 @@ import { agree, plural } from "../text/phrases.js";
 /** Images attached to queued prompts: a GUI drop or paste into the composer saves each image
  * beside the prompt's queue file (same stem, an image extension — the `.md` filter in
  * listQueueFiles never sees them) and appends one `[image attached: <absolute path>]` line per
- * image to the queued text, so the receiving loop's pi agent can view the file with its read
+ * image to the queued text, so the receiving role's pi agent can view the file with its read
  * tool. Validation lives here once; every surface (the GUI endpoints through submitRolePrompt,
  * the requeue policy through stripVanishedImageReferences) shares it. */
 /** The image extensions pi's read tool renders — exactly what an attachment may carry.
@@ -32,6 +31,17 @@ export function isPromptImageSibling(stem, entry) {
     return ((rest.startsWith(".") && PROMPT_IMAGE_EXTENSIONS.includes(rest.toLowerCase())) ||
         (/^-\d+\./.test(rest) && PROMPT_IMAGE_EXTENSIONS.includes(rest.slice(rest.indexOf(".")).toLowerCase())));
 }
+/** The image siblings of `stem` already in `dir`, as the collision set for a new image's name.
+ * A directory that is missing or unreadable yields an empty set: nothing there to collide
+ * with, and the write that follows reports the real failure, if any. */
+function takenImageSiblings(dir, stem) {
+    const taken = new Set();
+    for (const entry of dirEntryNames(dir)) {
+        if (isPromptImageSibling(stem, entry))
+            taken.add(entry);
+    }
+    return taken;
+}
 /** Pick a file name with extension `ext` under `stem` that does not collide with any name
  * already in `taken`, and record it: `<stem><ext>` when free, else the first
  * `<stem>-<n><ext>` (n from 2 up) that is. The one home of the dedup-suffix rule
@@ -60,7 +70,7 @@ const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
 /** The image-count rule: at most PROMPT_IMAGES_MAX_COUNT entries. Split out of
  * promptImagesProblem so a surface holding the raw path list can refuse an over-long
  * `--attach` list before reading or encoding a single file, with the count wording still the
- * one definition both call sites render. Null when the count is acceptable. */
+ * one definition every raw-path surface renders. Null when the count is acceptable. */
 export function promptImagesCountProblem(count) {
     return count > PROMPT_IMAGES_MAX_COUNT
         ? `at most ${PROMPT_IMAGES_MAX_COUNT} images per prompt (got ${count})`
@@ -186,16 +196,7 @@ export function savePromptImages(root, role, queueFile, images) {
     // that adds a `.png` to a prompt whose image is already `<stem>.png` lands as `<stem>-2.png`
     // instead of overwriting (and orphaning the reference to) the existing file. A directory
     // that does not exist yet leaves the set empty; the write below creates it.
-    const taken = new Set();
-    try {
-        for (const entry of fs.readdirSync(dir)) {
-            if (isPromptImageSibling(stem, entry))
-                taken.add(entry);
-        }
-    }
-    catch {
-        // No inbox dir yet (or unreadable): the write below reports the real failure, if any.
-    }
+    const taken = takenImageSiblings(dir, stem);
     const paths = [];
     // The image whose write is in flight: it only joins `paths` once its write returns, so a
     // write that throws after creating the file (ENOSPC, EIO) would otherwise be the one
@@ -237,7 +238,7 @@ export function imageReferenceLines(paths) {
  * counterpart to imageReferenceLines. Used by the edit path to carry an attached prompt's
  * references (and so their sibling files) over a text rewrite: an edit replaces the prompt's
  * text, not its attachments, which travel with the prompt until a cancel or the fulfilling
- * tick's sweep removes them. A line that is not exactly the writer's shape is content, not a
+ * run's sweep removes them. A line that is not exactly the writer's shape is content, not a
  * reference, and is ignored. */
 export function imageReferencePaths(text) {
     const paths = [];
@@ -250,7 +251,7 @@ export function imageReferencePaths(text) {
 }
 /** Move a re-queued prompt's attachments from its old queue file's stem to the new queue
  * file's stem and rewrite their `[image attached: …]` lines, so an attachment always travels
- * with the prompt's current queue file: the cancel sweep and the fulfilling tick's sweep
+ * with the prompt's current queue file: the cancel sweep and the fulfilling run's sweep
  * (removeSameStemSiblings, keyed on that file's stem) then find it, and a requeue can never
  * strand a file under a stem no queue file names. Only a line naming a same-stem sibling of
  * `fromFile` inside its directory is treated as an attachment — a hand-typed or edited
@@ -259,23 +260,16 @@ export function imageReferencePaths(text) {
  * referenced attachment that is already gone is left for stripVanishedImageReferences to drop
  * and record. Each attachment moves on its own: one file that is gone or cannot be renamed is
  * left in place and named in `problem`, while the attachments around it still move, so a
- * single missing or unmovable file cannot strand the rest under a stem no queue file names. */
+ * single missing or unmovable file cannot strand the rest under a stem no queue file names.
+ * `moves` lists each rename done, so a caller whose later write fails can move them back. */
 export function movePromptImages(fromFile, toFile, text) {
     const dir = path.resolve(path.dirname(fromFile));
     const fromStem = path.basename(fromFile, ".md");
     const toStem = path.basename(toFile, ".md");
     const toDir = path.resolve(path.dirname(toFile));
-    const taken = new Set();
-    try {
-        for (const entry of fs.readdirSync(toDir)) {
-            if (isPromptImageSibling(toStem, entry))
-                taken.add(entry);
-        }
-    }
-    catch {
-        // The queue directory is gone; nothing to collide with.
-    }
+    const taken = takenImageSiblings(toDir, toStem);
     const problems = [];
+    const moves = [];
     const out = [];
     for (const line of text.split("\n")) {
         const referenced = referencedImagePath(line);
@@ -306,9 +300,14 @@ export function movePromptImages(fromFile, toFile, text) {
             out.push(line);
             continue;
         }
+        moves.push({ from: resolved, to: target });
         out.push(line.replace(referenced, target));
     }
-    return { text: out.join("\n"), problem: problems.length > 0 ? problems.join("; ") : null };
+    return {
+        text: out.join("\n"),
+        problem: problems.length > 0 ? problems.join("; ") : null,
+        moves,
+    };
 }
 /** The prompt text without its `[image attached: …]` reference lines, trailing blank lines
  * trimmed — the editable body an editor should show. The reference block is plumbing the edit
@@ -322,8 +321,8 @@ export function stripImageReferenceLines(text) {
     return kept.join("\n");
 }
 /** Drop the `[image attached: …]` lines whose files are no longer on disk from a prompt being
- * re-queued after a tick whose attached image is gone (removed out of band, or by a cancel),
- * so a re-queued copy would otherwise send the loop's agent after files that are gone. Each
+ * re-queued after a run whose attached image is gone (removed out of band, or by a cancel),
+ * so a re-queued copy would otherwise send the role's agent after files that are gone. Each
  * vanished line is replaced by one honest note naming what
  * happened; references whose files still exist are kept. Unchanged text comes back untouched
  * (dropped: []) so the common no-images case costs nothing. */

package/dist/src/inbox/inbox-cancel.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 import path from "node:path";
 import { logEventBestEffort } from "../events/events.js";
 import { roleInboxDir } from "../paths.js";
@@ -7,8 +6,8 @@ import { gotSuffix } from "../text/text.js";
 import { promptPreview, queuedFileAtPosition, queuedFiles, removeSameStemSiblings, takeQueuedFile } from "./inbox.js";
 /** Read one addressed queue file and turn it into a cancel outcome — the one home of the
  * race-policy-and-event pairing both cancel paths go through: { status: "gone" } when the
- * loop already dequeued or another cancel removed the file (takeQueuedFile's race policy,
- * a normal race, never an error), else one prompt_cancelled event under that loop (preview
+ * role already dequeued or another cancel removed the file (takeQueuedFile's race policy,
+ * a normal race, never an error), else one prompt_cancelled event under that role (preview
  * via promptPreview, exactly like the prompt_enqueued sibling) logged, best-effort, only
  * after a successful removal — the removal is the durable effect, so an unwritable feed must
  * not report the cancel as failed;
@@ -19,14 +18,14 @@ function takeCancelledPrompt(root, role, file) {
     const text = takeQueuedFile(file);
     if (text === null)
         return { status: "gone" };
-    // A cancelled prompt's image attachments go with it; a dequeue leaves them for the tick to
+    // A cancelled prompt's image attachments go with it; a dequeue leaves them for the run to
     // read and they are removed on fulfillment (src/inbox/pending-prompt.ts).
     removeSameStemSiblings(root, role, file);
     logEventBestEffort(root, { source: role, type: "prompt_cancelled", preview: promptPreview(text) });
     return { status: "cancelled", text };
 }
-/** Remove the Nth prompt queued for one loop — 1-based, as shown by `tumwater prompt --list` —
- * and log one prompt_cancelled event under that loop (preview via promptPreview, exactly like
+/** Remove the Nth prompt queued for one role — 1-based, as shown by `tumwater prompt --list` —
+ * and log one prompt_cancelled event under that role (preview via promptPreview, exactly like
  * its prompt_enqueued sibling). Throws for out-of-range positions with no side effects; returns
  * { status: "gone" } when the file disappears between listing and removal instead of throwing.
  * The race policy and event live in takeCancelledPrompt. */
@@ -34,8 +33,8 @@ export function cancelRolePrompt(root, role, position) {
     return takeCancelledPrompt(root, role, queuedFileAtPosition(root, role, position));
 }
 /** Forward a resolution to a list-wide command's outcome: a miss shape returns verbatim, a
- * found one calls `found` with the resolved loop (so the command's own side-effecting queue
- * action stays lazy — it runs only for the single loop that holds the position). Both
+ * found one calls `found` with the resolved role (so the command's own side-effecting queue
+ * action stays lazy — it runs only for the single role that holds the position). Both
  * list-wide commands — cancelListedPrompt and editListedPrompt — are the call sites. */
 export function listedQueueOutcome(resolved, found) {
     switch (resolved.status) {
@@ -47,7 +46,7 @@ export function listedQueueOutcome(resolved, found) {
     }
 }
 /** Resolve a list-wide 1-based position (a `prompt --cancel`/`--edit` with no --role) to the
- * one loop whose queue is long enough to hold it, in `scope` order — the semantics the
+ * one role whose queue is long enough to hold it, in `scope` order — the semantics the
  * ListedQueueResolution doc above specifies. Sizes only: no queue content is read. */
 export function resolveListedQueue(root, scope, position) {
     const candidates = scope.filter((role) => queuedFiles(root, role).length >= position);
@@ -62,7 +61,7 @@ export function resolveListedQueue(root, scope, position) {
     return { status: "found", role };
 }
 /** Cancel by the position numbering `tumwater prompt --list` prints with no --role: the
- * position resolves through the shared resolveListedQueue (above), then one loop's queue
+ * position resolves through the shared resolveListedQueue (above), then one role's queue
  * takes the cancel (cancelRolePrompt's race policy and event). */
 export function cancelListedPrompt(root, scope, position) {
     const resolved = resolveListedQueue(root, scope, position);
@@ -73,7 +72,7 @@ export function cancelListedPrompt(root, scope, position) {
     }));
 }
 /** The queue-file-name guard for a file-addressed cancel: a name arriving over HTTP is
- * trusted only as a plain basename inside the loop's queue directory — anything containing a
+ * trusted only as a plain basename inside the role's queue directory — anything containing a
  * path separator or equal to `..` could name a file elsewhere on disk, a NUL byte is not a
  * character any filename can hold (the fs layer throws on it rather than answering ENOENT,
  * so the endpoint's 400 contract needs it rejected before anything touches the disk), and a

package/dist/src/inbox/inbox-edit.js

@@ -8,20 +8,20 @@ import { assertQueueFileName, listedQueueOutcome, resolveListedQueue } from "./i
 import { notBeforeMs, notBeforeMarker, stripNotBeforeMarker } from "./prompt-not-before.js";
 import { roleInboxDir } from "../paths.js";
 /** Rewrite one queued prompt's file in place — the shared core behind editRolePrompt (address
- * by per-loop position) and editQueuedFile (address by queue-file basename): same queue file
+ * by per-role position) and editQueuedFile (address by queue-file basename): same queue file
  * (so the filename's enqueue stamp and the entry's position behind older prompts are
  * untouched), same atomic write enqueueRolePrompt uses
  * (writeTextAtomic's temp file + rename, so a concurrent dequeue or another edit can never
  * expose a half-written file), and the existing not-before deferral carried over — when the
  * old file starts with the marker, the new text is written under the same marker; a
  * non-deferred prompt stays marker-free even if the new text's first line resembles a
- * marker. Logs one prompt_edited event under that loop (preview via promptPreview, exactly
+ * marker. Logs one prompt_edited event under that role (preview via promptPreview, exactly
  * like its prompt_cancelled sibling) after a successful write, best-effort: the rewrite is
  * the durable effect, so an unwritable feed must not report the edit as failed.
  *
  * Carries an attached prompt's `[image attached: …]` reference lines (and so their sibling
  * files) over the rewrite — the edit replaces the prompt's text, not its attachments, which
- * stay beside the edited queue file until a cancel or the fulfilling tick's sweep removes
+ * stay beside the edited queue file until a cancel or the fulfilling run's sweep removes
  * them. An optional `images` array (the CLI's
  * `prompt --edit … --attach`) appends its newly saved reference lines after the carried ones,
  * so one command corrects the text and the images in place instead of cancel-and-re-queue;
@@ -29,7 +29,7 @@ import { roleInboxDir } from "../paths.js";
  * new files again.
  *
  * Enforces the same prefill length cap as a submission (promptLengthProblem): the edited
- * text plus its carried image lines ride into the target tick's prefill exactly like a
+ * text plus its carried image lines ride into the target run's prefill exactly like a
  * queued prompt, so an edit to an over-cap value must not bypass the cap every enqueue path
  * applies. The initial text check throws before any read or write; the composed check (body
  * plus carried image lines) throws before the write when the body alone fit.
@@ -38,7 +38,7 @@ import { roleInboxDir } from "../paths.js";
  * the image-address form throws for a name failing queueFileNameProblem before touching disk.
  * The race policy pairs with the outcome: the file is read first, and a read that hits ENOENT
  * returns { status: "gone" } —
- * the loop dequeued it or a cancel removed it between listing and write, a normal race
+ * the role dequeued it or a cancel removed it between listing and write, a normal race
  * exactly like takeCancelledPrompt's; any other read error propagates (a permission failure
  * is not a race). The write itself is unconditional once the read succeeded: a dequeue that
  * lands between that read and the rename is a narrower race than takeQueuedFile's own
@@ -78,7 +78,7 @@ function editPromptAtFile(root, role, file, newText, images) {
                 throw new Error(saved.problem);
             savedImagePaths = saved.paths;
         }
-        // The composed text is what a tick's prefill receives, so the submission cap covers the
+        // The composed text is what a run's prefill receives, so the submission cap covers the
         // body plus every reference line; the carried paths stay first, the new ones append after
         // them in one reference block.
         composed = text + imageReferenceLines([...carriedPaths, ...savedImagePaths]);
@@ -96,7 +96,7 @@ function editPromptAtFile(root, role, file, newText, images) {
     logEventBestEffort(root, { source: role, type: "prompt_edited", preview: promptPreview(composed) });
     return { status: "edited", oldText, newText: composed };
 }
-/** Rewrite the Nth prompt queued for one loop — 1-based, as shown by `tumwater prompt
+/** Rewrite the Nth prompt queued for one role — 1-based, as shown by `tumwater prompt
  * --list` — in place, through the shared editPromptAtFile. See that helper for the full
  * contract (deferral carry-over, attachment carry-over, the prompt_edited event, the race
  * policy). */
@@ -118,7 +118,7 @@ export function editQueuedFile(root, role, name, newText, images) {
  * edit affordance (PLANS.md 2026-10-11): stripNotBeforeMarker drops the deferral plumbing,
  * stripImageReferenceLines drops the `[image attached: …]` reference block the edit carries
  * over unchanged (so it is never shown in the editor and cannot be edited away), and trimEnd
- * drops any blank lines left behind. null when the file is gone — the loop dequeued it or
+ * drops any blank lines left behind. null when the file is gone — the role dequeued it or
  * another operator cancelled it, which the endpoint reports as { status: "gone" } rather than
  * an error. Throws for a name failing queueFileNameProblem. Reading the one named file directly
  * keeps the dashboard's lazy fetch off the per-poll path. */
@@ -131,7 +131,7 @@ export function readQueuedPromptBody(root, role, name) {
 }
 /** Edit by the position numbering `tumwater prompt --list` prints with no --role: the same
  * candidate resolution cancelListedPrompt uses — resolveListedQueue, in inbox-cancel.ts, so
- * the two cannot drift — followed by editRolePrompt in the resolved loop. One loop holding
+ * the two cannot drift — followed by editRolePrompt in the resolved role. One role holding
  * the position resolves, several are an ambiguity the caller reports with a --role escape
  * hatch, none is a miss carrying the largest queue length for the error's count. */
 export function editListedPrompt(root, scope, position, newText, images) {

package/dist/src/inbox/inbox-submit.js

@@ -1,28 +1,28 @@
-// vocabulary: plain
 import { enqueueRolePrompt, promptPreview } from "./inbox.js";
 import { unlinkAllMissingTolerant } from "../files/files.js";
 import { imageReferenceLines, promptImagesProblem, savePromptImages, } from "./inbox-attachments.js";
 import { logEventBestEffort } from "../events/events.js";
-import { INITIAL_PROMPT_MAX_CHARS } from "../brief/brief.js";
+import { BRIEF_TEXT_MAX_CHARS } from "../brief/brief.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { tooLongMessage } from "../text/text.js";
 import { defaultConfig, loadConfigSafe } from "../config/config.js";
 import { roleImageInfo } from "../agent/image-input.js";
+import { readPiListedModels } from "../pi/pi-listed-models.js";
 import { readImageProbeCache } from "../doctor/image-probe.js";
 import { roleLabel } from "../roles/role-labels.js";
 /** The user-facing submission pipeline for the prompt queues (the store's mechanics —
  * listing, peeking, dequeuing, cancelling, and their race policy — live in src/inbox/inbox.ts,
  * and the image side of a submission in src/inbox/inbox-attachments.ts): the shared length cap,
  * the validation, and the submit wrappers the TUI, GUI, and CLI all go through. */
-/** Cap on a submitted prompt's length: the same ceiling for every loop's queue, director and
- * role alike, because every prompt rides into its target tick's prefill — a megabyte pasted
+/** Cap on a submitted prompt's length: the same ceiling for every role's queue, director and
+ * role alike, because every prompt rides into its target run's prefill — a megabyte pasted
  * into the TUI, a GUI POST, or a shell-mistaken `tumwater prompt $(cat …)` would otherwise
- * ride into the next tick's context wholesale. submitPrompt and submitRolePrompt reject
+ * ride into the next run's context wholesale. submitPrompt and submitRolePrompt reject
  * over-long text before it is queued, so no surface can enqueue it. */
-export const DIRECTOR_PROMPT_MAX_CHARS = INITIAL_PROMPT_MAX_CHARS;
-/** The one length rule for a submitted prompt, scoped to the loop it targets: the error
+export const DIRECTOR_PROMPT_MAX_CHARS = BRIEF_TEXT_MAX_CHARS;
+/** The one length rule for a submitted prompt, scoped to the role it targets: the error
  * message when the trimmed text exceeds DIRECTOR_PROMPT_MAX_CHARS, null when it fits. The
- * message names the target loop's tick — `--role qa` must not be told its text rides into
+ * message names the target role's run — `--role qa` must not be told its text rides into
  * the director's prefill. submitPrompt/submitRolePrompt throw it before anything is queued
  * or logged; the GUI asks it first so an over-long prompt answers 400 (a user-input error)
  * while an unexpected submit failure (a broken inbox's EACCES) stays the 500 its
@@ -33,12 +33,12 @@ export function promptLengthProblem(text, role = DIRECTOR_ROLE) {
         return null;
     return tooLongMessage("the prompt", prompt.length, DIRECTOR_PROMPT_MAX_CHARS, `it rides into the ${roleLabel(role)} run's prefill`);
 }
-/** The image-input submit guidance for one loop (plans/image-input.md "Surfaces" and
+/** The image-input submit guidance for one role (plans/image-input.md "Surfaces" and
  * "Attachments", part 5/5): what an image-carrying prompt to `role` means. `refusal` is the
- * throw-and-submit-nothing message when the loop's seam reads no images and no peer tier can
- * (an attachment no configured model can read is refused at submit, not discovered at tick
+ * throw-and-submit-nothing message when the role's seam reads no images and no peer tier can
+ * (an attachment no configured model can read is refused at submit, not discovered at run
  * time); `notice` is what a surface prints/shows when the prompt will instead rerun on another
- * tier. Both null when the loop's own model reads images (or capability is unknown — an
+ * tier. Both null when the role's own model reads images (or capability is unknown — an
  * unknown seam is never assumed incapable, mirroring the doctor's `tier models` stance), so
  * the common text-only or vision path says nothing. One resolver (roleImageInfo), shared with
  * the status rows and role page, so the gate cannot disagree with what `tumwater role` or the
@@ -49,7 +49,7 @@ export function imagePromptGuidance(root, role) {
     // The same probe cache the status rows, role page, and images alert read (roleImageInfo's
     // fourth argument): a claimed pi model whose doctor probe failed reads text-only here too,
     // so the gate never grants image capability that the surfaces report as absent.
-    const { imageInput, imageReroute } = roleImageInfo(cfg, role, undefined, readImageProbeCache(root));
+    const { imageInput, imageReroute } = roleImageInfo(cfg, role, undefined, readImageProbeCache(root), readPiListedModels(root));
     if (imageInput !== false)
         return {};
     if (imageReroute) {
@@ -61,8 +61,8 @@ export function imagePromptGuidance(root, role) {
         refusal: `${role}'s model can't read images and no configured model reads images for it — declare image input on a vision model in pi's models.json, or point a tier at one`,
     };
 }
-/** A user submits a new prompt for one loop (TUI, GUI, or CLI): enqueue it there and record it
- * in the event log under that loop, best-effort — the queue write is the durable effect the
+/** A user submits a new prompt for one role (TUI, GUI, or CLI): enqueue it there and record it
+ * in the event log under that role, best-effort — the queue write is the durable effect the
  * caller asked for, so an unwritable feed must not report the submit as failed. Returns the
  * trimmed prompt that was queued. The logged
  * preview goes through promptPreview — not a raw slice — so an over-long prompt is marked with
@@ -72,7 +72,7 @@ export function imagePromptGuidance(root, role) {
  * operator. An optional images array (the GUI composer's drop/paste attachments) rides
  * through savePromptImages beside the queue file, with one [image attached: …] reference line
  * appended to the queued text; image problems throw before anything is queued — and so does
- * an over-cap composed text: the reference lines ride into the tick's prefill just like the
+ * an over-cap composed text: the reference lines ride into the run's prefill just like the
  * prompt body, so the length cap is enforced on the final text (body + image lines), not the
  * body alone.
  * An optional `notBeforeMs` defers the prompt (PLANS.md "tumwater prompt --at <duration>"):
@@ -87,7 +87,7 @@ export function submitRolePrompt(root, role, text, images, notBeforeMs) {
             throw new Error(imageProblem);
         // Image input gate (plans/image-input.md "Attachments", part 5/5): an attachment no
         // configured model can read is refused here, before anything is queued or written — the
-        // tick would only fail discovering it. A loop that reroutes a blind read is not refused;
+        // run would only fail discovering it. A role that reroutes a blind read is not refused;
         // the surface prints/shows the notice instead (imagePromptGuidance is called again there).
         const guidance = imagePromptGuidance(root, role);
         if (guidance.refusal)
@@ -118,7 +118,7 @@ function submitPromptWithImages(root, role, text, images, notBeforeMs) {
                 throw new Error(saved.problem); // Unreachable: validated above.
             savedImagePaths = saved.paths;
             final = prompt + imageReferenceLines(saved.paths);
-            // The image reference lines ride into the target tick's prefill exactly like the
+            // The image reference lines ride into the target run's prefill exactly like the
             // prompt body, so the shared length cap applies to the composed text, not the body
             // alone. This runs inside the decorate hook, before enqueueRolePrompt's one atomic
             // write, so an over-cap composition queues nothing; the images saved above are

package/dist/src/inbox/inbox-top.js

@@ -1,6 +1,5 @@
-// vocabulary: plain
 import path from "node:path";
-import { existsSync } from "node:fs";
+import { existsSync, renameSync } from "node:fs";
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
 import { queueFileName, queueFileStamp, removeQueueFile } from "../files/file-queue.js";
 import { readTextIfExists, writeTextAtomic } from "../files/files.js";
@@ -13,9 +12,11 @@ import { movePromptImages, stripVanishedImageReferences } from "./inbox-attachme
  * `tumwater:not-before` marker, which rides in the text) byte-for-byte to the new stem, its
  * image attachments moving to that new stem too (movePromptImages, with
  * stripVanishedImageReferences dropping any already-gone reference) — and one `prompt_topped`
- * event is logged under the loop. Returns { status: "gone" } when the file disappears between
+ * event is logged under the role. Returns { status: "gone" } when the file disappears between
  * the caller's listing and the read here (a concurrent pop is a normal race, never an
- * error), sharing the store's takeQueuedFile convention. */
+ * error), sharing the store's takeQueuedFile convention. A failed write of the new queue file
+ * moves the attachments back and rethrows, so the prompt stays queued at its old position with
+ * its images. */
 function moveFileToTop(root, role, file) {
     const text = readTextIfExists(file);
     if (text === null)
@@ -40,18 +41,33 @@ function moveFileToTop(root, role, file) {
     if (moved.problem !== null)
         warnEventBestEffort(root, role, moved.problem);
     const carried = stripVanishedImageReferences(moved.text).text;
-    writeTextAtomic(newFile, carried);
+    try {
+        writeTextAtomic(newFile, carried);
+    }
+    catch (err) {
+        // Put the attachments back under the old stem, so the prompt still queued there keeps its
+        // images; one failed rename must not stop the others or mask the write error.
+        for (const m of moved.moves) {
+            try {
+                renameSync(m.to, m.from);
+            }
+            catch {
+                // Best effort: the write error is the one the caller sees.
+            }
+        }
+        throw err;
+    }
     removeQueueFile(file);
     logEventBestEffort(root, { source: role, type: "prompt_topped", preview: promptPreview(carried) });
     return { status: "topped", preview: promptPreview(carried) };
 }
-/** Move the Nth prompt queued for one loop — 1-based, as shown by `tumwater prompt --list` —
- * to the head of its queue, so the loop dequeues it next. Inbox order is the queue-file name
+/** Move the Nth prompt queued for one role — 1-based, as shown by `tumwater prompt --list` —
+ * to the head of its queue, so the role dequeues it next. Inbox order is the queue-file name
  * (`queueFileName`'s timestamp stamp), so the only way to make one prompt next is to give it a
  * stamp one below the queue's minimum; the file's text (and its `tumwater:not-before` marker,
  * which rides in the text) is carried byte-for-byte to the new stem, its image attachments
  * move to that new stem too (movePromptImages, with stripVanishedImageReferences dropping any
- * already-gone reference), and one `prompt_topped` event is logged under the loop.
+ * already-gone reference), and one `prompt_topped` event is logged under the role.
  *
  * Throws for out-of-range positions and for position 1 ("already first"), both with no side
  * effects — the moveEntryToTop precedent. Returns { status: "gone" } when the file disappears
@@ -68,7 +84,7 @@ export function movePromptToTop(root, role, position) {
  * queue — the file-addressed twin of movePromptToTop, for the dashboard's per-row Move to
  * top affordance: the address is the file itself, so a stale poll can never reorder the
  * wrong prompt. Throws for a name failing queueFileNameProblem (re-checked through
- * assertQueueFileName, so a caller that skips the guard fails closed); a file the loop
+ * assertQueueFileName, so a caller that skips the guard fails closed); a file the role
  * already dequeued answers "gone", and the queue head answers "already_first" with no write.
  * Reuses moveFileToTop's rename-and-event pairing, so both address forms cannot drift. */
 export function topQueuedFile(root, role, name) {