toolroll 0.9.60 → 0.9.61

package/dist/shared-deps.js

@@ -17,10 +17,12 @@
  * checkout links or matches; the plane's daily storage sweep removes one no checkout has used for a week.
  */
 import { createHash, randomBytes } from "node:crypto";
-import { spawnSync } from "node:child_process";
+import { execFile, spawnSync } from "node:child_process";
+import { rm } from "node:fs/promises";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { markNeverIndex } from "./never-index.js";
+import { QUARANTINE_NOTE, quarantine, quarantineEntries, claimQuarantine, releaseQuarantine, restoreQuarantine, deleteQuarantine } from "./sweep-quarantine.js";
 export const DEPS_FOLDER = "deps";
 const READY = "ready.json";
 const RETIRED = "retired";
@@ -199,7 +201,11 @@ function treeDigest(nodeModules) {
 }
 /** The shared node_modules for a key, when one is ready and unchanged since it was made. A changed one is retired. */
 export function readyCopy(root, key) {
+    if (!/^[0-9a-f]{24}$/.test(key))
+        return null;
     const dir = join(root, key);
+    if (existsSync(join(dir, QUARANTINE_NOTE)))
+        return null;
     const ready = readReady(dir);
     if (ready === null || ready.key !== key || existsSync(join(dir, RETIRED)) || !existsSync(join(dir, NODE_MODULES)))
         return null;
@@ -259,12 +265,20 @@ export function linkInto(worktree, shared) {
     const at = join(worktree, NODE_MODULES);
     if (existsSync(at) || isLink(at))
         return null;
+    const root = dirname(dirname(shared)), key = basename(dirname(shared));
+    if (readyCopy(root, key) !== shared)
+        return null;
     try {
         mkdirSync(at);
+        // Publish intent before reading the copy. A sweep that renames it mid-link sees this user and restores it;
+        // if the sweep won before the intent, the final ready check fails and no broken link is handed to a run.
+        writeFileSync(join(at, LINK_NOTE), `${shared}\n`, "utf8");
+        touch(dirname(shared));
         for (const entry of readdirSync(shared, { withFileTypes: true })) {
             symlinkSync(join(shared, entry.name), join(at, entry.name), entry.isDirectory() ? (process.platform === "win32" ? "junction" : "dir") : "file");
         }
-        writeFileSync(join(at, LINK_NOTE), `${shared}\n`, "utf8");
+        if (readyCopy(root, key) !== shared)
+            throw new Error("Shared copy is no longer available");
         markNeverIndex(at);
         touch(dirname(shared));
         return "link";
@@ -272,6 +286,8 @@ export function linkInto(worktree, shared) {
     catch {
         rmSync(at, { recursive: true, force: true });
     }
+    if (readyCopy(root, key) !== shared)
+        return null;
     const cloned = process.platform === "darwin" ? spawnSync("cp", ["-c", "-R", shared, at], { timeout: 600_000 })
         : process.platform === "linux" ? spawnSync("cp", ["--reflink=always", "-R", shared, at], { timeout: 600_000 })
             : null;
@@ -396,7 +412,9 @@ export function sharedCopies(root) {
 }
 /** Which checkouts use each copy: those linking it, and those whose lockfile it was installed from. */
 export function sharedUse(root, checkouts) {
-    const copies = sharedCopies(root);
+    return useCopies(root, sharedCopies(root), checkouts);
+}
+function useCopies(root, copies, checkouts) {
     const users = new Map(copies.map(one => [one.key, new Set()]));
     for (const checkout of checkouts) {
         const linked = linkedKey(checkout.path, root);
@@ -411,7 +429,8 @@ export function sharedUse(root, checkouts) {
             continue;
         for (const copy of copies) {
             const ready = readReady(copy.dir);
-            if (!copy.retired && copy.repo === checkout.repo && ready !== null && matchesInputs(copy.dir, ready, inputs))
+            if (!copy.retired && copy.repo === checkout.repo && (ready !== null ? matchesInputs(copy.dir, ready, inputs) :
+                [inputs.digest, digestPair(inputs.lock, inputs.manifest)].includes(copy.lock)))
                 users.get(copy.key).add(checkout.path);
         }
     }
@@ -456,24 +475,81 @@ export function removeShared(path) {
 }
 /**
  * The daily sweep: remove each copy no checkout uses and none has linked for `unusedMs` (a week), and old debris.
- * Right before a copy goes, who uses it and when it was last linked are read again; a copy a checkout picked up in
- * between stays.
+ * Right before a copy goes, who uses it, when it was last linked and whether live work uses it (`spare`,
+ * storage-sweep.ts) are read again; a copy a checkout picked up in between stays. Removal never holds the event loop.
  */
-export function pruneUnusedShared(root, checkouts, now, unusedMs = SHARED_UNUSED_MS) {
+export async function pruneUnusedShared(root, checkouts, now, unusedMs = SHARED_UNUSED_MS, options = {}) {
     const stale = (one) => one.checkouts.length === 0 && now.getTime() - Date.parse(one.usedAt) > unusedMs;
     const removed = [];
     const failed = [];
+    const finish = async (trash) => {
+        try {
+            await options.quarantined?.(trash.original, trash.path);
+            let used = options.spare?.(trash.original) === true || options.spare?.(trash.path) === true;
+            const copy = trash.journal.data;
+            if (copy !== null) {
+                let usedAt = copy.usedAt;
+                try {
+                    usedAt = statSync(join(trash.path, READY)).mtime.toISOString();
+                }
+                catch { /* partially deleted trash */ }
+                const fresh = useCopies(root, [{ ...copy, dir: trash.path, usedAt }], checkouts())[0];
+                used ||= !stale(fresh);
+            }
+            if (used) {
+                if (!restoreQuarantine(trash))
+                    failed.push(trash.original);
+                return;
+            }
+            await deleteQuarantine(trash, options.remove ?? removeSharedLater);
+            if (copy !== null)
+                removed.push(copy);
+        }
+        catch {
+            failed.push(trash.original);
+        }
+        finally {
+            releaseQuarantine(trash);
+        }
+    };
+    for (const entry of quarantineEntries(root)) {
+        const claimed = claimQuarantine(entry);
+        if (claimed !== null)
+            await finish(claimed);
+    }
     for (const one of sharedUse(root, checkouts()).filter(stale)) {
+        await nextTurn();
         const fresh = sharedUse(root, checkouts()).find(other => other.key === one.key);
-        if (fresh === undefined || !stale(fresh))
+        if (fresh === undefined || !stale(fresh) || options.spare?.(fresh.dir) === true)
             continue;
-        if (removeShared(fresh.dir))
-            removed.push(fresh);
-        else
+        try {
+            const trash = quarantine(fresh.dir, fresh);
+            if (trash !== null)
+                await finish(trash);
+        }
+        catch {
             failed.push(fresh.dir);
+        }
     }
-    for (const debris of sharedDebris(root, now))
-        if (!removeShared(debris))
+    for (const debris of sharedDebris(root, now)) {
+        await nextTurn();
+        if (options.spare?.(debris) === true)
+            continue;
+        try {
+            const trash = quarantine(debris, null);
+            if (trash !== null)
+                await finish(trash);
+        }
+        catch {
             failed.push(debris);
+        }
+    }
     return { removed, failed };
 }
+const nextTurn = () => new Promise(resolve => setImmediate(resolve));
+/** removeShared without holding the event loop: chmod and rm run off it. */
+async function removeSharedLater(path) {
+    if (process.platform !== "win32")
+        await new Promise(resolve => execFile("chmod", ["-R", "u+w", path], { timeout: 120_000 }, () => resolve()));
+    await rm(path, { recursive: true, force: true });
+}

package/dist/staged-runtimes.d.ts

@@ -1,3 +1,4 @@
+import { type ProcessRow } from "./run-closeout.js";
 /** A deploy or update that never finished keeps its stage this long (it may be resumed). */
 export declare const UNFINISHED_KEEP_MS: number;
 export declare const STAGED_FOLDER = "staged-upgrades";
@@ -22,9 +23,17 @@ export type StagePlan = {
 export declare function stagedRuntimes(stateDir: string): Stage[];
 /**
  * Paths a runtime may be running from: the launchd services' definitions, every `toolroll` (or older
- * `standing-orders`) command on PATH or under nvm, this process, and `extra`.
+ * `standing-orders`) command on PATH, in the usual link folders or under nvm (a link counts by its target), this
+ * process, and `extra`.
  */
-export declare function runtimesInUse(extra?: readonly string[], home?: string, path?: string): string[];
+export declare function runtimesInUse(extra?: readonly string[], home?: string, path?: string, stateDir?: string): string[];
+/** Retain only recognized Toolroll entry scripts in candidate stages, never complete argv. ps is asked only
+ * for Node/Toolroll processes; /proc supplies NUL-separated argv on Linux. Fail closed with a fixed message,
+ * since an execFileSync exception can otherwise contain private argument text in stdout/stderr. */
+export declare function runtimeScriptPaths(stateDir: string, onlyPids?: readonly number[], observations?: {
+    census?: () => ProcessRow[];
+    argv?: (pids: readonly number[]) => string[];
+}): string[];
 /** What stays and what goes now, and why. */
 export declare function stagePlan(stateDir: string, inUse: readonly string[], now: Date): StagePlan;
 export type StagePrune = {
@@ -33,10 +42,13 @@ export type StagePrune = {
     refused: string | null;
 };
 /**
- * Remove the stages that go. Right before each goes, the plan is made again (what's in use now) and the stage must
- * still be a real folder directly in staged-upgrades.
+ * Remove the stages that go. Right before each goes, the plan is made again (what's in use now), nothing live may use
+ * it (`spare`, storage-sweep.ts) and the stage must still be a real folder directly in staged-upgrades.
  */
 export declare function pruneStagedRuntimes(stateDir: string, now: Date, options?: {
     inUse?: () => string[];
     remove?: (path: string) => void;
+    spare?: (path: string) => boolean;
+    /** Deterministic race seam, not supplied by production callers. */
+    quarantined?: (original: string, trash: string) => void;
 }): StagePrune;

package/dist/staged-runtimes.js

@@ -8,9 +8,12 @@
  * and in the plane's daily storage sweep. `rollback-*` records and anything else in the folder are never touched.
  * With no current runtime found, nothing goes: which one is safe to remove is then unknown.
  */
-import { lstatSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
+import { lstatSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
+import { quarantine, quarantineEntries, claimQuarantine, releaseQuarantine, restoreQuarantine, deleteQuarantineSync } from "./sweep-quarantine.js";
+import { processCensus } from "./run-closeout.js";
 const DAY_MS = 86_400_000;
 /** A deploy or update that never finished keeps its stage this long (it may be resumed). */
 export const UNFINISHED_KEEP_MS = 7 * DAY_MS;
@@ -63,38 +66,46 @@ export function stagedRuntimes(stateDir) {
         catch {
             continue;
         }
-        const deploy = name.startsWith("browser-") ? readJson(join(path, "deployment.json")) : null;
-        const update = name.startsWith("release-") ? readJson(join(path, "update.json")) : null;
-        const journal = deploy ?? update;
-        const stamp = String(journal?.["deployedAt"] ?? journal?.["startedAt"] ?? journal?.["createdAt"] ?? "");
-        let at = Date.parse(stamp);
-        if (!Number.isFinite(at)) {
-            try {
-                at = statSync(path).mtimeMs;
-            }
-            catch {
-                at = 0;
-            }
-        }
-        const finished = deploy !== null ? deploy["phase"] === "deployed" : update !== null ? typeof update["finishedAt"] === "string" : false;
-        const from = update?.["from"];
-        const prior = typeof deploy?.["priorRuntime"] === "string" ? deploy["priorRuntime"] : typeof from?.dist === "string" ? from.dist : null;
-        let keptAside = false;
+        stages.push(readStage(path, name));
+    }
+    return stages.sort((a, b) => b.at - a.at);
+}
+function readStage(path, name, fallbackAt) {
+    const deploy = name.startsWith("browser-") ? readJson(join(path, "deployment.json")) : null;
+    const update = name.startsWith("release-") ? readJson(join(path, "update.json")) : null;
+    const journal = deploy ?? update;
+    const stamp = String(journal?.["deployedAt"] ?? journal?.["startedAt"] ?? journal?.["createdAt"] ?? "");
+    let at = Date.parse(stamp);
+    if (!Number.isFinite(at)) {
         try {
-            keptAside = readdirSync(path).some(one => /^orders\.(?:kept|unreadable)\./.test(one));
+            at = fallbackAt ?? statSync(path).mtimeMs;
         }
         catch {
-            keptAside = true;
+            at = 0;
         }
-        stages.push({ path, name, at, finished, prior, keptAside });
     }
-    return stages.sort((a, b) => b.at - a.at);
+    const finished = deploy !== null ? deploy["phase"] === "deployed" : update !== null ? typeof update["finishedAt"] === "string" : false;
+    const from = update?.["from"];
+    const prior = typeof deploy?.["priorRuntime"] === "string" ? deploy["priorRuntime"] : typeof from?.dist === "string" ? from.dist : null;
+    let keptAside = false;
+    try {
+        keptAside = readdirSync(path).some(one => /^orders\.(?:kept|unreadable)\./.test(one));
+    }
+    catch {
+        keptAside = true;
+    }
+    return { path, name, at, finished, prior, keptAside };
+}
+/** Where the CLI links usually are (link.ts, an npm or Homebrew global), on PATH or not: a launchd worker's PATH is short. */
+function linkFolders(home) {
+    return [join(home, ".local", "bin"), join(home, "bin"), "/usr/local/bin", "/opt/homebrew/bin"];
 }
 /**
  * Paths a runtime may be running from: the launchd services' definitions, every `toolroll` (or older
- * `standing-orders`) command on PATH or under nvm, this process, and `extra`.
+ * `standing-orders`) command on PATH, in the usual link folders or under nvm (a link counts by its target), this
+ * process, and `extra`.
  */
-export function runtimesInUse(extra = [], home = homedir(), path = process.env["PATH"] ?? "") {
+export function runtimesInUse(extra = [], home = homedir(), path = process.env["PATH"] ?? "", stateDir) {
     const found = [...extra];
     const agents = join(home, "Library", "LaunchAgents");
     try {
@@ -104,7 +115,7 @@ export function runtimesInUse(extra = [], home = homedir(), path = process.env["
         }
     }
     catch { /* no launch agents here */ }
-    const commands = path.split(":").filter(Boolean).flatMap(dir => ["toolroll", "standing-orders"].map(bin => join(dir, bin)));
+    const commands = [...new Set([...path.split(":").filter(Boolean), ...linkFolders(home)])].flatMap(dir => ["toolroll", "standing-orders"].map(bin => join(dir, bin)));
     try {
         for (const version of readdirSync(join(home, ".nvm", "versions", "node")))
             for (const bin of ["toolroll", "standing-orders"])
@@ -116,12 +127,84 @@ export function runtimesInUse(extra = [], home = homedir(), path = process.env["
             lstatSync(command);
             found.push(command);
         }
-        catch { /* not there */ }
+        catch {
+            continue; /* not there */
+        }
+        // A link counts by its target, even one that doesn't resolve now.
+        try {
+            found.push(resolve(dirname(command), readlinkSync(command)));
+        }
+        catch { /* not a link */ }
     }
     if (process.argv[1] !== undefined)
         found.push(process.argv[1]);
+    if (stateDir !== undefined)
+        found.push(...runtimeScriptPaths(stateDir));
     return found;
 }
+/** Retain only recognized Toolroll entry scripts in candidate stages, never complete argv. ps is asked only
+ * for Node/Toolroll processes; /proc supplies NUL-separated argv on Linux. Fail closed with a fixed message,
+ * since an execFileSync exception can otherwise contain private argument text in stdout/stderr. */
+export function runtimeScriptPaths(stateDir, onlyPids, observations = {}) {
+    const stages = stagedRuntimes(stateDir);
+    const trash = quarantineEntries(real(join(stateDir, STAGED_FOLDER)));
+    const bases = new Set(stages.flatMap(one => [one.path, join(stateDir, STAGED_FOLDER, one.name)]));
+    for (const one of trash) {
+        bases.add(one.path);
+        bases.add(one.original);
+        bases.add(join(stateDir, STAGED_FOLDER, one.journal.name));
+    }
+    if (bases.size === 0 || process.platform === "win32")
+        return [];
+    const scripts = new Set();
+    const collect = (args) => {
+        for (const base of bases) {
+            const escaped = base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            // All supported installs: runtime/dist, runtime/node_modules/{toolroll,standing-orders}/dist,
+            // or dist directly under a release stage. Matching a known base handles spaces without logging argv.
+            const pattern = new RegExp(`(?:^|[\\s\\0"'])(${escaped}/(?:runtime/)?(?:node_modules/(?:toolroll|standing-orders)/)?dist/(?:cli|bin|storage-sweep-child)\\.js)(?=$|[\\s\\0"'])`, "g");
+            for (const match of args.matchAll(pattern))
+                scripts.add(match[1]);
+        }
+    };
+    try {
+        const pids = (observations.census ?? processCensus)().filter(row => /^(?:node(?:js)?|toolroll|standing-orders)(?:\.exe)?$/.test(row.name) &&
+            (onlyPids === undefined || onlyPids.includes(row.pid))).map(row => row.pid);
+        if (observations.argv !== undefined) {
+            for (const args of observations.argv(pids))
+                collect(args);
+        }
+        else if (process.platform === "linux") {
+            for (const pid of pids) {
+                try {
+                    collect(readFileSync(`/proc/${pid}/cmdline`, "utf8"));
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT" && error.code !== "ESRCH")
+                        throw error;
+                }
+            }
+        }
+        else {
+            for (let at = 0; at < pids.length; at += 200) {
+                try {
+                    collect(execFileSync("/bin/ps", ["-ww", "-p", pids.slice(at, at + 200).join(","), "-o", "args="], {
+                        encoding: "utf8", timeout: 5_000, maxBuffer: 16 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"],
+                    }));
+                }
+                catch (error) {
+                    // ps exits 1 when every requested process has just gone. Any other failure keeps stages.
+                    if (error.status !== 1)
+                        throw error;
+                }
+            }
+        }
+    }
+    catch {
+        throw new Error("Toolroll runtime process paths could not be read");
+    }
+    return [...scripts];
+}
 /** The stage `path` lies in, or null. */
 function stageOf(stages, path) {
     if (path === null || path === undefined || path === "")
@@ -138,8 +221,21 @@ function stageOf(stages, path) {
 /** What stays and what goes now, and why. */
 export function stagePlan(stateDir, inUse, now) {
     const stages = stagedRuntimes(stateDir);
+    const trash = quarantineEntries(real(join(stateDir, STAGED_FOLDER)));
+    // A renamed stage still has its original identity for current/previous/newest protection, including a CLI
+    // symlink switched just before rename. Partial-delete journals retain this identity for the next retry.
+    for (const one of trash)
+        if (!stages.some(stage => stage.path === one.original)) {
+            const facts = one.journal.deleting ? one.journal.data : readStage(one.path, one.journal.name, one.journal.data.at);
+            stages.push({ ...facts, path: one.original });
+        }
+    stages.sort((a, b) => b.at - a.at);
+    const paths = inUse.map(path => {
+        const moved = trash.find(one => path === one.path || path.startsWith(one.path + sep));
+        return moved === undefined ? path : moved.original + path.slice(moved.path.length);
+    });
     const keep = new Map();
-    const current = inUse.map(path => stageOf(stages, path)).filter((one) => one !== null);
+    const current = paths.map(path => stageOf(stages, path)).filter((one) => one !== null);
     if (stages.length > 0 && current.length === 0)
         return { keep: [], go: [], refused: "no staged runtime is in use, so which one runs now is unknown" };
     for (const one of current)
@@ -162,29 +258,55 @@ export function stagePlan(stateDir, inUse, now) {
     return { keep: [...keep].map(([path, why]) => ({ path, why })), go: stages.filter(one => !keep.has(one.path)), refused: null };
 }
 /**
- * Remove the stages that go. Right before each goes, the plan is made again (what's in use now) and the stage must
- * still be a real folder directly in staged-upgrades.
+ * Remove the stages that go. Right before each goes, the plan is made again (what's in use now), nothing live may use
+ * it (`spare`, storage-sweep.ts) and the stage must still be a real folder directly in staged-upgrades.
  */
 export function pruneStagedRuntimes(stateDir, now, options = {}) {
-    const inUse = options.inUse ?? (() => runtimesInUse());
-    const first = stagePlan(stateDir, inUse(), now);
-    if (first.refused !== null)
-        return { removed: [], failed: [], refused: first.refused };
+    const inUse = options.inUse ?? (() => runtimesInUse([], undefined, undefined, stateDir));
     const root = real(join(stateDir, STAGED_FOLDER));
     const removed = [];
     const failed = [];
+    const finish = (trash) => {
+        try {
+            options.quarantined?.(trash.original, trash.path);
+            const again = stagePlan(stateDir, inUse(), now);
+            if (again.refused !== null || !again.go.some(one => one.path === trash.original) || options.spare?.(trash.original) === true || options.spare?.(trash.path) === true) {
+                if (!restoreQuarantine(trash))
+                    failed.push(trash.original);
+                return;
+            }
+            deleteQuarantineSync(trash, options.remove ?? (path => rmSync(path, { recursive: true, force: true, maxRetries: 3 })));
+            removed.push(trash.original);
+        }
+        catch {
+            failed.push(trash.original);
+        }
+        finally {
+            releaseQuarantine(trash);
+        }
+    };
+    for (const entry of quarantineEntries(root)) {
+        const claimed = claimQuarantine(entry);
+        if (claimed !== null)
+            finish(claimed);
+    }
+    const first = stagePlan(stateDir, inUse(), now);
+    if (first.refused !== null)
+        return { removed, failed, refused: first.refused };
     for (const one of first.go) {
         const again = stagePlan(stateDir, inUse(), now);
-        if (again.refused !== null || !again.go.some(other => other.path === one.path))
+        if (again.refused !== null || !again.go.some(other => other.path === one.path) || options.spare?.(one.path) === true)
             continue;
         try {
             if (lstatSync(one.path).isSymbolicLink() || dirname(one.path) !== root)
                 continue;
-            (options.remove ?? (path => rmSync(path, { recursive: true, force: true, maxRetries: 3 })))(one.path);
-            removed.push(one.path);
+            const trash = quarantine(one.path, one);
+            if (trash !== null)
+                finish(trash);
         }
-        catch {
-            failed.push(one.path);
+        catch (error) {
+            if (error.code !== "ENOENT")
+                failed.push(one.path);
         }
     }
     return { removed, failed, refused: null };

package/dist/steer-live.d.ts

@@ -0,0 +1,19 @@
+import type { LiveInput } from "./live-input.js";
+import { type SteerMailbox } from "./steer-mailbox.js";
+import type { SteerNote, Store } from "./store.js";
+/** How often the dispatcher looks: a note reaches a running Claude build within about this long. */
+export declare const LIVE_TICK_MS = 500;
+/** How long an unread note waits before it is sent again. */
+export declare const LIVE_RESEND_MS = 90000;
+/** How many times an unread note is sent again before it reads Not picked up. */
+export declare const LIVE_RESENDS = 3;
+export type LiveSteer = {
+    box: SteerMailbox;
+    session: LiveInput | null;
+};
+/** The stdin copy of a note: the same fenced text and key as its file, and what to do with the file. */
+export declare function liveNoteText(box: SteerMailbox, number: number, note: SteerNote): string;
+/** A re-send: only the note's number and file, and what to do with it. The note itself was sent in full once. */
+export declare function liveReminderText(box: SteerMailbox, number: number): string;
+/** One tick. `agentRunning`: the agent process is up, so a note written now can be read. */
+export declare function tickLiveSteer(store: Store, steer: LiveSteer, now: Date, agentRunning: boolean): void;

package/dist/steer-live.js

@@ -0,0 +1,93 @@
+/**
+ * Live steering's dispatcher: the builder runs one tick every half second
+ * while its agent works, independent of the 60-second lease pulse.
+ *
+ * - Every provider: what the agent moved to handled/ is recorded read, and a
+ *   note filed since the last tick is written to the steering folder at once
+ *   (steer-mailbox.ts). Codex reads it there.
+ * - A Claude build with live input (live-input.ts) also gets each note on
+ *   stdin as soon as it is in the folder, each Pause as an interrupt and
+ *   each Resume as a short continue frame — pauses first, so Pause and steer
+ *   stops the turn before the note arrives.
+ * - A note the agent has not moved to handled/ is followed up every 90
+ *   seconds, up to 3 times, with a short reminder naming its file — never
+ *   the note again, so an agent that already acted on it does not redo the
+ *   work; 90 seconds after the last one it reads Not picked up. A paused
+ *   session is not reminded: only a new note or Resume continues it. Moving
+ *   the file is still the only proof of reading, and a note still unread
+ *   when the attempt ends reaches the next attempt's brief as before.
+ *
+ * Every step is bookkeeping: a failure waits for the next tick and never
+ * touches the build.
+ */
+import { randomUUID } from "node:crypto";
+import { fence } from "./brief-fence.js";
+import { pulseSteerMailbox, STEER_HANDLED, steerNoteName } from "./steer-mailbox.js";
+/** How often the dispatcher looks: a note reaches a running Claude build within about this long. */
+export const LIVE_TICK_MS = 500;
+/** How long an unread note waits before it is sent again. */
+export const LIVE_RESEND_MS = 90_000;
+/** How many times an unread note is sent again before it reads Not picked up. */
+export const LIVE_RESENDS = 3;
+/** The stdin copy of a note: the same fenced text and key as its file, and what to do with the file. */
+export function liveNoteText(box, number, note) {
+    const name = steerNoteName(number);
+    return [
+        `Operator steering note ${number}, key ${box.key}, also saved as ${box.folder}/${name}:`,
+        fence(note.note),
+        `Act on it within the agreed scope, under the brief's rules for steering notes, then move ${box.folder}/${name} into ${box.folder}/${STEER_HANDLED}/ — moving the file is how the operator learns you read it.`,
+    ].join("\n");
+}
+/** A re-send: only the note's number and file, and what to do with it. The note itself was sent in full once. */
+export function liveReminderText(box, number) {
+    const name = steerNoteName(number);
+    return `Steering note ${number} is still unread: ${box.folder}/${name}. Act on it if you have not already, then move it into ${box.folder}/${STEER_HANDLED}/.`;
+}
+/** One tick. `agentRunning`: the agent process is up, so a note written now can be read. */
+export function tickLiveSteer(store, steer, now, agentRunning) {
+    const { box, session } = steer;
+    pulseSteerMailbox(store, box, now, agentRunning);
+    if (session === null || !session.open || !agentRunning)
+        return;
+    for (const pause of store.unsentPauses(box.runId)) {
+        const sent = session.interrupt(pause.requestId);
+        if (sent === "closed") {
+            store.endPause(pause.id, now);
+            continue;
+        }
+        store.markPauseSent(pause.id, now);
+        if (sent === "idle")
+            store.markRunPaused(box.runId, now);
+    }
+    for (const resume of store.unsentResumes(box.runId)) {
+        const sent = session.resume(randomUUID());
+        if (sent === "sent")
+            store.markResumeSent(resume.id, box.runId, now);
+        else
+            store.endResume(resume.id, now);
+    }
+    for (const [number, noteId] of [...box.waiting].sort((a, b) => a[0] - b[0])) {
+        const note = store.steerNote(noteId);
+        if (note === null || note.mailedRun !== box.runId || note.deliveredAt !== null || note.supersededAt !== null || note.liveMissedAt !== null)
+            continue;
+        const first = note.liveSends === 0;
+        if (!first) {
+            // A paused session waits for a new note; an old one sent again would continue it.
+            if (session.paused)
+                continue;
+            if (note.liveSentAt === null || now.getTime() - Date.parse(note.liveSentAt) < LIVE_RESEND_MS)
+                continue;
+            if (note.liveSends > LIVE_RESENDS) {
+                store.markLiveMissed(noteId, box.runId, now);
+                continue;
+            }
+        }
+        // The first send is the note itself, under its own identity; a re-send is a fresh frame (the harness may drop a
+        // repeated uuid) that only names the file.
+        if (!session.send(first ? liveNoteText(box, number, note) : liveReminderText(box, number), first ? (note.liveUuid ?? randomUUID()) : randomUUID()))
+            return;
+        store.recordLiveSend(noteId, box.runId, now);
+        if (first)
+            store.markRunResumed(box.runId, now);
+    }
+}

package/dist/steer-status.d.ts

@@ -6,7 +6,7 @@
  * either waiting for the agent that is running now, or for the next attempt.
  */
 import type { SteerNote } from "./store.js";
-export type SteerStanding = "read" | "waiting" | "next-attempt" | "ended" | "unverified";
+export type SteerStanding = "read" | "waiting" | "not-picked-up" | "next-attempt" | "ended" | "unverified";
 /** `liveBuild`: the task has a build whose agent is running and reads its steering folder (Store.steeringLiveBuild). */
 export declare function steerStandingOf(note: SteerNote, liveBuild: boolean): SteerStanding;
 /** The words, and the moment the agent read it when it has: each surface renders that time its own way. */
@@ -16,4 +16,10 @@ export declare function steerStandingParts(note: SteerNote, liveBuild: boolean):
 };
 export declare function steerStandingWords(note: SteerNote, liveBuild: boolean, time: (iso: string) => string): string;
 /** Where a note filed now goes, said before or right after filing it. */
-export declare function steerDestinationWords(liveBuild: boolean): string;
+export declare function steerDestinationWords(liveBuild: boolean, liveInput?: boolean): string;
+/** A paused live build's one sentence: until when it can wait before it ends, and how long that is (live-input.ts
+ * idleLimit), or only that it is paused when it has no idle limit. `time` renders the moment its surface's way. */
+export declare function pausedWords(pause: {
+    until: string | null;
+    limitMs: number | null;
+}, time: (iso: string) => string): string;

package/dist/steer-status.js

@@ -6,13 +6,17 @@ export function steerStandingOf(note, liveBuild) {
         return "ended";
     if (note.deliveredAt !== null)
         return "read";
-    return liveBuild ? "waiting" : "next-attempt";
+    if (!liveBuild)
+        return "next-attempt";
+    // Sent to the running build every time it was owed, and never moved to handled/ (steer-live.ts).
+    return note.liveMissedAt !== null ? "not-picked-up" : "waiting";
 }
 /** The words, and the moment the agent read it when it has: each surface renders that time its own way. */
 export function steerStandingParts(note, liveBuild) {
     switch (steerStandingOf(note, liveBuild)) {
         case "read": return { words: "Read by the agent at", readAt: note.ackedAt ?? note.deliveredAt };
         case "waiting": return { words: "Waiting for the agent to read it", readAt: null };
+        case "not-picked-up": return { words: "Not picked up", readAt: null };
         case "next-attempt": return { words: "Will reach the next attempt", readAt: null };
         case "ended": return { words: "The task ended before the agent read it", readAt: null };
         case "unverified": return { words: "Saved before notes required a sign-in; never sent", readAt: null };
@@ -23,8 +27,18 @@ export function steerStandingWords(note, liveBuild, time) {
     return readAt === null ? words : `${words} ${time(readAt)}`;
 }
 /** Where a note filed now goes, said before or right after filing it. */
-export function steerDestinationWords(liveBuild) {
-    return liveBuild
-        ? "The running agent reads it when it next checks for notes."
-        : "The next attempt reads it before starting.";
+export function steerDestinationWords(liveBuild, liveInput = false) {
+    // A Claude build with live input takes it in seconds (steer-live.ts); any other running build reads its folder.
+    return liveBuild && liveInput
+        ? "The running agent gets it now."
+        : liveBuild
+            ? "The running agent reads it when it next checks for notes."
+            : "The next attempt reads it before starting.";
+}
+/** A paused live build's one sentence: until when it can wait before it ends, and how long that is (live-input.ts
+ * idleLimit), or only that it is paused when it has no idle limit. `time` renders the moment its surface's way. */
+export function pausedWords(pause, time) {
+    if (pause.until === null || pause.limitMs === null)
+        return "Paused.";
+    return `Paused. It can wait until ${time(pause.until)} (${Math.max(1, Math.round(pause.limitMs / 60_000))} min) before it ends.`;
 }