tumwater 0.2.0 → 0.3.0

package/dist/src/inbox/inbox.js

@@ -1,20 +1,18 @@
-// vocabulary: plain
-import fs from "node:fs";
 import path from "node:path";
-import { ensureParentDir, readTextIfExists, writeTextAtomic } from "../files/files.js";
+import { dirEntryNames, ensureParentDir, readTextIfExists, writeTextAtomic } from "../files/files.js";
 import { listQueueFiles, queueFileName, queueFileStamp, removeQueueFile } from "../files/file-queue.js";
 import { cachedByStat } from "../files/stat-cache.js";
 import { roleInboxDir } from "../paths.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { knownRoleIdsCached } from "../config/config.js";
-import { humanSeconds, secondsSince, secondsUntil } from "../text/datetime.js";
+import { humanAgo, humanSeconds, secondsUntil } from "../text/datetime.js";
 import { errorMessage, truncate } from "../text/text.js";
 import { warnEvent } from "../events/events.js";
 import { isPromptImageSibling } from "./inbox-attachments.js";
 /** File-based queues of user prompts. Any process can enqueue; the orchestrator pops. Ordering
  * comes from the timestamped filenames. The director's queue is the historical one at the inbox
- * root; every other loop has its own subdirectory (roleInboxDir), so `tumwater prompt --role <id>`
- * queues a request only that loop's next tick sees.
+ * root; every other role has its own subdirectory (roleInboxDir), so `tumwater prompt --role <id>`
+ * queues a request only that role's next run sees.
  *
  * This module is the store: enqueueing, listing, peeking, and dequeuing, plus the shared
  * takeQueuedFile race policy. The cancel half — position-, list-, and file-addressed removal
@@ -41,14 +39,14 @@ export function promptPreview(text) {
     return truncate(stripNotBeforeMarker(text), PROMPT_PREVIEW_MAX);
 }
 let seq = 0;
-/** Append a prompt to a loop's queue as one timestamped file (creating the queue dir if needed)
+/** Append a prompt to a role's queue as one timestamped file (creating the queue dir if needed)
  * and return its path. The filename orders prompts across processes by wall-clock time; the
  * per-process counter and pid break ties within one process. No event is logged —
  * inbox-submit.ts's submitPrompt and submitRolePrompt are the user-facing wrappers that add the
  * prompt_enqueued line, and PendingPrompt's re-queue of an unfulfilled prompt calls this directly.
  * The write is atomic (writeTextAtomic) because the queue's readers — the dashboards' 1 s poll,
- * `tumwater prompt --list`, and the dequeuing loop — run in other processes, and a read that
- * raced a plain writeFileSync could see a truncated prompt and run a tick on a half user request.
+ * `tumwater prompt --list`, and the dequeuing role — run in other processes, and a read that
+ * raced a plain writeFileSync could see a truncated prompt and run a run on a half user request.
  * The optional decorate hook runs before that one write with the file's path and may return the
  * final text instead — submitPromptWithImages uses it to save the prompt's images beside the
  * queue file and append their reference lines, so the queue file is born complete and no
@@ -69,15 +67,15 @@ export function enqueueRolePrompt(root, role, prompt, notBeforeMs, decorate) {
     writeTextAtomic(file, text);
     return file;
 }
-/** Every queued prompt file for one loop as a path joined onto the loop's inbox dir, oldest
- * first (listQueueFiles over the loop's inbox dir, .md entries only). Prompts still deferred by
+/** Every queued prompt file for one role as a path joined onto the role's inbox dir, oldest
+ * first (listQueueFiles over the role's inbox dir, .md entries only). Prompts still deferred by
  * a not-before marker are included — deliverability filtering is the callers' job
  * (deliverablePredicate, deliverablePromptCount) — and a missing inbox dir reads as an empty
  * queue. */
 export function queuedFiles(root, role) {
     return listQueueFiles(roleInboxDir(root, role), ".md");
 }
-/** Resolve the 1-based position `tumwater prompt --list`'s per-loop numbering shows into one
+/** Resolve the 1-based position `tumwater prompt --list`'s per-role numbering shows into one
  * queue file — the shared range-check-and-pick half of cancelRolePrompt (inbox-cancel.ts)
  * and editRolePrompt (inbox-edit.ts), so the two cannot drift on the error or the numbering.
  * Throws for out-of-range positions with no side effects. The undefined-pick check folds into
@@ -94,12 +92,12 @@ export function queuedFileAtPosition(root, role, position) {
     }
     return file;
 }
-/** Number of prompts currently queued for one loop and deliverable now — a directory listing
+/** Number of prompts currently queued for one role and deliverable now — a directory listing
  * plus, per file, one stat-cached content read (the prompt cache below; an unchanged file
- * costs one stat). Defaults to the director's queue; a role argument counts that loop's own
- * per-role queue (scheduling passes it so a queued prompt makes its loop due by itself).
+ * costs one stat). Defaults to the director's queue; a role argument counts that role's own
+ * per-role queue (scheduling passes it so a queued prompt makes its role due by itself).
  * A prompt deferred by the not-before marker (its time still in the future) stays excluded,
- * so a deferred prompt alone never makes its loop due; once due, the marker falls out of the
+ * so a deferred prompt alone never makes its role due; once due, the marker falls out of the
  * count naturally. A missing inbox dir reads as 0, like queuedPrompts and dequeuePrompt. */
 export function inboxSize(root, role = DIRECTOR_ROLE) {
     return deliverablePromptCount(root, role);
@@ -132,7 +130,7 @@ const promptCache = new Map();
 function cachedPromptText(file) {
     return cachedByStat(promptCache, file, file, () => readTextIfExists(file), (t) => t);
 }
-/** The one read pass over a loop's queue that serves every list-shaped consumer: each queued
+/** The one read pass over a role's queue that serves every list-shaped consumer: each queued
  * file paired with its basename, full text, and the enqueue stamp parsed from the filename
  * (queueFileStamp; null for a hand-placed name). Same listing order and race policy as
  * queuedRolePrompts (a file that vanishes mid-listing is skipped, not thrown), and the same
@@ -153,10 +151,10 @@ export function queuedRolePromptRecords(root, role) {
     }
     return out;
 }
-/** Full text of every prompt queued for one loop, in execution order (oldest first) — the same
+/** Full text of every prompt queued for one role, in execution order (oldest first) — the same
  * filename sort dequeueRolePrompt pops by. A not-yet-deliverable prompt (the not-before marker
  * still in the future) is not part of the execution order: it is skipped here, so peek and
- * dequeue can never hand a tick a prompt its time has not reached. A missing queue directory
+ * dequeue can never hand a run a prompt its time has not reached. A missing queue directory
  * reads as an empty queue, like inboxSize and dequeueRolePrompt; a file that vanishes between
  * listing and reading (a concurrent dequeue or cancel) is skipped rather than throwing, so a
  * polled snapshot can never crash on it. Unchanged files are served from the stat-keyed cache
@@ -168,7 +166,7 @@ export function queuedRolePrompts(root, role) {
         .filter((e) => deliverableAt(e.notBeforeMs, now))
         .map((e) => e.text);
 }
-/** Every queued prompt of one loop with the queue-file basename that addresses it and its
+/** Every queued prompt of one role with the queue-file basename that addresses it and its
  * enqueue stamp, in execution order — the snapshot's cancel-addressable payload
  * (StatusSnapshot.inboxFiles and roleInboxPrompts). Same pass, order, race policy, and stat
  * cache as queuedRolePrompts. */
@@ -180,14 +178,14 @@ export function queuedRolePromptEntries(root, role) {
         notBeforeMs: e.notBeforeMs,
     }));
 }
-/** The loop order a list-wide position (`--cancel`/`--edit` with no `--role`) resolves across:
- * the director first, then the remaining cached catalog ids — the per-loop sections `prompt
+/** The role order a list-wide position (`--cancel`/`--edit` with no `--role`) resolves across:
+ * the director first, then the remaining cached catalog ids — the per-role sections `prompt
  * --list` and the TUI Queued pane print, each numbered from 1. The single home of that scope,
  * shared by the cancel and edit branches so neither can drift from what the list showed. */
 export function listWideScope(root) {
     return [DIRECTOR_ROLE, ...knownRoleIdsCached(root).filter((r) => r !== DIRECTOR_ROLE)];
 }
-/** One traversal of the queues behind the list-shaped queue views: with `role`, that loop's
+/** One traversal of the queues behind the list-shaped queue views: with `role`, that role's
  * queue alone; otherwise the director first (its queue is the shared pre-1/2 inbox), then the
  * remaining catalog ids in order, empty queues skipped — exactly the sections the prose
  * prints. */
@@ -195,7 +193,7 @@ export function queuedListRows(root, role, validIds) {
     const prompts = [];
     const record = (r, position, e) => 
     // The marker is stripped from the text both shapes print (stripNotBeforeMarker): the
-    // prose and --json are the operator's view of what a loop will tick, and the marker is
+    // prose and --json are the operator's view of what a role will run, and the marker is
     // plumbing, not content. Full verbatim prompt text minus plumbing, still not a preview.
     prompts.push({ role: r, position, file: e.file, text: stripNotBeforeMarker(e.text), queuedAtMs: e.queuedAtMs, notBeforeMs: e.notBeforeMs });
     if (role !== null) {
@@ -224,11 +222,19 @@ function queuedAgeSuffix(queuedAtMs, notBeforeMs, now) {
     }
     if (queuedAtMs === null)
         return "";
-    const ageSeconds = secondsSince(queuedAtMs, now);
-    return ` (queued ${humanSeconds(ageSeconds)} ago)`;
+    return ` (queued ${humanAgo(queuedAtMs, now)})`;
+}
+/** Keep the rows whose prompt text contains `grep`, case-insensitively, each row still carrying
+ * its unfiltered per-role `position`. A null grep keeps every row. The one filter `prompt --list
+ * --grep` and the TUI Inbox pane's `/` search share. */
+export function queuedRowsMatching(rows, grep) {
+    if (grep === null)
+        return [...rows];
+    const needle = grep.toLowerCase();
+    return rows.filter((row) => row.text.toLowerCase().includes(needle));
 }
 /** Render the list-shaped queue view as the prose `prompt --list` prints and the TUI Queued
- * pane shows: consecutive rows grouped by role, one `<role>:` section per loop holding
+ * pane shows: consecutive rows grouped by role, one `<role>:` section per role holding
  * `"<position>. <text><queuedAgeSuffix>"` lines, sections joined by `\n`. Empty rows render
  * the empty string, so each surface keeps its own empty-state note. One renderer so the CLI
  * and the TUI cannot drift on order, numbering, or the age/countdown wording. */
@@ -249,7 +255,7 @@ export function renderQueuedList(rows, now) {
         sections.push(`${currentRole}:\n${lines.join("\n")}`);
     return sections.join("\n");
 }
-/** How many prompts are queued for one loop and deliverable now, without re-reading unchanged
+/** How many prompts are queued for one role and deliverable now, without re-reading unchanged
  * contents — the snapshot's per-role counts poll every role
  * every second, so the count stays a listing plus one stat-cached read per file (the prompt
  * cache above keeps an unchanged file at one stat). A deferred prompt (its not-before time
@@ -283,9 +289,9 @@ export function takeQueuedFile(file) {
  * by a hyphen (`a-notes.md` beside `a.md`), and deleting it would take another prompt with
  * this one — files like that are left alone. ENOENT-tolerant through removeQueueFile, and a
  * queue directory that is already gone leaves nothing to clean. Called by the cancel paths
- * (inbox-cancel.ts's takeCancelledPrompt) and by a fulfilled tick's settle sweep
+ * (inbox-cancel.ts's takeCancelledPrompt) and by a fulfilled run's settle sweep
  * (src/inbox/pending-prompt.ts's settleImages): a cancelled or consumed prompt takes its
- * attachments with it. A DEQUEUE does not call this — the tick's agent still reads the
+ * attachments with it. A DEQUEUE does not call this — the run's agent still reads the
  * referenced files, so they must survive until the prompt is fulfilled or cancelled, and a
  * requeue first moves them to the new queue file's stem (movePromptImages) so this sweep
  * finds them under the stem the requeued file actually names.
@@ -296,14 +302,7 @@ export function takeQueuedFile(file) {
 export function removeSameStemSiblings(root, role, file) {
     const dir = path.dirname(file);
     const stem = path.basename(file, ".md");
-    let entries;
-    try {
-        entries = fs.readdirSync(dir);
-    }
-    catch {
-        return; // The queue directory itself is gone — nothing to clean.
-    }
-    for (const entry of entries) {
+    for (const entry of dirEntryNames(dir)) {
         if (entry === path.basename(file) || !isPromptImageSibling(stem, entry))
             continue;
         try {
@@ -324,11 +323,11 @@ export function removeSameStemSiblings(root, role, file) {
 /** Remove and return the oldest queued prompt, or null when empty — including when a
  * concurrent `tumwater prompt --cancel` removes it between listing and reading (or between
  * reading and removal): the module's race policy is that a vanished file is skipped rather
- * than throwing, so the director sees an empty inbox and skips its tick instead of failing
+ * than throwing, so the director sees an empty inbox and skips its run instead of failing
  * with a raw ENOENT. When the removal itself hits ENOENT the cancel won after our read —
  * the prompt was cancelled, so it must not be executed: null (skip), never the text we
  * already read. Non-ENOENT errors (e.g. EACCES) are rethrown — they are not a race with a
- * cancel. A caller that must clean the prompt's attachments afterwards (a tick's
+ * cancel. A caller that must clean the prompt's attachments afterwards (a run's
  * pending-prompt bookkeeping) needs the file's stem too, so dequeueRolePromptEntry also
  * returns the queue file it took. */
 export function dequeueRolePromptEntry(root, role) {
@@ -338,15 +337,15 @@ export function dequeueRolePromptEntry(root, role) {
     const text = takeQueuedFile(oldest);
     return text === null ? null : { text, file: oldest };
 }
-/** Remove and return the oldest prompt queued for one loop; see dequeueRolePromptEntry. */
+/** Remove and return the oldest prompt queued for one role; see dequeueRolePromptEntry. */
 export function dequeueRolePrompt(root, role) {
     return dequeueRolePromptEntry(root, role)?.text ?? null;
 }
-/** Full text of the oldest prompt queued for one loop, read WITHOUT consuming it — the
+/** Full text of the oldest prompt queued for one role, read WITHOUT consuming it — the
  * preview seam behind `tumwater role <id>`'s next-prompt view. Same reader, listing order,
  * and race policy as queuedRolePrompts (a file that vanishes mid-listing is skipped, not
  * thrown), but the queue file is never unlinked: a preview can never cost a queued prompt
- * its tick, which is the property test/tick-prompt.test.ts pins through the preview seam.
+ * its run, which is the property test/run-prompt.test.ts pins through the preview seam.
  * A missing queue directory reads as null, like dequeueRolePrompt. */
 export function peekRolePrompt(root, role) {
     return queuedRolePrompts(root, role)[0] ?? null;

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

@@ -3,31 +3,31 @@ import { movePromptImages, stripVanishedImageReferences } from "./inbox-attachme
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { warnEventBestEffort } from "../events/events.js";
 /**
- * The raw user prompt a director tick is executing, and the requeue policy for every outcome
- * that leaves the request unfulfilled — extracted from LoopRunner's private methods
- * (src/loop/loop.ts) so the subtle fresh-vs-resume requeue semantics have one named home beside
+ * The raw user prompt a director run is executing, and the requeue policy for every outcome
+ * that leaves the request unfulfilled — extracted from RoleRunner's private methods
+ * (src/runner/runner.ts) so the subtle fresh-vs-resume requeue semantics have one named home beside
  * the queue mechanics they ride on (src/inbox/inbox.ts).
  */
 export class PendingPrompt {
     root;
     role;
     /** The dequeued request, memory-only: the queue file is the durable store, and every
-     * unfulfilled outcome hands the request back to it before the tick ends. */
+     * unfulfilled outcome hands the request back to it before the run ends. */
     value = null;
-    /** The queue file the recorded request was dequeued from, so a fulfilled tick sweeps the
+    /** The queue file the recorded request was dequeued from, so a fulfilled run sweeps the
      * request's same-stem image attachments by that file's stem (settleImages). Null when the
      * request was recorded without one (tests) or carried no file. */
     queueFile = null;
     /** Whether the current request's images were handed back to a queue (requeue*), so a
-     * settle must keep them for the next tick instead of removing them. */
+     * settle must keep them for the next run instead of removing them. */
     retain = false;
     constructor(root, role) {
         this.root = root;
         this.role = role;
     }
-    /** Record the user request a just-dequeued tick prompt carries (assembleTickPrompt's
+    /** Record the user request a just-dequeued run prompt carries (assembleRunPrompt's
      * userPrompt) together with the queue file it came from (userPromptFile), so an unfulfilled
-     * tick can re-queue it instead of losing the request and a fulfilled one can clean its
+     * run can re-queue it instead of losing the request and a fulfilled one can clean its
      * attachments. */
     record(userPrompt, queueFile = null) {
         if (userPrompt === null)
@@ -36,23 +36,23 @@ export class PendingPrompt {
         this.queueFile = queueFile;
         this.retain = false;
     }
-    /** The raw user prompt this tick is executing (null for role loops), so an unfulfilled
+    /** The raw user prompt this run is executing (null for roles), so an unfulfilled
      * outcome below can re-queue it. */
     get() {
         return this.value;
     }
     /** Drop the recorded request without re-queueing it — the explicit-stop arm of
-     * finishAbortedTick and every fulfilled path. Leaves the image files for settleImages:
+     * finishAbortedRun and every fulfilled path. Leaves the image files for settleImages:
      * the same clear runs before the requeue branches, whose requeue* methods mark the images
      * retained, so only a genuinely unrequeued request loses them. */
     clear() {
         this.value = null;
     }
-    /** The end-of-tick half of the attachment lifetime: sweep the fulfilled request's same-stem
+    /** The end-of-run half of the attachment lifetime: sweep the fulfilled request's same-stem
      * image files (removeSameStemSiblings, keyed on the dequeued file's stem — never on paths
      * named by prompt text) UNLESS an unfulfilled outcome handed the request back to a queue
      * (retain), then the files must survive for the requeued prompt to read. Always forgets the
-     * request afterwards, so a fresh tick starts clean. */
+     * request afterwards, so a fresh run starts clean. */
     settleImages() {
         if (!this.retain && this.queueFile !== null)
             removeSameStemSiblings(this.root, this.role, this.queueFile);
@@ -60,17 +60,17 @@ export class PendingPrompt {
         this.retain = false;
         this.value = null;
     }
-    /** Put an unfulfilled user prompt back in the queue it came from so the next tick retries it
+    /** Put an unfulfilled user prompt back in the queue it came from so the next run retries it
      * — the one place that policy lives, shared by every outcome that leaves the request undone
      * (abort, timeout, failure without changes, review abort, context-ceiling cut-off, red-main
      * gate). The queue is the role's own (the director's historical inbox for the director), so a
-     * re-queued per-role request never leaks across loops. A fulfilled no_change never reaches
+     * re-queued per-role request never leaks across roles. A fulfilled no_change never reaches
      * here: re-queueing it would loop the prompt forever. Image attachments ride along: the
      * re-queue moves them to the new queue file's stem so a later cancel or fulfilling sweep
      * finds them, and a reference whose file is genuinely gone (removed out of band) is dropped
      * and replaced by one note naming the loss — a re-queued prompt must never send the next
-     * tick's agent after files that are no longer there. Either way the images are marked
-     * retained, so settleImages keeps them for the next tick. */
+     * run's agent after files that are no longer there. Either way the images are marked
+     * retained, so settleImages keeps them for the next run. */
     requeueUnfulfilled(userPrompt) {
         if (!userPrompt)
             return;
@@ -79,21 +79,21 @@ export class PendingPrompt {
     }
     /** Re-queue whatever request is still recorded and drop it from memory: an exception between
      * the dequeue/reclaim and the pi run leaves the request only in this field — memory the
-     * failed tick is about to drop, with no outcome handler left to re-queue it (the handlers
-     * run inside runTick, after the pi run). The queue is the durable store, so the catch
+     * failed run is about to drop, with no outcome handler left to re-queue it (the handlers
+     * run inside runOnce, after the pi run). The queue is the durable store, so the catch
      * re-queues whatever is still pending, like every unfulfilled outcome does; it is always
      * null once a pi run has been accounted for. */
     requeuePendingUnfulfilled() {
         this.requeueUnfulfilled(this.value);
         this.value = null;
     }
-    /** Re-queue an unfulfilled prompt whose pi session the next tick will resume: the resumed
+    /** Re-queue an unfulfilled prompt whose pi session the next run will resume: the resumed
      * session still owns the request in its (compacted) context, so the re-queued copy is only
      * the durable store for a restart — the resume must reclaim exactly it as its own user
      * prompt (the resume's fulfillment consumes it; only its failure paths re-queue it) instead
-     * of leaving it queued for a later fresh tick to run the same request twice. The queue file
+     * of leaving it queued for a later fresh run to run the same request twice. The queue file
      * is recorded so the reclaim takes that exact prompt whatever else was enqueued meanwhile.
-     * Director ticks never resume — their re-queued prompt always reruns fresh — so they take
+     * Director runs never resume — their re-queued prompt always reruns fresh — so they take
      * the plain path. */
     requeueForResume(state, userPrompt) {
         if (!userPrompt)
@@ -105,13 +105,13 @@ export class PendingPrompt {
         state.resumePromptFile = this.enqueueCarryingImages(userPrompt);
         this.retain = true;
     }
-    /** Reclaim the prompt the interrupted tick re-queued (requeueForResume): the resumed session
-     * still owns that request in its context, so this tick's outcome bookkeeping — re-queue on
+    /** Reclaim the prompt the interrupted run re-queued (requeueForResume): the resumed session
+     * still owns that request in its context, so this run's outcome bookkeeping — re-queue on
      * unfulfilled, clear on fulfillment — must operate on the queue's copy, or a fulfilling
-     * resume leaves it queued for a later fresh tick to run the same request twice. The exact
+     * resume leaves it queued for a later fresh run to run the same request twice. The exact
      * recorded file is taken, so an enqueue or cancel meanwhile cannot divert the reclaim; a
-     * vanished file (cancelled) reclaims nothing. The flag is consumed even when this tick does
-     * not resume: a fresh fallback re-derives its prompt from the queue like any other tick, and
+     * vanished file (cancelled) reclaims nothing. The flag is consumed even when this run does
+     * not resume: a fresh fallback re-derives its prompt from the queue like any other run, and
      * a stale record must never survive into a later resume. */
     reclaimForResume(state, resuming) {
         const reclaimFile = state.resumePromptFile;