toolroll 0.9.58 → 0.9.60

package/dist/contract-changes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The mechanical difference between two sets of contract terms — a task's goal, exclusions, touches and acceptance
+ * rubric. Pure and import-light, so both the planner's source (planner-source.ts) and scope filing (scope.ts, which
+ * restarts planning when the terms truly change) read the same comparison.
+ */
+import type { AcceptanceCriterion, EvidenceKind } from "./scope.js";
+/** The four contract fields a planner may propose to amend. */
+export type ContractTerms = {
+    goal: string;
+    outOfScope: string | null;
+    touches: string[];
+    acceptance: AcceptanceCriterion[];
+};
+export type ContractChange = {
+    field: "goal";
+    kind: "changed";
+    before: string;
+    after: string;
+} | {
+    field: "outOfScope";
+    kind: "added" | "removed" | "changed";
+    before: string | null;
+    after: string | null;
+} | {
+    field: "touches";
+    kind: "added" | "removed";
+    path: string;
+} | {
+    field: "acceptance";
+    kind: "added" | "removed" | "changed";
+    id: string;
+    before: {
+        statement: string;
+        evidence: EvidenceKind[];
+        how: string | null;
+    } | null;
+    after: {
+        statement: string;
+        evidence: EvidenceKind[];
+        how: string | null;
+    } | null;
+    /** For `changed`: which parts moved. `how` is advisory and unsigned,
+     * but a planner rewriting it is still a change the operator sees. */
+    moved: ("statement" | "evidence" | "how")[];
+};
+/**
+ * Every addition, change, and removal between the filed contract and a
+ * proposed one. Whitespace at the ends and touch/evidence order do not
+ * count (the scope digest ignores them too); everything else does,
+ * including the advisory `how`, because the operator wrote it.
+ */
+export declare function contractChangesOf(filed: ContractTerms, proposed: ContractTerms): ContractChange[];

package/dist/contract-changes.js

@@ -0,0 +1,61 @@
+const trimmed = (text) => {
+    if (text === null)
+        return null;
+    const t = text.trim();
+    return t === "" ? null : t;
+};
+/**
+ * Every addition, change, and removal between the filed contract and a
+ * proposed one. Whitespace at the ends and touch/evidence order do not
+ * count (the scope digest ignores them too); everything else does,
+ * including the advisory `how`, because the operator wrote it.
+ */
+export function contractChangesOf(filed, proposed) {
+    const changes = [];
+    if (filed.goal.trim() !== proposed.goal.trim()) {
+        changes.push({ field: "goal", kind: "changed", before: filed.goal, after: proposed.goal });
+    }
+    const filedOut = trimmed(filed.outOfScope);
+    const proposedOut = trimmed(proposed.outOfScope);
+    if (filedOut !== proposedOut) {
+        changes.push({
+            field: "outOfScope",
+            kind: filedOut === null ? "added" : proposedOut === null ? "removed" : "changed",
+            before: filed.outOfScope,
+            after: proposed.outOfScope,
+        });
+    }
+    const filedTouches = new Set(filed.touches.map(one => one.trim()).filter(one => one !== ""));
+    const proposedTouches = new Set(proposed.touches.map(one => one.trim()).filter(one => one !== ""));
+    for (const path of filedTouches)
+        if (!proposedTouches.has(path))
+            changes.push({ field: "touches", kind: "removed", path });
+    for (const path of proposedTouches)
+        if (!filedTouches.has(path))
+            changes.push({ field: "touches", kind: "added", path });
+    const criterionOf = (one) => ({ statement: one.statement, evidence: [...one.evidence].sort(), how: one.how });
+    const filedById = new Map(filed.acceptance.map(one => [one.id, one]));
+    const proposedById = new Map(proposed.acceptance.map(one => [one.id, one]));
+    for (const [id, before] of filedById) {
+        const after = proposedById.get(id);
+        if (after === undefined) {
+            changes.push({ field: "acceptance", kind: "removed", id, before: criterionOf(before), after: null, moved: [] });
+            continue;
+        }
+        const moved = [];
+        if (before.statement.trim() !== after.statement.trim())
+            moved.push("statement");
+        if ([...before.evidence].sort().join(",") !== [...after.evidence].sort().join(","))
+            moved.push("evidence");
+        if (trimmed(before.how) !== trimmed(after.how))
+            moved.push("how");
+        if (moved.length > 0) {
+            changes.push({ field: "acceptance", kind: "changed", id, before: criterionOf(before), after: criterionOf(after), moved });
+        }
+    }
+    for (const [id, after] of proposedById) {
+        if (!filedById.has(id))
+            changes.push({ field: "acceptance", kind: "added", id, before: null, after: criterionOf(after), moved: [] });
+    }
+    return changes;
+}

package/dist/decision.d.ts

@@ -43,6 +43,10 @@ export declare const LIMITS: {
 };
 /** Bytes an operator's note may occupy — the UTF-8 backstop under LIMITS.note. */
 export declare const NOTE_BYTE_CAP: 16000;
+/** Why a question closed without an answer (v119), in plain words. */
+export declare function closedQuestionReason(reason: "scope-changed" | "cancelled"): string;
+/** The same, said once on one line wherever its answer would show. */
+export declare function closedQuestionWords(reason: "scope-changed" | "cancelled"): string;
 /**
  * The one validator every note passes — before a draft persists AND inside
  * the answer CAS, which stays the final gate. Trims, then refuses empty,

package/dist/decision.js

@@ -25,6 +25,14 @@ export const LIMITS = {
 };
 /** Bytes an operator's note may occupy — the UTF-8 backstop under LIMITS.note. */
 export const NOTE_BYTE_CAP = TEXT_LIMITS.noteBytes;
+/** Why a question closed without an answer (v119), in plain words. */
+export function closedQuestionReason(reason) {
+    return reason === "scope-changed" ? "The scope changed, so planning started again." : "The task was cancelled.";
+}
+/** The same, said once on one line wherever its answer would show. */
+export function closedQuestionWords(reason) {
+    return `Closed without an answer. ${closedQuestionReason(reason)}`;
+}
 /**
  * Unicode that reorders or breaks lines invisibly: bidi controls and the
  * line/paragraph separators. A note carrying these can spoof what a

package/dist/deploy-lock.d.ts

@@ -0,0 +1,8 @@
+/** Separate from orders.db: no live writer is reserved while deployment drains or backs up.
+ * SQLite owns the OS lock until close/process death, including SIGKILL. Never unlink this file:
+ * replacing its inode would let two contenders hold different locks for the same journal. */
+export type DeploymentLock = {
+    assertHeld(journalFile: string): void;
+    release(): void;
+};
+export declare function acquireDeploymentLock(journalFile: string, waitMs?: number): DeploymentLock;

package/dist/deploy-lock.js

@@ -0,0 +1,45 @@
+import { createRequire } from "node:module";
+import { closeSync, constants, lstatSync, openSync, realpathSync } from "node:fs";
+import { dirname, join, basename } from "node:path";
+const canonical = (file) => join(realpathSync(dirname(file)), basename(file));
+export function acquireDeploymentLock(journalFile, waitMs = 5000) {
+    if (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > 5000)
+        throw Error("Invalid deployment lock wait.");
+    const journal = canonical(journalFile), file = `${journal}.lock.sqlite`;
+    // Only create a missing file. On POSIX, closing ANY independently opened descriptor
+    // for an existing inode can drop this process's fcntl lock, even another connection's.
+    // Let SQLite manage all descriptors for an existing coordination file.
+    try {
+        const fd = openSync(file, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+        closeSync(fd);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    if (!lstatSync(file).isFile())
+        throw Error(`Unexpected deployment lock: ${file}`);
+    // Lazy, as elsewhere in the CLI: merely importing the help must not load SQLite.
+    const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite");
+    const db = new DatabaseSync(file);
+    try {
+        db.exec(`PRAGMA busy_timeout=${waitMs}; BEGIN EXCLUSIVE`);
+    }
+    catch (cause) {
+        db.close();
+        throw new Error(`Deployment is busy or its lock is unavailable: ${journal}. Let it finish, then retry.`, { cause });
+    }
+    let held = true;
+    return {
+        assertHeld(expected) {
+            if (!held || canonical(expected) !== journal)
+                throw Error("The deployment journal lock is not held.");
+        },
+        release() {
+            if (!held)
+                return;
+            db.close();
+            held = false;
+        },
+    };
+}

package/dist/design/tokens.css

@@ -0,0 +1,234 @@
+/* @generated by youi from the Signal design language v1.0.0. Do not edit: change the tokens in design-language and run `youi sync`. */
+/* Built with Terrazzo (DTCG 2025.10 resolver). */
+:root {
+  color-scheme: light;
+  --so-accent: #171717;
+  --so-accent-hover: #383838;
+  --so-accent-text: #171717;
+  --so-attention: var(--so-signal);
+  --so-attention-soft: var(--so-signal-soft);
+  --so-code-bg: #fafafa;
+  /* Vermilion: failure and irreversible acts. */
+  --so-danger: #c4320a;
+  --so-danger-soft: #feebe7;
+  --so-ease-out: cubic-bezier(0.23, 1, 0.32, 1);
+  --so-font-mono: "Geist Mono", ui-monospace, "SF Mono", "SFMono-Regular", "Menlo", "Consolas", monospace;
+  --so-font-sans: "Geist", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  /* Frame Grey: the frame the sidebar sits on, and the page background of server pages. */
+  --so-ground: #efefef;
+  /* Live Blue: something is running right now. */
+  --so-info: #0d74ce;
+  --so-info-soft: #e6f4fe;
+  /* Ink: all body text, and the colour of every act: primary buttons, the New task button, switches and radio cards when on. */
+  --so-ink: #171717;
+  /* Control Line: the boundary of fields, the composer, and the switch track when off. */
+  --so-input-line: #d4d4d4;
+  /* Hairline: every divider. */
+  --so-line: #e6e6e6;
+  --so-live: #0d74ce;
+  /* Muted: meta lines, fact keys, ghost buttons, placeholders, idle tab counts. */
+  --so-muted: #666666;
+  --so-nav-current: #ffffff;
+  --so-nav-current-ink: #171717;
+  --so-nav-hover: #e4e4e4;
+  /* Nav Ink: idle sidebar rows and their hover fill on the frame. */
+  --so-nav-ink: #525252;
+  --so-neutral-ink: #525252;
+  /* Neutral Badge: the badge for anything that is a fact and not a claim on the person, such as queued, running or built today in a project peek, or a count in a fold. */
+  --so-neutral-soft: #f0f0f0;
+  --so-on-accent: #ffffff;
+  --so-on-attention: var(--so-on-signal);
+  --so-on-signal: #ffffff;
+  --so-overlay: rgb(0 0 0 / .32);
+  /* Paper: every sheet, card, field, menu and dialog. */
+  --so-paper: #ffffff;
+  --so-phone-block: 14px;
+  --so-phone-card: 12px;
+  --so-phone-gap: 12px;
+  --so-phone-gutter: 16px;
+  --so-phone-row: 8px;
+  --so-pill-shadow: 0px 0px 0px 1px rgb(0 0 0 / .06), 0px 1px 2px 0px rgb(0 0 0 / .06);
+  --so-radius-badge: 5px;
+  --so-radius-card: 10px;
+  --so-radius-full: 9999px;
+  --so-radius-md: 8px;
+  --so-radius-sheet: 12px;
+  --so-radius-sm: 6px;
+  /* Raised: segmented-tab tracks, notices, row hover fills, and the muted well behind a "next step" block or a neutral problem line. */
+  --so-raised: #f5f5f5;
+  --so-scroll: #cfcfcf;
+  /* Selection: text selection highlight, with ink text on it. */
+  --so-selection: #d4d4d4;
+  --so-shadow-overlay: 0px 0px 0px 1px rgb(0 0 0 / .08), 0px 24px 48px -12px rgb(0 0 0 / .22);
+  --so-sheet-shadow: 0px 0px 0px 1px rgb(0 0 0 / .06), 0px 1px 2px 0px rgb(0 0 0 / .04), 0px 4px 12px -6px rgb(0 0 0 / .06);
+  --so-sidebar: #efefef;
+  /* Ink accent: the default accent, used for what waits on a person. */
+  --so-signal: #171717;
+  --so-signal-hover: #383838;
+  /* Ink wash: the fill behind attention badge text and the 3px focus halo around a focused field or composer — one step stronger than the neutral badge fill, so a waiting badge still reads first. */
+  --so-signal-soft: #e8e8e8;
+  /* Soft: hover fills on outline and ghost buttons, menu items and suggestions. */
+  --so-soft: #f2f2f2;
+  --so-space-2xl: 24px;
+  --so-space-3xl: 28px;
+  --so-space-lg: 16px;
+  --so-space-md: 12px;
+  --so-space-sm: 8px;
+  --so-space-xl: 20px;
+  --so-space-xs: 4px;
+  /* Built Green: done and passed, used for "Checks passed", "Open now" and a finished live step. */
+  --so-success: #218358;
+  --so-success-soft: #e6f6eb;
+  --so-typography-badge: var(--so-typography-badge-font-weight) var(--so-typography-badge-font-size)/var(--so-typography-badge-line-height) var(--so-typography-badge-font-family);
+  --so-typography-badge-font-family: var(--so-font-sans);
+  --so-typography-badge-font-size: 11.5px;
+  --so-typography-badge-font-weight: 500;
+  --so-typography-badge-line-height: 1.5652;
+  --so-typography-body: var(--so-typography-body-font-weight) var(--so-typography-body-font-size)/var(--so-typography-body-line-height) var(--so-typography-body-font-family);
+  --so-typography-body-font-family: var(--so-font-sans);
+  --so-typography-body-font-size: 13px;
+  --so-typography-body-font-weight: 400;
+  --so-typography-body-line-height: 1.5;
+  --so-typography-body-reading: var(--so-typography-body-reading-font-weight) var(--so-typography-body-reading-font-size)/var(--so-typography-body-reading-line-height) var(--so-typography-body-reading-font-family);
+  --so-typography-body-reading-font-family: var(--so-font-sans);
+  --so-typography-body-reading-font-size: 14px;
+  --so-typography-body-reading-font-weight: 400;
+  --so-typography-body-reading-line-height: 1.7;
+  --so-typography-caption: var(--so-typography-caption-font-weight) var(--so-typography-caption-font-size)/var(--so-typography-caption-line-height) var(--so-typography-caption-font-family);
+  --so-typography-caption-font-family: var(--so-font-sans);
+  --so-typography-caption-font-size: 12px;
+  --so-typography-caption-font-weight: 500;
+  --so-typography-caption-line-height: 1.5;
+  --so-typography-display: var(--so-typography-display-font-weight) var(--so-typography-display-font-size)/var(--so-typography-display-line-height) var(--so-typography-display-font-family);
+  --so-typography-display-font-family: var(--so-font-sans);
+  --so-typography-display-font-size: 26px;
+  --so-typography-display-font-weight: 600;
+  --so-typography-display-letter-spacing: -0.65px;
+  --so-typography-display-line-height: 1.25;
+  --so-typography-headline: var(--so-typography-headline-font-weight) var(--so-typography-headline-font-size)/var(--so-typography-headline-line-height) var(--so-typography-headline-font-family);
+  --so-typography-headline-font-family: var(--so-font-sans);
+  --so-typography-headline-font-size: 18px;
+  --so-typography-headline-font-weight: 600;
+  --so-typography-headline-line-height: 1.375;
+  --so-typography-label: var(--so-typography-label-font-weight) var(--so-typography-label-font-size)/var(--so-typography-label-line-height) var(--so-typography-label-font-family);
+  --so-typography-label-font-family: var(--so-font-sans);
+  --so-typography-label-font-size: 13px;
+  --so-typography-label-font-weight: 500;
+  --so-typography-label-line-height: 1.2;
+  --so-typography-mono: var(--so-typography-mono-font-weight) var(--so-typography-mono-font-size)/var(--so-typography-mono-line-height) var(--so-typography-mono-font-family);
+  --so-typography-mono-count: var(--so-typography-mono-count-font-weight) var(--so-typography-mono-count-font-size)/var(--so-typography-mono-count-line-height) var(--so-typography-mono-count-font-family);
+  --so-typography-mono-count-font-family: var(--so-font-mono);
+  --so-typography-mono-count-font-size: 11px;
+  --so-typography-mono-count-font-weight: 500;
+  --so-typography-mono-count-line-height: 1;
+  --so-typography-mono-font-family: var(--so-font-mono);
+  --so-typography-mono-font-size: 12px;
+  --so-typography-mono-font-weight: 400;
+  --so-typography-mono-line-height: 1.5;
+  --so-typography-title: var(--so-typography-title-font-weight) var(--so-typography-title-font-size)/var(--so-typography-title-line-height) var(--so-typography-title-font-family);
+  --so-typography-title-font-family: var(--so-font-sans);
+  --so-typography-title-font-size: 15px;
+  --so-typography-title-font-weight: 600;
+  --so-typography-title-letter-spacing: -0.15px;
+  --so-typography-title-line-height: 1.4;
+  --so-typography-title-sm: var(--so-typography-title-sm-font-weight) var(--so-typography-title-sm-font-size)/var(--so-typography-title-sm-line-height) var(--so-typography-title-sm-font-family);
+  --so-typography-title-sm-font-family: var(--so-font-sans);
+  --so-typography-title-sm-font-size: 14px;
+  --so-typography-title-sm-font-weight: 600;
+  --so-typography-title-sm-letter-spacing: -0.14px;
+  --so-typography-title-sm-line-height: 1.3;
+  --so-user-bubble: #f2f2f2;
+  /* Amber: setup trouble and caution. */
+  --so-warning: #ab6400;
+  --so-warning-soft: #fff4d5;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    color-scheme: dark;
+    --so-accent: #ededed;
+    --so-accent-hover: #ffffff;
+    --so-accent-text: #ededed;
+    --so-code-bg: #111111;
+    --so-danger: #ff977d;
+    --so-danger-soft: rgb(255 151 125 / .12);
+    --so-ground: #0b0b0b;
+    --so-info: #70b8ff;
+    --so-info-soft: rgb(112 184 255 / .12);
+    --so-ink: #ededed;
+    --so-input-line: #363636;
+    --so-line: #262626;
+    --so-live: #70b8ff;
+    --so-muted: #a1a1a1;
+    --so-nav-current: #1f1f1f;
+    --so-nav-current-ink: #ededed;
+    --so-nav-hover: #171717;
+    --so-nav-ink: #a1a1a1;
+    --so-neutral-ink: #b4b4b4;
+    --so-neutral-soft: #1f1f1f;
+    --so-on-accent: #0a0a0a;
+    --so-on-signal: #0a0a0a;
+    --so-overlay: rgb(0 0 0 / .6);
+    --so-paper: #161616;
+    --so-pill-shadow: 0px 0px 0px 1px #2a2a2a, 0px 1px 2px 0px rgb(0 0 0 / .5);
+    --so-raised: #1c1c1c;
+    --so-scroll: #333333;
+    --so-selection: #3a3a3a;
+    --so-shadow-overlay: 0px 0px 0px 1px #2e2e2e, 0px 24px 48px -12px rgb(0 0 0 / .7);
+    --so-sheet-shadow: 0px 0px 0px 1px #262626, 0px 1px 2px 0px rgb(0 0 0 / .4);
+    --so-sidebar: #0b0b0b;
+    --so-signal: #ededed;
+    --so-signal-hover: #ffffff;
+    --so-signal-soft: #2e2e2e;
+    --so-soft: #1f1f1f;
+    --so-success: #3dd68c;
+    --so-success-soft: rgb(61 214 140 / .12);
+    --so-user-bubble: #202020;
+    --so-warning: #ffca16;
+    --so-warning-soft: rgb(255 202 22 / .12);
+  }
+}
+
+:root[data-theme="dark"] {
+  color-scheme: dark;
+  --so-accent: #ededed;
+  --so-accent-hover: #ffffff;
+  --so-accent-text: #ededed;
+  --so-code-bg: #111111;
+  --so-danger: #ff977d;
+  --so-danger-soft: rgb(255 151 125 / .12);
+  --so-ground: #0b0b0b;
+  --so-info: #70b8ff;
+  --so-info-soft: rgb(112 184 255 / .12);
+  --so-ink: #ededed;
+  --so-input-line: #363636;
+  --so-line: #262626;
+  --so-live: #70b8ff;
+  --so-muted: #a1a1a1;
+  --so-nav-current: #1f1f1f;
+  --so-nav-current-ink: #ededed;
+  --so-nav-hover: #171717;
+  --so-nav-ink: #a1a1a1;
+  --so-neutral-ink: #b4b4b4;
+  --so-neutral-soft: #1f1f1f;
+  --so-on-accent: #0a0a0a;
+  --so-on-signal: #0a0a0a;
+  --so-overlay: rgb(0 0 0 / .6);
+  --so-paper: #161616;
+  --so-pill-shadow: 0px 0px 0px 1px #2a2a2a, 0px 1px 2px 0px rgb(0 0 0 / .5);
+  --so-raised: #1c1c1c;
+  --so-scroll: #333333;
+  --so-selection: #3a3a3a;
+  --so-shadow-overlay: 0px 0px 0px 1px #2e2e2e, 0px 24px 48px -12px rgb(0 0 0 / .7);
+  --so-sheet-shadow: 0px 0px 0px 1px #262626, 0px 1px 2px 0px rgb(0 0 0 / .4);
+  --so-sidebar: #0b0b0b;
+  --so-signal: #ededed;
+  --so-signal-hover: #ffffff;
+  --so-signal-soft: #2e2e2e;
+  --so-soft: #1f1f1f;
+  --so-success: #3dd68c;
+  --so-success-soft: rgb(61 214 140 / .12);
+  --so-user-bubble: #202020;
+  --so-warning: #ffca16;
+  --so-warning-soft: rgb(255 202 22 / .12);
+}

package/dist/discord.js

@@ -1,7 +1,6 @@
 /** A single leased Discord Gateway connection, hosted by the ordinary worker. */
 import { randomBytes } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
-import { Client, GatewayIntentBits, Partials } from "discord.js";
 import { loadDiscordCredentials, discordApi, object, discordId, } from "./discord-api.js";
 import { ChatState, chatHash } from "./chat-delivery-state.js";
 import { receiveDiscord, processDiscordEvent, deliverDiscordPart, planDiscordNotifications, planDiscordRooms, } from "./discord-chat.js";
@@ -39,6 +38,8 @@ export async function followDiscord(options) {
         };
         const problem = (message) => state.setProblem(credentials.installation, owner, message);
         const api = discordApi(credentials.botToken);
+        // The SDK loads once Discord is set up, not with every command that could host the follower.
+        const { Client, GatewayIntentBits, Partials } = await import("discord.js");
         const client = new Client({
             // Guild messages and their content are needed for rooms; the Message
             // Content intent must be enabled for the app in Discord's developer portal.

package/dist/dispatch.js

@@ -319,7 +319,7 @@ export function diagnoseTaskDispatch(store, taskId, now, readableRepos = null) {
         // this is where the task page says so.
         const sourceProblem = plannerSourceProblemOf(store, taskId);
         if (sourceProblem !== null)
-            return answer("planner-source", "waiting", "The filed request cannot be planned as filed", sourceProblem, { action: "write-scope", role });
+            return answer("planner-source", "waiting", sourceProblem.title, sourceProblem.detail, { action: "write-scope", role });
         return answer("planning-ready", "retrying", "Planner ready", "An eligible worker can draft the scope on the next pass.", { role });
     }
     if (role === "scout")

package/dist/evidence.d.ts

@@ -47,6 +47,10 @@ export declare const PROGRESS_PREFIX = "STANDING-ORDERS-PROGRESS-";
  * (adaptive execution plans): a terminal file like park or proof, written
  * at most once, read once at settlement. */
 export declare const PROPOSAL_PREFIX = "STANDING-ORDERS-PROPOSAL-";
+/** The running build's steering mailbox: a FOLDER, not a file. The pulse
+ * writes each operator note into it as NNN.json (a temp name, then a
+ * rename); the agent acknowledges a note by moving it into `handled/`. */
+export declare const STEER_PREFIX = "STANDING-ORDERS-STEER-";
 export declare const MAILBOX_SUFFIX = ".json";
 /** v105: left in a run's evidence folder when the retention setting removed its files (retention.ts). */
 export declare const RETENTION_NOTE = "REMOVED-BY-RETENTION";
@@ -78,6 +82,11 @@ export declare function looksLikeMailbox(name: string): boolean;
  * The pre-rename NIGHTORDERS- prefix stays recognized here — a worktree cut
  * down before 2026-08-13 may still hold one, and cleanup has no vintage. */
 export declare function looksLikeProtocolFile(name: string): boolean;
+/** A steering mailbox folder, or anything in it, as a directory listing or
+ * `git status` names it: an untracked folder is reported with a trailing
+ * slash, or file by file where a repository shows every untracked file. */
+export declare function looksLikeSteerFolder(name: string): boolean;
+export declare function steerFolderName(): string;
 export declare function handoffName(): string;
 export declare function planFileName(): string;
 /** The build's optional proof manifest (Priority 2), named exactly like
@@ -208,6 +217,19 @@ export declare function readVerifiedArtifact(root: string, artifact: Artifact):
     ok: false;
     problem: string;
 };
+/**
+ * Whether an artifact's bytes still verify, without returning them. Status
+ * sweeps ask this of every artifact of every run, so a file proved earlier and
+ * not touched since (same artifact row, device, inode, size, mtime and ctime
+ * on the descriptor just opened) costs an fstat, not a re-read and SHA-256.
+ * Every path check still runs on each call; a changed or new file is hashed.
+ */
+export declare function verifyArtifact(root: string, artifact: Artifact): {
+    ok: true;
+} | {
+    ok: false;
+    problem: string;
+};
 /** The file alone, no row — quarantines use this; they belong to no live run. */
 export declare function writeEvidenceFile(root: string, runId: number, name: string, content: Buffer): string;
 /**

package/dist/evidence.js

@@ -14,7 +14,7 @@
  * store holds keys relative to that root, never absolute paths.
  */
 import { createHash, randomBytes } from "node:crypto";
-import { closeSync, existsSync, constants, fstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, unlinkSync, writeFileSync, } from "node:fs";
+import { closeSync, existsSync, constants, fstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
 import { join, sep } from "node:path";
 import { namedPath } from "./names.js";
 import { LIMITS } from "./decision.js";
@@ -50,6 +50,10 @@ export const PROGRESS_PREFIX = "STANDING-ORDERS-PROGRESS-";
  * (adaptive execution plans): a terminal file like park or proof, written
  * at most once, read once at settlement. */
 export const PROPOSAL_PREFIX = "STANDING-ORDERS-PROPOSAL-";
+/** The running build's steering mailbox: a FOLDER, not a file. The pulse
+ * writes each operator note into it as NNN.json (a temp name, then a
+ * rename); the agent acknowledges a note by moving it into `handled/`. */
+export const STEER_PREFIX = "STANDING-ORDERS-STEER-";
 export const MAILBOX_SUFFIX = ".json";
 /** v105: left in a run's evidence folder when the retention setting removed its files (retention.ts). */
 export const RETENTION_NOTE = "REMOVED-BY-RETENTION";
@@ -128,6 +132,8 @@ export function looksLikeMailbox(name) {
  * The pre-rename NIGHTORDERS- prefix stays recognized here — a worktree cut
  * down before 2026-08-13 may still hold one, and cleanup has no vintage. */
 export function looksLikeProtocolFile(name) {
+    if (looksLikeSteerFolder(name))
+        return true;
     return ((name.startsWith(MAILBOX_PREFIX) ||
         name.startsWith(HANDOFF_PREFIX) ||
         name.startsWith(PLAN_PREFIX) ||
@@ -141,6 +147,15 @@ export function looksLikeProtocolFile(name) {
         name.startsWith("NIGHTORDERS-")) &&
         name.endsWith(MAILBOX_SUFFIX));
 }
+/** A steering mailbox folder, or anything in it, as a directory listing or
+ * `git status` names it: an untracked folder is reported with a trailing
+ * slash, or file by file where a repository shows every untracked file. */
+export function looksLikeSteerFolder(name) {
+    return /^STANDING-ORDERS-STEER-[0-9a-f]{16}(?:\/.*)?$/.test(name);
+}
+export function steerFolderName() {
+    return `${STEER_PREFIX}${randomBytes(8).toString("hex")}`;
+}
 export function handoffName() {
     return `${HANDOFF_PREFIX}${randomBytes(8).toString("hex")}${MAILBOX_SUFFIX}`;
 }
@@ -412,6 +427,29 @@ export function storeEvidence(store, root, runId, kind, name, content, capture,
 // Recovery uses this read boundary for retained receipts and handoffs: inspecting
 // bytes must never reseal a missing artifact or turn a saved failure into a pass.
 export function readVerifiedArtifact(root, artifact) {
+    return withArtifactFile(root, artifact, readAndHash);
+}
+/**
+ * Whether an artifact's bytes still verify, without returning them. Status
+ * sweeps ask this of every artifact of every run, so a file proved earlier and
+ * not touched since (same artifact row, device, inode, size, mtime and ctime
+ * on the descriptor just opened) costs an fstat, not a re-read and SHA-256.
+ * Every path check still runs on each call; a changed or new file is hashed.
+ */
+export function verifyArtifact(root, artifact) {
+    return withArtifactFile(root, artifact, (fd, stat, memoKey) => {
+        if (VERIFIED_FILES.get(memoKey) === fileIdentity(artifact, stat))
+            return { ok: true };
+        const read = readAndHash(fd, stat, memoKey, artifact);
+        return read.ok ? { ok: true } : read;
+    });
+}
+/** Files proved by an earlier read, keyed by artifact and resolved path. Bounded; the oldest proof is forgotten first. */
+const VERIFIED_FILES = new Map();
+const VERIFIED_FILES_LIMIT = 20_000;
+const fileIdentity = (artifact, stat) => [artifact.sha256, artifact.bytesStored, stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
+/** The checks both readers share, on the descriptor `use` then reads. */
+function withArtifactFile(root, artifact, use) {
     const segments = artifact.key.split("/");
     const wellFormed = segments.length > 0 &&
         segments.every(segment => segment.length > 0 &&
@@ -447,32 +485,40 @@ export function readVerifiedArtifact(root, artifact) {
         return { ok: false, problem: "cannot open the file without following a link" };
     }
     try {
-        const stat = fstatSync(fd);
+        const stat = fstatSync(fd, { bigint: true });
         if (!stat.isFile())
             return { ok: false, problem: "not a regular file" };
         if (Number(stat.size) !== artifact.bytesStored) {
             return { ok: false, problem: "the file's size no longer matches its record" };
         }
-        const buffer = Buffer.alloc(artifact.bytesStored);
-        let offset = 0;
-        while (offset < buffer.length) {
-            const read = readSync(fd, buffer, offset, buffer.length - offset, offset);
-            if (read <= 0)
-                break;
-            offset += read;
-        }
-        if (offset !== buffer.length)
-            return { ok: false, problem: "the file ended early" };
-        const digest = createHash("sha256").update(buffer).digest("hex");
-        if (digest !== artifact.sha256) {
-            return { ok: false, problem: "the file no longer hashes to its record" };
-        }
-        return { ok: true, content: buffer };
+        return use(fd, stat, `${artifact.id}\0${resolved}`, artifact);
     }
     finally {
         closeSync(fd);
     }
 }
+/** Read the whole file from the open descriptor; only bytes matching the row's SHA-256 leave, and only they are remembered as proved. */
+function readAndHash(fd, stat, memoKey, artifact) {
+    VERIFIED_FILES.delete(memoKey);
+    const buffer = Buffer.alloc(artifact.bytesStored);
+    let offset = 0;
+    while (offset < buffer.length) {
+        const read = readSync(fd, buffer, offset, buffer.length - offset, offset);
+        if (read <= 0)
+            break;
+        offset += read;
+    }
+    if (offset !== buffer.length)
+        return { ok: false, problem: "the file ended early" };
+    const digest = createHash("sha256").update(buffer).digest("hex");
+    if (digest !== artifact.sha256) {
+        return { ok: false, problem: "the file no longer hashes to its record" };
+    }
+    if (VERIFIED_FILES.size >= VERIFIED_FILES_LIMIT)
+        VERIFIED_FILES.delete(VERIFIED_FILES.keys().next().value);
+    VERIFIED_FILES.set(memoKey, fileIdentity(artifact, stat));
+    return { ok: true, content: buffer };
+}
 /** The file alone, no row — quarantines use this; they belong to no live run. */
 export function writeEvidenceFile(root, runId, name, content) {
     const dir = join(root, String(runId));
@@ -502,6 +548,19 @@ export function quarantineMailboxes(worktree, root, runId) {
         if (!looksLikeProtocolFile(name))
             continue;
         const path = join(worktree, name);
+        // An earlier attempt's steering folder holds copies of notes the
+        // database already keeps: removed whole (a symlink is removed, never
+        // followed), never quarantined.
+        if (looksLikeSteerFolder(name)) {
+            try {
+                rmSync(path, { recursive: true, force: true });
+                swept.push(name);
+            }
+            catch {
+                // Its name carries an old nonce; nothing reads it again.
+            }
+            continue;
+        }
         if (root !== null && runId !== null) {
             const read = readMailbox(path);
             if (read.ok) {