@chrok/pi-braid 0.2.1 → 0.3.0

package/README.md

@@ -5,11 +5,15 @@
 This optional Pi extension runs Braid agent graphs as background jobs with
 bounded loops, live updates, pause/resume, and a live flow panel.
 
-**0.2 API:** The npm badge shows the published version; see
+**0.3 API:** The npm badge shows the published version; see
 [GitHub releases](https://github.com/Epsirom/braid/releases) for release notes.
-Review the [migration guide](https://github.com/Epsirom/braid/blob/v0.2.0/docs/compatibility.md#migrating-from-01-to-02)
-before upgrading an existing graph. For the previous API, use the
-[0.1.3 guide](https://github.com/Epsirom/braid/blob/v0.1.3/integrations/pi/README.md).
+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).
+For the previous release, use the
+[0.2.1 guide](https://github.com/Epsirom/braid/blob/v0.2.1/integrations/pi/README.md).
 
 It registers:
 
@@ -26,11 +30,19 @@ Submission and completion reminders use short session handles such as `job-1`.
 Status, cancellation and the panel accept either that exact handle or the original
 UUID. Unknown IDs report available handles; IDs are never guessed or fuzzy-matched.
 
+Invalid submissions show the validation error directly in the tool result,
+including failures before a background job is created. Correct the indicated
+field or graph relationship and resubmit. `braid_status` lookup failures also
+display their error text.
+
 The parent can continue independent work or finish its response while a job runs.
 On completion, failure, or cancellation, the extension sends a custom
 `system-reminder` containing the job ID and a request to retrieve its results.
-Pi queues it as a follow-up during streaming; when idle, it starts a new agent
-turn automatically. The agent should wait for this reminder rather than poll.
+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.
 Stopping the foreground response does not stop background jobs.
 
 Jobs live in memory for the current Pi session. Quitting, reloading extensions,
@@ -38,6 +50,38 @@ or switching/forking sessions aborts outstanding work and suppresses its
 reminders. Job IDs cannot be retrieved after that lifecycle ends. They are not
 persistent processes outside Pi.
 
+## Graph definitions
+
+Each node has a unique `id` and one of these four shapes:
+
+| `type` | `prompt` | `choices` | `workspace` |
+| --- | --- | --- | --- |
+| `execute` | Required | Omit | Optional: `read-only` or `worktree` |
+| `decision` | Required | Required, non-empty, distinct strings | Optional: `read-only` or `worktree` |
+| `merge` | Optional | Omit | Omit; combines changes in an isolated worktree |
+| `integrate` | Optional | Omit | Omit; applies changes to the invoking checkout |
+
+All four types accept `model`, `notifyOnCompletion`, `pauseAfter`, and
+`requireSuccess`. Omit optional fields when unused. Execute/decision nodes
+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.
+
+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: []`
+for independent roots. Historical `executionId` pins are available only in
+`braid_update`, after the source execution exists.
+
+A retry cycle needs a `loops` definition and exactly one feedback edge from a
+decision back to the loop entry, carrying both `choice` and `feedback: "<loop-id>"`.
+The decision needs another choice to exit. `maxIterations` counts the first round
+as well as retries. The body must be acyclic after removing the feedback edge;
+external edges enter only at the entry and leave only through that decision.
+Loops cannot nest or overlap. See the [loop example](../../docs/execution-control.md#structured-loops).
+
 ## Shared prompts
 
 The `braid` tool accepts a `promptTemplates` object alongside `goal`, `nodes`,
@@ -85,11 +129,33 @@ expectedRevision, executionIds})`. Definitions can be changed while executions
 are running or waiting, including inside a loop. Existing instances keep their
 captured prompt, inputs, and policy; completion routes through the latest graph.
 Rejected revisions/changes have no effects. Finalized jobs cannot be reopened.
+Include new nodes and their dependencies/loops in the same update. A new node
+without incoming edges is a runnable root; another node's `pauseAfter` does not
+hold it. After a rejected update, retry the complete corrected patch, including
+edges, loops, and resume IDs, instead of staging disconnected nodes separately.
+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.
+After cancellation or finalization there are no resumable paused executions;
+the event log still records where pauses occurred.
+
+`upsertNodes` replaces whole node definitions, so include all required fields.
+`promptTemplates` and `loops` replace their entire map/list when supplied;
+omitting them preserves the current definitions. `removeEdges` matches exact
+identities, including any `choice`, `feedback`, or `executionId`: omitted fields
+are not wildcards. `resume` and `braid_resume.executionIds` take paused execution
+IDs, not node IDs.
 
 `requireSuccess` defaults to false. Optional failures retain artifacts and allow
 unconditional recovery; required failures cancel siblings and fail the job after
 cleanup. All loops declare a finite `maxIterations`; total `maxExecutions`
 defaults to 1000 and spans updates. Deadlines keep running through pauses.
+The graph timeout includes time waiting for the parent to inspect and update a
+paused graph, and resuming does not extend it. Reserve time for integration.
 
 See [execution control](../../docs/execution-control.md) for loop schemas, exact
 update semantics, historical dependencies, and workspace lineage. There is no
@@ -109,6 +175,8 @@ The panel renders a Mermaid flowchart, node states, elapsed times, context-token
 estimates or provider-reported usage, context-window sizes, filesystem tool-call
 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, with the full text available on expansion.
 
 `/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.
@@ -119,6 +187,11 @@ 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.
 
 ## When Pi will use Braid
 
@@ -130,8 +203,8 @@ an explicit per-turn planning policy to Pi's system prompt and tool metadata:
   changes spanning multiple files, call Braid first when two or more concerns
   can be handled independently; use `workspace: "read-only"` for analysis,
   review, routing, and synthesis, and worktrees for implementation;
-- do not use Braid for simple one-step answers, trivial direct edits, or shell
-  work; keep tests and shell commands in the parent agent;
+- do not use Braid for simple one-step answers, trivial direct edits, or a single
+  shell command; writable nodes can implement, test, and fix their own work;
 - the user does not need to say “Braid” or design the graph;
 - when Braid fits, the model should submit a graph and refine it with live updates when needed, continue independent work, and retrieve the terminal outputs after
   the completion reminder.
@@ -142,16 +215,18 @@ or strengthen the project/system prompt for that model. The adapter explicitly
 asks the model to make the delegation choice before directly inspecting the
 repository. Do not add a generic `always call braid` rule: that would waste
 model calls and bypass direct tools.
-Merge nodes combine snapshots; integrate nodes apply selected changes to the caller; the parent reviews results and runs tests.
+Merge nodes combine and validate snapshots; integrate nodes apply selected changes to the caller; the parent reviews results and performs any remaining validation.
 Each node gets a new Pi AI context containing only the Braid goal, its node prompt,
 labelled direct predecessor outputs, and workspace metadata. It receives Pi's
 `read` and `ls`, plus `grep` when local `rg` is available and `find` when
 local `fd`/`fdfind` is available. Missing search dependencies are reported in the
 node prompt, with `ls`/`read` as alternatives. Dependencies are checked before
 exposing search tools and again before executing them; missing tools are not
-installed by Braid. Git worktrees additionally receive `write` and `edit`.
-It receives no parent transcript, shell tools, test runner, skills, or arbitrary
-code execution. Decision nodes additionally receive `decide`. Git nodes receive
+installed automatically by Braid. Writable workspaces additionally receive `write`,
+`edit`, and Pi's `bash` tool (`powershell` is also exposed on Windows), so nodes
+can install local dependencies, build, and run tests. Read-only nodes have no shell.
+Nodes receive no parent transcript, skills, or inherited extension/MCP tools.
+Decision nodes additionally receive `decide`. Git nodes receive
 local Git inspection; merge/integrate nodes also receive Git integration commands and
 `finish_merge`. Merge agents receive bounded changed-file lists, diff statistics
 and previews; integrate also receives the source checkout's dirty status. The model-facing `git`
@@ -237,7 +312,8 @@ Root executions use the initial job snapshot, including tracked and non-ignored
 untracked caller edits. Later loop rounds get new worktrees; they never reuse a
 previous invocation's workspace. `workspace: "read-only"` disables write/edit
 while retaining an isolated snapshot. Outside Git, all filesystem access is
-read-only. Search tools require installed `rg`/`fd`; shell/tests are unavailable.
+read-only, including no shell tools. Search tools require installed `rg`/`fd`.
+Writable nodes can run shell commands and tests in their assigned working directory.
 
 `merge` combines predecessor results into a new isolated worktree. `integrate`
 applies selected changes to the invoking checkout and preserves user edits. Both
@@ -261,6 +337,12 @@ results, explicitly connect them to an integrate node:
 }
 ```
 
+Checkpoints save tracked changes and non-ignored new files, following normal
+`git add --all` semantics. Existing tracked files remain tracked even when they
+match ignore rules. Ignored dependencies, caches, and build outputs are discarded
+with the worktree and are not carried to successors; keep required outputs in
+non-ignored paths. Files deliberately staged with `git add --force` remain tracked.
+
 `braid_status` retains execution-keyed workspace paths, checkpoint refs, and target
 merge dispositions. Cleanup removes worktrees while keeping immutable checkpoints.
 Inspect with `git show <checkpointRef>:path`. Integration additionally saves a
@@ -268,10 +350,22 @@ pre-write backup ref. A failed integration can leave partial source changes or
 conflicts; core does not reset the caller's checkout. Integrations serialize
 within the process, without locking parent edits or other processes.
 
-Pi's guarded writes reject external paths, Git metadata, symlinks, hard links,
-and special files. This is a capability boundary, not an OS sandbox. A custom
-runner must honor the core write barrier so cancellation can drain writes before
-cleanup. Calling the Pi runner without an assigned workspace stays read-only.
+Pi's guarded `write`/`edit` reject external paths, Git metadata, symlinks, hard links,
+and special files. Shell tools run with host permissions and can bypass those
+checks. Prompts require writes to stay in the assigned workspace, reserve source
+checkout changes for integrate nodes, and protect shared Git refs/configuration,
+other nodes, ports, databases, caches, and external services. These are cooperation
+rules, not an OS sandbox. Shell tools are created for each invocation; parent
+extension/MCP tools and their hooks are not inherited.
+
+Shell calls join the core write barrier: cancellation/timeout stops the process
+group (Windows uses `taskkill /T`), and checkpointing waits for the call to settle.
+On POSIX, remaining children in the command's process group are also stopped on
+normal command exit. Windows cleanup after the parent process exits is best effort.
+Run commands in the foreground; do not daemonize or leave servers/watchers running.
+Processes that detach from the group and external services are not contained by
+this mechanism. A custom runner must honor the core write barrier as well.
+Calling the Pi runner without an assigned workspace stays read-only.
 
 Tool and time budgets are unlimited by default in Pi. To set finite hard limits,
 pass any of these fields in the `braid` tool's `options`:

package/dist/display.js

@@ -324,6 +324,13 @@ export function applyEvent(state, event) {
         });
     if (state.events.length > MAX_VISIBLE_EVENTS)
         state.events.shift();
+    if (event.type === "graph_completed" || event.type === "graph_failed") {
+        state.status = event.type === "graph_completed" ? "completed" : "failed";
+        state.pausedExecutionIds = [];
+        if (event.type === "graph_failed")
+            state.error = { ...event.error };
+        return;
+    }
     if (event.type === "node_created") {
         Object.defineProperty(state.nodes, event.nodeId, {
             value: {
@@ -421,6 +428,22 @@ export function applyProgress(state, progress) {
         writable: true,
     });
 }
+/** Focused status reads must show the requested execution, including historical ones. */
+export function renderNodeResult(node, expanded, theme, fullOutputPath) {
+    const failed = node.status === "failed";
+    const clean = (value) => stripTerminalSequences(value).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, "");
+    const lines = [
+        theme.fg(failed ? "error" : "accent", `${failed ? "✗" : node.status === "completed" ? "✓" : "○"} Braid node ${compact(node.id, 80)} · ${node.status}`),
+        ...(node.executionId ? [theme.fg("dim", `execution: ${compact(node.executionId, 80)}`)] : []),
+        ...(node.decision ? [theme.fg("accent", `decision: ${compact(node.decision, 80)}`)] : []),
+        ...(node.error ? [theme.fg("error", `${node.error.code}: ${clean(node.error.message)}`)] : []),
+        ...(node.skipReason ? [theme.fg("muted", `skipped: ${node.skipReason}`)] : []),
+        ...(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)}`)] : []),
+    ];
+    return new Text(lines.join("\n"), 0, 0);
+}
 export function renderGraphResult(result, expanded, isPartial, theme, fallback = "", isError = false) {
     if (isError || !result?.nodes) {
         const message = fallback ||
@@ -438,7 +461,9 @@ export function renderGraphResult(result, expanded, isPartial, theme, fallback =
         ? theme.fg("warning", "⟳ Braid executing")
         : result.status === "completed"
             ? theme.fg("success", "✓ Braid completed")
-            : theme.fg("error", "✗ Braid failed");
+            : result.error?.code === "CANCELLED"
+                ? theme.fg("warning", "■ Braid cancelled")
+                : theme.fg("error", "✗ Braid failed");
     const lines = [
         title,
         theme.fg("muted", `${completed}/${nodes.length} completed · ${result.status === "running" ? `${active} active · ${pending} pending · ` : ""}${skipped} skipped · ${failed} failed · ${elapsed(elapsedMs)}`),
@@ -447,9 +472,9 @@ export function renderGraphResult(result, expanded, isPartial, theme, fallback =
         const terminals = Object.keys(result.terminalOutputs);
         if (terminals.length)
             lines.push(theme.fg("accent", `terminals: ${compact(terminals.join(", "), 120)}`));
-        if (result.error)
-            lines.push(theme.fg("error", `${result.error.code}: ${compact(result.error.message, 120)}`));
     }
+    if (result.error)
+        lines.push(theme.fg("error", `${result.error.code}: ${compact(result.error.message, 120)}`));
     if ("pausedExecutionIds" in result && result.pausedExecutionIds?.length)
         lines.push(theme.fg("warning", `${result.pausedExecutionIds.length} paused executions · revision ${result.revision ?? 0}`));
     if ("executions" in result)

package/dist/index.js

@@ -6,54 +6,88 @@ import { defineTool, truncateHead, } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { BraidJobs } from "./jobs.js";
 import { registerBraidCommand } from "./command.js";
-import { renderGraphCall, renderGraphResult } from "./display.js";
-const text = () => Type.String({ minLength: 1 });
+import { renderGraphCall, renderGraphResult, renderNodeResult } from "./display.js";
+const text = (description) => Type.String({ minLength: 1, pattern: "\\S", ...(description ? { description } : {}) });
 const prompt = () => Type.Union([
-    text(),
+    text("Instructions for this node; it does not receive the parent conversation."),
     Type.Object({
-        template: text(),
-        variables: Type.Record(Type.String(), Type.String()),
+        template: text("Exact key in promptTemplates."),
+        variables: Type.Record(Type.String(), Type.String(), {
+            description: "Exactly the template's placeholder names with string values; use {} if there are no placeholders. No missing or extra keys.",
+        }),
     }, { additionalProperties: false }),
-]);
-const timeout = () => Type.Optional(Type.Number({
+], { description: "Required for execute/decision; optional for merge/integrate. A non-blank instruction string or a reference to a declared prompt template." });
+const timeout = (scope) => Type.Optional(Type.Number({
     exclusiveMinimum: 0,
     maximum: 2_147_483_647,
-    description: "Timeout in milliseconds; omit for no time limit",
+    description: scope === "graph"
+        ? "Total wall-clock timeout in milliseconds, including queueing and pauses. Updates/resume do not reset it; reserve time for final integration. Omit for no time limit."
+        : "Timeout in milliseconds per node execution; omit for no time limit.",
 }));
 const toolBudget = (unit) => Type.Optional(Type.Integer({
     minimum: 1,
     maximum: Number.MAX_SAFE_INTEGER,
     description: `Maximum tool ${unit} per node, including decide and rejected requests; omit for no limit`,
 }));
-const nodeParameters = Type.Object({
-    type: StringEnum(["execute", "decision", "merge", "integrate"]),
-    id: text(), prompt: Type.Optional(prompt()), model: Type.Optional(text()),
+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." })),
     requireSuccess: Type.Optional(Type.Boolean({ description: "If true, failure aborts the entire job and cancels running siblings. Default false: unconditional successors can recover." })),
-    workspace: Type.Optional(StringEnum(["read-only", "worktree"], { description: "Execute/decision only. Both use fresh predecessor snapshots in Git; read-only disables writes. Outside Git, all workers are read-only." })),
-    choices: Type.Optional(Type.Array(text(), { minItems: 1, description: "Required only for decision nodes." })),
-}, { additionalProperties: false });
-const edgeParameters = Type.Object({
-    from: text(), to: text(), choice: Type.Optional(text()),
-    feedback: Type.Optional(text()),
-    executionId: Type.Optional(Type.String({ minLength: 1, description: "Pin an exact completed historical source execution; available in braid_update only." })),
+};
+const workspace = Type.Optional(StringEnum(["read-only", "worktree"], {
+    description: "Only for execute/decision; omit for merge/integrate. Defaults to worktree in Git. Both modes use fresh predecessor snapshots; read-only disables writes and shell tools. Outside Git, all workers are read-only.",
+}));
+// Keep all fields visible in one object. Kimi sessions using object-variant
+// unions repeatedly emitted bare merge nodes instead of intended executions.
+// Core validates the conditional requirements before starting or changing a job.
+const nodeParameters = Type.Object({
+    id: commonNodeParameters.id,
+    type: StringEnum(["execute", "decision", "merge", "integrate"], {
+        description: "execute: analyze/implement; decision: choose a route; merge: combine predecessor checkpoints in an isolated worktree; integrate: apply predecessor changes to the invoking checkout.",
+    }),
+    prompt: Type.Optional(prompt()),
+    choices: Type.Optional(Type.Array(text(), { minItems: 1, uniqueItems: true, description: "Required only for decision; omit for every other type. Distinct routing labels used by decide and outgoing choice edges." })),
+    workspace,
+    model: commonNodeParameters.model,
+    notifyOnCompletion: commonNodeParameters.notifyOnCompletion,
+    pauseAfter: commonNodeParameters.pauseAfter,
+    requireSuccess: commonNodeParameters.requireSuccess,
+}, { additionalProperties: false, description: "execute/decision REQUIRE prompt; decision also REQUIRES choices. merge/integrate may omit prompt but MUST omit choices and workspace. Omit unused optional fields. All types accept model, notifyOnCompletion, pauseAfter, and requireSuccess." });
+const edgeFields = {
+    from: text("Source node ID."),
+    to: text("Target node ID."),
+    choice: Type.Optional(text("Only for a decision source: one exact declared choice. Omit for an unconditional dependency, including error recovery.")),
+    feedback: Type.Optional(text("Loop ID, only on the single back edge from its decision to its entry. Requires choice and a matching loops definition; not a boolean. Cannot be combined with executionId.")),
+};
+const edgeParameters = Type.Object(edgeFields, { additionalProperties: false });
+const updateEdgeParameters = Type.Object({
+    ...edgeFields,
+    executionId: Type.Optional(text("Pin a completed historical source execution from braid_status; from must match that execution's node ID. Available only in braid_update, never in the initial graph.")),
 }, { additionalProperties: false });
-const loopParameters = Type.Object({ id: text(), entry: text(), maxIterations: Type.Integer({ minimum: 1 }) }, { additionalProperties: false });
-const templates = Type.Record(Type.String(), text());
+const loopParameters = Type.Object({
+    id: text("Unique loop ID referenced by exactly one edge.feedback."),
+    entry: text("Node ID where every iteration starts; the feedback edge must target this node."),
+    maxIterations: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER, description: "Total rounds including the first, not the number of retries. Choosing feedback on the last round fails with LOOP_LIMIT." }),
+}, { additionalProperties: false, description: "A bounded loop with one entry and a decision that selects retry or exit. The body is acyclic after removing the feedback edge; external edges enter only at entry and leave only from that decision. Loops cannot overlap or nest." });
+const templateDescription = "Named prompt strings. Placeholders use {{name}} with names matching [A-Za-z_][A-Za-z0-9_]*. Node variables must match exactly; string values are inserted literally.";
+const templates = Type.Record(Type.String(), text(), { description: templateDescription });
 const braidParameters = Type.Object({
-    goal: text(), nodes: Type.Array(nodeParameters, { minItems: 1 }), edges: Type.Array(edgeParameters),
+    goal: text("Shared goal included in every worker's context."),
+    nodes: Type.Array(nodeParameters, { minItems: 1 }),
+    edges: Type.Array(edgeParameters, { description: "Dependencies between node IDs; use [] for independent roots. Cycles require a declared loop and explicit feedback edge. Historical executionId is not allowed at submission." }),
     promptTemplates: Type.Optional(templates), loops: Type.Optional(Type.Array(loopParameters)),
     options: Type.Optional(Type.Object({
-        maxConcurrency: Type.Optional(Type.Integer({ minimum: 1 })),
-        maxExecutions: Type.Optional(Type.Integer({ minimum: 1, description: "Total execution limit across all iterations and updates; default 1000." })),
-        nodeTimeoutMs: timeout(), graphTimeoutMs: timeout(), maxToolRounds: toolBudget("rounds"), maxToolCalls: toolBudget("calls"),
+        maxConcurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum simultaneous node executions; default 4." })),
+        maxExecutions: Type.Optional(Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER, description: "Total execution limit across all iterations and updates; default 1000." })),
+        nodeTimeoutMs: timeout("node"), graphTimeoutMs: timeout("graph"), maxToolRounds: toolBudget("rounds"), maxToolCalls: toolBudget("calls"),
     }, { additionalProperties: false })),
 }, { additionalProperties: false });
 const BRAID_FILESYSTEM_GUIDANCE = "Every execute/decision activation gets a fresh worktree in Git, based on its predecessor execution checkpoint (roots use the initial job snapshot). Set workspace=read-only to disable writes. Multiple independent code snapshots require an explicit merge node. " +
-    "merge combines selected predecessor checkpoints into a new isolated worktree; integrate writes selected changes to the invoking checkout while preserving user edits. Both must call finish_merge using executionId for each source. There is no automatic final integration. " +
+    "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, merge/integrate have local Git integration tools. Search tools require local rg/fd. Outside Git all filesystem access is read-only. Shell, tests, network Git, and recursive Braid calls are unavailable. Run tests in the parent after explicit integration.";
+    "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.";
 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.",
@@ -61,29 +95,57 @@ const BRAID_USAGE_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.",
-    "Do not use braid for a simple one-step answer, a trivial direct edit, shell work, or when decomposition adds no value. The parent reviews results, runs tests, and executes shell commands after Braid completes.",
+    "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.",
+    "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) {
+    // Pi uses details={} for validation/execution errors, including before execute runs.
+    if (!value || typeof value !== "object")
+        return false;
+    const job = value;
+    return typeof job.jobId === "string" && job.jobId.length > 0 &&
+        ["running", "completed", "failed", "cancelled"].includes(job.status ?? "") &&
+        !!job.live && typeof job.live.nodes === "object" && job.live.nodes !== null;
+}
+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 } : {}),
+    };
+}
 export function createBraidTools(jobs) {
     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. " +
-            "Use execute, decision, merge, or integrate nodes. Decision nodes must declare choices and call decide; matching choice edges activate together. Merge/integrate nodes accept multiple predecessors and an optional prompt. Structured loops declare id, entry, maxIterations, and one decision feedback edge labelled feedback=loopId; the body must be acyclic and loops cannot overlap or nest. Each round uses new executions and worktrees. " +
+            "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. ' +
             "For repeated prompts, define promptTemplates and set node prompt to {template: name, variables: {name: value}}; core renders {{name}} placeholders using explicit string variables before execution. " +
             "Unlabelled edges are unconditional. Joins wait for all possible predecessor paths to resolve. " +
             "Nodes see only the goal, their prompt, labelled direct-predecessor outputs, and their filesystem capabilities: " +
-            "no parent history, shell, tests, or recursive Braid calls. " +
+            "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 or allow graph mutation. " +
+            "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. " +
             "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 and merge nodes for integration",
+        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: [
             "Call braid before direct repository inspection when a code task has two or more separable review, debugging, design, test-planning, or implementation concerns; the Braid nodes can inspect the project and edit isolated Git worktrees.",
             "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 user does not need to mention Braid or design the graph.",
-            "Do not use braid for simple one-step answers or trivial direct edits. Keep shell commands and test execution in the parent; use merge nodes for integration.",
+            "Do not use braid for simple one-step answers or trivial direct edits. Let writable nodes run shell commands and tests for their work; use merge nodes to combine and validate snapshots before explicit integration.",
             BRAID_FILESYSTEM_GUIDANCE,
             "Decision nodes additionally receive decide. Nodes cannot call recursive Braid.",
             "Tool and time budgets are unlimited by default. Set maxToolRounds, maxToolCalls, nodeTimeoutMs, or graphTimeoutMs in options to impose hard limits; nodes receive system reminders of their remaining budgets before each model call.",
@@ -92,14 +154,17 @@ export function createBraidTools(jobs) {
         renderCall(args, theme) {
             return renderGraphCall(args, theme);
         },
-        renderResult(result, _options, theme) {
+        renderResult(result, options, theme, ctx) {
             const job = result.details;
-            return new Text(theme.fg(job ? "accent" : "error", job
-                ? `Braid background job ${job.jobId} · ${job.status} · /braid to view`
-                : result.content
-                    .filter((item) => item.type === "text")
-                    .map((item) => item.text)
-                    .join("\n")), 0, 0);
+            const fallback = result.content
+                .filter((item) => item.type === "text")
+                .map((item) => item.text)
+                .join("\n");
+            if (ctx.isError || !isJobSnapshot(job)) {
+                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);
         },
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
             signal?.throwIfAborted();
@@ -119,7 +184,8 @@ export function createBraidTools(jobs) {
                                 jobId: job.handle,
                                 canonicalJobId: job.jobId,
                                 status: job.status,
-                                message: "Running in background. Use braid_status to retrieve progress/results. A completion reminder will resume you; do not poll repeatedly.",
+                                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.",
                             }),
                         },
                     ],
@@ -132,23 +198,36 @@ export function createBraidTools(jobs) {
         },
     });
     const statusParameters = Type.Object({
-        jobId: Type.Optional(text()),
-        executionId: Type.Optional(text()),
-        nodeId: Type.Optional(Type.String({ minLength: 1, description: "Exact node ID; requires jobId. Retrieve this node's full output/error even while the job is running." })),
+        jobId: Type.Optional(text("Exact session handle (e.g. job-1) or UUID; omit all IDs to list jobs.")),
+        executionId: Type.Optional(text("Exact execution ID from braid_status or a reminder; requires jobId. Takes precedence over nodeId; if both are provided they must match.")),
+        nodeId: Type.Optional(text("Exact node ID; requires jobId. Retrieve this node's latest full output/error even while the job is running.")),
     }, { additionalProperties: false });
     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. Large results include a path to the full JSON. Prefer the short handle from submission/reminders. Omit both IDs to list jobs in this session. Completion reminders arrive automatically; avoid repeated polling.",
+        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. 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.",
         parameters: statusParameters,
-        renderResult(result, options, theme) {
+        renderResult(result, options, theme, ctx) {
             const job = result.details;
             const fallback = result.content
                 .filter((item) => item.type === "text")
                 .map((item) => item.text)
                 .join("\n");
-            if (!job)
-                return new Text(fallback, 0, 0);
+            if (ctx.isError)
+                return new Text(theme.fg("error", `✗ ${fallback || "Braid status failed without error details"}`), 0, 0);
+            if (!isJobSnapshot(job))
+                return new Text(fallback || "Braid returned no job details", 0, 0);
+            // Older saved sessions stored only the job snapshot for focused reads.
+            const state = job.result ?? job.execution;
+            const executionId = ctx.args?.executionId;
+            const nodeId = ctx.args?.nodeId;
+            const selectedNode = job.selectedNode ?? (executionId
+                ? state && Object.hasOwn(state.executions, executionId) ? state.executions[executionId] : undefined
+                : nodeId && state && Object.hasOwn(state.nodes, nodeId) ? state.nodes[nodeId] : undefined);
+            if (selectedNode)
+                return renderNodeResult(selectedNode, options.expanded, theme, job.nodeOutputPath);
+            if (executionId || nodeId)
+                return new Text(fallback || "Braid returned no node details", 0, 0);
             if (job.error)
                 return new Text(theme.fg("error", `Braid ${job.status}: ${job.error}`), 0, 0);
             return renderGraphResult({
@@ -171,31 +250,60 @@ 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 full = JSON.stringify({ jobId: job.jobId, handle: job.handle, status: job.status, node }, null, 2);
+                const { id, executionId, status, error, output, ...nodeDetails } = node;
+                const full = JSON.stringify({
+                    jobId: job.jobId, handle: job.handle, status: job.status, execution: executionControl(job),
+                    node: { id, executionId, status, error, output, ...nodeDetails },
+                }, 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}]`;
                 }
                 // Focused reads do not claim the whole job's usage; final job retrieval does.
-                return { content: [{ type: "text", text: preview.content + suffix }], details: job };
+                return { content: [{ type: "text", text: preview.content + suffix }], details: {
+                        ...job, selectedNode: node, ...(nodeOutputPath ? { nodeOutputPath } : {}),
+                    } };
+            }
+            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 preview = truncateHead(JSON.stringify(job, null, 2));
-            const suffix = preview.truncated
-                ? `\n[Preview truncated. ${job.fullOutputPath ? `Full result/log: ${job.fullOutputPath}` : "Full results will be available when the job finishes."}]`
-                : "";
-            const usage = jobs.claimUsage(job.jobId);
+            // 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);
             return {
                 content: [{ type: "text", text: preview.content + suffix }],
-                details: job,
+                details,
                 ...(usage ? { usage } : {}),
             };
         },
     });
-    const cancelParameters = Type.Object({ jobId: text() }, { additionalProperties: false });
+    const cancelParameters = Type.Object({ jobId: text("Exact session handle (e.g. job-1) or UUID returned by braid or braid_status.") }, { additionalProperties: false });
     const cancelTool = defineTool({
         name: "braid_cancel",
         label: "Cancel Braid",
@@ -217,23 +325,37 @@ export function createBraidTools(jobs) {
         },
     });
     const updateParameters = Type.Object({
-        jobId: text(), expectedRevision: Type.Integer({ minimum: 0 }),
-        upsertNodes: Type.Optional(Type.Array(nodeParameters)), removeNodeIds: Type.Optional(Type.Array(text())),
-        addEdges: Type.Optional(Type.Array(edgeParameters)), removeEdges: Type.Optional(Type.Array(edgeParameters)),
-        promptTemplates: Type.Optional(templates), loops: Type.Optional(Type.Array(loopParameters)),
-        resume: Type.Optional(Type.Array(text())),
+        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." }),
+        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." })),
+        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." })),
     }, { additionalProperties: false });
     const updateTool = defineTool({
         name: "braid_update", label: "Update Braid",
-        description: "Atomically edit a running or waiting job using its current expectedRevision from braid_status. Upserts replace complete node definitions; removeNodeIds also removes incident edges. Existing executions and their failure policy remain unchanged. Completion routes through the latest graph. Pin historical inputs with edge.executionId. Optional resume releases paused execution IDs in the same transaction. Rejected updates change nothing; finalized jobs cannot be reopened.",
+        description: "Atomically edit a running or waiting job using its current expectedRevision from braid_status. Upserts replace complete node definitions; removeNodeIds also removes incident edges. Submit new nodes, dependencies, loops, and optional resume together; do not stage disconnected nodes in separate calls, as they can start immediately. Existing executions and their failure policy remain unchanged. Completion routes through the latest graph. Pin historical inputs with edge.executionId. Optional resume releases paused execution IDs in the same transaction. Rejected updates change nothing; retry the entire corrected patch. Finalized jobs cannot be reopened.",
         parameters: updateParameters,
         async execute(_id, params) {
             const { jobId, ...patch } = params;
-            const job = jobs.update(jobId, patch);
-            return { content: [{ type: "text", text: JSON.stringify({ jobId: job.handle, revision: job.execution.revision, pausedExecutionIds: job.execution.pausedExecutionIds }) }], details: job };
+            let job;
+            try {
+                job = jobs.update(jobId, patch);
+            }
+            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 };
         },
     });
-    const resumeParameters = Type.Object({ jobId: text(), expectedRevision: Type.Integer({ minimum: 0 }), executionIds: Type.Array(text(), { minItems: 1 }) }, { additionalProperties: false });
+    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." }),
+    }, { additionalProperties: false });
     const resumeTool = defineTool({
         name: "braid_resume", label: "Resume Braid",
         description: "Release specific paused execution IDs using expectedRevision from braid_status. Independent branches keep running during a pause; this does not reset deadlines or execution limits.",
@@ -249,7 +371,9 @@ export default function braidExtension(pi) {
     const pending = new Map();
     const remind = (message) => {
         try {
-            pi.sendMessage(message, { triggerTurn: true, deliverAs: "followUp" });
+            // Pi consumes steering after the assistant response and its entire tool
+            // batch. followUp waits until the whole foreground task would stop.
+            pi.sendMessage(message, { triggerTurn: true, deliverAs: "steer" });
         }
         catch {
             // Keep failed deliveries pending for the next settled retry.
@@ -273,13 +397,13 @@ export default function braidExtension(pi) {
         const message = {
             customType: "braid-node-completed",
             display: true,
-            content: `[system-reminder] Braid job ${handle} node ${JSON.stringify(nodeId)} execution ${executionId}${iteration ? ` (iteration ${iteration})` : ""} finished with status ${status}${errorCode ? ` (${errorCode})` : ""}. Retrieve its output or error with braid_status(${lookup}) and continue the original task. ${paused ? "Outgoing scheduling is paused. Inspect the current revision, then use braid_update with resume or braid_resume to continue. Independent branches may still be running." : "This execution reminder does not pause downstream scheduling; the job may still be running."} [/system-reminder]`,
+            content: `[system-reminder] Braid job ${handle} node ${JSON.stringify(nodeId)} execution ${executionId}${iteration ? ` (iteration ${iteration})` : ""} finished with status ${status}${errorCode ? ` (${errorCode})` : ""}. Retrieve its output or error with braid_status(${lookup}) and continue the original task. ${paused ? "Outgoing scheduling was paused at completion. Inspect the current status, revision, and pausedExecutionIds; if this execution is still paused, use braid_update with resume or braid_resume to continue. Independent branches may still be running. A finalized job cannot be resumed." : "This execution reminder does not pause downstream scheduling; the job may still be running."} [/system-reminder]`,
             details: { ...completion, reminderId },
         };
         pending.set(reminderId, message);
         remind(message);
     });
-    // Foreground cancellation can discard queued follow-ups. Retry only reminders
+    // Foreground cancellation can discard queued steering. Retry only reminders
     // that never entered context, once Pi has settled and emptied its queues.
     pi.on("message_start", (event) => {
         const message = event.message;

package/dist/jobs.js

@@ -145,7 +145,9 @@ export class BraidJobs {
             const status = job.result.error?.code === "CANCELLED"
                 ? "cancelled"
                 : job.result.status;
-            const full = JSON.stringify({ ...job.result, workspaces: job.workspaces }, null, 2);
+            // 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-"));
@@ -157,6 +159,8 @@ export class BraidJobs {
         }
         catch (error) {
             job.status = "failed";
+            job.live.status = "failed";
+            job.live.pausedExecutionIds = [];
             job.error = error instanceof Error ? error.message : String(error);
             if (reports.length)
                 job.usage = sumPiUsage(reports);

package/dist/runner.js

@@ -3,6 +3,7 @@ import { StringEnum, Type, validateToolCall, } from "@earendil-works/pi-ai";
 import { formatBudgetReminder, gitToolDefinition, finishMergeToolDefinition, mergeInstructions, parseGitToolArguments, parseFinishMergeArguments, } from "@chrok/braid";
 import { createWorktreeWriteTools } from "./write-tools.js";
 import { createAvailableReadTools } from "./read-tools.js";
+import { createWorkspaceShellTools } from "./shell-tools.js";
 /** 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"
@@ -61,7 +62,10 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
         const fileTools = [
             ...readTools.tools,
             ...(writeRoot
-                ? await createWorktreeWriteTools(workingDirectory, writeRoot, request.signal, readOnlyPaths)
+                ? [
+                    ...await createWorktreeWriteTools(workingDirectory, writeRoot, request.signal, readOnlyPaths),
+                    ...createWorkspaceShellTools(workingDirectory),
+                ]
                 : []),
         ];
         // Send only serializable definitions to the model, not execute functions.
@@ -96,12 +100,20 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
                     : workspace.mode === "worktree"
                         ? "You may write and edit files inside your own isolated Git worktree. Use workingDirectory as your cwd; do not write to sourceRoot or any other node's worktree. " +
                             "Each execution starts from its predecessor checkpoint; root executions use the initial job snapshot. Repeated loop executions get new worktrees. Inspect exact predecessor checkpoints with git show. " +
-                            "Describe your changes in your final answer. Core will save your checkpoint and clean up the worktree. Only explicit integrate nodes write to the source checkout. "
+                            "Describe your changes and verification in your final answer. Core will save your checkpoint and clean up the worktree. Leave source checkout changes to explicit integrate nodes. "
                         : "This node has no writable workspace assigned. Its filesystem tools are read-only; you cannot write or edit files. " +
                             "Read workingDirectory directly; in Git this is an isolated predecessor snapshot. Outside Git it is the source directory. " +
                             (request.git ? "Use Git inspection to review changes or predecessor checkpoints; the assigned snapshot contains predecessor edits. " : "")) +
                 mergeInstructions(request) +
-                "You cannot run shell commands, run tests, or call arbitrary tools. " +
+                (writeRoot
+                    ? "You may use Pi's shell tools to install local dependencies, build, run tests, and fix failures in workingDirectory. " +
+                        "Worktrees isolate code snapshots, not host permissions: shell access is not sandboxed. Keep file changes within your assigned workspace; integrate alone may edit sourceRoot. " +
+                        "Git refs, configuration, hooks, and object storage are shared with the caller and other nodes. Do not change shared Git configuration, hooks, branches, Braid refs, or worktree registrations, and do not switch branches. Prefer the provided git tool for inspection and merge operations. " +
+                        "Nodes run concurrently and loop executions start fresh: ports, databases, caches, credentials, and external services are shared. Use execution-specific temporary resources, avoid global installs and destructive or externally visible actions unless explicitly requested, and do not spawn recursive Braid/Pi agents. " +
+                        "Run commands in the foreground; command completion, timeout, or cancellation stops their process group. Do not daemonize or leave servers/watchers running. " +
+                        "Checkpoints include tracked changes and non-ignored new files; ignored dependencies, caches, and build products are not carried to successors and are removed during cleanup. "
+                    : "You cannot run shell commands or tests in this read-only workspace. ") +
+                "Parent extension/MCP tools, skills, and session history are not inherited; use only the tools provided here. " +
                 ((request.node.type === "merge" || request.node.type === "integrate") && workspace.mode === "read-only"
                     ? "This merge has no Git sources; call finish_merge with an empty dispositions array before answering."
                     : request.node.type === "decision"
@@ -223,7 +235,7 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
                 }
                 const args = validateToolCall(allToolDefinitions, call);
                 const execute = () => tool.execute(call.id, args, request.signal, undefined);
-                const result = ["write", "edit"].includes(call.name) && request.withWorkspaceWrite
+                const result = ["write", "edit", "bash", "powershell"].includes(call.name) && request.withWorkspaceWrite
                     ? await request.withWorkspaceWrite(execute)
                     : await execute();
                 request.signal.throwIfAborted();
@@ -233,7 +245,7 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
                     toolName: call.name,
                     content: result.content,
                     ...(result.details === undefined ? {} : { details: result.details }),
-                    isError: false,
+                    isError: result.isError ?? false,
                     timestamp: Date.now(),
                 };
             }

package/dist/shell-tools.js

@@ -0,0 +1,109 @@
+import { execFile, spawn } from "node:child_process";
+import { constants } from "node:os";
+import { join } from "node:path";
+import { createBashTool, createPowerShellTool, getShellConfig, getPowerShellConfig, } from "@earendil-works/pi-coding-agent";
+/** Pi owns the tool schema/output handling; Braid owns the command lifetime. */
+function managedOperations(resolveShell, prefix = "") {
+    return {
+        async exec(command, cwd, { onData, signal, timeout, env }) {
+            signal?.throwIfAborted();
+            if (timeout !== undefined && (!Number.isFinite(timeout) || timeout <= 0 || timeout * 1000 > 2_147_483_647))
+                throw new Error("Invalid timeout: expected positive seconds within the timer limit");
+            const config = resolveShell();
+            signal?.throwIfAborted();
+            const stdin = config.commandTransport === "stdin";
+            const child = spawn(config.shell, stdin ? config.args : [...config.args, prefix + command], {
+                cwd, env, detached: process.platform !== "win32", windowsHide: true,
+                stdio: [stdin ? "pipe" : "ignore", "pipe", "pipe"],
+            });
+            const closed = new Promise(resolve => child.once("close", () => resolve()));
+            const exited = new Promise((resolve, reject) => {
+                child.once("error", reject);
+                child.once("exit", resolve);
+            });
+            child.stdout.on("data", onData);
+            child.stderr.on("data", onData);
+            if (stdin) {
+                child.stdin.on("error", () => { });
+                child.stdin.end(prefix + command);
+            }
+            let termination;
+            const terminate = () => termination ??= (async () => {
+                if (!child.pid)
+                    return;
+                if (process.platform === "win32") {
+                    await new Promise((resolve, reject) => {
+                        execFile(join(process.env.SystemRoot ?? "C:\\Windows", "System32", "taskkill.exe"), ["/F", "/T", "/PID", String(child.pid)], { windowsHide: true }, error => {
+                            // taskkill reports 128 when the process has already exited.
+                            if (error && error.code !== 128)
+                                reject(error);
+                            else
+                                resolve();
+                        });
+                    });
+                }
+                else {
+                    try {
+                        process.kill(-child.pid, "SIGKILL");
+                    }
+                    catch (error) {
+                        if (error.code !== "ESRCH")
+                            throw error;
+                    }
+                }
+            })();
+            // The completion path awaits termination; event handlers must not create
+            // unhandled rejections while the shell is still exiting.
+            const stop = () => { void terminate().catch(() => { }); };
+            let timedOut = false;
+            const timer = timeout === undefined ? undefined : setTimeout(() => {
+                timedOut = true;
+                stop();
+            }, timeout * 1000);
+            signal?.addEventListener("abort", stop, { once: true });
+            if (signal?.aborted)
+                stop();
+            let exitCode;
+            try {
+                exitCode = await exited;
+            }
+            finally {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", stop);
+                // Stop leftover children even on successful command completion. Commands
+                // cannot leave a server/watch process writing during checkpoint/cleanup.
+                try {
+                    await terminate();
+                }
+                finally {
+                    // A daemon can leave the process group while holding inherited pipes.
+                    // Bound pipe draining; this process-group cleanup is not an OS sandbox.
+                    const drainTimer = setTimeout(() => {
+                        child.stdout.destroy();
+                        child.stderr.destroy();
+                    }, 250);
+                    try {
+                        await closed;
+                    }
+                    finally {
+                        clearTimeout(drainTimer);
+                    }
+                }
+            }
+            if (signal?.aborted)
+                throw new Error("aborted");
+            if (timedOut)
+                throw new Error(`timeout:${timeout}`);
+            return { exitCode: exitCode ?? (child.signalCode ? 128 + (constants.signals[child.signalCode] ?? 0) : 1) };
+        },
+    };
+}
+export function createWorkspaceShellTools(cwd) {
+    return [
+        createBashTool(cwd, { operations: managedOperations(getShellConfig), exposeSessionEnvironment: false }),
+        ...(process.platform === "win32" ? [createPowerShellTool(cwd, {
+                operations: managedOperations(getPowerShellConfig, "try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}\n"),
+                exposeSessionEnvironment: false,
+            })] : []),
+    ];
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chrok/pi-braid",
-  "version": "0.2.1",
+  "version": "0.3.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.2.1"
+    "@chrok/braid": "0.3.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",