@chrok/pi-braid 0.3.6 → 0.5.0

package/dist/drain.js

@@ -0,0 +1,171 @@
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { defineTool, } from "@earendil-works/pi-coding-agent";
+/** Pi exits once print and JSON runs settle, so Braid drains jobs before that. */
+export const isSingleShot = (ctx) => ctx.mode === "print" || ctx.mode === "json";
+export const BRAID_DRAIN_GUIDANCE = "This is a single-shot run. It stays open until every Braid job finishes and its reminder is delivered, so submit, end your turn, and continue from the reminder as usual. " +
+    "Paused executions and paused jobs are not resumed automatically: resume or cancel them before ending your turn. If only paused work remains when you end a turn, you get one warning; ending the next turn without resuming it cancels those jobs and the run exits with a failure status.";
+export const BRAID_FINISH_GUIDANCE = "When the task is done and no Braid job is outstanding, call braid_finish once with status success or failure and a short summary of the outcome, then end your turn with your final response. " +
+    "A failure status makes the run exit 1. braid_finish only records the outcome: the run still ends when your turn ends and every Braid job has finished. Call it again to replace the outcome if more work follows.";
+/** The run's wall-clock budget is checked by a timer, so the drain also wakes periodically. */
+const RECHECK_MS = 1_000;
+export function parseDuration(value) {
+    const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h)?\s*$/.exec(value);
+    const scale = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000 };
+    const ms = match ? Number(match[1]) * scale[(match[2] ?? "ms")] : NaN;
+    if (!(ms > 0) || ms > 2_147_483_647)
+        throw new Error(`Invalid --braid-ci-timeout ${JSON.stringify(value)}: use a positive duration such as 90000, 90s, 30m, or 2h`);
+    return ms;
+}
+const waitingOn = (job) => [
+    job.pausedExecutionIds.length ? `paused executions ${JSON.stringify(job.pausedExecutionIds)}` : "",
+    job.suspendedExecutionIds.length ? `suspended executions ${JSON.stringify(job.suspendedExecutionIds)}` +
+        (job.timedOutExecutionIds?.length ? ` (paused by their node timeout: ${JSON.stringify(job.timedOutExecutionIds)})` : "") : "",
+    job.paused ? "its job pause" : "",
+].filter(Boolean).join(" and ") || "paused work";
+const stalledReminder = (jobs) => `[system-reminder] This single-shot run cannot end while Braid jobs are outstanding, and nothing can progress: ` +
+    jobs.map(job => `${job.handle} is waiting on ${waitingOn(job)} at revision ${job.revision}`).join("; ") +
+    `. Resume executions with braid_resume or braid_update with resume, resume a paused job with braid_resume({jobId}), fail single executions with braid_cancel and executionIds, or cancel the job with braid_cancel, then continue the original task. ` +
+    `If you end your turn again without doing so, Braid cancels these jobs and the run exits with a failure status. [/system-reminder]`;
+/**
+ * Keeps print and JSON runs alive until every Braid job reaches a terminal
+ * status. Reminders are steered into the run as in interactive mode, so the
+ * parent keeps the async model: it ends its turn and the reminder resumes it.
+ */
+export function registerDrain(pi, jobs, hasPendingReminders) {
+    pi.registerFlag("braid-ci-timeout", {
+        description: "Wall-clock budget for Braid jobs in print/JSON mode (e.g. 90000, 90s, 30m, 2h); on expiry, outstanding jobs are cancelled and the run exits 1",
+        type: "string",
+    });
+    let closed = false;
+    let timer;
+    let timedOut = false;
+    let warnedStall;
+    const failures = new Set();
+    let outcome;
+    let reported;
+    const fail = (reason) => {
+        if (failures.has(reason))
+            return;
+        failures.add(reason);
+        process.exitCode = 1;
+        console.error(`Braid: ${reason}`);
+    };
+    const cancelOutstanding = (reason) => {
+        const outstanding = jobs.outstanding();
+        if (!outstanding.length)
+            return;
+        fail(reason);
+        for (const job of outstanding)
+            jobs.cancel(job.jobId);
+    };
+    const expire = () => {
+        timedOut = true;
+        cancelOutstanding("--braid-ci-timeout expired; cancelled outstanding Braid jobs");
+    };
+    const nextChange = () => new Promise(resolve => {
+        const done = () => {
+            clearTimeout(tick);
+            unsubscribe();
+            resolve();
+        };
+        const tick = setTimeout(done, RECHECK_MS);
+        const unsubscribe = jobs.subscribe(done);
+    });
+    const finishParameters = Type.Object({
+        status: StringEnum(["success", "failure"], { description: "Whether the run achieved its task. failure makes the process exit 1." }),
+        summary: Type.String({ minLength: 1, description: "Short summary of the outcome for CI logs and JSON output." }),
+    }, { additionalProperties: false });
+    pi.registerTool(defineTool({
+        name: "braid_finish",
+        label: "Finish Braid run",
+        description: "Single-shot (print/JSON) runs only: record the run outcome for CI. status failure makes the process exit 1. " +
+            "It does not end the run; call it once the task is done and no Braid job is outstanding, then end your turn. A later call replaces the outcome.",
+        parameters: finishParameters,
+        // Activated in single-shot sessions only, so interactive runs never see it.
+        defaultActive: false,
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            if (!isSingleShot(ctx))
+                throw new Error("braid_finish is only available in print and JSON runs");
+            outcome = { status: params.status, summary: params.summary };
+            const outstanding = jobs.outstanding().length;
+            return {
+                content: [{
+                        type: "text",
+                        text: `Recorded ${params.status}.` + (outstanding
+                            ? ` ${outstanding} Braid job(s) are still outstanding; the run stays open until they finish, so continue from their reminders and call braid_finish again if the outcome changes.`
+                            : " End your turn with your final response."),
+                    }],
+                details: outcome,
+            };
+        },
+    }));
+    /** Applies the reported outcome once the run is about to settle with nothing outstanding. */
+    const settle = (event) => {
+        if (!outcome || outcome === reported)
+            return;
+        reported = outcome;
+        // Never reset the exit code: success must not mask a forced cancellation or a Pi error.
+        if (outcome.status === "failure") {
+            process.exitCode = 1;
+            console.error(`Braid: run reported failure: ${outcome.summary}`);
+        }
+        // A custom entry is not model context and leaves the final assistant message last,
+        // so text output is unchanged; JSON mode streams it as an entry_appended event.
+        return {
+            entries: [...event.entries, {
+                    type: "custom",
+                    customType: "braid-finish",
+                    data: { ...outcome, forcedFailures: [...failures] },
+                }],
+        };
+    };
+    pi.on("session_start", (_event, ctx) => {
+        if (isSingleShot(ctx) && !pi.getActiveTools().includes("braid_finish"))
+            pi.setActiveTools([...pi.getActiveTools(), "braid_finish"]);
+    });
+    pi.on("before_agent_start", (_event, ctx) => {
+        const budget = pi.getFlag("braid-ci-timeout");
+        if (timer || timedOut || !isSingleShot(ctx) || typeof budget !== "string")
+            return;
+        // The budget covers the whole run, starting at its first prompt.
+        timer = setTimeout(expire, parseDuration(budget));
+        timer.unref();
+    });
+    pi.on("agent_before_settle", async (event, ctx) => {
+        if (!isSingleShot(ctx))
+            return;
+        while (!closed) {
+            // A queued reminder continues this run; Pi settles only when its queues are empty.
+            if (hasPendingReminders())
+                return;
+            if (timedOut)
+                cancelOutstanding("--braid-ci-timeout expired; cancelled outstanding Braid jobs");
+            const outstanding = jobs.outstanding();
+            if (!outstanding.length)
+                return settle(event);
+            if (outstanding.every(job => job.stalled)) {
+                const key = JSON.stringify(outstanding.map(job => [job.jobId, job.revision, job.pausedExecutionIds, job.suspendedExecutionIds, job.paused]));
+                if (key !== warnedStall) {
+                    warnedStall = key;
+                    return {
+                        entries: [...event.entries, {
+                                type: "custom_message",
+                                customType: "braid-drain-stalled",
+                                display: true,
+                                content: stalledReminder(outstanding),
+                                details: { jobs: outstanding },
+                            }],
+                        continue: true,
+                    };
+                }
+                // Cancellation reminders give the parent a final turn to report the outcome.
+                cancelOutstanding(`paused work was never resumed; cancelled ${outstanding.map(job => job.handle).join(", ")}`);
+            }
+            await nextChange();
+        }
+    });
+    pi.on("session_shutdown", () => {
+        closed = true;
+        clearTimeout(timer);
+    });
+}

package/dist/index.js

@@ -7,8 +7,9 @@ import { Text } from "@earendil-works/pi-tui";
 import { BraidJobs } from "./jobs.js";
 import { registerBraidCommand, registerBraidWidget } from "./command.js";
 import { registerReviewCommand } from "./review.js";
+import { BRAID_DRAIN_GUIDANCE, BRAID_FINISH_GUIDANCE, isSingleShot, registerDrain } from "./drain.js";
 import { renderGraphCall, renderGraphResult, renderNodeResult } from "./display.js";
-import { formatJobList, formatJobStatus, formatNodeStatus, formatReceipt, formatResume, formatUpdate } from "./status-text.js";
+import { formatCancelExecutions, formatHold, formatJobList, formatJobStatus, formatNodeStatus, formatPause, formatReceipt, formatResume, formatTimeoutPause, formatUpdate } from "./status-text.js";
 const text = (description) => Type.String({ minLength: 1, pattern: "\\S", ...(description ? { description } : {}) });
 const prompt = () => Type.Union([
     text("Instructions for this node; it does not receive the parent conversation."),
@@ -24,7 +25,12 @@ const timeout = (scope) => Type.Optional(Type.Number({
     maximum: 2_147_483_647,
     description: scope === "graph"
         ? "Total wall-clock timeout in milliseconds, including queueing and pauses. Updates/resume do not reset it; reserve time for final integration. Omit for no time limit."
-        : "Timeout in milliseconds per node execution; omit for no time limit.",
+        : "Active time in milliseconds per node execution, excluding pauses; omit for no time limit. See onNodeTimeout for what happens when it runs out.",
+}));
+const resumeTimeout = Type.Optional(Type.Number({
+    exclusiveMinimum: 0,
+    maximum: 2_147_483_647,
+    description: "New node time budget in milliseconds for the suspended executions, counted from when each continues. Default: a node timeout pause gets the job's nodeTimeoutMs again; other pauses keep their remaining budget.",
 }));
 const toolBudget = (unit) => Type.Optional(Type.Integer({
     minimum: 1,
@@ -34,8 +40,8 @@ const toolBudget = (unit) => Type.Optional(Type.Integer({
 const commonNodeParameters = {
     id: text("Unique node definition ID; edges refer to this exact ID. This is not an executionId."),
     model: Type.Optional(text("Model override as provider/model-id; omit to use the parent model.")),
-    notifyOnCompletion: Type.Optional(Type.Boolean({ description: "In background mode, send an execution completion reminder; default false. Does not pause scheduling." })),
-    pauseAfter: Type.Optional(Type.Boolean({ description: "Background mode only: hold this execution's outgoing dependencies until braid_resume or an atomic braid_update with resume. Sends a pause reminder." })),
+    notifyOnCompletion: Type.Optional(Type.Boolean({ description: "Send an execution completion reminder; default false. Does not pause scheduling." })),
+    pauseAfter: Type.Optional(Type.Boolean({ description: "Hold this execution's outgoing dependencies until braid_resume or an atomic braid_update with resume. Sends a pause reminder." })),
     requireSuccess: Type.Optional(Type.Boolean({ description: "If true, failure aborts the entire job and cancels running siblings. Default false: unconditional successors can recover." })),
 };
 const workspace = Type.Optional(StringEnum(["read-only", "worktree"], {
@@ -84,6 +90,8 @@ const braidParameters = Type.Object({
         maxConcurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum simultaneous node executions; default 4." })),
         maxExecutions: Type.Optional(Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER, description: "Total execution limit across all iterations and updates; default 1000." })),
         nodeTimeoutMs: timeout("node"), graphTimeoutMs: timeout("graph"), maxToolRounds: toolBudget("rounds"), maxToolCalls: toolBudget("calls"),
+        onNodeTimeout: Type.Optional(StringEnum(["pause", "fail"], { description: "What a node timeout does. pause (default): interrupt the current step and suspend the execution with its work, and send you a reminder to resume it with a new time budget or cancel it. fail: the execution fails with NODE_TIMEOUT." })),
+        maxModelRetries: Type.Optional(Type.Integer({ minimum: 0, maximum: 10, description: "Retries per model request for transient provider errors such as rate limits, overload, and network failures. The node continues where it was; completed tool calls are not repeated. Default 3; 0 disables." })),
     }, { additionalProperties: false })),
 }, { additionalProperties: false });
 const BRAID_FILESYSTEM_GUIDANCE = "Every execute/decision activation gets a fresh worktree in Git, based on its predecessor execution checkpoint (roots use the initial job snapshot). Set workspace=read-only to disable writes. Multiple independent code snapshots require an explicit merge node. " +
@@ -91,18 +99,19 @@ const BRAID_FILESYSTEM_GUIDANCE = "Every execute/decision activation gets a fres
     "Do not set workspace on merge/integrate nodes. Checkpoints remain recoverable after cleanup. Optional failed predecessors pass errors and partial work along unconditional edges; requireSuccess=true makes failure abort the job. " +
     "Nodes have local read/ls and Git inspection; writable nodes have write/edit and Pi shell tools for dependencies, builds, and tests, while merge/integrate also have local Git integration tools. Search tools require local rg/fd. Outside Git all filesystem access is read-only; read-only nodes have no shell. Worktrees are not an OS sandbox: prompts constrain shell writes and shared resources. Checkpoints omit ignored new files. Parent extension/MCP tools and recursive Braid calls are not provided. Nodes should verify their changes; the parent reviews results and performs any remaining validation after integration.";
 /** Lifecycle guidance shared by the system prompt and tool descriptions. */
-export const BRAID_ASYNC_GUIDANCE = "By default, Braid is asynchronous: braid returns a jobId immediately and the job keeps running independently of the foreground response; ending your turn does not cancel it. " +
+export const BRAID_ASYNC_GUIDANCE = "Braid is asynchronous: braid returns a jobId immediately and the job keeps running independently of the foreground response; ending your turn does not cancel it. " +
     "Completion, failure, or cancellation sends a reminder: an idle agent is resumed automatically, and a running agent receives it at the next model step. " +
     "After submitting, continue useful independent work. If nothing else can proceed until the result arrives, end your turn and let the reminder resume the task. " +
     "Do not call sleep, run a shell sleep, use a timer, or enter a sleep/poll loop solely to wait for a Braid job; delays required by the user's actual task remain allowed. " +
     "On the reminder, retrieve terminal outputs with braid_status before relying on them and continue the original task. Between reminders, use braid_status only for deliberate progress checks or diagnosis. " +
-    "Set notifyOnCompletion=true on selected nodes to receive intermediate success/failure reminders. Use braid_status({jobId, executionId}) to retrieve the exact execution; nodeId selects the latest instance. Use pauseAfter=true to hold outgoing scheduling. Definitions can always be changed with braid_update using expectedRevision; existing executions retain their captured inputs. Use resume in the same update to apply changes and release held executions atomically, or braid_resume for no graph changes.";
+    "Set notifyOnCompletion=true on selected nodes to receive intermediate success/failure reminders. Use braid_status({jobId, executionId}) to retrieve the exact execution; nodeId selects the latest instance. Use pauseAfter=true to hold outgoing scheduling. Definitions can always be changed with braid_update using expectedRevision; existing executions retain their captured inputs. Use resume in the same update to apply changes and release held executions atomically, or braid_resume for no graph changes. " +
+    "Use braid_pause to stop running executions temporarily (each stops before its next model request and keeps its conversation and workspace), or the whole job; send them a message or adjust the graph, then resume. " +
+    "pauseAfter is captured when an execution starts; to review a running execution's result before downstream work starts, use braid_pause({jobId, executionIds, after: true}) instead, and braid_resume({jobId, executionIds, after: true}) removes that hold. " +
+    "The user can also pause and resume from /braid; you get a notice with your next turn. Do not resume work the user paused unless the user asks. " +
+    "When an execution exceeds its nodeTimeoutMs it is paused, not failed, and you get a reminder: resume it with braid_resume (optionally a new nodeTimeoutMs), or fail only that execution with braid_cancel and executionIds.";
 /** Short reminder repeated in every submission receipt. */
 export const BRAID_WAIT_REMINDER = "Braid runs asynchronously and notifies you when the job finishes. Continue independent work, or end your turn if you need the result before proceeding; the completion reminder will resume you. " +
     "Do not sleep or poll in a loop to wait for this job. Retrieve its results with braid_status after the reminder.";
-const BRAID_BLOCKING_GUIDANCE = "In blocking mode (enabled by --braid-blocking or /braid:blocking on), braid waits for the entire graph and workspace cleanup, then returns final status, outputs, and usage directly. " +
-    "Foreground cancellation cancels the submitted job and waits for cleanup. Completion reminders are suppressed unless the job is cancelled; cancellation reminders preserve its handle and access to partial results. " +
-    "Do not set pauseAfter=true in blocking mode: it requires a later resume call and is rejected. Use braid_status for focused reads, diagnosis, or retrieving an existing job after cancellation or a wait/result error.";
 const BRAID_USAGE_GUIDANCE = [
     "Braid is a proactive execution primitive, not only a user-requested command.",
     "Selection rule: for a code review, bug investigation, design comparison, test-planning request, or change spanning multiple files, call braid FIRST when two or more concerns can be handled independently. Nodes can analyze the project and implement changes in isolated Git worktrees. Do this without waiting for the user to say Braid; do not read everything in the parent and then decide whether to delegate.",
@@ -133,7 +142,7 @@ async function boundedText(text, name) {
     await writeFile(path, text, { mode: 0o600 });
     return { text: `${preview.content}\n[Truncated. Full text: ${path}]`, path };
 }
-export function createBraidTools(jobs, blocking = () => false) {
+export function createBraidTools(jobs) {
     const braidTool = defineTool({
         name: "braid",
         label: "Braid",
@@ -158,7 +167,7 @@ export function createBraidTools(jobs, blocking = () => false) {
             "Do not use braid for simple one-step answers or trivial direct edits. Let writable nodes run shell commands and tests for their work; use merge nodes to combine and validate snapshots before explicit integration.",
             BRAID_FILESYSTEM_GUIDANCE,
             "Decision nodes additionally receive decide. Nodes cannot call recursive Braid.",
-            "Tool and time budgets are unlimited by default. Set maxToolRounds, maxToolCalls, nodeTimeoutMs, or graphTimeoutMs in options to impose hard limits; nodes receive system reminders of their remaining budgets before each model call.",
+            "Tool and time budgets are unlimited by default. Set maxToolRounds, maxToolCalls, nodeTimeoutMs, or graphTimeoutMs in options to impose hard limits; nodes receive system reminders of their remaining budgets before each model call. By default a node timeout pauses the execution instead of failing it, and you get a reminder to resume or cancel it; set onNodeTimeout=fail to fail it instead.",
         ],
         parameters: braidParameters,
         renderCall(args, theme) {
@@ -178,9 +187,8 @@ export function createBraidTools(jobs, blocking = () => false) {
                 return statusTool.renderResult(result, options, theme, { ...ctx, args: { jobId: job.jobId } });
             return new Text(theme.fg("accent", `Braid ${options.isPartial ? "job" : "background job"} ${job.handle ?? job.jobId} · ${job.status} · /braid to view${job.error ? `\n${job.error}` : ""}`), 0, 0);
         },
-        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
             signal?.throwIfAborted();
-            const waitForCompletion = blocking();
             let job;
             try {
                 job = jobs.start({
@@ -189,42 +197,17 @@ export function createBraidTools(jobs, blocking = () => false) {
                     edges: params.edges,
                     ...(params.loops !== undefined ? { loops: params.loops } : {}),
                     ...(params.promptTemplates !== undefined ? { promptTemplates: params.promptTemplates } : {}),
-                }, params.options ?? {}, ctx, waitForCompletion);
+                }, 
+                // StringEnum is typed as string; the schema has already checked the value.
+                (params.options ?? {}), ctx);
             }
             catch (error) {
                 throw new Error(`Braid submission failed: ${error instanceof Error ? error.message : String(error)}`);
             }
-            if (!waitForCompletion)
-                return {
-                    content: [{ type: "text", text: formatReceipt(job, `${BRAID_WAIT_REMINDER} Humans can follow it live in /braid.`) }],
-                    details: job,
-                };
-            const cancel = () => { jobs.cancel(job.jobId); };
-            signal?.addEventListener("abort", cancel, { once: true });
-            try {
-                try {
-                    onUpdate?.({
-                        content: [{ type: "text", text: formatReceipt(job, "Waiting for the graph and workspace cleanup. Humans can follow it live in /braid.") }],
-                        details: job,
-                    });
-                }
-                catch { /* Progress observers must not stop the foreground wait. */ }
-                await jobs.wait(job.jobId);
-                return await statusTool.execute(_toolCallId, { jobId: job.jobId }, signal, undefined, ctx);
-            }
-            catch (error) {
-                const current = jobs.get(job.jobId);
-                const usage = current.status === "running" || signal?.aborted ? undefined : jobs.claimUsage(job.jobId);
-                return {
-                    content: [{ type: "text", text: `Braid job ${job.handle} was started and is ${current.status}. Could not wait for or retrieve its results: ${error instanceof Error ? error.message : String(error)}. Do not resubmit this graph: it may already have changed the checkout. Retrieve the existing job with braid_status(${JSON.stringify({ jobId: job.handle })}).` }],
-                    details: current,
-                    isError: true,
-                    ...(usage ? { usage } : {}),
-                };
-            }
-            finally {
-                signal?.removeEventListener("abort", cancel);
-            }
+            return {
+                content: [{ type: "text", text: formatReceipt(job, `${BRAID_WAIT_REMINDER} Humans can follow it live in /braid.`) }],
+                details: job,
+            };
         },
     });
     const statusParameters = Type.Object({
@@ -305,13 +288,20 @@ export function createBraidTools(jobs, blocking = () => false) {
             };
         },
     });
-    const cancelParameters = Type.Object({ jobId: text("Exact session handle (e.g. job-1) or UUID returned by braid or braid_status.") }, { additionalProperties: false });
+    const cancelParameters = Type.Object({
+        jobId: text("Exact session handle (e.g. job-1) or UUID returned by braid or braid_status."),
+        executionIds: Type.Optional(Type.Array(text(), { minItems: 1, uniqueItems: true, description: "Running or paused execution IDs from braid_status, not node IDs. Cancels only these executions; omit to cancel the whole job." })),
+    }, { additionalProperties: false });
     const cancelTool = defineTool({
         name: "braid_cancel",
         label: "Cancel Braid",
-        description: "Cancel a background Braid job by jobId. Stopping the foreground response does not cancel background jobs.",
+        description: "Cancel a background Braid job by jobId. Stopping the foreground response does not cancel background jobs. With executionIds, fail only those running or paused executions and keep the job running: their successors follow the usual failure rules (unconditional edges receive the error; requireSuccess aborts the job). A node timeout pause fails with NODE_TIMEOUT, anything else with CANCELLED.",
         parameters: cancelParameters,
         async execute(_id, params) {
+            if (params.executionIds) {
+                const job = jobs.cancelExecutions(params.jobId, params.executionIds, "agent");
+                return { content: [{ type: "text", text: formatCancelExecutions(job, params.executionIds) }], details: job };
+            }
             const cancelled = jobs.cancel(params.jobId);
             return {
                 content: [
@@ -335,7 +325,8 @@ export function createBraidTools(jobs, blocking = () => false) {
         removeEdges: Type.Optional(Type.Array(updateEdgeParameters, { description: "Exact edge identities to remove: copy from, to, and every present choice/feedback/executionId from the current graph edges in braid_status. Omitted optional fields do not act as wildcards." })),
         promptTemplates: Type.Optional(Type.Record(Type.String(), text(), { description: `${templateDescription} Replaces the entire template map; omit to preserve it. Include every template still referenced by nodes.` })),
         loops: Type.Optional(Type.Array(loopParameters, { description: "Replaces all loop definitions; omit to preserve them, or use [] to remove all (also remove their feedback edges)." })),
-        resume: Type.Optional(Type.Array(text(), { uniqueItems: true, description: "Paused execution IDs from braid_status, not node IDs. Releases them atomically with the graph edit." })),
+        resume: Type.Optional(Type.Array(text(), { uniqueItems: true, description: "Paused or suspended execution IDs from braid_status, not node IDs. Releases them atomically with the graph edit." })),
+        resumeOptions: Type.Optional(Type.Object({ nodeTimeoutMs: resumeTimeout }, { additionalProperties: false, description: "Requires resume. Applies to the suspended executions in resume." })),
     }, { additionalProperties: false });
     const updateTool = defineTool({
         name: "braid_update", label: "Update Braid",
@@ -355,39 +346,83 @@ export function createBraidTools(jobs, blocking = () => false) {
     });
     const resumeParameters = Type.Object({
         jobId: text("Exact session handle (e.g. job-1) or UUID."),
-        expectedRevision: Type.Integer({ minimum: 0, description: "Current graph revision from braid_status." }),
-        executionIds: Type.Array(text(), { minItems: 1, uniqueItems: true, description: "Paused execution IDs from braid_status, not node IDs. Only these completed, paused executions are released." }),
+        expectedRevision: Type.Optional(Type.Integer({ minimum: 0, description: "Current graph revision from braid_status. Required with executionIds." })),
+        executionIds: Type.Optional(Type.Array(text(), { minItems: 1, uniqueItems: true, description: "Paused (pauseAfter) or suspended execution IDs from braid_status, not node IDs. Omit to resume a paused job." })),
+        after: Type.Optional(Type.Boolean({ description: "true: remove the hold that braid_pause after=true or pauseAfter put on these still-running executions, so their results go downstream when they finish. Requires executionIds; expectedRevision is not needed. A result that is already held is released without after." })),
+        nodeTimeoutMs: resumeTimeout,
     }, { additionalProperties: false });
     const resumeTool = defineTool({
         name: "braid_resume", label: "Resume Braid",
-        description: "Release specific paused execution IDs using expectedRevision from braid_status. Independent branches keep running during a pause; this does not reset deadlines or execution limits.",
+        description: "Release paused (pauseAfter) executions, or resume suspended ones in the same conversation, by execution ID with expectedRevision from braid_status. Omit executionIds to resume a job paused with braid_pause; executions you paused separately stay suspended. Independent branches keep running during a pause; this does not reset the graph deadline or execution limits. An execution paused by its node timeout gets the job's nodeTimeoutMs again, or nodeTimeoutMs if given; resuming the job does not resume it. With after=true it instead removes the hold on still-running executions. Do not resume work the user paused or held unless the user asks.",
         parameters: resumeParameters,
         async execute(_id, params) {
-            const job = jobs.resume(params.jobId, params.executionIds, params.expectedRevision);
+            if (params.after) {
+                if (params.nodeTimeoutMs !== undefined)
+                    throw new Error("nodeTimeoutMs cannot be combined with after");
+                const job = hold(params.jobId, params.executionIds, false);
+                return { content: [{ type: "text", text: formatHold(job, params.executionIds, false) }], details: job };
+            }
+            if (!params.executionIds) {
+                if (params.nodeTimeoutMs !== undefined)
+                    throw new Error("nodeTimeoutMs requires executionIds");
+                return { content: [{ type: "text", text: formatResume(jobs.resumeJob(params.jobId)) }], details: jobs.get(params.jobId) };
+            }
+            if (params.expectedRevision === undefined)
+                throw new Error("expectedRevision is required with executionIds; read it from braid_status");
+            const job = jobs.resume(params.jobId, params.executionIds, params.expectedRevision, "agent", params.nodeTimeoutMs === undefined ? undefined : { nodeTimeoutMs: params.nodeTimeoutMs });
             return { content: [{ type: "text", text: formatResume(job) }], details: job };
         },
     });
-    return { braidTool, statusTool, cancelTool, updateTool, resumeTool };
-}
-export default function braidExtension(pi) {
-    pi.registerFlag("braid-blocking", {
-        description: "Experimental: wait for braid tool calls to finish in the foreground (for CI/print mode)",
-        type: "boolean",
-        default: false,
-    });
-    let sessionBlocking;
-    const blocking = () => sessionBlocking ?? (pi.getFlag("braid-blocking") === true);
-    pi.registerCommand("braid:blocking", {
-        description: "Experimental: set blocking mode for new braid tool calls: /braid:blocking [on|off]; omit to show the current mode",
-        handler: async (args, ctx) => {
-            const setting = args.trim().toLowerCase();
-            if (setting === "on" || setting === "off")
-                sessionBlocking = setting === "on";
-            else if (setting)
-                throw new Error("Usage: /braid:blocking [on|off]");
-            ctx.ui.notify(`Braid blocking mode: ${blocking() ? "on" : "off"}. Applies to new braid tool calls.`, "info");
+    /** Holds and their removal apply to running executions only; explain the usual mistake. */
+    const hold = (jobId, executionIds, value) => {
+        if (!executionIds)
+            throw new Error("after=true requires executionIds of running executions; read them from braid_status");
+        try {
+            return jobs.holdAfter(jobId, executionIds, value, "agent");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!/running execution IDs/.test(message))
+                throw error;
+            throw new Error(`${message}. after=true applies only while an execution is still running; a finished result that is held is released with braid_resume({jobId, expectedRevision, executionIds}) without after.`);
+        }
+    };
+    const pauseParameters = Type.Object({
+        jobId: text("Exact session handle (e.g. job-1) or UUID."),
+        executionIds: Type.Optional(Type.Array(text(), { minItems: 1, uniqueItems: true, description: "Running execution IDs from braid_status, not node IDs. Omit to pause the whole job." })),
+        after: Type.Optional(Type.Boolean({ description: "true: do not suspend; let these running executions finish, then hold their results like pauseAfter, so downstream work waits for braid_resume. Use it to review a result that is still being produced. Requires executionIds; applies to these executions only, not their node definitions." })),
+    }, { additionalProperties: false });
+    const pauseTool = defineTool({
+        name: "braid_pause", label: "Pause Braid",
+        description: "Temporarily stop running executions without losing their work: each finishes its running tool, then stops before its next model request, keeping its conversation, workspace, and tool budgets, and releasing its concurrency slot. Omit executionIds to pause the whole job: no new executions start and running ones pause. Use it to inspect a node, correct it with a message, or stop spending while you adjust the graph. Resume with braid_resume. The node timeout stops while suspended; the graph timeout keeps running, so resume or cancel paused work. With after=true it does not suspend: each execution finishes, then its result is held until braid_resume.",
+        parameters: pauseParameters,
+        async execute(_id, params) {
+            if (params.after) {
+                const job = hold(params.jobId, params.executionIds, true);
+                return { content: [{ type: "text", text: formatHold(job, params.executionIds, true) }], details: job };
+            }
+            const job = jobs.pause(params.jobId, params.executionIds, "agent");
+            return { content: [{ type: "text", text: formatPause(job, params.executionIds) }], details: job };
         },
     });
+    return { braidTool, statusTool, cancelTool, updateTool, resumeTool, pauseTool };
+}
+/** One sentence for a pause, resume, or hold change the parent did not make. */
+export function formatControlNotice(notice) {
+    const who = notice.source === "user" ? "The user" : `A ${notice.source} control`;
+    const target = notice.executions
+        ? notice.executions.map(execution => `node ${JSON.stringify(execution.nodeId)} execution ${execution.executionId}`).join(", ")
+        : "the whole job";
+    const lookup = JSON.stringify({ jobId: notice.handle, ...(notice.executions?.length === 1 ? { executionId: notice.executions[0].executionId } : {}) });
+    switch (notice.action) {
+        case "paused": return `${who} paused ${target} of Braid job ${notice.handle}. Paused work keeps its conversation and workspace. Do not resume it unless the user asks; check the current state with braid_status(${lookup}).`;
+        case "resumed": return `${who} resumed ${target} of Braid job ${notice.handle}; it continues where it stopped.`;
+        case "held": return `${who} set ${target} of Braid job ${notice.handle} to hold its result once it finishes; downstream work waits for a resume. Do not release it unless the user asks; check the current state with braid_status(${lookup}).`;
+        case "unheld": return `${who} removed the hold on ${target} of Braid job ${notice.handle}; its result goes downstream when it finishes.`;
+        case "cancelled": return `${who} cancelled ${target} of Braid job ${notice.handle}. It failed; its successors follow the usual failure rules. Check the current state with braid_status(${lookup}).`;
+    }
+}
+export default function braidExtension(pi) {
     const pending = new Map();
     const remind = (message) => {
         try {
@@ -399,6 +434,23 @@ export default function braidExtension(pi) {
             // Keep failed deliveries pending for the next settled retry.
         }
     };
+    // Pauses, resumes, and holds made by someone else wait for the parent's next turn instead of
+    // waking it: a woken parent could resume work the user deliberately paused.
+    const notices = new Map();
+    const noteControl = (notice) => {
+        for (const execution of notice.executions ?? [undefined]) {
+            // The latest change per execution or job wins; holds and pauses are tracked separately.
+            const kind = notice.action === "held" || notice.action === "unheld" ? "hold" : "pause";
+            notices.set(JSON.stringify([notice.jobId, execution?.executionId ?? "job", kind]), { ...notice, ...(execution ? { executions: [execution] } : {}) });
+        }
+    };
+    pi.on("before_agent_start", () => {
+        if (!notices.size)
+            return;
+        const lines = [...notices.values()].map(formatControlNotice);
+        notices.clear();
+        return { message: { customType: "braid-control", display: true, content: `[system-reminder] ${lines.join(" ")} [/system-reminder]`, details: { notices: lines } } };
+    });
     const jobs = new BraidJobs((job) => {
         const { jobId, handle, status } = job;
         const reminderId = JSON.stringify([jobId, "job"]);
@@ -422,13 +474,23 @@ export default function braidExtension(pi) {
         };
         pending.set(reminderId, message);
         remind(message);
+    }, noteControl, (pause) => {
+        const reminderId = JSON.stringify([pause.jobId, "timeout", pause.executionId, pause.eventSequence]);
+        const message = {
+            customType: "braid-node-timeout",
+            display: true,
+            content: `[system-reminder] ${formatTimeoutPause(pause)} [/system-reminder]`,
+            details: { ...pause, reminderId },
+        };
+        pending.set(reminderId, message);
+        remind(message);
     });
     // Foreground cancellation can discard queued steering. Retry only reminders
     // that never entered context, once Pi has settled and emptied its queues.
     pi.on("message_start", (event) => {
         const message = event.message;
         if (message.role === "custom" &&
-            (message.customType === "braid-completed" || message.customType === "braid-node-completed")) {
+            (message.customType === "braid-completed" || message.customType === "braid-node-completed" || message.customType === "braid-node-timeout")) {
             const details = message.details;
             if (details?.reminderId)
                 pending.delete(details.reminderId);
@@ -440,7 +502,8 @@ export default function braidExtension(pi) {
                 remind(message);
         }
     });
-    const { braidTool, statusTool, cancelTool, updateTool, resumeTool } = createBraidTools(jobs, blocking);
+    const { braidTool, statusTool, cancelTool, updateTool, resumeTool, pauseTool } = createBraidTools(jobs);
+    registerDrain(pi, jobs, () => pending.size > 0);
     registerBraidCommand(pi, jobs);
     registerReviewCommand(pi, jobs);
     const disposeWidget = registerBraidWidget(pi, jobs);
@@ -449,12 +512,16 @@ export default function braidExtension(pi) {
     pi.registerTool(cancelTool);
     pi.registerTool(updateTool);
     pi.registerTool(resumeTool);
+    pi.registerTool(pauseTool);
     pi.on("session_shutdown", () => {
         pending.clear();
+        notices.clear();
         jobs.dispose();
         disposeWidget();
     });
-    pi.on("before_agent_start", (event) => ({
-        systemPrompt: `${event.systemPrompt}\n\n## Braid execution policy\n${BRAID_USAGE_GUIDANCE}\n${blocking() ? "Blocking mode is enabled for this session. " + BRAID_BLOCKING_GUIDANCE : BRAID_ASYNC_GUIDANCE}\n\nFor the current user request, make this delegation choice before using read, grep, find, edit, write, or bash. Completion reminders refer to existing jobs: retrieve their results instead of submitting the same graph again.`,
-    }));
+    pi.on("before_agent_start", (event, ctx) => {
+        return {
+            systemPrompt: `${event.systemPrompt}\n\n## Braid execution policy\n${BRAID_USAGE_GUIDANCE}\n${BRAID_ASYNC_GUIDANCE}${isSingleShot(ctx) ? `\n${BRAID_DRAIN_GUIDANCE}\n${BRAID_FINISH_GUIDANCE}` : ""}\n\nFor the current user request, make this delegation choice before using read, grep, find, edit, write, or bash. Completion reminders refer to existing jobs: retrieve their results instead of submitting the same graph again.`,
+        };
+    });
 }