@chrok/braid 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,72 @@
 
 ## Unreleased
 
+## 0.3.0 — 2026-10-04
+
+### Features and breaking changes
+
+- Give writable Pi nodes built-in shell tools for dependency installation, builds,
+  tests, and repair. Shell calls participate in cancellation and the workspace
+  write barrier before checkpointing; prompts describe workspace boundaries and
+  shared resources. Read-only nodes still have no shell, and parent extension/MCP
+  tools are not inherited
+  ([#41](https://github.com/Epsirom/braid/pull/41)) — @Epsirom.
+- Checkpoint tracked changes and non-ignored new files using normal Git staging
+  semantics. Ignored dependencies, caches, and build outputs are no longer
+  automatically archived or passed to successors; already tracked and deliberately
+  force-added files remain tracked
+  ([#41](https://github.com/Epsirom/braid/pull/41)) — @Epsirom.
+
+See the [0.2 → 0.3 migration guide](docs/compatibility.md#migrating-from-02-to-03)
+before upgrading if you rely on shell-free workers or preservation of ignored
+outputs. Use read-only nodes or a custom runner to restrict worker capabilities,
+and keep successor artifacts in non-ignored or deliberately tracked paths.
+
+### Fixes
+
+- Include `changes.baseCommit` in merge-source previews and explain cumulative
+  diffs versus invocation snapshots. Read-only review checkpoints can otherwise
+  suggest an empty patch; multi-parent checkpoints also need an explicit
+  strategy instead of a bare cherry-pick
+  ([#42](https://github.com/Epsirom/braid/pull/42)) — @Epsirom.
+- Display Pi submission and status errors even when the host supplies empty
+  result details; failed graph definitions no longer appear as background jobs
+  with an undefined ID/status. Validation errors identify offending nodes/edges
+  and explain how to declare feedback cycles
+  ([#42](https://github.com/Epsirom/braid/pull/42)) — @Epsirom.
+- Clarify Pi node requirements, loop/template parameters, and revision controls
+  while retaining a flat provider-facing node schema with type-specific core
+  validation. Restrict historical execution pins to updates. Submission/update
+  replies echo accepted graph types and policies
+  ([#42](https://github.com/Epsirom/braid/pull/42)) — @Epsirom.
+- Deliver Pi completion/pause reminders at the next model step using steering,
+  after the current tool batch, instead of queuing follow-ups behind the entire
+  foreground task. Clarify that pause reminders need a current-state check
+  ([#42](https://github.com/Epsirom/braid/pull/42)) — @Epsirom.
+- Explain atomic update failures and retrying complete patches: new nodes and
+  their edges/loops must be submitted together to avoid starting disconnected
+  roots while another execution is paused. Discourage repeated replacement jobs
+  when a definition problem recurs
+  ([#42](https://github.com/Epsirom/braid/pull/42)) — @Epsirom.
+- Show the requested execution's output/error in focused Pi status reads and
+  include the current revision and paused IDs, separately from its captured
+  revision. Preserve this rendering for older saved Pi sessions
+  ([#42](https://github.com/Epsirom/braid/pull/42)) — @Epsirom.
+- Keep errors, control fields, and Pi usage ahead of large status payloads;
+  save complete running snapshots and include failed-worker provider usage as
+  `piUsage` in exported final results
+  ([#42](https://github.com/Epsirom/braid/pull/42)) — @Epsirom.
+- Update live status on graph completion/failure and clear resumable pause IDs
+  when finalizing, while retaining pause history in the event log. Loop
+  validation now names feedback targets and edges that bypass the loop entry
+  ([#42](https://github.com/Epsirom/braid/pull/42)) — @Epsirom.
+
+### New Contributors
+
+No first-time human contributors in this release.
+
+[Full comparison](https://github.com/Epsirom/braid/compare/v0.2.1...v0.3.0).
+
 ## 0.2.1 — 2026-10-04
 
 ### Maintenance

package/README.md

@@ -11,20 +11,38 @@ checkpoints; explicit `integrate` nodes apply selected work to the source checko
 [![npm Pi](https://img.shields.io/npm/v/%40chrok%2Fpi-braid?label=%40chrok%2Fpi-braid)](https://www.npmjs.com/package/@chrok/pi-braid)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-**0.2 API:** Experimental, Node.js 22+, ESM. The framework-agnostic core
+**0.3 API:** Experimental, Node.js 22+, ESM. The framework-agnostic core
 has no runtime dependencies; the OpenAI-compatible runner and Pi extension are
 optional integrations. The npm badges show published versions; see
 [GitHub releases](https://github.com/Epsirom/braid/releases) for release notes.
-Read the [0.1 → 0.2 migration guide](docs/compatibility.md#migrating-from-01-to-02)
-before upgrading. For the previous API, use the
-[0.1.3 documentation](https://github.com/Epsirom/braid/tree/v0.1.3).
+Read the [0.2 → 0.3 migration guide](docs/compatibility.md#migrating-from-02-to-03)
+before upgrading; users coming from 0.1 also need the
+[0.1 → 0.2 guide](docs/compatibility.md#migrating-from-01-to-02).
+For the previous release, use the
+[0.2.1 documentation](https://github.com/Epsirom/braid/tree/v0.2.1).
 
 | Package | Purpose |
 | --- | --- |
 | [@chrok/braid](https://www.npmjs.com/package/@chrok/braid) | Core runtime and optional OpenAI-compatible runner |
 | [@chrok/pi-braid](https://www.npmjs.com/package/@chrok/pi-braid) | Pi background jobs, execution controls, reminders, and live flow panel; installs the matching core dependency |
 
-## What changed in 0.2?
+## What changed in 0.3?
+
+- **Shell tools in writable Pi nodes.** Workers can install dependencies, build,
+  test, and repair in their assigned workspaces. Read-only nodes remain shell-free;
+  worktrees use host permissions and are not security sandboxes.
+- **Git-aware checkpoints.** Tracked changes and non-ignored new files are
+  checkpointed. Keep artifacts needed by successors in non-ignored or deliberately
+  tracked paths; ignored dependencies and build outputs are no longer preserved.
+- **Pi reminders between steps.** Completion and pause reminders arrive after
+  the current response and tool batch, before the next model step.
+- **Clearer errors and status.** Invalid graphs show actionable errors; focused
+  reads show the selected execution's output/error and current control state.
+  Full status exports retain snapshots and failed-worker usage.
+
+See the [changelog](CHANGELOG.md#030--2026-10-04) for all fixes and credits.
+
+## Execution-control foundation from 0.2
 
 - **Editable graphs, captured executions.** `startBraid` exposes revision-checked
   updates and pause/resume; `executionId` identifies a particular invocation,
@@ -416,10 +434,11 @@ provides `request.merge.sources` and `request.merge.finish(dispositions)` to
 merge agents. Adapters must enforce workspace capabilities and wrap mutating
 file tools in `request.withWorkspaceWrite(operation)`, so cleanup waits for
 in-flight writes and rejects later writes. Core Git mutations use this barrier.
-The included Pi adapter provides guarded `write`/`edit` alongside its read tools.
+The included Pi adapter provides guarded `write`/`edit` and Pi shell tools alongside its read tools.
 For read-only workspaces, adapters must omit mutating tools; the core write
-barrier also rejects writes. This includes all nodes outside Git. Pi never provides
-`bash`, `powershell`, or a test runner to nodes.
+barrier also rejects writes. This includes all nodes outside Git. Writable Pi nodes
+can use `bash` (and `powershell` on Windows) to build and run tests. Shell calls
+participate in the write barrier and forward cancellation to their processes.
 
 `request.predecessors` contains direct active predecessors in incoming-edge
 order, including failures on unconditional edges with an `error` field. Each source appears once:
@@ -467,7 +486,10 @@ The model-facing Git tool separates `command` from `args`, for example
 accepts the complete argument array. Duplicate command prefixes, network Git,
 branch switching, and filesystem-boundary overrides are rejected.
 
-Instances checkpoint before downstream admission. All source checkpoints remain
+Instances checkpoint tracked changes and non-ignored new files before downstream
+admission. Ignored dependencies, caches, and build products are discarded on cleanup;
+files already tracked or explicitly force-added remain tracked under normal Git rules.
+All source checkpoints remain
 reusable; no merge consumes or deletes a predecessor's result. Job cleanup
 archives and removes owned worktrees, retaining refs under
 `refs/braid/checkpoints/`. Integration additionally captures a pre-write
@@ -489,19 +511,22 @@ isolated from those source edits. See [execution control](docs/execution-control
 
 **The adapter is a trust boundary, not a security sandbox.** It must avoid shared
 conversation state, expose only its declared capabilities, and forward `signal` to its provider.
-The core never gives the model arbitrary code execution or a recursive Braid
-tool. An optional Pi adapter translates this same contract without changing the
-runtime; the core package does not depend on Pi. See
+The core does not supply shell tools or a recursive Braid tool; adapters choose
+their tool capabilities. The Pi adapter supplies shell tools to writable nodes
+without changing the runtime; the core package does not depend on Pi. See
 [`integrations/pi/README.md`](integrations/pi/README.md) for installation and testing.
 
 The included OpenAI-compatible adapter uses fresh Chat Completions contexts,
 a strict `decide({ choice })` tool and one tool-free continuation for decisions.
 Merge/integrate nodes use a local `git` / `finish_merge` tool loop; ordinary OpenAI nodes
-have no filesystem tools. Pi exposes read and guarded write tools plus these
-core Git/merge tools. Tool errors go back to merge agents for recovery. Both
+have no filesystem tools. Pi exposes read, guarded write, and shell tools plus
+these core Git/merge tools. Tool errors go back to nodes for recovery. Both
 adapters sum usage across their model calls and forward cancellation.
 Pi writes reject external paths, Git metadata, symlinks, hard links, and special
-files. These checks are not an OS sandbox against concurrent filesystem attacks.
+files. Shell tools can bypass these checks and run with host permissions; prompts
+require nodes to respect workspace boundaries, shared Git state, and external
+resources. Parent extension/MCP tools and hooks are not inherited. These checks
+and cooperation rules are not an OS sandbox.
 See the [Pi filesystem capabilities](integrations/pi/README.md#node-filesystem-capabilities).
 
 Pi tool and time budgets are unlimited by default. Its `options.maxToolRounds`

package/ROADMAP.md

@@ -6,12 +6,25 @@ and thin host adapters. This is a direction for discussion, not a delivery sched
 
 ## Release status
 
-The 0.2 execution-control foundation is implemented. Source availability and npm
-availability are separate milestones. Check
+The 0.3 workspace and Pi reliability changes are implemented on top of the 0.2
+execution-control foundation. Source availability and npm availability are
+separate milestones. Check
 [GitHub releases](https://github.com/Epsirom/braid/releases),
 [@chrok/braid](https://www.npmjs.com/package/@chrok/braid), and
 [@chrok/pi-braid](https://www.npmjs.com/package/@chrok/pi-braid) for published versions.
 
+## 0.3 implemented changes
+
+- [x] Shell tools for writable Pi nodes, with cancellation and checkpoint write
+  barriers; keep read-only nodes shell-free.
+- [x] Git-aware checkpoints that preserve tracked changes and non-ignored files.
+- [x] Pi completion/pause reminders between model steps, with actionable graph
+  errors and complete focused status reads and exports.
+- [x] Cumulative merge-source baselines and atomic update/retry guidance.
+
+Read the [0.2 → 0.3 migration guide](docs/compatibility.md#migrating-from-02-to-03)
+for workspace capabilities and artifact preservation.
+
 ## 0.2 implemented foundation
 
 - [x] Separate editable node definitions from captured execution instances,
@@ -41,9 +54,10 @@ provenance, and clean installation before marking publication complete.
 
 - Exercise real edit → review → refine → integrate tasks and use the results to
   improve migration examples, update-conflict diagnostics, and recovery guidance.
-- Refresh scheduler measurements for 0.2 before optimizing data structures.
-  Include execution history, updates, and loops; measure Git workspace costs
-  separately. The [checked-in benchmark](docs/benchmark.md) is a 0.1 baseline.
+- Refresh scheduler measurements for the current execution model before
+  optimizing data structures. Include execution history, updates, and loops;
+  measure Git workspace costs separately. The [checked-in benchmark](docs/benchmark.md)
+  is a 0.1 baseline.
 - Explore explicit retention and cleanup policies for execution history, Git
   recovery refs, and Pi temporary result files without breaking result retrieval,
   reusable checkpoints, or usage accounting.
@@ -59,7 +73,7 @@ provenance, and clean installation before marking publication complete.
   consumption, package builds, and the complete Node/platform matrix. Keep Node
   declarations on 22.x while Node 22 remains the minimum supported runtime.
 
-## Scope after 0.2
+## Scope after 0.3
 
 The original fixed-DAG-only boundary no longer applies. Bounded loops, live
 graph changes, parent-controlled pause/resume, and execution history are part of

package/SECURITY.md

@@ -44,17 +44,21 @@ answer that question.
 - Braid isolates invocation context; it is not a process or filesystem sandbox.
   A custom runner is trusted code with the host process's permissions.
 - The core manages Git snapshots, worktrees, checkpoint refs, and merge tools.
-  Pi workers can write/edit their assigned Git worktree. Integrate agents can apply
+  Writable Pi workers can write/edit and run shell commands in their assigned Git
+  worktree. Shells run with host permissions; prompts constrain workspace writes,
+  shared Git state, and external side effects. Integrate agents can apply
   changes to the source checkout; merge agents use isolated worktrees; they are not restricted to read-only analysis.
   Outside Git, Pi file tools stay read-only. Read paths can expose files outside
   the checkout and disclose content to a model provider.
 - Execute/decision nodes can request `workspace: "read-only"` inside Git. Pi
-  omits write/edit tools, and core rejects write-barrier operations. Git inspection
+  omits write/edit and shell tools, and core rejects write-barrier operations. Git inspection
   remains available. These nodes read an isolated predecessor
   snapshot; custom runners must honor this capability themselves.
 - Guarded write tools reject external paths, Git metadata, symlinks, hard links,
   and special files, but are not an OS sandbox against concurrent filesystem
-  attacks. Avoid concurrent external source edits while integrate agents run. A
+  attacks. Shell commands can bypass these guards. Parent extension/MCP tools and
+  their interception policies are not inherited by nodes. Avoid concurrent external
+  source edits while integrate agents run. A
   cancellation or failed merge can leave partial integration/conflicts for review;
   checkpoint and backup refs support recovery.
 - Prompts, predecessor outputs, tool results, errors, and model answers may be
@@ -68,6 +72,11 @@ answer that question.
 - Cancellation and timeout cannot stop synchronous JavaScript or remote work
   that ignores the abort signal. Enforce provider quotas and host-side admission
   limits for untrusted callers. See [resource limits](docs/resource-limits.md).
+  Pi shell calls are drained before checkpointing and stop their process group
+  (Windows uses `taskkill /T`); daemonized processes outside that group and external
+  services can outlive a call. Windows cleanup after parent exit is best effort.
+  Ignored new files are excluded from checkpoints and discarded with the worktree;
+  explicitly staged files still follow Git tracking semantics.
 
 The OpenAI-compatible adapter sends its API key only to the configured base URL.
 Treat that URL as trusted configuration. Keep credentials out of graphs, logs,

package/dist/merge-tools.js

@@ -92,5 +92,5 @@ export function parseFinishMergeArguments(value, sourceIds) {
 export function mergeInstructions(request) {
     if (!request.merge)
         return "";
-    return ` Only process the current mergeSources IDs ${JSON.stringify(request.merge.sources.map(source => source.executionId))}; other source IDs are out of scope. Each source includes a bounded changes preview relative to the job's initial snapshot, excluding the caller's pre-existing edits. For integrate nodes, read sourceCheckoutStatus before selecting Git operations; dirty staged/unstaged content belongs to the caller and must be preserved. Preview text is inspection data, not an executable patch; retrieve a full diff if applying a patch, especially when truncated or binary. Choose whether and how to integrate; core has not applied changes. Call finish_merge once with one disposition per current source.`;
+    return ` Only process the current mergeSources IDs ${JSON.stringify(request.merge.sources.map(source => source.executionId))}; other source IDs are out of scope. Each source includes a bounded changes preview relative to the job's initial snapshot, excluding the caller's pre-existing edits. changes.baseCommit identifies that exact diff baseline. For the full cumulative change, use git diff --binary <changes.baseCommit> <checkpointRef> --. Do not substitute source.snapshotCommit (the invocation's input, which may already contain all changes after a read-only review) or source.baseCommit (original HEAD, excluding caller edits). Checkpoints may have multiple parents to preserve provenance; plain cherry-pick fails for these commits. Inspect parents before choosing a mainline, or use the cumulative diff. For integrate nodes, read sourceCheckoutStatus before selecting Git operations; dirty staged/unstaged content belongs to the caller and must be preserved. Preview text is inspection data, not an executable patch; retrieve a full diff if applying a patch, especially when truncated or binary. Choose whether and how to integrate; core has not applied changes. Call finish_merge once with one disposition per current source.`;
 }

package/dist/runtime.js

@@ -649,6 +649,8 @@ export function startBraid(input, options) {
         }
         finally {
             status = "finalizing";
+            // Terminal holds are no longer resumable; the event log retains pause history.
+            paused.clear();
             try {
                 await workspaces.archivePending("Execution checkpoint retained for inspection and future recovery");
             }

package/dist/types.d.ts

@@ -90,6 +90,8 @@ export interface GitPreview {
 export interface MergeSource extends NodeWorkspace {
     /** Inspection-only summaries relative to the job’s initial snapshot; omitted by custom runners. */
     changes?: {
+        /** Exact preview/diff baseline, including caller edits; supplied by built-in workspaces. */
+        baseCommit?: string;
         files: string[];
         filesTruncated: boolean;
         stat: GitPreview;

package/dist/validate.js

@@ -91,13 +91,13 @@ export function compileGraph(input) {
     const byId = new Map();
     for (const node of input.nodes) {
         requireValid(isRecord(node), "Node must be an object");
-        requireValid(node.type === "execute" || node.type === "decision" || (node.type === "merge" || node.type === "integrate"), "Unknown node type");
+        requireValid(text(node.id), "Node id must be a non-empty string");
+        requireValid(node.type === "execute" || node.type === "decision" || (node.type === "merge" || node.type === "integrate"), `Node '${node.id}': unknown node type; expected execute, decision, merge, or integrate`);
         fields(node, node.type === "decision"
             ? ["type", "id", "prompt", "model", "choices", "workspace", "notifyOnCompletion", "requireSuccess", "pauseAfter"]
             : node.type === "execute"
                 ? ["type", "id", "prompt", "model", "workspace", "notifyOnCompletion", "requireSuccess", "pauseAfter"]
-                : ["type", "id", "prompt", "model", "notifyOnCompletion", "requireSuccess", "pauseAfter"], "Node");
-        requireValid(text(node.id), "Node id must be a non-empty string");
+                : ["type", "id", "prompt", "model", "notifyOnCompletion", "requireSuccess", "pauseAfter"], `Node '${node.id}' (${node.type})`);
         requireValid(!byId.has(node.id), `Duplicate node id '${node.id}'`);
         const prompt = (node.type === "merge" || node.type === "integrate") && node.prompt === undefined
             ? (node.type === "merge" ? "Merge selected predecessor results into this new isolated worktree. Resolve conflicts and account for every source with finish_merge." : "Integrate selected predecessor results into the invoking checkout. Preserve user changes and account for every source with finish_merge.")
@@ -139,7 +139,7 @@ export function compileGraph(input) {
     }
     for (const edge of input.edges) {
         requireValid(isRecord(edge), "Edge must be an object");
-        fields(edge, ["from", "to", "choice", "feedback", "executionId"], "Edge");
+        fields(edge, ["from", "to", "choice", "feedback", "executionId"], `Edge '${edge.from}' -> '${edge.to}'`);
         requireValid(edge.executionId === undefined || text(edge.executionId), "Invalid edge executionId");
         requireValid(edge.feedback === undefined || text(edge.feedback), "Invalid edge feedback");
         requireValid(!edge.feedback || !edge.executionId, "Feedback cannot pin an execution");
@@ -179,7 +179,7 @@ export function compileGraph(input) {
                 topologicalOrder.push(byId.get(edge.to));
         }
     }
-    requireValid(topologicalOrder.length === nodes.length, "Graph contains a cycle without a declared feedback edge");
+    requireValid(topologicalOrder.length === nodes.length, "Graph contains a cycle without a declared feedback edge. Declare a bounded loop in loops and label its decision-to-entry edge with choice and feedback=loopId");
     const loops = new Map();
     const membership = new Map();
     requireValid(input.loops === undefined || Array.isArray(input.loops), "Graph loops must be an array");
@@ -208,7 +208,7 @@ export function compileGraph(input) {
         requireValid(feedback.length === 1, `Loop '${loop.id}' needs exactly one feedback edge`);
         const back = feedback[0];
         const decision = byId.get(back.from);
-        requireValid(back.to === loop.entry && decision.type === "decision" && back.choice !== undefined, `Loop '${loop.id}' feedback must route a decision choice to its entry`);
+        requireValid(back.to === loop.entry && decision.type === "decision" && back.choice !== undefined, `Loop '${loop.id}' feedback edge '${back.from}' -> '${back.to}' must route a decision choice to its entry '${loop.entry}'. Set feedback on the decision-to-entry edge and include choice`);
         requireValid(decision.choices.some(choice => choice !== back.choice), `Loop '${loop.id}' needs an exit choice`);
         const ancestors = reachable(back.from, true);
         const members = new Set([...reachable(loop.entry)].filter(id => ancestors.has(id)));
@@ -220,8 +220,8 @@ export function compileGraph(input) {
         for (const edge of edges) {
             if (edge.feedback || edge.executionId)
                 continue;
-            requireValid(!(!members.has(edge.from) && members.has(edge.to) && edge.to !== loop.entry), `Loop '${loop.id}' has multiple entries`);
-            requireValid(!(members.has(edge.from) && !members.has(edge.to) && edge.from !== back.from), `Loop '${loop.id}' must exit through its feedback decision`);
+            requireValid(!(!members.has(edge.from) && members.has(edge.to) && edge.to !== loop.entry), `Loop '${loop.id}' has multiple entries: edge '${edge.from}' -> '${edge.to}' bypasses entry '${loop.entry}'. Route external dependencies to '${loop.entry}'`);
+            requireValid(!(members.has(edge.from) && !members.has(edge.to) && edge.from !== back.from), `Loop '${loop.id}' must exit through its feedback decision '${back.from}': edge '${edge.from}' -> '${edge.to}' leaves from another node`);
         }
         loops.set(loop.id, { id: loop.id, entry: loop.entry, maxIterations: loop.maxIterations, feedback: back, members });
     }

package/dist/workspaces.d.ts

@@ -22,7 +22,7 @@ export declare class GitWorkspaces {
     private sealCheckpoint;
     all(): Record<string, NodeWorkspace>;
     pending(): string[];
-    /** Checkpoint every file, including ignored node outputs, before releasing a worktree. */
+    /** Preserve tracked changes and non-ignored new files before releasing a worktree. */
     private checkpoint;
     private release;
     /** Only archive/remove here. Choosing merge/cherry-pick/apply always belongs to the agent. */

package/dist/workspaces.js

@@ -180,7 +180,7 @@ export class GitWorkspaces {
             // A temporary index captures tracked edits/deletions and non-ignored new files
             // without changing the parent's real index, branch, or working files.
             await git(sourceRoot, ["add", "--all", "--", "."], options);
-            // Include ignored files contributed by selected sources, without capturing the
+            // Include ignored files deliberately tracked by selected sources, without capturing the
             // caller's unrelated ignored build products or dependencies.
             const existing = [];
             for (const file of extraFiles) {
@@ -345,7 +345,7 @@ export class GitWorkspaces {
             .filter(workspace => workspace.worktreeRoot && ["preparing", "ready", "failed"].includes(workspace.state))
             .map(workspace => workspace.executionId ?? workspace.nodeId);
     }
-    /** Checkpoint every file, including ignored node outputs, before releasing a worktree. */
+    /** Preserve tracked changes and non-ignored new files before releasing a worktree. */
     async checkpoint(workspace) {
         if (workspace.checkpointRef)
             return;
@@ -366,7 +366,7 @@ export class GitWorkspaces {
                     throw error;
             }
         }
-        await git(cwd, ["add", "--force", "--all", "--", "."], options);
+        await git(cwd, ["add", "--all", "--", "."], options);
         const tree = await git(cwd, ["write-tree"], options);
         const baseTree = await git(cwd, ["rev-parse", `${workspace.snapshotCommit}^{tree}`]);
         const parents = [...new Set([workspace.snapshotCommit, ...(this.mergeParents.get(workspace.executionId ?? workspace.nodeId) ?? [])])];
@@ -527,7 +527,7 @@ export class GitWorkspaces {
                 const stat = await gitPreview(source.sourceRoot, [...diffArgs.slice(0, -1), "--stat", "--"], Math.floor(4_000 / count));
                 const diff = await gitPreview(source.sourceRoot, diffArgs, Math.min(6_000, Math.floor(24_000 / count)));
                 const names = files.text.slice(0, files.text.lastIndexOf("\0") + 1).split("\0").filter(Boolean);
-                sources.push({ ...source, changes: { files: names, filesTruncated: files.truncated, stat, diff } });
+                sources.push({ ...source, changes: { baseCommit: baseline.snapshotCommit, files: names, filesTruncated: files.truncated, stat, diff } });
             }
             const sourceStatus = integrating && target ? await gitPreview(target, ["status", "--porcelain=v1", "--untracked-files=all"], 4_000) : undefined;
             return {

package/docs/compatibility.md

@@ -6,7 +6,7 @@
 | Pi package | Node.js 22.19+, Pi 1.0.1 is the pinned validation target |
 | CI | Core minimum Node 22.0; both packages on Node 22.19 and 24 on Linux, macOS, Windows |
 | OpenAI-compatible runner | Chat Completions text and function-tool calls; decisions and merge/integrate nodes require tool calling |
-| Browsers / CommonJS | No supported browser build or CommonJS entry point in 0.2 |
+| Browsers / CommonJS | No supported browser build or CommonJS entry point in 0.3 |
 
 The CI matrix describes configured checks; see actual workflow results for each
 commit. Offline HTTP fixtures validate the adapter contract. They do not prove
@@ -19,10 +19,10 @@ The wildcard is a loader/distribution convention, **not a claim that every Pi
 version works**. Test the whole Pi suite before updating the supported target.
 The offline host compatibility test loads the extension into a real Pi session
 with an in-memory model provider. It checks worker prompt/tool normalization and
-exactly one automatic continuation per node/job reminder delivered during
-`agent_settled`, including retrieval of a node output while its job still runs.
-This covers the Pi 0.86/0.87 transcript and settling changes without provider
-credentials or network model calls. Version 0.1.0 was originally validated with
+reminder delivery between model steps after the current tool batch, idle
+continuation, and acknowledgement, including retrieval of a node output while
+its job still runs. These fixtures run without provider credentials or network
+model calls. Version 0.1.0 was originally validated with
 Pi 0.85.1; the current checkout's pinned validation target is 1.0.1.
 The Pi npm package declares an exact dependency on the matching `@chrok/braid`
 release. npm installs the core automatically; Pi does not bundle another copy of
@@ -32,7 +32,7 @@ Git must be installed for workspace execution inside a Git checkout. Non-Git
 text-only runs do not require Git workspace management.
 ## Migrating from 0.1 to 0.2
 
-This release deliberately changes the execution and workspace contracts:
+Version 0.2 deliberately changed the execution and workspace contracts:
 
 - Replace old source-checkout `merge` nodes with `integrate`. The new `merge`
   combines inputs in a fresh isolated worktree.
@@ -71,6 +71,35 @@ separate gate reminder; when both preferences are enabled it supplies the single
 completion reminder for that instance. Cancellation still sends failure reminders
 for opted-in running instances.
 
+## Migrating from 0.2 to 0.3
+
+Version 0.3 changes workspace capabilities and checkpoint contents:
+
+- Writable Pi nodes now receive `bash` and, on Windows, `powershell`, allowing
+  dependency installation, builds, and tests within a node. If a graph relies on
+  workers having no shell, set execute/decision nodes to `workspace: "read-only"`
+  (which also disables file writes), or use a custom runner with the required
+  capability policy. Writable shell access uses host permissions and prompt-based
+  cooperation rules; worktrees are not a security sandbox. Parent extension/MCP
+  tools and their hooks are not inherited.
+- Core checkpoints now follow `git add --all` semantics instead of force-adding
+  every output. Move artifacts needed by successors or for recovery to non-ignored
+  paths, or deliberately track them. Already tracked files, including files
+  explicitly staged with `git add --force`, remain tracked even when they match
+  ignore rules. Untracked ignored outputs are discarded when worktrees are removed,
+  including after failed or cancelled executions. This applies to every adapter.
+- Shell commands must run in the foreground. On POSIX, Braid stops remaining
+  children in the command's process group even on normal completion; Windows uses
+  best-effort process-tree cleanup. Run a temporary server and its checks within
+  one foreground command and clean it up before returning. Detached daemons and
+  external services are not contained by this lifecycle.
+
+No graph field, result shape, or event schema migration is required. Pi now
+delivers completion/pause reminders after the current assistant response and
+tool batch, before the next model step, rather than waiting for the entire
+foreground task to finish. Fetch current status before updating or resuming a
+paused execution because the reminder describes the state when it was queued.
+
 ## Versioning
 
 Core and Pi release together with matching versions. During 0.x, patch releases

package/docs/execution-control.md

@@ -135,6 +135,17 @@ workspace; source worktrees remain available until job cleanup. Integration
 captures a `backupRef` first and serializes source-checkout access within the
 process. It must preserve unrelated staged, unstaged, and untracked caller edits.
 
+Each merge source's `changes.baseCommit` identifies the frozen job snapshot used
+for its cumulative diff preview, including the caller's initial uncommitted
+edits. Retrieve the full patch with
+`git diff --binary <changes.baseCommit> <checkpointRef> --` when choosing patch
+integration. `source.snapshotCommit` is that invocation's input: after a read-only
+review it may equal the checkpoint, yielding an empty diff despite earlier
+changes. `source.baseCommit` is the original HEAD and excludes uncommitted edits.
+Checkpoints can have multiple parents recording merged sources. A bare
+`cherry-pick` then fails; inspect the parents before choosing a mainline, or use
+the cumulative diff. The runtime does not choose or apply a merge strategy.
+
 There is no implicit final integration. Each instance is checkpointed before
 successors are released, including partial work on optional failure. Finalization
 archives/removes owned worktrees while retaining checkpoint refs. Cancelled or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrok/braid",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "TypeScript runtime for LLM agent graphs with bounded loops, live updates, and isolated Git worktrees",
   "type": "module",