toolroll 0.9.59 → 0.9.61

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-mailbox.d.ts

@@ -0,0 +1,39 @@
+import type { Store } from "./store.js";
+export declare const STEER_HANDLED = "handled";
+export type SteerMailbox = {
+    runId: number;
+    taskRef: number;
+    /** Worktree-relative, as the brief names it. */
+    folder: string;
+    dir: string;
+    /** The folder's real path, resolved once when it was made inside the worktree. */
+    realDir: string;
+    /** This attempt's note key: in the brief and in every genuine note, nowhere else. */
+    key: string;
+    /** The highest number this pulse has written. */
+    last: number;
+    /** Mailed and not yet moved to handled/: number → note id. */
+    waiting: Map<number, number>;
+};
+export declare const steerNoteName: (number: number) => string;
+/** Make the folder and its handled/ inside the worktree; null when it cannot be made. */
+export declare function openSteerMailbox(worktree: string, folder: string, runId: number, taskRef: number, key: string): SteerMailbox | null;
+/** One beat: record what the agent read, then mail what is new while the agent runs. */
+export declare function pulseSteerMailbox(store: Store, box: SteerMailbox, now: Date, agentRunning: boolean): void;
+/** The attempt is over: one last read, then the folder goes. Unread notes stay pending for the next attempt. */
+export declare function closeSteerMailbox(store: Store, box: SteerMailbox, now: Date): void;
+/**
+ * Claude's doorbell: a synchronous PostToolUse hook that lists the folder and,
+ * while a note is unread, hands the agent one line of context between tool
+ * calls. It only says notes are waiting — it never quotes one, and its firing
+ * is never an acknowledgement. Rendered into the run's own --settings.
+ */
+export declare function claudeSteerHooks(dir: string, folder: string): {
+    PostToolUse: {
+        matcher: string;
+        hooks: {
+            type: "command";
+            command: string;
+        }[];
+    }[];
+};

package/dist/steer-mailbox.js

@@ -0,0 +1,207 @@
+/**
+ * The running build's steering mailbox (v120). A note an operator files
+ * while a build runs used to wait for the next attempt; now the builder's
+ * pulse writes it into one nonce-named folder in the worktree, as a numbered
+ * file the agent reads and acknowledges by moving it into `handled/` — the
+ * same small contract a person's own inbox keeps:
+ *
+ * - The durable record is the delivery. A note is mailed (written into the
+ *   folder) and read (moved by the agent); nothing else counts. A hook
+ *   reminding the agent, or a file the pulse wrote, proves nothing.
+ * - Numbers are never reused: the next one is past every name in the folder
+ *   and in `handled/`, and past every one this pulse has used.
+ * - Whatever is still unread when the attempt ends keeps today's road: the
+ *   note stays pending, the next attempt's brief quotes it, and a task that
+ *   ends first supersedes it.
+ *
+ * Every step is bookkeeping, and bookkeeping never fails a build: a folder
+ * the agent removed is made again, one it replaced with anything but a real
+ * directory is never written through, and an error waits for the next beat.
+ *
+ * Two boundaries, because the folder lives where the agent and anything it
+ * runs can write:
+ * - Every genuine note carries this attempt's key, which only the brief and
+ *   the notes themselves name. A file in the folder without it was not
+ *   written by the operator, and the brief tells the agent to act on none.
+ *   (The brief rides the agent's argv, so a process that reads argv could
+ *   learn it: this keeps ordinary repository code from posing as the
+ *   operator, not a determined local process.)
+ * - The pulse writes only while the folder still resolves to this worktree's
+ *   own folder, before and after each write, so swapping it for a link can
+ *   never make the plane write a note somewhere else.
+ */
+import { lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fence } from "./brief-fence.js";
+export const STEER_HANDLED = "handled";
+const NOTE_NAME = /^(\d+)\.json$/;
+export const steerNoteName = (number) => `${String(number).padStart(3, "0")}.json`;
+const isRealDirectory = (path) => {
+    try {
+        return lstatSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/** Make the folder and its handled/ inside the worktree; null when it cannot be made. */
+export function openSteerMailbox(worktree, folder, runId, taskRef, key) {
+    let realDir;
+    try {
+        realDir = join(realpathSync(worktree), folder);
+    }
+    catch {
+        return null;
+    }
+    const box = { runId, taskRef, folder, dir: join(worktree, folder), realDir, key, last: 0, waiting: new Map() };
+    return ensureFolder(box) ? box : null;
+}
+/** The folder is still this worktree's own, not a link to somewhere else. */
+const stillInside = (box) => {
+    try {
+        return realpathSync(box.dir) === box.realDir;
+    }
+    catch {
+        return false;
+    }
+};
+function ensureFolder(box) {
+    for (const path of [box.dir, join(box.dir, STEER_HANDLED)]) {
+        try {
+            mkdirSync(path, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                return false;
+        }
+        // Something the agent put in the folder's place is never written through.
+        if (!isRealDirectory(path))
+            return false;
+    }
+    return stillInside(box);
+}
+function highestNumber(box) {
+    let highest = box.last;
+    for (const path of [box.dir, join(box.dir, STEER_HANDLED)]) {
+        let names;
+        try {
+            names = readdirSync(path);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const number = NOTE_NAME.exec(name)?.[1];
+            if (number !== undefined)
+                highest = Math.max(highest, Number(number));
+        }
+    }
+    return highest;
+}
+/** Every waiting note the agent moved into handled/ is read, by this run. */
+function collectAcknowledgements(store, box, now) {
+    if (box.waiting.size === 0)
+        return;
+    const handled = join(box.dir, STEER_HANDLED);
+    if (!isRealDirectory(box.dir) || !isRealDirectory(handled))
+        return;
+    for (const [number, noteId] of [...box.waiting]) {
+        let moved;
+        try {
+            moved = lstatSync(join(handled, steerNoteName(number))).isFile();
+        }
+        catch {
+            moved = false;
+        }
+        if (!moved)
+            continue;
+        box.waiting.delete(number);
+        store.ackSteerNote(noteId, box.runId, now);
+    }
+}
+/** Remove a name this pulse wrote, only while the folder is still this worktree's own; a link goes, never its target. */
+function removeOwn(box, name) {
+    if (!stillInside(box))
+        return;
+    try {
+        unlinkSync(join(box.dir, name));
+    }
+    catch { /* never written, or the agent already took it */ }
+}
+/** Write each note this run has not seen yet: a temp name, then the number. */
+function mailNotes(store, box, now) {
+    const notes = store.mailableSteerNotes(box.taskRef, box.runId);
+    if (notes.length === 0 || !ensureFolder(box))
+        return;
+    for (const note of notes) {
+        if (!stillInside(box))
+            return;
+        const number = highestNumber(box) + 1;
+        const name = steerNoteName(number);
+        const temp = `.${name}.tmp`;
+        const body = { version: 1, number, key: box.key, filedAt: note.createdAt, note: fence(note.note) };
+        try {
+            writeFileSync(join(box.dir, temp), `${JSON.stringify(body, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+            renameSync(join(box.dir, temp), join(box.dir, name));
+        }
+        catch {
+            removeOwn(box, temp);
+            return;
+        }
+        // Checked again after the write: a folder swapped for a link mid-write
+        // leaves the note unrecorded, deletes nothing, and mails nothing more this beat.
+        if (!stillInside(box))
+            return;
+        box.last = number;
+        let recorded;
+        try {
+            recorded = store.markSteerMailed(note.id, box.runId, now);
+        }
+        catch {
+            recorded = false;
+        }
+        if (recorded) {
+            box.waiting.set(number, note.id);
+        }
+        else {
+            // The task ended or the note settled between the read and the write, or
+            // the mailing could not be recorded: an unrecorded file would only be
+            // mailed twice, so it goes, and the next beat tries again.
+            removeOwn(box, name);
+        }
+    }
+}
+/** One beat: record what the agent read, then mail what is new while the agent runs. */
+export function pulseSteerMailbox(store, box, now, agentRunning) {
+    collectAcknowledgements(store, box, now);
+    if (agentRunning)
+        mailNotes(store, box, now);
+}
+/** The attempt is over: one last read, then the folder goes. Unread notes stay pending for the next attempt. */
+export function closeSteerMailbox(store, box, now) {
+    try {
+        collectAcknowledgements(store, box, now);
+    }
+    catch { /* the notes stay pending */ }
+    try {
+        rmSync(box.dir, { recursive: true, force: true });
+    }
+    catch { /* the next attempt's sweep removes it */ }
+}
+const shellQuote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+/**
+ * Claude's doorbell: a synchronous PostToolUse hook that lists the folder and,
+ * while a note is unread, hands the agent one line of context between tool
+ * calls. It only says notes are waiting — it never quotes one, and its firing
+ * is never an acknowledgement. Rendered into the run's own --settings.
+ */
+export function claudeSteerHooks(dir, folder) {
+    const context = {
+        hookSpecificOutput: {
+            hookEventName: "PostToolUse",
+            additionalContext: `Operator steering waiting: %s unread note(s) in ${folder}/. Read them in number order now, act on each within the agreed scope, then move each into ${folder}/${STEER_HANDLED}/.`,
+        },
+    };
+    const command = `set -- ${shellQuote(dir)}/[0-9]*.json; [ -e "$1" ] || exit 0; printf ${shellQuote(`${JSON.stringify(context)}\n`)} "$#"`;
+    return { PostToolUse: [{ matcher: "*", hooks: [{ type: "command", command }] }] };
+}

package/dist/steer-status.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Where a steering note stands, in the one set of words the task page, the
+ * CLI and the lead all use (v120). A note is read only when the agent proves
+ * it: the stream's receipt of a brief that quoted it, or the agent moving it
+ * to handled/ in a running build's steering folder. Everything else is
+ * 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" | "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. */
+export declare function steerStandingParts(note: SteerNote, liveBuild: boolean): {
+    words: string;
+    readAt: string | null;
+};
+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, 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;