tumwater 0.1.3 → 0.2.0

package/dist/src/history/history.js

@@ -1,61 +1,18 @@
-import { formatTimestamp } from "../text/datetime.js";
+// vocabulary: plain
 import { fail, say, sayJson } from "../cli/cli-output.js";
 import { durationLabel, failRivalShapes, flagValue, parseCountFlag, parseGrepFlag, parseRoleScope, parseSinceFlag } from "../cli/cli-args.js";
-import { displayWidth, padToWidth } from "../text/text-width.js";
-import { HISTORY_DEFAULT_TICKS, HISTORY_MAX_TICKS, HISTORY_RESULT_CLASSES, historyClass, readTickRows, readTickRowsSince, summarizeTickRows, tickRowCells, tickRowLine, tickRowsMatchingGrep } from "./history-data.js";
+import { HISTORY_DEFAULT_TICKS, HISTORY_MAX_TICKS, HISTORY_RESULT_FLAG_NAMES, historyClass, parseHistoryResultClass, readTickRows, readTickRowsSince, summarizeTickRows, tickRowsMatchingGrep } from "./history-data.js";
+import { renderRow, renderSummary, widestWidths } from "./history-render.js";
 import { LOGS_SINCE_MAX_MS, SPARSE_WINDOW_NOTE } from "../events/event-window.js";
 import { gotSuffix } from "../text/text.js";
-/** Each column's width from its unpadded cell. Text cells measure terminal display columns
- * (displayWidth), not UTF-16 code units: a loop name holding CJK or emoji renders two columns
- * per code point, and a code-unit padEnd lets that row's later columns drift right of its
- * ASCII neighbors. The tick cell measures before its "#" prefix is added (the prefix rides
- * outside the pad), and duration is ASCII, so both take plain length. */
-function widthsOf(cells) {
-    return {
-        loop: displayWidth(cells.loop),
-        tick: cells.tick.length,
-        result: displayWidth(cells.result),
-        duration: cells.duration.length,
-        usage: displayWidth(cells.usage),
-    };
-}
-/** The per-column maxima over every row the table shows — the widths derive from the rows
- * actually shown, so a single-row table has no padding gap. */
-function widestWidths(rows) {
-    const widths = { loop: 0, tick: 0, result: 0, duration: 0, usage: 0 };
-    for (const row of rows) {
-        const w = widthsOf(tickRowCells(row));
-        widths.loop = Math.max(widths.loop, w.loop);
-        widths.tick = Math.max(widths.tick, w.tick);
-        widths.result = Math.max(widths.result, w.result);
-        widths.duration = Math.max(widths.duration, w.duration);
-        widths.usage = Math.max(widths.usage, w.usage);
-    }
-    return widths;
-}
-/** One aligned table line: fixed-width columns over the row set, then the free-text detail.
- * Every cell is padded to its column's width even when empty — usage is the one cell that can
- * be empty (a tick with neither tokens nor cost), and dropping it would pull the detail left,
- * misaligning that row against its neighbors; tickRowLine strips only the trailing pad. The
- * row's column order rides history-data.ts's tickRowLine, shared with the grep haystack so the
- * two cannot disagree about which field sits where. */
-function renderRow(row, widths) {
-    return tickRowLine(row, (column, value) => padToWidth(value, widths[column]));
-}
-/** The `--summary` text: a header, one line per loop, then the total line. The loop column pads to
- * display width; each number column right-aligns under its header; the last column, `last change`,
- * is the newest change's timestamp (`—` when none) and is left-aligned, unpadded. */
-export function renderSummary(summary) {
-    const all = [...summary.loops, summary.total];
-    const loopWidth = Math.max(...["loop", ...all.map((r) => r.loop)].map(displayWidth));
-    const cols = ["ticks", "changes", "none", "problems"];
-    const widths = cols.map((c) => Math.max(c.length, ...all.map((r) => String(r[c]).length)));
-    const line = (loop, cells, lastChange) => [padToWidth(loop, loopWidth), ...cells.map((c, i) => c.padStart(widths[i] ?? 0)), lastChange].join("  ").trimEnd();
-    return [
-        line("loop", [...cols], "last change"),
-        ...all.map((r) => line(r.loop, cols.map((c) => String(r[c])), r.lastChangeTs === null ? "—" : formatTimestamp(r.lastChangeTs))),
-    ].join("\n");
-}
+import { typoSuffix } from "../text/suggest.js";
+/** `tumwater history [--role <id>] [-n N]`: one row per completed tick, newest first. The
+ * observing half beside cmdLogs (log-commands.ts): read-only over the event log, stdout only —
+ * every datum rides the `run_end` events src/tick/tick-finalize.ts already writes, so this
+ * is a rendering of the existing record, not a new one. The rows themselves are collected
+ * by history-data.ts (beside src/report/report-data.ts and src/failure/failure-data.ts), and
+ * the aligned table/summary text they print is rendered by history-render.ts (beside
+ * src/report/report-render.ts); this module parses the args, drives the CLI, and prints. */
 /** The missing-pattern error cmdHistory prints for a valueless or empty `--grep`, exported so
  * cli.ts's rejectUnknownArgs spec for --grep can fail a trailing `history --grep` with the same
  * wording. Kept local to this module — log-commands.ts holds its own GREP_VALUE_ERROR — so the
@@ -72,10 +29,10 @@ export const HISTORY_RESULT_VALUE_ERROR = "history --result needs a value";
  * speak. `--grep` keeps rows whose rendered line matches, and `--result` narrows to one outcome
  * class (changes/none/problems, the dashboard History filter's buckets); both compose with
  * --role, -n, and --since. Read-only: stdout only, no state file created — a missing or empty
- * event log prints `no ticks yet` and exits 0. */
+ * event log prints `no runs yet` and exits 0. */
 export async function cmdHistory(root, args) {
     // `--grep <text>` filters the row set case-insensitively against the WYSIWYG row line (plus a
-    // `tick_end` prefix, the same haystack rule logs --grep applies to its rendered lines), so
+    // `run_end` prefix, the same haystack rule logs --grep applies to its rendered lines), so
     // both observing views answer substring questions the same way. The flag scan itself — the
     // value lookup, the `rest` construction that keeps a flag-shaped pattern (`history --grep
     // --since` greps for the text "--since") from impersonating a rival flag, and the
@@ -116,28 +73,30 @@ export async function cmdHistory(root, args) {
         rows = tickRowsMatchingGrep(rows, grepPattern);
     // The set --grep admitted, saved so the empty-state wording blames the filter that actually
     // emptied it: if the result filter below removes rows grep matched, naming the pattern would
-    // be false (`no ticks matching "widget"` when feature #7 does match). The GUI draws the same
+    // be false (`no runs matching "widget"` when feature #7 does match). The GUI draws the same
     // line between a search and its outcome filter.
     const afterGrep = rows.length;
     // `--result <class>` narrows to one outcome bucket, reading the same canonical historyClass
     // rule the dashboard's History filter applies (shared from history-data.ts, not copied). It
     // composes with --role, -n, --since, and --grep, so no rival-shape rule: a missing or empty
     // value fails with its own wording, and an unknown class names the accepted ones (the gotSuffix
-    // shape the other flag validators use). Applied after --grep, over the same rows both the table
+    // shape the other flag validators use, plus a did-you-mean hint for a near-miss of a real
+    // result — the same typoSuffix treatment `logs --type` gives its codes). Applied after --grep,
+    // over the same rows both the table
     // and --json serialize.
     const resultRaw = flagValue(rest, "--result");
     let resultClass = null;
     if (resultRaw !== null) {
         if (resultRaw === undefined || resultRaw === "")
             fail(HISTORY_RESULT_VALUE_ERROR);
-        if (!HISTORY_RESULT_CLASSES.includes(resultRaw))
-            fail(`history --result must be one of ${HISTORY_RESULT_CLASSES.join(", ")}${gotSuffix(resultRaw)}`);
-        resultClass = resultRaw;
+        resultClass = parseHistoryResultClass(resultRaw);
+        if (resultClass === null)
+            fail(`history --result must be one of ${Object.values(HISTORY_RESULT_FLAG_NAMES).join(", ")}${gotSuffix(resultRaw)}${typoSuffix(resultRaw, Object.values(HISTORY_RESULT_FLAG_NAMES))}`);
         rows = rows.filter((r) => historyClass(r.result) === resultClass);
     }
     // --json swaps the renderer for the collector's own payload, exactly as status --json and
     // report --json: the same rows the table prints, each with ts/tokens/costUsd kept raw. A
-    // JSON document even when the log is empty ({"rows":[]} — never the prose `no ticks yet`,
+    // JSON document even when the log is empty ({"rows":[]} — never the prose `no runs yet`,
     // the report --json precedent: the flag's output must be parseable in every exit-0 case).
     const summary = rest.includes("--summary") && rows.length > 0;
     if (rest.includes("--json")) {
@@ -145,9 +104,9 @@ export async function cmdHistory(root, args) {
         return;
     }
     if (rows.length === 0) {
-        // A grep that matched nothing must not borrow the empty-log prose: `no ticks yet` and
-        // `no ticks in 2h` are statements about the LOG and the WINDOW, and both are false when
-        // rows were scanned and filtered out — the operator would read a quiet fleet where the
+        // A grep that matched nothing must not borrow the empty-log prose: `no runs yet` and
+        // `no runs in 2h` are statements about the LOG and the WINDOW, and both are false when
+        // rows were scanned and filtered out — the operator would read a quiet team where the
         // truth is `the ticks are there, none match`. The logs --grep rule (its `no events
         // matching "<pattern>"`, src/cli/log-commands.ts) names the pattern instead; --json stays
         // a bare {"rows":[]} document above, never prose in either form.
@@ -157,12 +116,12 @@ export async function cmdHistory(root, args) {
         // empty-log/window prose is the true one — the dashboard's History view draws the same
         // line. A grep that admitted nothing keeps its own wording regardless of --result.
         say(resultClass !== null && afterGrep > 0
-            ? `no ticks with result "${resultClass}"`
+            ? `no runs with result "${resultClass}"`
             : grepPattern !== null
-                ? `no ticks matching "${grepPattern}"`
+                ? `no runs matching "${grepPattern}"`
                 : sinceMs === null
-                    ? "no ticks yet"
-                    : `no ticks in ${durationLabel(sinceMs)}`);
+                    ? "no runs yet"
+                    : `no runs in ${durationLabel(sinceMs)}`);
         return;
     }
     if (summary)
@@ -171,7 +130,7 @@ export async function cmdHistory(root, args) {
         const widths = widestWidths(rows);
         say(rows.map((r) => renderRow(r, widths)).join("\n"));
     }
-    // A sparse window is never mistaken for a quiet fleet — but the note only ever rides rows
+    // A sparse window is never mistaken for a quiet team — but the note only ever rides rows
     // (an empty window returned above), it never touches --json output, and it is the shared
     // SPARSE_WINDOW_NOTE wording: the oldest retained event being inside the window is exactly
     // the unproven case, whether the cause is rotation or idleness.

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

@@ -1,9 +1,11 @@
+// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { 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";
+import { typoSuffix } from "../text/suggest.js";
 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
@@ -30,6 +32,18 @@ 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())));
 }
+/** 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
+ * savePromptImages and movePromptImages both use, so a same-stem sibling can never overwrite
+ * another. `taken` is updated with the chosen name. */
+function uniqueStemName(stem, ext, taken) {
+    let name = `${stem}${ext}`;
+    for (let n = 2; taken.has(name); n++)
+        name = `${stem}-${n}${ext}`;
+    taken.add(name);
+    return name;
+}
 /** Per-image decoded-size cap. Exported so a surface that holds a file before reading it
  * (the GUI composer's drop/paste handler) can refuse an oversized image with the same bound
  * the endpoint enforces, instead of offering a chip the server later rejects. */
@@ -59,7 +73,7 @@ export function promptImageExtensionProblem(name) {
     const ext = path.extname(name).toLowerCase();
     if (PROMPT_IMAGE_EXTENSIONS.includes(ext))
         return null;
-    return `unsupported image type ${JSON.stringify(ext === "" ? name : `*${ext}`)} — expected one of ${PROMPT_IMAGE_EXTENSIONS.join(" ")}`;
+    return `unsupported image type ${JSON.stringify(ext === "" ? name : `*${ext}`)} — expected one of ${PROMPT_IMAGE_EXTENSIONS.join(" ")}${typoSuffix(ext, PROMPT_IMAGE_EXTENSIONS)}`;
 }
 /** The per-image size rule, in decoded bytes: at most PROMPT_IMAGE_MAX_BYTES. Split out so a
  * surface holding an on-disk path can stat it and refuse an oversized file before reading it
@@ -104,6 +118,54 @@ export function promptImagesProblem(images) {
     }
     return null;
 }
+/** Read and validate an on-disk `--attach` path list into the GUI's image input shape — the
+ * throwing core the CLI's `readPromptImages` and the TUI's prompt-line image attach share, so
+ * both surfaces validate from one home. It applies the same cheap path-only rules first — the
+ * shared count cap before any file is read (so a glob that expanded past it is rejected
+ * without reading or base64-encoding dozens of files), then each path's extension,
+ * regular-file shape, and on-disk size (the regular-file check keeps this from reading a FIFO
+ * or device node that would block the caller indefinitely); a path that cannot be statted is
+ * left for the read below to report with its own missing-file wording. It reads each
+ * surviving file whole and re-runs the endpoint's validation (promptImagesProblem) so the
+ * error names the broken rule with the same wording the dashboard answers 400 with. Each
+ * failure is a thrown Error carrying that existing wording. */
+export function readPromptImageFiles(paths) {
+    const countProblem = promptImagesCountProblem(paths.length);
+    if (countProblem !== null)
+        throw new Error(countProblem);
+    for (const p of paths) {
+        const extProblem = promptImageExtensionProblem(p);
+        if (extProblem !== null)
+            throw new Error(extProblem);
+        let stat;
+        try {
+            stat = fs.statSync(p);
+        }
+        catch {
+            // Missing or unreadable: the read below names it.
+            continue;
+        }
+        if (!stat.isFile())
+            throw new Error(`attached image ${JSON.stringify(p)} is not a regular file — pass a path to an image file`);
+        const sizeProblem = promptImageSizeProblem(path.basename(p), stat.size);
+        if (sizeProblem !== null)
+            throw new Error(sizeProblem);
+    }
+    const images = paths.map((p) => {
+        let bytes;
+        try {
+            bytes = fs.readFileSync(p);
+        }
+        catch (err) {
+            throw new Error(`cannot read attached image ${JSON.stringify(p)}: ${errorMessage(err)}`);
+        }
+        return { name: path.basename(p), dataBase64: bytes.toString("base64") };
+    });
+    const problem = promptImagesProblem(images);
+    if (problem !== null)
+        throw new Error(problem);
+    return images;
+}
 /** Save already-validated images beside a queued prompt's queue file — one file per image,
  * named with the queue file's stem plus the image's extension (`<stem>.png`); same-extension
  * images after the first get a `-<n>` suffix so they cannot overwrite each other. The client's
@@ -142,10 +204,7 @@ export function savePromptImages(root, role, queueFile, images) {
     try {
         for (const image of images) {
             const ext = path.extname(image.name).toLowerCase();
-            let name = `${stem}${ext}`;
-            for (let n = 2; taken.has(name); n++)
-                name = `${stem}-${n}${ext}`;
-            taken.add(name);
+            const name = uniqueStemName(stem, ext, taken);
             const file = path.join(dir, name);
             inFlight = file;
             fs.writeFileSync(file, Buffer.from(image.dataBase64, "base64"));
@@ -235,10 +294,7 @@ export function movePromptImages(fromFile, toFile, text) {
             continue;
         }
         const ext = path.extname(base).toLowerCase();
-        let name = `${toStem}${ext}`;
-        for (let n = 2; taken.has(name); n++)
-            name = `${toStem}-${n}${ext}`;
-        taken.add(name);
+        const name = uniqueStemName(toStem, ext, taken);
         const target = path.join(toDir, name);
         try {
             fs.renameSync(resolved, target);
@@ -286,6 +342,6 @@ export function stripVanishedImageReferences(text) {
         return { text, dropped: 0 };
     const body = kept.join("\n").replace(/\n+$/, "");
     const note = `[image attachments dropped: ${plural(dropped, "image file")} ${agree(dropped, "was", "were")}` +
-        ` missing when this prompt was re-queued and ${agree(dropped, "is", "are")} no longer on disk]`;
+        ` missing when this prompt was returned to the inbox and ${agree(dropped, "is", "are")} no longer on disk]`;
     return { text: `${body}\n\n${note}`, dropped };
 }

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

@@ -1,3 +1,4 @@
+// vocabulary: plain
 import path from "node:path";
 import { logEventBestEffort } from "../events/events.js";
 import { roleInboxDir } from "../paths.js";
@@ -21,7 +22,7 @@ function takeCancelledPrompt(root, role, file) {
     // A cancelled prompt's image attachments go with it; a dequeue leaves them for the tick to
     // read and they are removed on fulfillment (src/inbox/pending-prompt.ts).
     removeSameStemSiblings(root, role, file);
-    logEventBestEffort(root, { loop: role, type: "prompt_cancelled", preview: promptPreview(text) });
+    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` —
@@ -90,13 +91,14 @@ export function queueFileNameProblem(name) {
         return `file must be a plain queue-file basename${gotSuffix(name)} — send just the name, not a path`;
     }
     if (!name.endsWith(".md"))
-        return `file must name a queued prompt's .md file${gotSuffix(name)}`;
+        return `file must name an inbox message's .md file${gotSuffix(name)}`;
     return null;
 }
 /** The file-addressed queue functions' shared entry guard: throw the reason a name fails
- * queueFileNameProblem, so cancelQueuedFile, editQueuedFile, and readQueuedPromptBody all
- * fail closed with the same error before touching disk. The callers run the guard anyway;
- * naming it in one place keeps the throw contract from drifting between them. */
+ * queueFileNameProblem, so cancelQueuedFile, editQueuedFile, readQueuedPromptBody, and
+ * topQueuedFile all fail closed with the same error before touching disk. The callers run
+ * the guard anyway; naming it in one place keeps the throw contract from drifting between
+ * them. */
 export function assertQueueFileName(name) {
     const problem = queueFileNameProblem(name);
     if (problem)

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

@@ -93,7 +93,7 @@ function editPromptAtFile(root, role, file, newText, images) {
         throw err;
     }
     const oldText = stripNotBeforeMarker(oldFileText);
-    logEventBestEffort(root, { loop: role, type: "prompt_edited", preview: promptPreview(composed) });
+    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

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

@@ -1,10 +1,15 @@
+// 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.js";
+import { INITIAL_PROMPT_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 { 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,
@@ -26,7 +31,35 @@ export function promptLengthProblem(text, role = DIRECTOR_ROLE) {
     const prompt = text.trim();
     if (prompt.length <= DIRECTOR_PROMPT_MAX_CHARS)
         return null;
-    return tooLongMessage("the prompt", prompt.length, DIRECTOR_PROMPT_MAX_CHARS, `it rides into the ${role} tick's prefill`);
+    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
+ * "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
+ * 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
+ * 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
+ * images alert claim. */
+export function imagePromptGuidance(root, role) {
+    const { config } = loadConfigSafe(root);
+    const cfg = config ?? defaultConfig();
+    // 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));
+    if (imageInput !== false)
+        return {};
+    if (imageReroute) {
+        return {
+            notice: `${role}'s model can't read images; this prompt runs on ${imageReroute}`,
+        };
+    }
+    return {
+        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
@@ -52,11 +85,18 @@ export function submitRolePrompt(root, role, text, images, notBeforeMs) {
         const imageProblem = promptImagesProblem(images);
         if (imageProblem)
             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;
+        // the surface prints/shows the notice instead (imagePromptGuidance is called again there).
+        const guidance = imagePromptGuidance(root, role);
+        if (guidance.refusal)
+            throw new Error(guidance.refusal);
         return submitPromptWithImages(root, role, text, images, notBeforeMs);
     }
     const prompt = text.trim();
     enqueueRolePrompt(root, role, prompt, notBeforeMs);
-    logEventBestEffort(root, { loop: role, type: "prompt_enqueued", preview: promptPreview(prompt) });
+    logEventBestEffort(root, { source: role, type: "prompt_enqueued", preview: promptPreview(prompt) });
     return prompt;
 }
 /** submitRolePrompt's image-carrying path: save each image beside the queue file and queue the
@@ -93,7 +133,7 @@ function submitPromptWithImages(root, role, text, images, notBeforeMs) {
         unlinkAllMissingTolerant(savedImagePaths);
         throw err;
     }
-    logEventBestEffort(root, { loop: role, type: "prompt_enqueued", preview: promptPreview(final) });
+    logEventBestEffort(root, { source: role, type: "prompt_enqueued", preview: promptPreview(final) });
     return final;
 }
 /** A user submits a new director prompt; see submitRolePrompt. The optional `notBeforeMs` is

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

@@ -0,0 +1,83 @@
+// vocabulary: plain
+import path from "node:path";
+import { existsSync } 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";
+import { roleInboxDir } from "../paths.js";
+import { assertQueueFileName } from "./inbox-cancel.js";
+import { promptPreview, queuedFileAtPosition, queuedFiles } from "./inbox.js";
+import { movePromptImages, stripVanishedImageReferences } from "./inbox-attachments.js";
+/** The rename-and-event pairing behind both address forms, given a resolved queue file: one
+ * stamp below the queue's minimum carries the file to the head — its text (and its
+ * `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
+ * the caller's listing and the read here (a concurrent pop is a normal race, never an
+ * error), sharing the store's takeQueuedFile convention. */
+function moveFileToTop(root, role, file) {
+    const text = readTextIfExists(file);
+    if (text === null)
+        return { status: "gone" }; // Dequeued or cancelled mid-listing.
+    // One stamp below the queue's minimum makes the renamed file the oldest (first) entry; a
+    // queue with no parseable stamps falls back to now (it is before every hand-placed name).
+    const stamps = queuedFiles(root, role)
+        .map((f) => queueFileStamp(path.basename(f)))
+        .filter((s) => s !== null);
+    let stamp = (stamps.length > 0 ? Math.min(...stamps) : Date.now()) - 1;
+    const dir = path.dirname(file);
+    let newFile = path.join(dir, queueFileName(stamp, 0, ".md"));
+    // A concurrent writer may have just taken a name we computed — step one lower rather than
+    // overwrite it; the pid in queueFileName keeps two concurrent tops' names apart too.
+    while (existsSync(newFile)) {
+        stamp--;
+        newFile = path.join(dir, queueFileName(stamp, 0, ".md"));
+    }
+    // The attachments travel with the prompt to the new stem, so the fulfil/cancel sweep finds
+    // them; a move that could not carry one attachment is warned but never fails the reorder.
+    const moved = movePromptImages(file, newFile, text);
+    if (moved.problem !== null)
+        warnEventBestEffort(root, role, moved.problem);
+    const carried = stripVanishedImageReferences(moved.text).text;
+    writeTextAtomic(newFile, carried);
+    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
+ * (`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.
+ *
+ * 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
+ * between listing and rename instead of throwing. The race policy and event live here,
+ * sharing the store's takeQueuedFile convention: a vanished file is a normal race, never an
+ * error. */
+export function movePromptToTop(root, role, position) {
+    const file = queuedFileAtPosition(root, role, position);
+    if (position === 1)
+        throw new Error(`prompt ${position} is already first`);
+    return moveFileToTop(root, role, file);
+}
+/** Move one queued prompt addressed by its queue-file basename to the head of its role's
+ * 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
+ * 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) {
+    assertQueueFileName(name);
+    const target = path.join(roleInboxDir(root, role), name);
+    const index = queuedFiles(root, role).indexOf(target);
+    if (index === -1)
+        return { status: "gone" };
+    if (index === 0)
+        return { status: "already_first" };
+    return moveFileToTop(root, role, target);
+}

package/dist/src/inbox/inbox.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { ensureParentDir, readTextIfExists, writeTextAtomic } from "../files/files.js";
@@ -19,7 +20,9 @@ import { isPromptImageSibling } from "./inbox-attachments.js";
  * takeQueuedFile race policy. The cancel half — position-, list-, and file-addressed removal
  * and its event pairing — lives in inbox-cancel.ts; the in-place edit of one queued
  * prompt's text (`prompt --edit`, position-addressed like cancel and sharing its
- * resolveListedQueue) lives in inbox-edit.ts; the submission pipeline that validates and
+ * resolveListedQueue) lives in inbox-edit.ts; moving one queued prompt to its queue's
+ * head (`prompt --top`, position-addressed like cancel) lives in inbox-top.ts; the
+ * submission pipeline that validates and
  * logs a user-submitted prompt lives in inbox-submit.ts; the image side of a submission in
  * inbox-attachments.ts. The not-before marker vocabulary for deferred prompts lives in
  * prompt-not-before.ts (compose, parse, strip, and the deliverableNow predicate this module
@@ -84,7 +87,10 @@ export function queuedFileAtPosition(root, role, position) {
     const files = queuedFiles(root, role);
     const file = files[position - 1];
     if (position < 1 || position > files.length || !file) {
-        throw new Error(`no prompt at position ${position} (${files.length} queued)`);
+        // Name the valid range when the queue is non-empty, so the operator sees the fix in the
+        // same line instead of deriving `1..N` from the count; an empty queue needs no range.
+        const range = files.length > 0 ? ` — valid: 1-${files.length}` : "";
+        throw new Error(`no prompt at position ${position} (${files.length} in the inbox)${range}`);
     }
     return file;
 }

package/dist/src/inbox/pending-prompt.js

@@ -140,7 +140,7 @@ export class PendingPrompt {
                 return stripVanishedImageReferences(userPrompt).text;
             const moved = movePromptImages(fromFile, newFile, userPrompt);
             if (moved.problem !== null) {
-                warnEventBestEffort(this.root, this.role, `could not move every re-queued prompt attachment: ${moved.problem}`);
+                warnEventBestEffort(this.root, this.role, `could not move every attachment of the prompt returned to the inbox: ${moved.problem}`);
             }
             return stripVanishedImageReferences(moved.text).text;
         });