toolroll 0.9.59 → 0.9.60

package/dist/server/console.css

@@ -30,83 +30,28 @@
     font-family: "Geist Mono"; font-style: normal; font-weight: 600;
     font-display: swap; src: url("/fonts/geist-mono-600.woff2") format("woff2");
   }
-  /* One palette for every page (2026-09-27): neutral grey and paper with
-   * one chart magenta, light by day and dark after hours. The device decides unless
-   * the person pins a theme (html[data-theme], set from their cookie). The
-   * console's older token names map onto it, so the React workspace, the
-   * server-rendered pages and the pre-script fallback all paint the same. */
+  /* Signal's colour, shadow, radius, type and spacing tokens (--so-*) are
+   * generated by youi into src/design/tokens.css, light and dark, and the
+   * server prepends that sheet to this one (chrome.ts STYLE). Edit them in the
+   * design-language repo, never here. The device decides the scheme unless the
+   * person pins one (html[data-theme], set from their cookie). What follows are
+   * the console's older names: views onto those tokens, never a second ramp. */
   :root {
-    color-scheme: light;
-
-    --so-ground: #efefef; --so-paper: #ffffff; --so-sidebar: #efefef; --so-raised: #f5f5f5;
-    --so-ink: #171717; --so-muted: #666666; --so-line: #e6e6e6; --so-input-line: #d4d4d4;
-    --so-accent: #171717; --so-accent-hover: #383838; --so-accent-text: #171717; --so-on-accent: #ffffff; --so-soft: #f2f2f2;
-    --so-nav-ink: #525252; --so-nav-hover: #e4e4e4; --so-nav-current: #ffffff; --so-nav-current-ink: #171717;
-    --so-signal: #171717; --so-signal-hover: #383838; --so-on-signal: #ffffff; --so-signal-soft: #e8e8e8;
-    --so-danger: #c4320a; --so-danger-soft: #feebe7; --so-success: #218358; --so-success-soft: #e6f6eb;
-    --so-warning: #ab6400; --so-warning-soft: #fff4d5; --so-info: #0d74ce; --so-info-soft: #e6f4fe;
-    --so-neutral-ink: #525252; --so-neutral-soft: #f0f0f0; --so-live: #0d74ce;
-    --so-attention: var(--so-signal); --so-on-attention: var(--so-on-signal); --so-attention-soft: var(--so-signal-soft);
-    --so-sheet-shadow: 0 0 0 1px rgb(0 0 0 / .06), 0 1px 2px rgb(0 0 0 / .04), 0 4px 12px -6px rgb(0 0 0 / .06);
-    --so-pill-shadow: 0 0 0 1px rgb(0 0 0 / .06), 0 1px 2px rgb(0 0 0 / .06);
-    --so-overlay: rgb(0 0 0 / .32); --so-shadow-overlay: 0 0 0 1px rgb(0 0 0 / .08), 0 24px 48px -12px rgb(0 0 0 / .22);
-    --so-selection: #d4d4d4; --so-scroll: #cfcfcf; --so-code-bg: #fafafa; --so-user-bubble: #f2f2f2;
-
     --background: var(--so-ground); --foreground: var(--so-ink); --card: var(--so-paper);
     --muted: var(--so-raised); --muted-foreground: var(--so-muted); --border: var(--so-line); --input: var(--so-input-line);
     --primary: var(--so-accent); --primary-foreground: var(--so-on-accent); --secondary: var(--so-raised); --secondary-foreground: var(--so-ink);
     --accent: var(--so-soft); --destructive: var(--so-danger); --destructive-strong: var(--so-danger); --destructive-soft: var(--so-danger-soft);
     --success: var(--so-success); --success-soft: var(--so-success-soft); --warning: var(--so-warning); --warning-soft: var(--so-warning-soft);
     --running: var(--so-info); --running-soft: var(--so-info-soft); --ring: var(--so-signal);
-    /* Magenta means one thing: a person is needed (approve, answer, decide). */
+    /* The accent means one thing: a person is needed (approve, answer, decide). */
     --brand: var(--so-attention); --brand-foreground: var(--so-on-attention); --brand-soft: var(--so-attention-soft);
     --glass: var(--so-paper); --glass-strong: var(--so-paper); --glass-border: var(--so-line); --glass-highlight: transparent;
     --ambient-one: transparent; --ambient-two: transparent; --user-message: var(--so-user-bubble);
     --surface: var(--so-paper); --ok: var(--so-success); --danger: var(--so-danger); --fg-muted: var(--so-muted);
     --shadow: none; --shadow-overlay: var(--so-shadow-overlay);
     --radius: 0.625rem;
-    --so-ease-out: cubic-bezier(.23, 1, .32, 1);
-    --font-sans: "Geist", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
-    --font-mono: "Geist Mono", ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, monospace;
-    /* Phone spacing steps (760px and narrower): side gutter, gap under the
-       header, gap between page blocks, between rows, and inside a card. */
-    --so-phone-gutter: 16px; --so-phone-gap: 12px; --so-phone-block: 14px; --so-phone-row: 8px; --so-phone-card: 12px;
-  }
-  @media (prefers-color-scheme: dark) {
-    :root:not([data-theme="light"]) {
-      color-scheme: dark;
-
-    --so-ground: #0b0b0b; --so-paper: #161616; --so-sidebar: #0b0b0b; --so-raised: #1c1c1c;
-    --so-ink: #ededed; --so-muted: #a1a1a1; --so-line: #262626; --so-input-line: #363636;
-    --so-accent: #ededed; --so-accent-hover: #ffffff; --so-accent-text: #ededed; --so-on-accent: #0a0a0a; --so-soft: #1f1f1f;
-    --so-nav-ink: #a1a1a1; --so-nav-hover: #171717; --so-nav-current: #1f1f1f; --so-nav-current-ink: #ededed;
-    --so-signal: #ededed; --so-signal-hover: #ffffff; --so-on-signal: #0a0a0a; --so-signal-soft: #2e2e2e;
-    --so-danger: #ff977d; --so-danger-soft: rgb(255 151 125 / .12); --so-success: #3dd68c; --so-success-soft: rgb(61 214 140 / .12);
-    --so-warning: #ffca16; --so-warning-soft: rgb(255 202 22 / .12); --so-info: #70b8ff; --so-info-soft: rgb(112 184 255 / .12);
-    --so-neutral-ink: #b4b4b4; --so-neutral-soft: #1f1f1f; --so-live: #70b8ff;
-    --so-attention: var(--so-signal); --so-on-attention: var(--so-on-signal); --so-attention-soft: var(--so-signal-soft);
-    --so-sheet-shadow: 0 0 0 1px #262626, 0 1px 2px rgb(0 0 0 / .4);
-    --so-pill-shadow: 0 0 0 1px #2a2a2a, 0 1px 2px rgb(0 0 0 / .5);
-    --so-overlay: rgb(0 0 0 / .6); --so-shadow-overlay: 0 0 0 1px #2e2e2e, 0 24px 48px -12px rgb(0 0 0 / .7);
-    --so-selection: #3a3a3a; --so-scroll: #333333; --so-code-bg: #111111; --so-user-bubble: #202020;
-    }
-  }
-  :root[data-theme="dark"] {
-    color-scheme: dark;
-
-    --so-ground: #0b0b0b; --so-paper: #161616; --so-sidebar: #0b0b0b; --so-raised: #1c1c1c;
-    --so-ink: #ededed; --so-muted: #a1a1a1; --so-line: #262626; --so-input-line: #363636;
-    --so-accent: #ededed; --so-accent-hover: #ffffff; --so-accent-text: #ededed; --so-on-accent: #0a0a0a; --so-soft: #1f1f1f;
-    --so-nav-ink: #a1a1a1; --so-nav-hover: #171717; --so-nav-current: #1f1f1f; --so-nav-current-ink: #ededed;
-    --so-signal: #ededed; --so-signal-hover: #ffffff; --so-on-signal: #0a0a0a; --so-signal-soft: #2e2e2e;
-    --so-danger: #ff977d; --so-danger-soft: rgb(255 151 125 / .12); --so-success: #3dd68c; --so-success-soft: rgb(61 214 140 / .12);
-    --so-warning: #ffca16; --so-warning-soft: rgb(255 202 22 / .12); --so-info: #70b8ff; --so-info-soft: rgb(112 184 255 / .12);
-    --so-neutral-ink: #b4b4b4; --so-neutral-soft: #1f1f1f; --so-live: #70b8ff;
-    --so-attention: var(--so-signal); --so-on-attention: var(--so-on-signal); --so-attention-soft: var(--so-signal-soft);
-    --so-sheet-shadow: 0 0 0 1px #262626, 0 1px 2px rgb(0 0 0 / .4);
-    --so-pill-shadow: 0 0 0 1px #2a2a2a, 0 1px 2px rgb(0 0 0 / .5);
-    --so-overlay: rgb(0 0 0 / .6); --so-shadow-overlay: 0 0 0 1px #2e2e2e, 0 24px 48px -12px rgb(0 0 0 / .7);
-    --so-selection: #3a3a3a; --so-scroll: #333333; --so-code-bg: #111111; --so-user-bubble: #202020;
+    --font-sans: var(--so-font-sans);
+    --font-mono: var(--so-font-mono);
   }
   * { box-sizing: border-box; }
   /* Touch: no grey flash on a tap, no double-tap zoom wait on a control,

package/dist/server/render-chat.js

@@ -494,7 +494,7 @@ export function proposalCardParts(view, inert, decision, returnTo = null) {
         reserve: { label: "Worker assignment", action: payload["worker"] === null ? "release" : "reserve", icon: html `<circle cx="12" cy="8" r="4"/><path d="M4 21a8 8 0 0 1 16 0"/>` },
         hold: { label: "Pause work", action: "hold", icon: html `<rect x="6" y="4" width="4" height="16" rx="1"/><rect x="14" y="4" width="4" height="16" rx="1"/>` },
         unhold: { label: "Resume work", action: "release hold", icon: html `<path d="m7 4 13 8-13 8z"/>` },
-        steer: { label: "Guidance for next attempt", action: "add guidance", icon: html `<path d="M5 12h14"/><path d="m13 6 6 6-6 6"/>` },
+        steer: { label: "Guidance for the agent", action: "add guidance", icon: html `<path d="M5 12h14"/><path d="m13 6 6 6-6 6"/>` },
         scope: { label: "Scope revision", action: "save scope", icon: html `<path d="M12 20h9"/><path d="M16.5 3.5a2.1 2.1 0 0 1 3 3L8 18l-4 1 1-4z"/>` },
         answer: { label: "Decision answer", action: "confirm answer", icon: html `<path d="M9.1 9a3 3 0 1 1 5.8 1c0 2-3 2-3 4"/><path d="M12 18h.01"/><circle cx="12" cy="12" r="9"/>` },
         cancel: { label: "Cancel task", action: "open task", icon: html `<path d="m15 9-6 6"/><path d="m9 9 6 6"/><circle cx="12" cy="12" r="9"/>` },
@@ -572,7 +572,7 @@ export function proposalCardParts(view, inert, decision, returnTo = null) {
     }
     else if (view.kind === "steer") {
         const taskTitle = text("taskTitle") || task;
-        what = html `<h3>Guide <a href="${taskHref(task)}">${taskTitle}</a>'s next attempt</h3><p class="proposal-summary">${text("note")}</p>${facts(["when", "next attempt"], ["project", mono(repoId)])}<p class="meta proposal-disclosure">This guides the next attempt without changing the task’s scope. It does not interrupt work already running.</p>`;
+        what = html `<h3>Guidance for <a href="${taskHref(task)}">${taskTitle}</a></h3><p class="proposal-summary">${text("note")}</p>${facts(["project", mono(repoId)])}<p class="meta proposal-disclosure">A running agent reads it when it next checks for notes; otherwise the next attempt does. The task’s scope doesn’t change.</p>`;
     }
     else if (view.kind === "agents") {
         // The agents card (v48): exactly what changes, in the same words the

package/dist/server/render-tasks.d.ts

@@ -570,6 +570,8 @@ export declare function taskBodyParts(data: {
     } | null;
     /** Operator steering notes (arc 1), delivery state included. */
     steering?: SteerNote[];
+    /** A build's agent is running now and reads new notes when it next checks for them (v120). */
+    steeringLive?: boolean;
     /** The publication grant the publisher would act under — from
      * publicationGrantFor(repo) only; null when none, or no project. */
     grant?: PublicationGrant | null;

package/dist/server/render-tasks.js

@@ -36,6 +36,7 @@ import { assignmentStageOf, demoChecksOf, stageOfCode, stageOfDispatch, STATUS_M
 import { buildProgressOf, dispatchActionLabel, earlierAttemptsWords, receiptPublicationWords, resultStatusOf, REVIEW_TOKENS, workStatusOf } from "../workspace-ui.js";
 import { createHash } from "node:crypto";
 import { isOverdue, oneLineOf, projectChip, regionScript, safePrUrl, screen, SENSITIVE_INPUT, sentenceCase, shortDigest, transcriptScript, whenTime } from "./chrome.js";
+import { steerDestinationWords, steerStandingParts } from "../steer-status.js";
 import { reviewHref, taskChatHref, taskHref } from "./http.js";
 import { coordinatorProposalsSection } from "./render-chat.js";
 import { completionReceiptCard, criterionMatrixHtml, evidenceWords, homePhaseWords, incidentWords, needsCheck, pullRequestCardHtml, reasonWords, receiptStatusOf, repairChainHtml, reportItemsHtml, reviewRetryPanel, runNoun, runOutcomeBadge, semanticCoverageHtml, terminalDiffCard, verificationExplanation, verificationRecovered } from "./render-results.js";
@@ -1370,24 +1371,21 @@ export function taskBodyParts(data) {
         }
         return box("problem", "Dispatch unknown", "Refresh this task before relying on its scheduler state.", "unknown");
     })();
-    // Operator steering (arc 1): notes for the agent, each wearing exactly
-    // where it stands — waiting, attached, proven delivered, or superseded.
+    // Operator steering (arc 1, v120): notes for the agent, each wearing the
+    // same words the CLI and the lead use — read (and when), waiting for the
+    // running agent, bound for the next attempt, or ended unread.
     const steering = data.steering ?? [];
-    const steerState = (one) => one.authorshipState !== "verified"
-        ? "recorded before steering required a credential — never delivered"
-        : one.supersededAt !== null
-            ? "the task ended before this landed"
-            : one.deliveredAt !== null
-                ? `reached build #${one.attachedRun}`
-                : one.attachedRun !== null
-                    ? `attached to build #${one.attachedRun} — delivery not yet proven`
-                    : "waiting for the next attempt";
+    const steeringLive = data.steeringLive === true;
+    const steerState = (one) => {
+        const { words, readAt } = steerStandingParts(one, steeringLive);
+        return readAt === null ? html `${words}` : html `${words} ${whenTime(readAt)}`;
+    };
     const steerRows = steering.length === 0 ? "" : joinHtml(steering.map(one => html `<p class="row"><span class="meta">${one.author} · ${whenTime(one.createdAt)} · ${steerState(one)}</span> ${one.note}</p>`), "\n");
     const steerForm = data.csrf === "" || task.state === "done" || task.state === "cancelled"
         ? ""
         : joinHtml([
-            postForm(`${taskHref(task.id)}/steer`, html `<input type="text" name="note" placeholder="guidance for the next attempt" aria-label="steering note" style="width:100%;max-width:28rem"><button type="submit">Steer</button>`, { attrs: { class: "row" } }),
-            html `<p class="meta">Lands when the next attempt starts — a running agent is not interrupted, and a note cannot widen the approved scope</p>`,
+            postForm(`${taskHref(task.id)}/steer`, html `<input type="text" name="note" placeholder="guidance for the agent" aria-label="steering note" style="width:100%;max-width:28rem"><button type="submit">Steer</button>`, { attrs: { class: "row" } }),
+            html `<p class="meta">${steerDestinationWords(steeringLive)} A note can't widen the approved scope.</p>`,
         ]);
     const steeringCard = steerRows === "" && steerForm === "" ? "" : html `<h2>Steering</h2>${steerRows}${steerForm}`;
     const holds = data.holds.length === 0

package/dist/server/task-views.js

@@ -473,6 +473,7 @@ export function createTaskViews(runtime) {
                 return { rows, decisions: decisionsFor(runtime.store, rows), now };
             })(),
             steering: ref === null ? [] : runtime.store.listSteerNotes(ref.id),
+            steeringLive: ref !== null && runtime.store.steeringLiveBuild(ref.id, now) !== null,
             // "publishes as" reads ONLY publicationGrantFor(repo) — the grant
             // the publisher would act under — never listGrants(), which is
             // dispatch authority (slice 1c).

package/dist/slack-socket.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The Socket Mode client, apart from the follower so the Slack SDK loads only
+ * once Slack is set up (slack.ts imports this when it finds credentials).
+ */
+import { SocketModeClient } from "@slack/socket-mode";
+export { LogLevel } from "@slack/socket-mode";
+/** The bot and socket tokens must belong to the same app, including after reconnect. */
+export declare class ToolrollSlackSocket extends SocketModeClient {
+    expectedApp: string;
+    wrongApp: () => void;
+    protected onWebSocketMessage(data: string | ArrayBuffer, isBinary: boolean): Promise<void>;
+}

package/dist/slack-socket.js

@@ -0,0 +1,29 @@
+/**
+ * The Socket Mode client, apart from the follower so the Slack SDK loads only
+ * once Slack is set up (slack.ts imports this when it finds credentials).
+ */
+import { SocketModeClient } from "@slack/socket-mode";
+export { LogLevel } from "@slack/socket-mode";
+/** The bot and socket tokens must belong to the same app, including after reconnect. */
+export class ToolrollSlackSocket extends SocketModeClient {
+    expectedApp = "";
+    wrongApp = () => { };
+    async onWebSocketMessage(data, isBinary) {
+        let packet;
+        try {
+            packet = JSON.parse(typeof data === "string" ? data : new TextDecoder().decode(data));
+        }
+        catch {
+            return;
+        }
+        if (packet.type === "hello") {
+            const info = packet.connection_info;
+            if (info?.app_id !== this.expectedApp) {
+                this.wrongApp();
+                await this.disconnect();
+                return;
+            }
+        }
+        return super.onWebSocketMessage(data, isBinary);
+    }
+}

package/dist/slack.d.ts

@@ -1,11 +1,4 @@
-import { SocketModeClient } from "@slack/socket-mode";
 import { type SlackChatOptions } from "./slack-chat.js";
-/** The bot and socket tokens must belong to the same app, including after reconnect. */
-export declare class ToolrollSlackSocket extends SocketModeClient {
-    expectedApp: string;
-    wrongApp: () => void;
-    protected onWebSocketMessage(data: string | ArrayBuffer, isBinary: boolean): Promise<void>;
-}
 export declare function followSlack(options: Omit<SlackChatOptions, "identity" | "api" | "owner" | "current"> & {
     dir: string;
     signal: AbortSignal;

package/dist/slack.js

@@ -1,33 +1,9 @@
 /** One leased Socket Mode connection, hosted by the ordinary worker. */
 import { randomBytes } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
-import { SocketModeClient, LogLevel } from "@slack/socket-mode";
 import { loadSlackCredentials, slackApi } from "./slack-api.js";
 import { ChatState } from "./chat-delivery-state.js";
 import { receiveSlack, processSlackEvent, deliverSlackPart, planSlackNotifications, planSlackRooms, } from "./slack-chat.js";
-/** The bot and socket tokens must belong to the same app, including after reconnect. */
-export class ToolrollSlackSocket extends SocketModeClient {
-    expectedApp = "";
-    wrongApp = () => { };
-    async onWebSocketMessage(data, isBinary) {
-        let packet;
-        try {
-            packet = JSON.parse(typeof data === "string" ? data : new TextDecoder().decode(data));
-        }
-        catch {
-            return;
-        }
-        if (packet.type === "hello") {
-            const info = packet.connection_info;
-            if (info?.app_id !== this.expectedApp) {
-                this.wrongApp();
-                await this.disconnect();
-                return;
-            }
-        }
-        return super.onWebSocketMessage(data, isBinary);
-    }
-}
 export async function followSlack(options) {
     const owner = randomBytes(16).toString("hex"), state = new ChatState(options.store, "slack");
     const pause = async (ms) => {
@@ -56,6 +32,8 @@ export async function followSlack(options) {
                 state.owns(credentials.installation, owner));
         };
         const problem = (text) => state.setProblem(credentials.installation, owner, text);
+        // The SDK loads once Slack is set up, not with every command that could host the follower.
+        const { ToolrollSlackSocket, LogLevel } = await import("./slack-socket.js");
         // SDK log output can include envelopes/tokens. Only fixed status phrases are saved.
         const client = new ToolrollSlackSocket({
             appToken: credentials.appToken,

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,19 @@
+/**
+ * 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" | "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): string;

package/dist/steer-status.js

@@ -0,0 +1,30 @@
+/** `liveBuild`: the task has a build whose agent is running and reads its steering folder (Store.steeringLiveBuild). */
+export function steerStandingOf(note, liveBuild) {
+    if (note.authorshipState !== "verified")
+        return "unverified";
+    if (note.supersededAt !== null)
+        return "ended";
+    if (note.deliveredAt !== null)
+        return "read";
+    return liveBuild ? "waiting" : "next-attempt";
+}
+/** 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 "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 };
+    }
+}
+export function steerStandingWords(note, liveBuild, time) {
+    const { words, readAt } = steerStandingParts(note, liveBuild);
+    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.";
+}