toolroll 0.9.60 → 0.9.61

package/dist/lead-cli.js

@@ -71,25 +71,28 @@ export function proposalLines(proposals, repos, ordinal = (_p) => 0) {
                 ? `${t("operation") === "revise" ? "request a revision" : "save feedback"} for ${t("taskTitle") || t("task")}: ${t("note")}${Array.isArray(payload["notes"]) && payload["notes"].length > 0 ? ` (saved notes: ${payload["notes"].join(", ")})` : ""}`
                 : one.kind === "control"
                     ? (isChatControl(payload["control"]) ? `${CHAT_CONTROLS[payload["control"]].label}: ${chatControlHref(payload["control"], t("task"), payload["run"], payload["project"])} (open in the console)` : "control unavailable")
-                    : one.kind === "steer" ? `guidance for ${t("task")}'s agent: ${t("note")}`
-                        : one.kind === "agents" ? `change agents for ${t("task")}: ${t("role")} ${t("provider")} ${t("model")} ${t("risk")}`
-                            : one.kind === "repair" ? `${t("operation")} dependency ${t("blocker")} for ${t("task")}`
-                                :
-                                    one.kind === "task"
-                                        ? `file "${t("title")}" in ${repoLabel}${payload["report"] === true ? " (a scout task — it delivers a report, never a branch)" : ""}`
-                                        : one.kind === "next"
-                                            ? `move ${t("task")} to the front (was ${String(payload["position"] ?? "?")} of ${String(payload["of"] ?? "?")})`
-                                            : one.kind === "reserve"
-                                                ? `${payload["worker"] === null ? `release ${t("task")} to the shared queue` : `reserve ${t("task")} for ${t("worker")}`}`
-                                                : one.kind === "hold"
-                                                    ? `hold ${t("task")}: ${t("reason")}`
-                                                    : one.kind === "unhold"
-                                                        ? `release ${t("task")} from its hold`
-                                                        : one.kind === "answer"
-                                                            ? `answer decision #${String(payload["decision"])} on ${t("task")} with "${t("optionLabel")}"${payload["reversible"] === false ? " (irreversible — confirm N yes)" : ""}: ${t("rationale")}`
-                                                            : one.kind === "scope"
-                                                                ? `rewrite the scope of ${t("task")} (then approve it: toolroll task approve ${t("task")})`
-                                                                : `cancel ${t("task")}: ${t("reason")} (arm it yourself: toolroll task cancel ${t("task")})`;
+                    : one.kind === "steer" && one.payload["mode"] === "pause" ? `pause ${t("task")}'s build`
+                        : one.kind === "steer" && one.payload["mode"] === "resume" ? `resume ${t("task")}'s paused build`
+                            : one.kind === "steer" && one.payload["mode"] === "pause-and-steer" ? `pause ${t("task")}'s build, then send: ${t("note")}`
+                                : one.kind === "steer" ? `guidance for ${t("task")}'s agent: ${t("note")}`
+                                    : one.kind === "agents" ? `change agents for ${t("task")}: ${t("role")} ${t("provider")} ${t("model")} ${t("risk")}`
+                                        : one.kind === "repair" ? `${t("operation")} dependency ${t("blocker")} for ${t("task")}`
+                                            :
+                                                one.kind === "task"
+                                                    ? `file "${t("title")}" in ${repoLabel}${payload["report"] === true ? " (a scout task — it delivers a report, never a branch)" : ""}`
+                                                    : one.kind === "next"
+                                                        ? `move ${t("task")} to the front (was ${String(payload["position"] ?? "?")} of ${String(payload["of"] ?? "?")})`
+                                                        : one.kind === "reserve"
+                                                            ? `${payload["worker"] === null ? `release ${t("task")} to the shared queue` : `reserve ${t("task")} for ${t("worker")}`}`
+                                                            : one.kind === "hold"
+                                                                ? `hold ${t("task")}: ${t("reason")}`
+                                                                : one.kind === "unhold"
+                                                                    ? `release ${t("task")} from its hold`
+                                                                    : one.kind === "answer"
+                                                                        ? `answer decision #${String(payload["decision"])} on ${t("task")} with "${t("optionLabel")}"${payload["reversible"] === false ? " (irreversible — confirm N yes)" : ""}: ${t("rationale")}`
+                                                                        : one.kind === "scope"
+                                                                            ? `rewrite the scope of ${t("task")} (then approve it: toolroll task approve ${t("task")})`
+                                                                            : `cancel ${t("task")}: ${t("reason")} (arm it yourself: toolroll task cancel ${t("task")})`;
         const state = one.state === "pending" ? "" : ` [${one.state}${one.outcome !== null && typeof one.outcome.said === "string" ? `: ${one.outcome.said}` : ""}]`;
         return `  ${number}. ${what}${state}`;
     });

package/dist/lead-contract.js

@@ -20,7 +20,7 @@ export const LEAD_CONTRACT = [
     "Talk like a colleague in everyday words: task titles, 'the changes', 'the checks', 'try again'. Never say execution, run, scope, digest, dispatch or lane to the operator; say what happens next and what they can do.",
     "Read get_result for the exact execution/run; page nextFeedbackOffset. propose_review revise requests changes; note saves feedback. Use read notes only; clarify ambiguous intent. Ready is a saved result, not a reviewer stage. Historical missing assessments never require rerunning work. Failed checks and missing files remain visible; completion never deploys or changes checks.",
     "For screenshots, call get_result_images for that exact execution and run. On Telegram say they follow, never that they were delivered; elsewhere name result and image count. Limit 8/reply. If nextImageOffset exists, name remaining count; call it again with that offset or with the image ids it listed when asked. Select a newer revision explicitly; never describe unselected images or expose paths.",
-    "propose_steer reaches a running build when it next checks for notes, else the next attempt; get_task steering says if it was read. propose_scope changes scope. propose_task_action uses control.run for stop/resume and supports retry, plan, dependencies. Requested stop is not stopped; ending chat differs. For protected actions read get_actions, use propose_action and full secure review. get_action_status proves saved outcomes; show_control only opens controls.",
+    "propose_steer reaches a running build (a Claude build in seconds), else the next attempt; get_task steering says if it was read. Its mode pause stops a running Claude build's turn and keeps the build; pause-and-steer then sends the note; resume continues a paused build; never use these for Stop. propose_scope changes scope. propose_task_action uses control.run for stop/resume and supports retry, plan, dependencies. Requested stop is not stopped; ending chat differs. For protected actions read get_actions, use propose_action and full secure review. get_action_status proves saved outcomes; show_control only opens controls.",
     "For a task's models/risk, read get_agents and answer in its words; for defaults, CLI versions and new models, read get_models; never an agent that is not listed. Changes require renewed approval. Before propose_answer read get_decision in an earlier step, including every option and consequence. Irreversible answers require explicit confirmation; cards retain consequences and recommendations.",
     "For intake, a plain-language outcome is enough to draft a task. Infer title, narrow goal, safe non-goals and testable criteria; leave touches empty for discovery. Do not ask the operator for a title, paths, implementation details, acceptance wording, model, budget or safely inferable fields. Ask at most three questions with defaults (one at a time with ask_owner) for material ambiguity, conflicting goals or unresolved irreversible/public/security/data-loss/migration choices. With 'use your judgment', use reversible defaults; real blockers may still arise.",
     "Set propose_task planning to 'required' for broad, risky or plan-first work, 'skip' for explicitly small direct builds, otherwise 'auto'. report:true investigates without a branch; follow-ups require confirmed proposals.",

package/dist/lead-doors.js

@@ -18,6 +18,7 @@ import { closedQuestionWords } from "./decision.js";
 import { steerDestinationWords } from "./steer-status.js";
 import { isCheckLevel, setTaskCheckLevel } from "./check-levels.js";
 import { leadTurnKeepsProposals, verifiedAuthor } from "./store.js";
+import { agentQuestion, answerAgentQuestion } from "./agent-board.js";
 import { isVerifiedApprover, reproveApprover } from "./principal.js";
 import { TURN_WALL_CLOCK_MS } from './converse.js';
 import { teamChatAuthorization, subscriptionTeamChatProvider } from './team-chat-authorization.js';
@@ -408,10 +409,52 @@ function executeProposal(store, actor, kind, payload, now, options) {
         store.unhold(ref.id);
         return { ok: true, kind, said: `${taskId} released from its hold`, taskId };
     }
+    if (kind === "steer" && payload["mode"] === "resume") {
+        // Resume (live steering): the paused build the proposal saw, under the request id it was drafted with; no note.
+        const sawRun = payloadNumber(payload, "sawRun");
+        const request = payloadString(payload, "request");
+        if (sawRun === null || request === null)
+            return refuse("refused", "this proposal is missing what it saw");
+        const asked = store.requestResume({ taskId, runId: sawRun, by: verifiedAuthor(actor.name), via: "chat", requestId: request }, now);
+        if (!asked.ok) {
+            return refuse(asked.reason === "stale" || asked.reason === "not-paused" ? "stale" : "refused", asked.reason === "stale" ? "that build has stopped taking notes — look again" : asked.reason === "not-paused" ? "that build isn't paused any more — look again" : asked.detail);
+        }
+        const taskName = payloadString(payload, "taskTitle") ?? taskId;
+        return { ok: true, kind, said: `Resuming ${taskName} where it stopped.`, taskId };
+    }
+    if (kind === "steer" && (payload["mode"] === "pause" || payload["mode"] === "pause-and-steer")) {
+        // Pause, or Pause and steer (live steering): the build the proposal saw, under the request id it was drafted with.
+        const mode = payload["mode"];
+        const sawRun = payloadNumber(payload, "sawRun");
+        const request = payloadString(payload, "request");
+        const note = payloadString(payload, "note");
+        if (sawRun === null || request === null || (mode === "pause-and-steer" && note === null))
+            return refuse("refused", "this proposal is missing what it saw");
+        const asked = store.requestPause({ taskId, runId: sawRun, by: verifiedAuthor(actor.name), via: "chat", requestId: request, ...(mode === "pause-and-steer" ? { note: note } : {}) }, now);
+        if (!asked.ok)
+            return refuse(asked.reason === "stale" ? "stale" : "refused", asked.reason === "stale" ? "that build has stopped taking notes — look again" : asked.detail);
+        const taskName = payloadString(payload, "taskTitle") ?? taskId;
+        return { ok: true, kind, said: mode === "pause" ? `Pausing ${taskName}. Its next note continues it.` : `Pausing ${taskName}, then sending your note.`, taskId };
+    }
     if (kind === "steer") {
         const note = payloadString(payload, "note");
         if (note === null)
             return refuse("refused", "this proposal carries no guidance");
+        // A reply to the running agent's own question: the same door the Agents board's Reply uses, closing exactly that key.
+        const question = payloadNumber(payload, "question");
+        if (question !== null) {
+            const asked = agentQuestion(store, question);
+            if (asked === null || asked.taskRef !== ref.id)
+                return refuse("stale", "that question is not on this task");
+            const answered = answerAgentQuestion(store, { question, answer: note, author: actor.name, at: now,
+                file: (task, text) => store.fileSteerNote(task, verifiedAuthor(actor.name), text, now) });
+            if (!answered.ok) {
+                return answered.reason === "invalid-answer" || answered.reason === "not-saved"
+                    ? refuse("refused", answered.problem ?? "that reply could not be saved")
+                    : refuse("stale", "the agent's question already closed or its attempt ended — look again");
+            }
+            return { ok: true, kind, said: `Reply sent to the agent working on ${payloadString(payload, "taskTitle") ?? taskId}.`, taskId };
+        }
         const filed = store.fileSteerNote(taskId, verifiedAuthor(actor.name), note, now);
         if (!filed.ok) {
             const said = filed.reason === "task-finished"
@@ -424,7 +467,8 @@ function executeProposal(store, actor, kind, payload, now, options) {
         const taskName = payloadString(payload, "taskTitle") ?? taskId;
         const steered = store.lookupRef(taskId);
         const live = steered !== null && store.steeringLiveBuild(steered.id, now) !== null;
-        return { ok: true, kind, said: `Guidance saved for ${taskName}. ${steerDestinationWords(live)}`, taskId };
+        const liveInput = steered !== null && store.liveInputRun(steered.id, now) !== null;
+        return { ok: true, kind, said: `Guidance saved for ${taskName}. ${steerDestinationWords(live, liveInput)}`, taskId };
     }
     if (kind === "repair") {
         const blocker = payloadString(payload, "blocker");

package/dist/lead-tools.js

@@ -67,6 +67,7 @@ import { undoFor, weekOf, weekWords } from "./subagent-week.js";
 import { PERSON_ID, personEntry, teamRoomOf } from "./lead-people.js";
 import { aboutYouOf, checkAboutYouLine } from "./lead-about.js";
 import { steerStandingWords } from "./steer-status.js";
+import { agentQuestion, openAgentQuestions } from "./agent-board.js";
 import { utcMinute } from "./when-html.js";
 const REPO_ID = /^r[0-9]{1,3}$/;
 const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
@@ -1545,6 +1546,17 @@ const LEAD_TOOL_HANDLERS = {
                         const live = ctx.store.steeringLiveBuild(ref.id, ctx.now) !== null;
                         return ctx.store.listSteerNotes(ref.id).slice(-5).map(one => ({ note: one.id, filedAt: one.createdAt, state: steerStandingWords(one, live, utcMinute) }));
                     })(),
+                    // Live steering: the running Claude build a note reaches in seconds and a pause can reach, and its pause.
+                    liveBuild: (() => {
+                        const run = ctx.store.liveInputRun(ref.id, ctx.now);
+                        if (run === null)
+                            return null;
+                        const pause = ctx.store.livePauseOf(run);
+                        const until = pause?.state === "paused" && pause.pausedAt !== null && pause.limitMs !== null ? new Date(Date.parse(pause.pausedAt) + pause.limitMs).toISOString() : null;
+                        return { build: run, pause: pause?.state ?? null, ...(until === null ? {} : { pausedUntil: until }) };
+                    })(),
+                    // The running agent's open questions (Agents board): reply with propose_steer and its question id.
+                    agentQuestions: openAgentQuestions(ctx.store, ref.id).map(one => ({ question: one.id, key: one.key, asks: one.question, askedAt: one.askedAt })),
                 },
             };
         },
@@ -1698,23 +1710,44 @@ const LEAD_TOOL_HANDLERS = {
         },
     },
     propose_steer: {
-        description: "Send guidance within existing scope: a running build's agent reads it when it next checks for notes, otherwise the next attempt does. It never stops work.",
+        description: "Send guidance within existing scope: a running Claude build gets it in seconds, another running build reads it when it next checks for notes, otherwise the next attempt does. mode pause stops a running Claude build's current turn and keeps the build (its next note continues it); pause-and-steer pauses, then sends the note; resume continues a paused build without a note. None stops work; get_task liveBuild says when a pause or resume is possible. With question (from get_task agentQuestions, mode note) the note is the reply to that open question.",
         handle: (ctx, args) => {
             const taskId = taskIdOf(args);
             const ref = taskId === null ? null : admittedRef(ctx, taskId);
             const task = taskId === null ? null : ctx.store.getTask(taskId);
             if (taskId === null || ref === null || task === null)
                 return notFound();
-            if (typeof args["note"] === "string" && args["note"].length > LIMITS.note)
-                return { ok: false, message: `guidance is ${args["note"].length} characters; the limit is ${LIMITS.note}. Shorten it and propose again.` };
-            if (!honest(args["note"], LIMITS.note))
-                return { ok: false, message: `guidance is plain text up to ${LIMITS.note} characters` };
+            const mode = args["mode"] === "pause" || args["mode"] === "pause-and-steer" || args["mode"] === "resume" ? args["mode"] : "note";
+            if (mode !== "pause" && mode !== "resume") {
+                if (typeof args["note"] === "string" && args["note"].length > LIMITS.note)
+                    return { ok: false, message: `guidance is ${args["note"].length} characters; the limit is ${LIMITS.note}. Shorten it and propose again.` };
+                if (!honest(args["note"], LIMITS.note))
+                    return { ok: false, message: `guidance is plain text up to ${LIMITS.note} characters` };
+            }
             if (task.state === "done" || task.state === "cancelled")
                 return { ok: false, message: "that task is finished, so guidance has no next attempt to reach" };
-            const id = ctx.draft("steer", { task: taskId, taskTitle: task.title, repoId: ref.repoId, note: args["note"] });
+            // A pause binds to the build running now: confirming it later reaches that build or none.
+            const sawRun = mode === "note" ? null : ctx.store.liveInputRun(ref.id, ctx.now);
+            if (mode !== "note" && sawRun === null)
+                return { ok: false, message: `that task has no running Claude build to ${mode === "resume" ? "resume" : "pause"}; send the guidance as a note instead` };
+            if (mode === "resume" && ctx.store.pauseStateOf(sawRun) !== "paused")
+                return { ok: false, message: "that task's build isn't paused, so there is nothing to resume" };
+            // A reply names exactly one open question of this task's running agent; the confirmation re-checks it. A reply is
+            // an ordinary note (the confirmation files it through the question's own door), so it never rides a pause or resume.
+            if (typeof args["question"] === "number" && mode !== "note")
+                return { ok: false, message: "a reply to the agent's question is sent as a note; propose it without mode" };
+            const asked = typeof args["question"] === "number" ? agentQuestion(ctx.store, args["question"]) : null;
+            if (typeof args["question"] === "number" && (asked === null || asked.taskRef !== ref.id || asked.closedAt !== null))
+                return { ok: false, message: "that question is no longer open; read get_task agentQuestions again" };
+            const id = ctx.draft("steer", {
+                task: taskId, taskTitle: task.title, repoId: ref.repoId,
+                ...(mode === "pause" || mode === "resume" ? {} : { note: args["note"] }),
+                ...(mode === "note" ? {} : { mode, sawRun, request: `lead-${randomUUID()}` }),
+                ...(asked === null ? {} : { question: asked.id, questionKey: asked.key }),
+            });
             if (id === null)
                 return tooMany();
-            return { ok: true, body: { proposal: id, kind: "steer", task: taskId, awaiting: "the operator's confirmation" } };
+            return { ok: true, body: { proposal: id, kind: "steer", task: taskId, mode, awaiting: "the operator's confirmation" } };
         },
     },
     propose_dependency_repair: {

package/dist/live-input.d.ts

@@ -0,0 +1,68 @@
+/** The child's stdin, as the transport hands it over. */
+export type LiveInputIo = {
+    write(line: string): void;
+    end(): void;
+};
+/** Why stdin closed: the handoff was written, the session had nothing more owed, the turn budget ran out, a paused
+ * session reached the idle limit, the process ended first, or a write failed. */
+export type LiveCloseReason = "finished" | "settled" | "turn-budget" | "paused-idle" | "ended" | "input-failed";
+/** What Resume sends a paused session: only a nudge to go on, never a note. */
+export declare const CONTINUE_TEXT = "continue";
+export type LiveInputOptions = {
+    /** Toolroll's total for the whole session: distinct assistant turns across every message. */
+    maxTurns: number;
+    /** The agent wrote its handoff (done, park or a plan revision): a turn that ends now closes stdin. */
+    finished?: () => boolean;
+    /** stdin is attached and the brief was written. */
+    onOpen?: () => void;
+    onClose?: (why: LiveCloseReason) => void;
+    /** The current turn stopped for a Pause (the harness confirmed the interrupt, or the turn's result arrived). */
+    onPaused?: () => void;
+};
+/** A stdin user frame, in the shape the harness reads. */
+export declare const userFrame: (text: string, uuid: string) => string;
+/** A stdin interrupt: stop the current turn, keep the session. */
+export declare const interruptFrame: (requestId: string, cancelQueued?: boolean) => string;
+export declare class LiveInput {
+    #private;
+    readonly maxTurns: number;
+    /** The brief's frame uuid, once begun. */
+    briefUuid: string | null;
+    constructor(options: LiveInputOptions);
+    /** Queue the brief as the first frame. Once, before the process is attached. */
+    begin(brief: string, uuid?: string): void;
+    /** The transport spawned the child with stdin piped: write what is queued, brief first. */
+    attach(io: LiveInputIo): void;
+    /** stdin is attached and still open: a note reaches the agent in seconds, and a Pause can stop its turn. */
+    get open(): boolean;
+    get paused(): boolean;
+    /** Distinct assistant turns so far, across every message. */
+    get turns(): number;
+    /** Why stdin closed, once it has. */
+    get closeReason(): LiveCloseReason | null;
+    /**
+     * Send a note (or anything the session should read next). A paused session continues. False once stdin is closed.
+     * Mid-turn, the harness folds it into the running turn; after an interrupt that turn is over, so the frame starts a
+     * turn of its own whose result is owed before stdin closes.
+     */
+    send(text: string, uuid: string): boolean;
+    /** Resume a paused session with a short continue frame and no note. "not-paused" when nothing waits to go on. */
+    resume(uuid: string): "sent" | "not-paused" | "closed";
+    /**
+     * The transport's idle limit was reached. A paused session closes stdin instead of being killed — the harness exits
+     * and the build settles from whatever handoff it saved — and true asks the watchdog to wait once more for that exit.
+     * Anything else is an ordinary idle timeout.
+     */
+    idleLimit(): boolean;
+    /**
+     * Pause: stop the current turn, keep the session. "sent" when an interrupt was written; "idle" when no turn was
+     * running (the session is already waiting, so it is paused as it stands); "closed" when stdin is gone.
+     */
+    interrupt(requestId: string): "sent" | "idle" | "closed";
+    /** Every parsed stdout event, in order. */
+    observe(event: Record<string, unknown>): void;
+    /** Close stdin: the harness finishes what it has and exits. Further sends refuse. */
+    close(why: LiveCloseReason): void;
+    /** The process ended (or its stdin failed): nothing more is written. */
+    detach(why?: "ended" | "input-failed"): void;
+}

package/dist/live-input.js

@@ -0,0 +1,254 @@
+/**
+ * A Claude build's live input (live steering). The build runs with
+ * `--input-format stream-json` and its stdin left open, so Toolroll can talk
+ * to the session while it works instead of only through files it reads
+ * between steps (checked on Claude Code 2.1.290):
+ *
+ * - The brief is the FIRST stdin message, a user frame with its own uuid. A
+ *   `-p` prompt is silently dropped once stdin carries input, so the argv
+ *   never carries the brief.
+ * - A later user frame is taken up as soon as the current tool call ends,
+ *   inside the turn that is running: it adds no result of its own.
+ * - An interrupt control request stops the current turn within milliseconds
+ *   and keeps the process; the next user frame continues the same session
+ *   as a new turn. That is Pause; Resume is that next frame with only a
+ *   short "continue". Stop is still the process-tree kill it always was.
+ * - One process emits a result per turn, so the run ends when Toolroll
+ *   closes stdin, not at the first result: after a turn ends with the
+ *   handoff written or with nothing more owed, when the turn budget is
+ *   spent, or when a paused session reaches the idle limit. `--max-turns`
+ *   applies per user message, so the total is counted here. The idle
+ *   watchdog stays the transport's own; a paused session only asks it to
+ *   close stdin first (idleLimit), so the build settles from its handoff.
+ *   closeReason tells settlement which ending Toolroll chose.
+ *
+ * Sending is never reading: a note written here still counts as read only
+ * when the agent moves its file to handled/ (steer-mailbox.ts). Nothing here
+ * touches the store; the builder's dispatcher records what happened.
+ */
+import { randomUUID } from "node:crypto";
+/** What Resume sends a paused session: only a nudge to go on, never a note. */
+export const CONTINUE_TEXT = "continue";
+/** A stdin user frame, in the shape the harness reads. */
+export const userFrame = (text, uuid) => JSON.stringify({ type: "user", message: { role: "user", content: text }, uuid });
+/** A stdin interrupt: stop the current turn, keep the session. */
+export const interruptFrame = (requestId, cancelQueued = false) => JSON.stringify({ type: "control_request", request_id: requestId, request: { subtype: "interrupt", ...(cancelQueued ? { cancel_queued: true } : {}) } });
+/** The session's own words count; a subagent's (parent_tool_use_id set) or a background task's never do. */
+const topLevel = (event) => event["parent_tool_use_id"] === undefined || event["parent_tool_use_id"] === null;
+const primaryResult = (event) => {
+    const origin = event["origin"];
+    return origin === undefined || origin === null || (typeof origin === "object" && String(origin["kind"] ?? "") === "human");
+};
+export class LiveInput {
+    maxTurns;
+    #options;
+    #io = null;
+    #pending = [];
+    #begun = false;
+    #closed = false;
+    #turnActive = false;
+    /** A user frame was written while an interrupted turn had not yet ended: that frame's own turn is owed a result. */
+    #owed = false;
+    #paused = false;
+    #interrupts = new Set();
+    #turns = new Set();
+    #closeReason = null;
+    /** The brief's frame uuid, once begun. */
+    briefUuid = null;
+    constructor(options) {
+        this.#options = options;
+        this.maxTurns = Math.max(1, Math.floor(options.maxTurns));
+    }
+    /** Queue the brief as the first frame. Once, before the process is attached. */
+    begin(brief, uuid = randomUUID()) {
+        if (this.#begun)
+            throw new Error("a live session's brief is sent once");
+        this.#begun = true;
+        this.briefUuid = uuid;
+        this.#turnActive = true;
+        this.#write(userFrame(brief, uuid));
+    }
+    /** The transport spawned the child with stdin piped: write what is queued, brief first. */
+    attach(io) {
+        if (this.#io !== null || this.#closed)
+            return;
+        this.#io = io;
+        const pending = this.#pending;
+        this.#pending = [];
+        for (const line of pending)
+            if (!this.#raw(line))
+                return;
+        try {
+            this.#options.onOpen?.();
+        }
+        catch { /* display state never touches the session */ }
+    }
+    /** stdin is attached and still open: a note reaches the agent in seconds, and a Pause can stop its turn. */
+    get open() {
+        return this.#io !== null && !this.#closed;
+    }
+    get paused() {
+        return this.#paused;
+    }
+    /** Distinct assistant turns so far, across every message. */
+    get turns() {
+        return this.#turns.size;
+    }
+    /** Why stdin closed, once it has. */
+    get closeReason() {
+        return this.#closeReason;
+    }
+    /**
+     * Send a note (or anything the session should read next). A paused session continues. False once stdin is closed.
+     * Mid-turn, the harness folds it into the running turn; after an interrupt that turn is over, so the frame starts a
+     * turn of its own whose result is owed before stdin closes.
+     */
+    send(text, uuid) {
+        if (!this.open)
+            return false;
+        if (!this.#write(userFrame(text, uuid)))
+            return false;
+        if (this.#turnActive && this.#interrupts.size > 0)
+            this.#owed = true;
+        this.#paused = false;
+        this.#turnActive = true;
+        return true;
+    }
+    /** Resume a paused session with a short continue frame and no note. "not-paused" when nothing waits to go on. */
+    resume(uuid) {
+        if (!this.open)
+            return "closed";
+        if (!this.#paused)
+            return "not-paused";
+        return this.send(CONTINUE_TEXT, uuid) ? "sent" : "closed";
+    }
+    /**
+     * The transport's idle limit was reached. A paused session closes stdin instead of being killed — the harness exits
+     * and the build settles from whatever handoff it saved — and true asks the watchdog to wait once more for that exit.
+     * Anything else is an ordinary idle timeout.
+     */
+    idleLimit() {
+        if (!this.open || !this.#paused)
+            return false;
+        this.close("paused-idle");
+        return true;
+    }
+    /**
+     * Pause: stop the current turn, keep the session. "sent" when an interrupt was written; "idle" when no turn was
+     * running (the session is already waiting, so it is paused as it stands); "closed" when stdin is gone.
+     */
+    interrupt(requestId) {
+        if (!this.open)
+            return "closed";
+        this.#paused = true;
+        if (!this.#turnActive)
+            return "idle";
+        if (!this.#write(interruptFrame(requestId)))
+            return "closed";
+        this.#interrupts.add(requestId);
+        return "sent";
+    }
+    /** Every parsed stdout event, in order. */
+    observe(event) {
+        const type = String(event["type"] ?? "");
+        if (type === "assistant" && topLevel(event)) {
+            this.#turnActive = true;
+            const message = event["message"];
+            const id = typeof message?.["id"] === "string" ? message["id"] : `turn-${this.#turns.size + 1}`;
+            this.#turns.add(id);
+            if (this.#turns.size > this.maxTurns && this.open) {
+                // The total is spent once a turn past it starts: the last allowed turn ran in full, tools and all. Stop this
+                // one, then let the process finish on its own; settlement reads the handoff (closeReason).
+                // cancel_queued: a note already queued must not start a turn past the budget after stdin closes.
+                this.#write(interruptFrame(`budget-${randomUUID()}`, true));
+                this.close("turn-budget");
+            }
+        }
+        else if (type === "control_response") {
+            const response = event["response"];
+            const requestId = typeof response?.["request_id"] === "string" ? response["request_id"] : null;
+            if (requestId !== null && this.#interrupts.has(requestId) && response?.["subtype"] === "success" && this.#paused)
+                this.#notifyPaused();
+        }
+        else if (type === "result" && primaryResult(event)) {
+            this.#turnActive = false;
+            this.#interrupts.clear();
+            if (this.#paused) {
+                // A paused session waits for the next note; the idle watchdog still bounds the wait.
+                this.#notifyPaused();
+                return;
+            }
+            // A frame written after this turn was interrupted starts a turn of its own: wait for its result.
+            if (this.#owed) {
+                this.#owed = false;
+                return;
+            }
+            let finished = false;
+            try {
+                finished = this.#options.finished?.() === true;
+            }
+            catch {
+                finished = false;
+            }
+            this.close(finished ? "finished" : "settled");
+        }
+    }
+    /** Close stdin: the harness finishes what it has and exits. Further sends refuse. */
+    close(why) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#closeReason = why;
+        this.#paused = false;
+        if (this.#io !== null) {
+            try {
+                this.#io.end();
+            }
+            catch { /* already gone */ }
+        }
+        try {
+            this.#options.onClose?.(why);
+        }
+        catch { /* display state never touches the session */ }
+    }
+    /** The process ended (or its stdin failed): nothing more is written. */
+    detach(why = "ended") {
+        const closedAlready = this.#closed;
+        this.#closed = true;
+        if (!closedAlready)
+            this.#closeReason = why;
+        this.#paused = false;
+        this.#io = null;
+        if (!closedAlready) {
+            try {
+                this.#options.onClose?.(why);
+            }
+            catch { /* display state never touches the session */ }
+        }
+    }
+    #notifyPaused() {
+        try {
+            this.#options.onPaused?.();
+        }
+        catch { /* display state never touches the session */ }
+    }
+    #write(line) {
+        if (this.#closed)
+            return false;
+        if (this.#io === null) {
+            this.#pending.push(line);
+            return true;
+        }
+        return this.#raw(line);
+    }
+    #raw(line) {
+        try {
+            this.#io.write(`${line}\n`);
+            return true;
+        }
+        catch {
+            this.detach("input-failed");
+            return false;
+        }
+    }
+}

package/dist/live.d.ts

@@ -46,7 +46,7 @@ export declare function liveActivityKind(event: Record<string, unknown>): LiveAc
  * chatter — renders nothing in v1.
  */
 export declare function renderTranscriptLines(event: Record<string, unknown>): string[];
-/** Sanitize one display line: strip, redact whole on any secret hit, cap. */
+/** Sanitize one display line: strip controls and bidi overrides, redact whole on any secret hit, cap. */
 export declare function sanitizeTranscriptLine(line: string): string;
 export type LiveLog = {
     observe(event: Record<string, unknown>): void;

package/dist/live.js

@@ -190,9 +190,11 @@ export function renderTranscriptLines(event) {
     }
     return lines;
 }
-/** Sanitize one display line: strip, redact whole on any secret hit, cap. */
+/** Bidirectional overrides and isolates (U+202A–U+202E, U+2066–U+2069): they can make shown text read differently from what was written. */
+const BIDI_CONTROLS = /[\u202a-\u202e\u2066-\u2069]/g;
+/** Sanitize one display line: strip controls and bidi overrides, redact whole on any secret hit, cap. */
 export function sanitizeTranscriptLine(line) {
-    const stripped = stripControls(line);
+    const stripped = stripControls(line).replace(BIDI_CONTROLS, "");
     if (scanForSecrets(stripped).length > 0)
         return LIVE_REDACTED_LINE;
     return capBytes(stripped, LIVE_LINE_CAP);

package/dist/maintenance.d.ts

@@ -5,6 +5,8 @@ export declare function startMaintenance(args: {
     run: () => Promise<void>;
     shouldStop: () => boolean;
     onError: (error: unknown) => void;
+    /** Synchronously cancel owned background work before waiting for the current pass. */
+    onStop?: () => void;
 }): {
     runNow: () => Promise<void>;
     stop: () => Promise<void>;

package/dist/maintenance.js

@@ -27,8 +27,11 @@ export function startMaintenance(args) {
     return {
         runNow,
         stop: async () => {
-            stopped = true;
-            clearInterval(timer);
+            if (!stopped) {
+                stopped = true;
+                clearInterval(timer);
+                args.onStop?.();
+            }
             await pending;
         },
     };

package/dist/operate-remote-arguments.js

@@ -29,7 +29,11 @@ export const REMOTE_ARGUMENTS = new Map([
     ['task block', args('id:task', 'key', { on: 'task' })],
     ['task unblock', args('id:task', 'key', { on: 'task' })],
     ['task next', args('id:task', 'key undo')],
-    ['task steer', args('id:task', 'note')],
+    // Live steering: --now pauses the running Claude build first; pause and continue name the exact attempt like stop and
+    // resume, and a repeated --request (or --key) id is the same request.
+    ['task steer', args('id:task', 'note now request key', { run: 'run' })],
+    ['task pause', args('id:task', 'request key', { run: 'run' })],
+    ['task continue', args('id:task', 'request key', { run: 'run' })],
     ['task assign', args('id:task', 'key runner anyone')],
     ['task scope', args('id:task', 'key goal not touches budget-usd risk acceptance candidate model provider repair-model')],
     ['task plan', args('id:task', 'key provider model')],

package/dist/operate-remote.js

@@ -37,7 +37,7 @@ const references = { kind: "references" }, listing = { kind: "listing" };
 export const REMOTE_SCOPES = new Map([
     ["status", listing], ["integrations", installation], ["ready", listing], ["grants", installation], ["sync", installation],
     ["gaps", repo], ["task add", repo],
-    ...["ask", "checks", "add-tests", "show", "wait", "complete", "revise", "state", "block", "unblock", "next", "steer", "assign", "scope", "plan", "hold",
+    ...["ask", "checks", "add-tests", "show", "wait", "complete", "revise", "state", "block", "unblock", "next", "steer", "pause", "continue", "assign", "scope", "plan", "hold",
         "unhold", "require", "requeue", "review", "repair", "route", "reopen", "stop", "resume"].map(action => [`task ${action}`, references]),
     ["check-progress", references],
     ["task list", listing],

package/dist/operate.d.ts

@@ -102,7 +102,7 @@ type Args = {
  * exports are behavior, not commentary — and the declared command guide
  * (surface.ts) is tested for exact equality against them.
  */
-export declare const TASK_ACTIONS: readonly ["add", "list", "show", "wait", "state", "block", "unblock", "next", "steer", "assign", "reopen", "scope", "approve", "hold", "unhold", "require", "requeue", "regate", "plan", "review", "accept", "repair", "route", "stop", "resume", "complete", "revise", "merge", "ask", "checks", "add-tests"];
+export declare const TASK_ACTIONS: readonly ["add", "list", "show", "wait", "state", "block", "unblock", "next", "steer", "pause", "continue", "assign", "reopen", "scope", "approve", "hold", "unhold", "require", "requeue", "regate", "plan", "review", "accept", "repair", "route", "stop", "resume", "complete", "revise", "merge", "ask", "checks", "add-tests"];
 export declare const PUBLISH_ACTIONS: readonly ["setup", "grant", "revoke", "status", "unblock", "rearm", "merge", "refire"];
 export declare const CONFIG_ACTIONS: readonly ["show", "set", "clear"];
 export declare const APPROVER_ACTIONS: readonly ["list", "add"];