@chrok/pi-braid 0.3.5 → 0.4.0

package/README.md

@@ -2,29 +2,37 @@
 
 [![npm](https://img.shields.io/npm/v/%40chrok%2Fpi-braid?label=%40chrok%2Fpi-braid)](https://www.npmjs.com/package/@chrok/pi-braid)
 
-This optional Pi extension runs Braid agent graphs as background jobs with
+This optional Pi extension runs Braid agent graphs as background jobs by default, with
 bounded loops, live updates, pause/resume, and a live flow panel.
 
-**0.3 API:** The npm badge shows the published version; see
+**0.4 API:** The npm badge shows the published version; see
 [GitHub releases](https://github.com/Epsirom/braid/releases) for release notes.
-Review the [0.2 → 0.3 migration guide](https://github.com/Epsirom/braid/blob/v0.3.0/docs/compatibility.md#migrating-from-02-to-03)
-before upgrading: writable nodes now have shell tools, checkpoints exclude
-untracked ignored outputs, and reminders can interrupt work between model steps.
-Users coming from 0.1 also need the
-[0.1 → 0.2 guide](https://github.com/Epsirom/braid/blob/v0.3.0/docs/compatibility.md#migrating-from-01-to-02).
+Review the [0.3 → 0.4 migration guide](https://github.com/Epsirom/braid/blob/v0.4.0/docs/compatibility.md#migrating-from-03-to-04)
+before upgrading: print and JSON runs wait for background jobs, Pi SDK sessions
+in the default print mode drain jobs before `session.prompt()` returns, and
+blocking mode is deprecated. Users coming from 0.2 also need the
+[0.2 → 0.3 guide](https://github.com/Epsirom/braid/blob/v0.4.0/docs/compatibility.md#migrating-from-02-to-03),
+and users coming from 0.1 the
+[0.1 → 0.2 guide](https://github.com/Epsirom/braid/blob/v0.4.0/docs/compatibility.md#migrating-from-01-to-02).
 For the previous release, use the
-[0.2.1 guide](https://github.com/Epsirom/braid/blob/v0.2.1/integrations/pi/README.md).
+[0.3.6 guide](https://github.com/Epsirom/braid/blob/v0.3.6/integrations/pi/README.md).
 
 It registers:
 
-- `braid` — submit a graph with optional bounded loops and immediately receive a `jobId`.
+- `braid` — submit a graph with optional bounded loops; receive a `jobId`
+  immediately in background mode (print/JSON runs wait for it before exiting), or
+  final results in deprecated blocking mode.
 - `braid_status` — retrieve progress and results with `{ "jobId": "..." }`, or
   add `"executionId": "..."` for an exact invocation's full output/error.
   `"nodeId": "..."` selects that definition's latest invocation. Omit all IDs
   to list jobs in the current session.
 - `braid_update` / `braid_resume` — edit live definitions or release paused executions.
 - `braid_cancel` — cancel a job with `{ "jobId": "..." }`.
+- `braid_finish` — print/JSON runs only: record the run outcome with
+  `{ "status": "success" | "failure", "summary": "..." }`.
 - `/braid [jobId]` — open a live flow panel in interactive Pi.
+- `/braid:blocking [on|off]` — deprecated, removed in 0.5.0: enable or disable
+  blocking for new `braid` tool calls; omit the argument to show the current mode.
 - `/braid:review [target or focus]` — run a bounded parallel review/fix loop.
 - `/braid:clear` — clear the progress widget above the editor; run it again while
   the widget is empty to restore what was cleared.
@@ -50,6 +58,91 @@ work, or end its turn if it needs the result, and not to sleep, use a timer, or
 poll in a loop to wait for the job.
 Stopping the foreground response does not stop background jobs.
 
+### Single-shot and CI runs
+
+In print mode (`pi -p`) and `--mode json`, background execution works unchanged:
+the run stays open until every Braid job reaches a terminal status and its
+reminder has been delivered, then exits after the parent's final response.
+
+```sh
+pi -p "Use Braid to review the changes and summarize the results."
+```
+
+The parent submits, ends its turn, and is resumed by the reminder as in
+interactive Pi, so `pauseAfter`, `notifyOnCompletion`, `braid_update`, and
+`braid_resume` keep working. Paused executions are never resumed automatically.
+If the parent ends its turn while only paused executions remain, it receives one
+warning naming them; ending the next turn without resuming them cancels their
+jobs, gives the parent a final turn on the cancellation reminder, and exits 1.
+
+`--braid-ci-timeout <duration>` bounds the whole run, starting at its first
+prompt. It accepts milliseconds or an `s`, `m`, or `h` suffix (for example
+`--braid-ci-timeout 30m`). On expiry, outstanding jobs are cancelled, the parent
+gets a final turn on the cancellation reminders, and the run exits 1. Either
+forced cancellation prints a `Braid:` line on stderr.
+
+A failed graph does not by itself fail the run. Instead, the parent is told to
+call `braid_finish` with `status` `success` or `failure` and a short `summary`
+once the task is done. The tool only records the outcome; the run still ends
+when the parent ends its turn with no Braid job outstanding, and a later call
+replaces the earlier outcome. A final `failure` exits 1 and prints
+`Braid: run reported failure: <summary>` on stderr. `success` never overrides a
+non-zero exit from a forced cancellation or from Pi itself. If the parent never
+calls it, the exit status is Pi's own apart from forced cancellations.
+
+In `--mode json`, the final outcome is also written as a session entry, after the
+`tool_execution_end` event of the call itself:
+
+```json
+{"type":"entry_appended","entry":{"type":"custom","customType":"braid-finish","data":{"status":"failure","summary":"Review found 2 blocking issues.","forcedFailures":[]},...}}
+```
+
+`forcedFailures` lists any forced cancellations, which fail the run whatever the
+reported status. The entry is not part of model context, and text mode still
+prints only the parent's final response. `braid_finish` is not offered in
+interactive or RPC sessions.
+
+Pi SDK sessions default to print mode too, so `session.prompt()` returns only
+after outstanding Braid jobs drain. Hosts that stay running and want reminders
+to start new runs after settling should bind with another mode, for example
+`session.bindExtensions({ mode: "rpc" })`.
+
+### Blocking mode (deprecated)
+
+> **Deprecated:** `--braid-blocking` and `/braid:blocking` will be removed in
+> 0.5.0. Print and JSON runs now wait for background jobs (see above), which keeps
+> `pauseAfter`, reminders, and live updates, and `braid_finish` sets the exit
+> status. To migrate, drop `--braid-blocking` (or `/braid:blocking on`) from the
+> command line ([#80](https://github.com/Epsirom/braid/issues/80)). Using either
+> prints a one-time warning: on stderr in print/JSON mode, or as a UI notice.
+
+Until then, to make each `braid` call wait in the foreground, enable blocking when starting Pi:
+
+```sh
+pi --braid-blocking -p "Use Braid to review the changes and summarize the results."
+```
+
+With `@chrok/pi-braid` installed, `--braid-blocking` makes every `braid` tool call
+wait for the entire graph and workspace cleanup, then return final status, outputs,
+and usage directly. The parent can summarize those results before `pi -p` exits.
+It also works with `--mode json` for structured tool results. The CLI flag sets the
+initial mode; within a session, use `/braid:blocking on` to enable it,
+`/braid:blocking off` to disable it, or `/braid:blocking` to check the current mode.
+Switching affects only new `braid` tool calls; running jobs keep their original
+mode. The session override is not persisted. These are user controls, not model
+tool parameters; the default remains background execution.
+For CI pass/fail decisions, inspect the returned job status: a failed graph does
+not by itself set Pi's process exit code.
+Blocking calls emit an initial progress update with the job handle while waiting.
+They suppress node/job completion reminders except for cancellation: stopping the
+foreground response cancels their work, waits for cleanup, and sends a reminder
+so the next turn can retrieve partial outputs and recovery checkpoints.
+Wait/result retrieval errors include the existing job handle and any terminal
+usage; retrieve that job with `braid_status` instead of submitting the graph again.
+`pauseAfter: true` is rejected before starting a blocking job because it requires
+a later resume call. The interactive
+`/braid:review` command continues to use its background review workflow.
+
 Jobs live in memory for the current Pi session. Quitting, reloading extensions,
 or switching/forking sessions aborts outstanding work and suppresses its
 reminders. Job IDs cannot be retrieved after that lifecycle ends. They are not
@@ -602,9 +695,11 @@ fails that node cleanly and does not invoke another provider.
 
 The Pi extension has no node or graph time limit by default. Use `braid_cancel`
 or press `c` in the flow panel to abort running nodes and mark queued nodes
-`cancelled`. Escape stops the foreground response or closes the panel without
-cancelling jobs. To set a node or graph timeout, supply milliseconds in the
-submission tool input under `options`; each omitted timeout remains unlimited:
+`cancelled`. In the default background mode, Escape stops the foreground response
+or closes the panel without cancelling jobs. In blocking mode, stopping the
+foreground response also cancels its Braid job. To set a node or graph timeout,
+supply milliseconds in the submission tool input under `options`; each omitted
+timeout remains unlimited:
 
 ```json
 {

package/dist/drain.js

@@ -0,0 +1,165 @@
+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 are not resumed automatically: resume or cancel them before ending your turn. If only paused executions remain when you end a turn, you get one warning; ending the next turn without resuming them cancels their 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 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 paused executions ${JSON.stringify(job.pausedExecutionIds)} at revision ${job.revision}`).join("; ") +
+    `. Resume them with braid_resume or braid_update with resume, 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]));
+                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 executions were never resumed; cancelled ${outstanding.map(job => job.handle).join(", ")}`);
+            }
+            await nextChange();
+        }
+    });
+    pi.on("session_shutdown", () => {
+        closed = true;
+        clearTimeout(timer);
+    });
+}

package/dist/index.js

@@ -7,6 +7,7 @@ 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";
 const text = (description) => Type.String({ minLength: 1, pattern: "\\S", ...(description ? { description } : {}) });
@@ -34,8 +35,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: "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." })),
+    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." })),
     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"], {
@@ -91,22 +92,26 @@ 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 = "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 = "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. " +
     "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 results with braid_status and continue the original task. Between reminders, use braid_status only for deliberate progress checks or diagnosis.";
+    "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.";
+export const BRAID_BLOCKING_DEPRECATION = "Blocking mode (--braid-blocking, /braid:blocking) is deprecated and will be removed in 0.5.0. " +
+    "Print and JSON runs (pi -p) now wait for background Braid jobs; call braid_finish to report the outcome.";
 /** 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.",
     BRAID_FILESYSTEM_GUIDANCE,
     "For repeated instructions, define promptTemplates once and use prompt={template: name, variables: {name: value}} on nodes. Values are strings inserted literally into {{name}} placeholders; plain-string prompts remain supported.",
-    "When Braid fits, submit a graph: use parallel execute nodes for independent analysis or implementation, execute nodes to synthesize findings, merge nodes to combine code snapshots, and integrate nodes to apply changes to the working branch. Use braid_status with the jobId to retrieve terminal outputs before relying on them.",
-    BRAID_ASYNC_GUIDANCE,
-    "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.",
+    "When Braid fits, submit a graph: use parallel execute nodes for independent analysis or implementation, execute nodes to synthesize findings, merge nodes to combine code snapshots, and integrate nodes to apply changes to the working branch. Read terminal outputs before relying on them.",
     "Make the delegation choice once per user request. Reminders and definition errors are not new tasks. If the same definition problem recurs, stop resubmitting and report the concrete mismatch; do not launch repeated probe/replacement jobs. In braid_update, add new nodes together with their dependencies and loops: a node added without incoming edges can start immediately, even while another execution is paused.",
     "Do not use braid for a simple one-step answer, a trivial direct edit, a single shell command, or when decomposition adds no value. Writable nodes can implement and test their work. The parent reviews results and performs any remaining validation after Braid completes.",
 ].join("\n");
@@ -131,12 +136,12 @@ 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) {
+export function createBraidTools(jobs, blocking = () => false) {
     const braidTool = defineTool({
         name: "braid",
         label: "Braid",
         description: "Use this tool FIRST for nontrivial engineering work: code reviews, bug investigations, design comparisons, test planning, and changes spanning multiple files. " +
-            "It starts a background job and immediately returns jobId for a mutable graph of isolated LLM invocations with parallel branches and joins; the user does not need to mention Braid. " +
+            "Run a mutable graph of isolated LLM invocations with parallel branches and joins; the user does not need to mention Braid. " +
             "Use execute, decision, merge, or integrate nodes. Execute/decision nodes require prompt. Only decision nodes declare choices and call decide; matching choice edges activate together. Merge/integrate nodes accept multiple predecessors and an optional prompt, with no workspace or choices field. " +
             "Structured loops declare id, entry, maxIterations, and one back edge from a decision to entry with both choice and feedback=loopId. The decision also needs an exit choice. External edges enter only at entry and leave only through that decision; the body must be acyclic and loops cannot overlap or nest. Each round uses new executions and worktrees. " +
             'Example retry loop: nodes work (execute with prompt) and check (decision with prompt and choices ["retry","done"]); edges [{"from":"work","to":"check"},{"from":"check","to":"work","choice":"retry","feedback":"retryLoop"}]; loops [{"id":"retryLoop","entry":"work","maxIterations":3}]. An optional done edge leaves check to a downstream node. ' +
@@ -147,8 +152,7 @@ export function createBraidTools(jobs) {
             BRAID_FILESYSTEM_GUIDANCE + " " +
             "Do not use it for a simple one-step answer or trivial direct edit. " +
             "Use braid_cancel(jobId) to stop it. Humans can open /braid for the live flow panel. " +
-            BRAID_ASYNC_GUIDANCE + " " +
-            "Set notifyOnCompletion=true on selected nodes for intermediate success/failure reminders; retrieve their output/error with braid_status({jobId, nodeId}). Notifications do not pause scheduling; use pauseAfter for a hold, and braid_update to edit definitions. " +
+            "Follow the current session's Braid execution policy in the system prompt for waiting, result retrieval, and pause/notification controls. " +
             "Read result.status: failed graphs can still return successful terminal outputs.",
         promptSnippet: "Use FIRST for nontrivial code review/debug/design/implementation work; set workspace=read-only for analysis/synthesis, use worktrees for edits, merge to combine snapshots, and integrate to apply changes",
         promptGuidelines: [
@@ -173,30 +177,56 @@ export function createBraidTools(jobs) {
                 const pending = options.isPartial && !ctx.isError;
                 return new Text(theme.fg(pending ? "warning" : "error", pending ? fallback || "Braid submission pending…" : `✗ ${fallback || "Braid submission failed without error details"}`), 0, 0);
             }
-            return new Text(theme.fg(job.status === "failed" ? "error" : "accent", `Braid background job ${job.handle ?? job.jobId} · ${job.status} · /braid to view${job.error ? `\n${job.error}` : ""}`), 0, 0);
+            if (job.status !== "running")
+                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 {
-                const job = jobs.start({
+                job = jobs.start({
                     goal: params.goal,
                     nodes: params.nodes,
                     edges: params.edges,
                     ...(params.loops !== undefined ? { loops: params.loops } : {}),
                     ...(params.promptTemplates !== undefined ? { promptTemplates: params.promptTemplates } : {}),
-                }, params.options ?? {}, ctx);
+                }, params.options ?? {}, ctx, waitForCompletion);
+            }
+            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.`),
-                        },
-                    ],
+                    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) {
-                throw new Error(`Braid submission failed: ${error instanceof Error ? error.message : String(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);
             }
         },
     });
@@ -209,7 +239,7 @@ export function createBraidTools(jobs) {
     const statusTool = defineTool({
         name: "braid_status",
         label: "Braid status",
-        description: "Retrieve a background Braid job's status, node progress, and final results by exact session handle (e.g. job-1) or UUID in jobId. Add executionId for an exact execution, or nodeId for the latest instance, including intermediate results while the job runs. Focused reads include live activity: phase, time in phase and since the last observed signal, model request/stream state, running tools, and recent history. Lack of observed activity is a diagnostic signal, not proof of a stall. Every job read starts with the current graph revision and paused execution IDs for live control. Results are text; long ones are truncated and the full text is saved to a file whose path is shown. Usage is Pi's provider accounting, including rounds from failed nodes. Prefer the short handle from submission/reminders. Omit all IDs to list jobs in this session. Completion reminders arrive automatically: read results after the reminder, or deliberately for a progress check or diagnosis; do not sleep, use a timer, or poll in a loop to wait for a job.",
+        description: "Retrieve a Braid job's status, node progress, and final results by exact session handle (e.g. job-1) or UUID in jobId. Add executionId for an exact execution, or nodeId for the latest instance, including intermediate results while the job runs. Focused reads include live activity: phase, time in phase and since the last observed signal, model request/stream state, running tools, and recent history. Lack of observed activity is a diagnostic signal, not proof of a stall. Every job read starts with the current graph revision and paused execution IDs for live control. Results are text; long ones are truncated and the full text is saved to a file whose path is shown. Usage is Pi's provider accounting, including rounds from failed nodes. Prefer the short handle from submission/reminders. Omit all IDs to list jobs in this session. Follow the current session's Braid execution policy for result retrieval; do not sleep, use a timer, or poll in a loop to wait for a job.",
         parameters: statusParameters,
         renderResult(result, options, theme, ctx) {
             const job = result.details;
@@ -242,7 +272,7 @@ export function createBraidTools(jobs) {
                 ...(job.fullOutputPath ? { fullOutputPath: job.fullOutputPath } : {}),
             }, options.expanded, options.isPartial, theme, fallback);
         },
-        async execute(_id, params) {
+        async execute(_id, params, signal) {
             if ((params.nodeId !== undefined || params.executionId !== undefined) && !params.jobId)
                 throw new Error("nodeId/executionId requires jobId");
             if (params.activityBefore !== undefined && params.nodeId === undefined && params.executionId === undefined)
@@ -270,7 +300,7 @@ export function createBraidTools(jobs) {
             const details = result.path ? { ...job, fullOutputPath: result.path } : job;
             // Saving a running snapshot can race job completion; claim usage only
             // when this response actually contains a terminal snapshot.
-            const usage = job.status === "running" ? undefined : jobs.claimUsage(job.jobId);
+            const usage = job.status === "running" || signal?.aborted ? undefined : jobs.claimUsage(job.jobId);
             return {
                 content: [{ type: "text", text: result.text }],
                 details,
@@ -343,6 +373,37 @@ export function createBraidTools(jobs) {
     return { braidTool, statusTool, cancelTool, updateTool, resumeTool };
 }
 export default function braidExtension(pi) {
+    pi.registerFlag("braid-blocking", {
+        description: "Deprecated, removed in 0.5.0: wait for braid tool calls to finish in the foreground. pi -p now waits for background jobs",
+        type: "boolean",
+        default: false,
+    });
+    let sessionBlocking;
+    const blocking = () => sessionBlocking ?? (pi.getFlag("braid-blocking") === true);
+    let warnedBlocking = false;
+    const warnBlocking = (ctx) => {
+        if (warnedBlocking)
+            return;
+        warnedBlocking = true;
+        // Print and JSON runs have no UI; stderr keeps JSON stdout parseable.
+        if (ctx.hasUI)
+            ctx.ui.notify(BRAID_BLOCKING_DEPRECATION, "warning");
+        else
+            console.error(`Braid: ${BRAID_BLOCKING_DEPRECATION}`);
+    };
+    pi.registerCommand("braid:blocking", {
+        description: "Deprecated, removed in 0.5.0: 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]");
+            if (setting === "on")
+                warnBlocking(ctx);
+            ctx.ui.notify(`Braid blocking mode: ${blocking() ? "on" : "off"}. Applies to new braid tool calls.`, "info");
+        },
+    });
     const pending = new Map();
     const remind = (message) => {
         try {
@@ -395,7 +456,8 @@ export default function braidExtension(pi) {
                 remind(message);
         }
     });
-    const { braidTool, statusTool, cancelTool, updateTool, resumeTool } = createBraidTools(jobs);
+    const { braidTool, statusTool, cancelTool, updateTool, resumeTool } = createBraidTools(jobs, blocking);
+    registerDrain(pi, jobs, () => pending.size > 0);
     registerBraidCommand(pi, jobs);
     registerReviewCommand(pi, jobs);
     const disposeWidget = registerBraidWidget(pi, jobs);
@@ -409,7 +471,11 @@ export default function braidExtension(pi) {
         jobs.dispose();
         disposeWidget();
     });
-    pi.on("before_agent_start", (event) => ({
-        systemPrompt: `${event.systemPrompt}\n\n## Braid execution policy\n${BRAID_USAGE_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) => {
+        if (pi.getFlag("braid-blocking") === true)
+            warnBlocking(ctx);
+        return {
+            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}${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.`,
+        };
+    });
 }

package/dist/jobs.js

@@ -36,10 +36,12 @@ export class BraidJobs {
             }
         }
     }
-    start(input, options, ctx) {
+    start(input, options, ctx, blocking = false) {
         if (this.disposed)
             throw new Error("Braid session has closed");
         validateGraph(input);
+        if (blocking && input.nodes.some(node => node.pauseAfter))
+            throw new Error("Blocking Braid jobs cannot use pauseAfter; remove it or disable blocking with /braid:blocking off.");
         const snapshot = structuredClone(input);
         const settings = { ...options };
         const model = ctx.model
@@ -49,6 +51,7 @@ export class BraidJobs {
         const cwd = ctx.cwd;
         this.cwd = cwd;
         const job = {
+            blocking,
             handle: `job-${this.nextHandle++}`,
             jobId: crypto.randomUUID(),
             goal: snapshot.goal,
@@ -73,7 +76,7 @@ export class BraidJobs {
     async run(job, input, options, registry, cwd, model) {
         const reports = [];
         try {
-            // Return the submission to Pi before doing provider work or sending reminders.
+            // Defer provider work until the job handle has been published.
             job.run = startBraid(input, {
                 ...options,
                 cwd,
@@ -150,7 +153,7 @@ export class BraidJobs {
                     const shouldNotify = event.type === "execution_paused" ||
                         ((event.type === "node_completed" || event.type === "node_failed") && instance?.node.notifyOnCompletion &&
                             (!instance.node.pauseAfter || state?.error));
-                    if (!this.disposed && shouldNotify && "nodeId" in event && instance) {
+                    if (!this.disposed && !job.blocking && shouldNotify && "nodeId" in event && instance) {
                         try {
                             void Promise.resolve(this.onNodeFinished({
                                 jobId: job.jobId,
@@ -190,7 +193,7 @@ export class BraidJobs {
                 job.usage = sumPiUsage(reports);
         }
         this.changed();
-        if (!this.disposed) {
+        if (!this.disposed && (!job.blocking || job.status === "cancelled")) {
             try {
                 this.onFinished(this.get(job.jobId));
             }
@@ -210,7 +213,7 @@ export class BraidJobs {
         const job = this.lookup(jobId);
         if (!job)
             return undefined;
-        const { run: _run, controller: _controller, done: _done, usageClaimed: _claimed, nodeResults: _nodeResults, runningExecutions: _runningExecutions, activity: _activity, transcripts: _transcripts, humanInputs: _humanInputs, ...snapshot } = job;
+        const { blocking: _blocking, run: _run, controller: _controller, done: _done, usageClaimed: _claimed, nodeResults: _nodeResults, runningExecutions: _runningExecutions, activity: _activity, transcripts: _transcripts, humanInputs: _humanInputs, ...snapshot } = job;
         const copy = structuredClone(snapshot);
         if (job.run)
             copy.execution = job.run.snapshot();
@@ -310,6 +313,23 @@ export class BraidJobs {
         }))
             .reverse();
     }
+    /**
+     * Jobs that have not reached a terminal status. A job is stalled when only
+     * paused executions remain, so it cannot progress without resume or cancel.
+     */
+    outstanding() {
+        return [...this.jobs.values()].filter(job => job.status === "running").map(job => {
+            // Skip the snapshot copy while executions are visibly running.
+            const state = job.runningExecutions.size ? undefined : job.run?.snapshot();
+            return {
+                jobId: job.jobId,
+                handle: job.handle,
+                stalled: state?.status === "waiting",
+                ...(state ? { revision: state.revision } : {}),
+                pausedExecutionIds: state?.pausedExecutionIds ?? [],
+            };
+        });
+    }
     /** Editor progress without copying outputs, transcripts, or execution snapshots. */
     progress(jobId) {
         const job = this.lookup(jobId);

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chrok/pi-braid",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "license": "MIT",
   "description": "Pi extension for Braid: background agent graphs, bounded loops, live updates, and a flow panel",
   "type": "module",
   "dependencies": {
     "grok-mermaid": "^0.2.2",
-    "@chrok/braid": "0.3.5"
+    "@chrok/braid": "0.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",