@chrok/pi-braid 0.3.4 → 0.3.6

package/README.md

@@ -2,7 +2,7 @@
 
 [![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
@@ -17,7 +17,8 @@ For the previous release, use the
 
 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, or final results in experimental 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
@@ -25,6 +26,8 @@ It registers:
 - `braid_update` / `braid_resume` — edit live definitions or release paused executions.
 - `braid_cancel` — cancel a job with `{ "jobId": "..." }`.
 - `/braid [jobId]` — open a live flow panel in interactive Pi.
+- `/braid:blocking [on|off]` — experimental: 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.
@@ -44,10 +47,44 @@ On completion, failure, or cancellation, the extension sends a custom
 Pi queues it as steering during streaming: it enters context after the current
 assistant response and its entire tool batch, before the next model step. It
 does not wait for the whole foreground task to finish or skip remaining tools.
-When idle, it starts a new agent turn automatically. The agent should wait for
-this reminder rather than poll.
+When idle, it starts a new agent turn automatically. Tool descriptions, the
+system prompt, and the submission receipt tell the agent to continue independent
+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.
 
+> **Experimental:** blocking mode is a stopgap for single-shot runs. Its flag,
+> command, and behavior may change or be replaced by an async-preserving CI mode
+> that keeps reminders, `pauseAfter`, and live updates
+> ([#80](https://github.com/Epsirom/braid/issues/80)).
+
+For CI or other single-shot runs, enable blocking manually 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
@@ -107,9 +144,10 @@ All four types accept `model`, `notifyOnCompletion`, `pauseAfter`, and
 default to writable worktrees in Git; outside Git, all workers are read-only.
 The model-facing schema exposes these fields in one object with a `type` enum;
 core validation enforces the type-specific requirements before a submission or
-update takes effect. Submission/update replies echo the accepted node types,
-model overrides, policies, and edges without repeating prompts. If a definition
-problem repeats, inspect/report the mismatch instead of launching more probe jobs.
+update takes effect. The submission reply gives the job ID and how to wait for
+it; it does not repeat the graph the agent just sent. Update replies list the
+resulting graph without prompts. If a definition problem repeats,
+inspect/report the mismatch instead of launching more probe jobs.
 
 Edges use exact node IDs in `from` and `to`. `choice` is an exact label declared
 by the source decision; omitting it makes the edge unconditional. Pass `edges: []`
@@ -152,7 +190,7 @@ drops the queued message. Session shutdown suppresses delivery.
 
 Set `pauseAfter: true` to hold an execution's outgoing scheduling and receive a
 pause reminder. Independent branches continue. Fetch `braid_status` to obtain
-`execution.revision` and `execution.pausedExecutionIds`, then:
+the current graph revision and paused execution IDs, then:
 
 ```json
 {
@@ -178,9 +216,9 @@ Pause reminders describe the event when it occurred: check current status and
 paused IDs before attempting an update/resume, since the job can time out or be
 cancelled before the parent handles the reminder.
 
-Focused `braid_status` reads also include the current control fields; the
-returned `node.revision` is the revision captured when that invocation started.
-Use `execution.revision` for updates even when inspecting an older invocation.
+Focused `braid_status` reads also start with the current control fields: graph
+status, revision, and paused execution IDs. Use that current revision for
+updates even when inspecting an older invocation.
 After cancellation or finalization there are no resumable paused executions;
 the event log still records where pauses occurred.
 
@@ -317,9 +355,15 @@ counts, and the execution log. Active nodes are marked `▶ ACTIVE`. The status
 tool also renders a flowchart; expand its result to see more log events.
 When selecting `nodeId` or `executionId`, it instead shows that invocation's
 output/error and activity, with the full text and history available on expansion.
-The JSON includes `activity` with the latest 40 history entries; pass
+
+The Braid tools return plain-text documents to the model, not JSON. A
+whole-job read lists the control state, every execution, their outputs,
+workspaces, and the current graph without prompts. A focused read shows one
+execution's output and its activity with the latest 40 history entries; pass
 `activityBefore` with an entry sequence to page earlier ones. While the invocation
-runs, `activity` comes before `node` so it survives preview truncation.
+runs, the activity comes before the output so it survives preview truncation.
+Worker `git` results read like Pi's bash output, and `decide` returns
+`Recorded choice: <choice>`.
 
 `/braid` now opens this panel; it no longer arms the next prompt. To request
 Braid explicitly, ask the agent to analyze the task using Braid.
@@ -330,11 +374,9 @@ model lookup, credentials/OAuth, provider transport, filesystem tool execution,
 and token/cost accounting. The first
 whole-job `braid_status` retrieval of a finished job reports its accumulated Pi usage;
 subsequent retrievals do not count the same usage again.
-Use the status response's `usage` for Pi totals, including completed provider
-rounds from nodes that later fail or time out. Saved final result files expose
-the same accounting as `piUsage`; core `metadata.usage` only includes usage
-returned by runners. Large running status reads save a complete snapshot too,
-so truncation never requires waiting for job completion to inspect the graph.
+The whole-job status text reports Pi's totals as `Usage`, including completed
+provider rounds from nodes that later fail or time out; core `metadata.usage`
+only includes usage returned by runners.
 
 ## When Pi will use Braid
 
@@ -378,7 +420,7 @@ only the current source IDs and diagnoses missing, duplicate or unexpected IDs.
 
 ## Install from npm
 
-Requires Node.js 22.19+ and Pi 1.0.1 (the tested version):
+Requires Node.js 22.19+ and Pi 1.2.0 (the tested version):
 
 ```sh
 pi install npm:@chrok/pi-braid
@@ -389,7 +431,7 @@ The package depends on the exact matching `@chrok/braid` release; npm installs
 core automatically. It does not bundle core or depend on a source checkout.
 Pi supplies its core peer packages at runtime.
 Their wildcard ranges follow Pi's packaging convention, not universal version
-compatibility. Development and CI pin Pi 1.0.1.
+compatibility. Development and CI pin Pi 1.2.0.
 
 ## Install this local checkout in Pi
 
@@ -595,9 +637,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
 {
@@ -618,9 +662,9 @@ writes already made. Core waits for tracked writes, preserves checkpoints, and
 removes worker worktrees before completing cancellation.
 
 The tool output is capped at 50KB/2000 lines to protect Pi context. When exceeded,
-the adapter writes a full JSON result to a temporary file (mode 600 on POSIX;
-inherited ACLs on Windows) and includes
-its path in the tool output.
+the adapter writes the complete text to a temporary file (mode 600 on POSIX;
+inherited ACLs on Windows) and ends the preview with its path, for running jobs
+as well as finished ones.
 
 For a test of proactive selection, start a fresh Pi turn with a task such as:
 

package/dist/command.js

@@ -201,9 +201,6 @@ export class BraidPanel {
                         ...(current.result ?? current.live),
                         progress: current.live.progress,
                         ...(current.workspaces ? { workspaces: current.workspaces } : {}),
-                        ...(current.fullOutputPath
-                            ? { fullOutputPath: current.fullOutputPath }
-                            : {}),
                     }, true, false, this.theme, "", false, this.choosing).render(width),
                 ]
                 : ["No Braid jobs in this session."];

package/dist/display.js

@@ -551,7 +551,7 @@ export function renderNodeResult(node, expanded, theme, fullOutputPath, progress
         ...(activity && activity.executionId === node.executionId ? renderActivity(activity, expanded, theme, now) : []),
         ...(node.output ? [expanded ? clean(node.output) : compact(node.output, 400)] : []),
         ...(!expanded && node.output && (node.output.length > 400 || node.output.includes("\n")) ? [theme.fg("dim", "Expand for full node output")] : []),
-        ...(fullOutputPath ? [theme.fg("dim", `full node result: ${compact(fullOutputPath, 240)}`)] : []),
+        ...(fullOutputPath ? [theme.fg("dim", `full text: ${compact(fullOutputPath, 240)}`)] : []),
     ];
     return new Text(lines.join("\n"), 0, 0);
 }
@@ -655,7 +655,7 @@ export function renderGraphResult(result, expanded, isPartial, theme, fallback =
     if (expanded)
         lines.push(...renderEventLog(result.events ?? [], true, theme));
     if ("fullOutputPath" in result && result.fullOutputPath)
-        lines.push(theme.fg("dim", `full result/log: ${compact(result.fullOutputPath, 240)}`));
+        lines.push(theme.fg("dim", `full text: ${compact(result.fullOutputPath, 240)}`));
     return new FixedLines(lines, chartStart, chart.length, nodeList, [
         ...(selectedNodeId === undefined ? [] : [{ mark: SELECTED_NODE_MARK, label: "selected node" }]),
         { mark: "▶ ACTIVE", label: "running node" },

package/dist/index.js

@@ -8,6 +8,7 @@ import { BraidJobs } from "./jobs.js";
 import { registerBraidCommand, registerBraidWidget } from "./command.js";
 import { registerReviewCommand } from "./review.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 } : {}) });
 const prompt = () => Type.Union([
     text("Instructions for this node; it does not receive the parent conversation."),
@@ -33,8 +34,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"], {
@@ -89,14 +90,26 @@ const BRAID_FILESYSTEM_GUIDANCE = "Every execute/decision activation gets a fres
     "merge combines selected predecessor checkpoints into a new isolated worktree; integrate writes selected changes to the invoking checkout while preserving user edits. Workers apply changes with Git/file tools, then call finish_merge using executionId for each source; finish_merge only records dispositions and does not apply changes. There is no automatic final integration. " +
     "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. " +
+    "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.";
+/** 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. The tool returns a jobId immediately. Continue independent work or finish your turn while it runs; do not poll repeatedly. A completion reminder will resume you. Use braid_status with the jobId to retrieve terminal outputs before relying on them.",
-    "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.",
-    "Make the delegation choice once per user request. Reminders and definition errors are not new tasks. Check the accepted node types and settings in the tool response. 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.",
+    "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");
 function isJobSnapshot(value) {
@@ -110,28 +123,22 @@ function isJobSnapshot(value) {
 }
 /** Focused reads return the latest activity entries; activityBefore pages earlier ones. */
 export const STATUS_ACTIVITY_ENTRIES = 40;
-function executionControl(job) {
-    return job.execution && {
-        status: job.execution.status,
-        revision: job.execution.revision,
-        pausedExecutionIds: job.execution.pausedExecutionIds,
-    };
-}
-function graphReceipt(job) {
-    const graph = job.execution?.graph;
-    return graph && {
-        // Echo accepted types/policies without duplicating potentially large prompts.
-        nodes: graph.nodes.map(({ prompt: _prompt, ...node }) => node),
-        edges: graph.edges,
-        ...(graph.loops ? { loops: graph.loops } : {}),
-    };
+/** Bound a text result; the complete document stays readable in a private file. */
+async function boundedText(text, name) {
+    const preview = truncateHead(text);
+    if (!preview.truncated)
+        return { text };
+    const directory = await mkdtemp(join(tmpdir(), "braid-status-"));
+    const path = join(directory, 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. ' +
@@ -141,8 +148,8 @@ export function createBraidTools(jobs) {
             "no parent history, inherited extension/MCP tools, or recursive Braid tools. " +
             BRAID_FILESYSTEM_GUIDANCE + " " +
             "Do not use it for a simple one-step answer or trivial direct edit. " +
-            "Use braid_status(jobId) for progress and results, or braid_cancel(jobId) to stop it. A completion reminder resumes the agent if idle; do independent work or end your turn instead of polling. Humans can open /braid for the live flow panel. " +
-            "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. " +
+            "Use braid_cancel(jobId) to stop it. Humans can open /braid for the live flow panel. " +
+            "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: [
@@ -167,36 +174,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: JSON.stringify({
-                                jobId: job.handle,
-                                canonicalJobId: job.jobId,
-                                status: job.status,
-                                graph: graphReceipt(job),
-                                message: "Running in background. Check the accepted graph above. Use braid_status to retrieve progress/results. Reminders arrive after the current step or resume you when idle; do not poll repeatedly.",
-                            }),
-                        },
-                    ],
+                    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 +236,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. All job reads include current execution.revision and execution.pausedExecutionIds for live control; node.revision is the historical invocation revision. Large results include a path to the full JSON, including while running. For usage totals use usage (Pi provider accounting, including rounds from failed nodes), or piUsage in the saved final result. Prefer the short handle from submission/reminders. Omit all IDs to list jobs in this session. Completion reminders arrive automatically; avoid repeated polling.",
+        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,14 +269,14 @@ 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)
                 throw new Error("activityBefore requires nodeId or executionId");
             if (!params.jobId)
                 return {
-                    content: [{ type: "text", text: JSON.stringify(jobs.list()) }],
+                    content: [{ type: "text", text: formatJobList(jobs.list()) }],
                     details: undefined,
                 };
             const job = jobs.get(params.jobId);
@@ -257,63 +284,22 @@ export function createBraidTools(jobs) {
                 throw jobs.unknownJob(params.jobId);
             if (params.nodeId !== undefined || params.executionId !== undefined) {
                 const node = jobs.getNode(params.jobId, params.nodeId, params.executionId);
-                const { id, executionId, status, error, output, ...nodeDetails } = node;
-                const activity = executionId ? jobs.getActivity(params.jobId, executionId, {
+                const activity = node.executionId ? jobs.getActivity(params.jobId, node.executionId, {
                     limit: STATUS_ACTIVITY_ENTRIES, ...(params.activityBefore === undefined ? {} : { before: params.activityBefore }),
                 }) : undefined;
-                // While running, activity is the useful part; afterwards the output is,
-                // so it comes first and history cannot push it out of the preview.
-                const running = activity && activity.finishedAt === undefined;
-                const live = activity ? { observedAt: job.live.observedAt, activity } : {};
-                const full = JSON.stringify({
-                    jobId: job.jobId, handle: job.handle, status: job.status, execution: executionControl(job),
-                    ...(running ? live : {}),
-                    node: { id, executionId, status, error, output, ...nodeDetails },
-                    ...(running ? {} : live),
-                }, null, 2);
-                const preview = truncateHead(full);
-                let suffix = "";
-                let nodeOutputPath;
-                if (preview.truncated) {
-                    const directory = await mkdtemp(join(tmpdir(), "braid-node-result-"));
-                    const path = join(directory, "result.json");
-                    await writeFile(path, full, { mode: 0o600 });
-                    nodeOutputPath = path;
-                    suffix = `\n[Preview truncated. Full node result: ${path}]`;
-                }
+                const result = await boundedText(formatNodeStatus({ job, node, ...(activity ? { activity } : {}), now: Date.now() }), "node.txt");
                 // Focused reads do not claim the whole job's usage; final job retrieval does.
-                return { content: [{ type: "text", text: preview.content + suffix }], details: {
-                        ...job, selectedNode: node, ...(activity ? { selectedActivity: activity } : {}), ...(nodeOutputPath ? { nodeOutputPath } : {}),
+                return { content: [{ type: "text", text: result.text }], details: {
+                        ...job, selectedNode: node, ...(activity ? { selectedActivity: activity } : {}), ...(result.path ? { nodeOutputPath: result.path } : {}),
                     } };
             }
-            const { jobId, handle, status, error, usage: providerUsage, fullOutputPath, execution, ...snapshot } = job;
-            // Put control/error/accounting fields before large prompts, outputs and logs.
-            const full = JSON.stringify({
-                jobId, handle, status,
-                error: error ?? job.result?.error ?? execution?.error,
-                usage: providerUsage, fullOutputPath,
-                execution: execution && { ...executionControl(job), ...execution },
-                ...snapshot,
-            }, null, 2);
-            const preview = truncateHead(full);
-            let suffix = "";
-            let details = job;
-            if (preview.truncated) {
-                if (job.fullOutputPath)
-                    suffix = `\n[Preview truncated. Full result/log: ${job.fullOutputPath}]`;
-                else {
-                    const directory = await mkdtemp(join(tmpdir(), "braid-status-"));
-                    const path = join(directory, "status.json");
-                    await writeFile(path, full, { mode: 0o600 });
-                    details = { ...job, fullOutputPath: path };
-                    suffix = `\n[Preview truncated. Full status snapshot: ${path}]`;
-                }
-            }
+            const result = await boundedText(formatJobStatus(job, Date.now()), "status.txt");
+            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: preview.content + suffix }],
+                content: [{ type: "text", text: result.text }],
                 details,
                 ...(usage ? { usage } : {}),
             };
@@ -342,14 +328,14 @@ export function createBraidTools(jobs) {
     });
     const updateParameters = Type.Object({
         jobId: text("Exact session handle (e.g. job-1) or UUID."),
-        expectedRevision: Type.Integer({ minimum: 0, description: "Current execution.revision from braid_status. A stale revision rejects the entire update." }),
+        expectedRevision: Type.Integer({ minimum: 0, description: "Current graph revision from braid_status. A stale revision rejects the entire update." }),
         upsertNodes: Type.Optional(Type.Array(nodeParameters, { description: "Complete node definitions to add or replace, not partial patches. Add dependencies and loops in this SAME update: new roots may start immediately even if another execution is paused. Already admitted executions keep their captured definitions." })),
         removeNodeIds: Type.Optional(Type.Array(text(), { description: "Node IDs to remove, together with all incident edges." })),
         addEdges: Type.Optional(Type.Array(updateEdgeParameters, { description: "Edges to add. Pin a historical source using executionId when needed." })),
-        removeEdges: Type.Optional(Type.Array(updateEdgeParameters, { description: "Exact edge identities to remove: copy from, to, and every present choice/feedback/executionId from execution.graph.edges. Omitted optional fields do not act as wildcards." })),
+        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 execution.pausedExecutionIds, not node IDs. Releases them atomically with the graph edit." })),
+        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." })),
     }, { additionalProperties: false });
     const updateTool = defineTool({
         name: "braid_update", label: "Update Braid",
@@ -364,13 +350,13 @@ export function createBraidTools(jobs) {
             catch (error) {
                 throw new Error(`Braid update rejected; no changes or resumes were applied. ${error instanceof Error ? error.message : String(error)}. Retry the complete corrected patch, including its edges/loops/resume; adding disconnected nodes separately can start them immediately.`);
             }
-            return { content: [{ type: "text", text: JSON.stringify({ jobId: job.handle, revision: job.execution.revision, pausedExecutionIds: job.execution.pausedExecutionIds, graph: graphReceipt(job) }) }], details: job };
+            return { content: [{ type: "text", text: formatUpdate(job) }], details: job };
         },
     });
     const resumeParameters = Type.Object({
         jobId: text("Exact session handle (e.g. job-1) or UUID."),
-        expectedRevision: Type.Integer({ minimum: 0, description: "Current execution.revision from braid_status." }),
-        executionIds: Type.Array(text(), { minItems: 1, uniqueItems: true, description: "IDs from execution.pausedExecutionIds, not node IDs. Only these completed, paused executions are released." }),
+        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." }),
     }, { additionalProperties: false });
     const resumeTool = defineTool({
         name: "braid_resume", label: "Resume Braid",
@@ -378,12 +364,30 @@ export function createBraidTools(jobs) {
         parameters: resumeParameters,
         async execute(_id, params) {
             const job = jobs.resume(params.jobId, params.executionIds, params.expectedRevision);
-            return { content: [{ type: "text", text: JSON.stringify({ jobId: job.handle, revision: job.execution.revision, pausedExecutionIds: job.execution.pausedExecutionIds }) }], details: job };
+            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");
+        },
+    });
     const pending = new Map();
     const remind = (message) => {
         try {
@@ -436,7 +440,7 @@ export default function braidExtension(pi) {
                 remind(message);
         }
     });
-    const { braidTool, statusTool, cancelTool, updateTool, resumeTool } = createBraidTools(jobs);
+    const { braidTool, statusTool, cancelTool, updateTool, resumeTool } = createBraidTools(jobs, blocking);
     registerBraidCommand(pi, jobs);
     registerReviewCommand(pi, jobs);
     const disposeWidget = registerBraidWidget(pi, jobs);
@@ -451,6 +455,6 @@ export default function braidExtension(pi) {
         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.`,
+        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.`,
     }));
 }

package/dist/jobs.js

@@ -1,8 +1,4 @@
-import { mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { setImmediate as nextTurn } from "node:timers/promises";
-import { truncateHead, } from "@earendil-works/pi-coding-agent";
 import { ExecutionActivityTracker, startBraid, validateGraph, } from "@chrok/braid";
 import { applyEvent, applyProgress, createLiveState, } from "./display.js";
 import { createPiRunner, sumPiUsage } from "./runner.js";
@@ -40,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
@@ -53,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,
@@ -77,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,
@@ -154,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,
@@ -182,16 +181,6 @@ export class BraidJobs {
             const status = job.result.error?.code === "CANCELLED"
                 ? "cancelled"
                 : job.result.status;
-            // Core metadata counts usage returned by runners; Pi also records completed
-            // provider rounds from workers that later fail or time out.
-            const full = JSON.stringify({ ...job.result, workspaces: job.workspaces, piUsage: job.usage }, null, 2);
-            const preview = JSON.stringify({ ...this.get(job.jobId), status }, null, 2);
-            if (truncateHead(preview).truncated) {
-                const directory = await mkdtemp(join(tmpdir(), "braid-result-"));
-                const path = join(directory, "result.json");
-                await writeFile(path, full, { mode: 0o600 });
-                job.fullOutputPath = path;
-            }
             job.status = status;
         }
         catch (error) {
@@ -204,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));
             }
@@ -224,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();

package/dist/runner.js

@@ -5,6 +5,18 @@ import { createWorktreeWriteTools } from "./write-tools.js";
 import { createAvailableReadTools } from "./read-tools.js";
 import { createWorkspaceShellTools } from "./shell-tools.js";
 import { formatHumanInput } from "./human-input.js";
+/**
+ * Present a Git result the way Pi's bash tool presents command output. Output
+ * stays byte-exact, so a diff can be passed back to git apply.
+ */
+export function formatGitResult(result) {
+    let output = result.stdout;
+    if (result.stderr)
+        output += (output && !output.endsWith("\n") ? "\n" : "") + result.stderr;
+    if (result.exitCode === 0)
+        return output || "(no output)";
+    return `${output ? `${output.replace(/\n$/, "")}\n\n` : ""}Command exited with code ${result.exitCode}`;
+}
 /** Keep Pi's provider/auth plumbing and filesystem capabilities out of Braid's core. */
 export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd()) {
     const options = typeof onUsageOrOptions === "function"
@@ -289,7 +301,7 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
                 if (call.name === "git" && request.git) {
                     const args = parseGitToolArguments(call.arguments, (request.node.type === "merge" || request.node.type === "integrate"));
                     const result = await request.git(args.args, args.input);
-                    return toolResult(call, JSON.stringify(result), result.exitCode !== 0);
+                    return toolResult(call, formatGitResult(result), result.exitCode !== 0);
                 }
                 if (call.name === "finish_merge" && request.merge) {
                     const dispositions = parseFinishMergeArguments(call.arguments, request.merge.sources.map(source => source.executionId));
@@ -339,7 +351,7 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
             // No coercion or prose parsing: the core enforces the enum and exactly one call.
             request.decide(args.choice);
             decided = true;
-            return toolResult(call, JSON.stringify({ choice: args.choice }), false);
+            return toolResult(call, `Recorded choice: ${args.choice}`, false);
         };
         while (true) {
             const response = await complete();

package/dist/status-text.js

@@ -0,0 +1,179 @@
+/** Model-facing text documents for the parent Braid tools. */
+const iso = (ms) => new Date(ms).toISOString();
+const duration = (ms) => ms < 1000 ? `${Math.max(0, Math.round(ms))}ms` : ms < 60_000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1000)}s`;
+const failure = (error) => `${error.code}: ${error.message}`;
+const ids = (values) => values?.length ? values.join(", ") : "none";
+const GOAL_CHARS = 2000;
+const clip = (text, limit) => text.length > limit ? `${text.slice(0, limit)}… [${text.length} chars]` : text;
+const indent = (text) => text.split("\n").map(line => line ? `  ${line}` : line).join("\n");
+export function formatUsage(usage) {
+    if (!usage)
+        return undefined;
+    const parts = [`input ${usage.input}`, `output ${usage.output}`];
+    if (usage.cacheRead)
+        parts.push(`cache read ${usage.cacheRead}`);
+    if (usage.cacheWrite)
+        parts.push(`cache write ${usage.cacheWrite}`);
+    const cost = usage.cost?.total ? `, $${usage.cost.total.toFixed(4)}` : "";
+    return `${parts.join(", ")} (${usage.totalTokens} tokens${cost})`;
+}
+function nodeLine(node) {
+    const settings = [node.type];
+    if ("workspace" in node && node.workspace)
+        settings.push(`workspace=${node.workspace}`);
+    if ("choices" in node)
+        settings.push(`choices=${node.choices.join("|")}`);
+    if (node.model)
+        settings.push(`model=${node.model}`);
+    if (typeof node.prompt === "object")
+        settings.push(`template=${node.prompt.template}`);
+    for (const flag of ["pauseAfter", "notifyOnCompletion", "requireSuccess"])
+        if (node[flag])
+            settings.push(flag);
+    return `- ${node.id}: ${settings.join(", ")}`;
+}
+/** Accepted definitions without prompts, which the caller already sent. */
+export function formatGraph(graph) {
+    const lines = ["Nodes:", ...graph.nodes.map(nodeLine), "Edges:"];
+    lines.push(...graph.edges.length ? graph.edges.map(edge => {
+        const labels = [edge.choice && `choice=${edge.choice}`, edge.feedback && `feedback=${edge.feedback}`, edge.executionId && `execution=${edge.executionId}`].filter(Boolean);
+        return `- ${edge.from} -> ${edge.to}${labels.length ? ` [${labels.join(", ")}]` : ""}`;
+    }) : ["- none"]);
+    if (graph.loops?.length)
+        lines.push("Loops:", ...graph.loops.map(loop => `- ${loop.id}: entry ${loop.entry}, at most ${loop.maxIterations} iterations`));
+    return lines.join("\n");
+}
+function workspaceLine(workspace) {
+    const parts = [`${workspace.mode} ${workspace.workingDirectory}`, workspace.state];
+    for (const root of [workspace.worktreeRoot, workspace.sourceRoot])
+        if (root && root !== workspace.workingDirectory)
+            parts.push(`root ${root}`);
+    if (workspace.checkpointRef)
+        parts.push(`checkpoint ${workspace.checkpointRef}`);
+    if (workspace.backupRef)
+        parts.push(`backup ${workspace.backupRef}`);
+    if (workspace.reason)
+        parts.push(workspace.reason);
+    for (const item of workspace.dispositions ?? [])
+        parts.push(`${item.executionId} ${item.disposition}: ${item.reason}`);
+    return parts.join(" · ");
+}
+function executionLine(execution) {
+    const parts = [execution.executionId ?? "(no execution)", `node ${execution.id}`];
+    if (execution.iteration)
+        parts.push(`iteration ${execution.iteration}`);
+    parts.push(execution.skipReason ? `${execution.status} (${execution.skipReason})` : execution.status);
+    if (execution.latencyMs !== undefined)
+        parts.push(duration(execution.latencyMs));
+    if (execution.decision)
+        parts.push(`decision ${execution.decision}`);
+    if (execution.error)
+        parts.push(failure(execution.error));
+    return `- ${parts.join(" · ")}`;
+}
+export function formatJobList(jobs) {
+    if (!jobs.length)
+        return "No Braid jobs in this session.";
+    return [`${jobs.length} Braid job${jobs.length === 1 ? "" : "s"} in this session, newest first:`,
+        ...jobs.map(job => `- ${job.handle} · ${job.status} · started ${iso(job.createdAt)} · id ${job.jobId}\n  Goal: ${job.goal}`)].join("\n");
+}
+function control(execution) {
+    return execution ? `Graph ${execution.status} · revision ${execution.revision} · paused executions: ${ids(execution.pausedExecutionIds)}` : "Graph not started";
+}
+/** The submission receipt. The caller already has the graph it submitted. */
+export function formatReceipt(job, message) {
+    return [`Braid job ${job.handle} started (${job.status}).`, `ID: ${job.jobId}`, message].join("\n");
+}
+export function formatUpdate(job) {
+    return [`Braid job ${job.handle} updated to revision ${job.execution.revision}.`,
+        `Paused executions: ${ids(job.execution.pausedExecutionIds)}`, "Current graph:", formatGraph(job.execution.graph)].join("\n");
+}
+export function formatResume(job) {
+    return `Braid job ${job.handle} resumed at revision ${job.execution.revision}. Still paused: ${ids(job.execution.pausedExecutionIds)}.`;
+}
+export function formatActivity(activity, now, jobId) {
+    const lines = [`Activity: ${activity.phase} for ${duration(now - activity.phaseStartedAt)}; last observed signal ${duration(now - activity.lastActivityAt)} ago (${activity.lastActivity}). Model requests ${activity.modelRequests}, tool calls ${activity.toolCalls}.`];
+    const model = activity.model;
+    if (model && model.completedAt === undefined) {
+        const stream = model.firstStreamAt === undefined ? "no stream received yet"
+            : `receiving ${model.receiving ?? "output"}${model.toolName ? ` for ${model.toolName}` : ""}, ${model.receivedChars} chars, last chunk ${duration(now - (model.lastStreamAt ?? model.firstStreamAt))} ago`;
+        lines.push(`Model request ${model.round}: started ${duration(now - model.startedAt)} ago; ${stream}.`);
+    }
+    for (const tool of activity.tools) {
+        lines.push(`Running tool ${tool.name} for ${duration(now - tool.startedAt)}: ${tool.arguments}`);
+        if (tool.outputTail)
+            lines.push(indent(`Output tail:\n${tool.outputTail}`));
+    }
+    for (const limitation of activity.limitations)
+        lines.push(`Not observable: ${limitation}`);
+    if (activity.entries.length) {
+        lines.push("History:");
+        for (const entry of activity.entries) {
+            lines.push(`- #${entry.sequence} ${iso(entry.timestamp)} ${entry.kind}${entry.toolName ? ` ${entry.toolName}` : ""}${entry.isError ? " (error)" : ""}${entry.durationMs !== undefined ? ` ${duration(entry.durationMs)}` : ""}: ${entry.summary}`);
+            if (entry.detail)
+                lines.push(indent(entry.detail + (entry.detailLength ? `\n[preview of ${entry.detailLength} chars]` : "")));
+        }
+        const first = activity.entries[0].sequence;
+        if (first > 1)
+            lines.push(first - 1 > activity.droppedEntries
+                ? `Earlier entries: braid_status({"jobId":"${jobId}","executionId":"${activity.executionId}","activityBefore":${first}})`
+                : `${activity.droppedEntries} earlier entries are no longer retained.`);
+    }
+    return lines.join("\n");
+}
+/** A focused read: the current control state, then one execution in full. */
+export function formatNodeStatus({ job, node, activity, now }) {
+    const lines = [`Braid job ${job.handle} · ${job.status} · ${control(job.execution)}`,
+        `Execution ${node.executionId ?? "(none yet)"} · node ${node.id}${node.node ? ` (${node.node.type})` : ""}${node.iteration ? ` · iteration ${node.iteration}` : ""} · ${node.skipReason ? `${node.status} (${node.skipReason})` : node.status}`];
+    const timing = [node.startedAt !== undefined && `started ${iso(node.startedAt)}`, node.latencyMs !== undefined && `took ${duration(node.latencyMs)}`,
+        node.model && `model ${node.model}`, node.usage && `usage input ${node.usage.inputTokens}, output ${node.usage.outputTokens}`].filter(Boolean);
+    if (timing.length)
+        lines.push(timing.join(" · "));
+    if (node.decision)
+        lines.push(`Decision: ${node.decision}`);
+    if (node.error)
+        lines.push(`Error: ${failure(node.error)}`);
+    if (node.workspace)
+        lines.push(`Workspace: ${workspaceLine(node.workspace)}`);
+    if (node.humanInputs?.length)
+        lines.push("Human input delivered during this execution:", ...node.humanInputs.map(input => `- ${iso(input.timestamp)}: ${input.text}`));
+    const output = `Output:\n${node.output ?? "(none)"}`;
+    // While running, activity is the useful part; afterwards the output is.
+    const running = activity && activity.finishedAt === undefined;
+    const sections = [lines.join("\n"), ...running ? [formatActivity(activity, now, job.handle), output] : [output, ...activity ? [formatActivity(activity, now, job.handle)] : []]];
+    return sections.join("\n\n");
+}
+/** The whole job: control state, every execution, then their outputs and the current definition. */
+export function formatJobStatus(job, now) {
+    const state = job.result ?? job.execution;
+    // Control fields lead: a long goal or output must not push them out of a truncated preview.
+    const header = [`Braid job ${job.handle} · ${job.status}`, `ID: ${job.jobId}`, control(job.execution)];
+    const error = job.error ?? (job.result?.error ? failure(job.result.error) : job.execution?.error ? failure(job.execution.error) : undefined);
+    if (error)
+        header.push(`Error: ${error}`);
+    const usage = formatUsage(job.usage);
+    if (usage)
+        header.push(`Usage: ${usage}`);
+    if (job.result)
+        header.push(`Finished ${iso(job.result.metadata.finishedAt)} after ${duration(job.result.metadata.latencyMs)}`);
+    else
+        header.push(`Started ${iso(job.createdAt)}, ${duration(now - job.createdAt)} ago`);
+    header.push(`Goal: ${clip(job.goal, GOAL_CHARS)}`);
+    const sections = [header.join("\n")];
+    const executions = Object.values(state?.executions ?? {});
+    if (executions.length)
+        sections.push([`Executions (${executions.length}):`, ...executions.map(executionLine)].join("\n"));
+    const pending = Object.values(state?.nodes ?? {}).filter(node => !node.executionId);
+    if (pending.length)
+        sections.push(["Nodes without executions:", ...pending.map(executionLine)].join("\n"));
+    const terminal = new Set(job.result?.terminalExecutionIds ?? []);
+    const outputs = executions.filter(execution => execution.output !== undefined);
+    if (outputs.length)
+        sections.push(["Outputs:", ...outputs.map(execution => `## ${execution.id} · ${execution.executionId}${terminal.has(execution.executionId) ? " · terminal" : ""}${execution.decision ? ` · decision ${execution.decision}` : ""}\n${execution.output}`)].join("\n\n"));
+    const workspaces = executions.filter(execution => execution.workspace);
+    if (workspaces.length)
+        sections.push(["Workspaces:", ...workspaces.map(execution => `- ${execution.executionId}: ${workspaceLine(execution.workspace)}`)].join("\n"));
+    if (job.execution)
+        sections.push(`Current graph (revision ${job.execution.revision}):\n${formatGraph(job.execution.graph)}`);
+    return sections.join("\n\n");
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chrok/pi-braid",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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.4"
+    "@chrok/braid": "0.3.6"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -14,9 +14,9 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "1.0.1",
-    "@earendil-works/pi-tui": "1.0.1",
-    "@earendil-works/pi-coding-agent": "1.0.1",
+    "@earendil-works/pi-ai": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
     "typescript": "^5.0.0",
     "tsx": "^4.0.0",
     "@types/node": "^22.0.0"