@chrok/braid 0.1.3 → 0.2.1

package/dist/workspaces.js

@@ -70,7 +70,7 @@ async function git(cwd, args, options = {}) {
         ...(options.signal ? { signal: options.signal } : {}),
         maxBuffer: 8 * 1024 * 1024,
     });
-    return stdout.trim();
+    return args.includes("-z") ? stdout : stdout.trim();
 }
 /** Read-only, bounded output. A large diff cannot fail workspace preparation or flood the model. */
 async function gitPreview(cwd, args, limit) {
@@ -91,7 +91,7 @@ async function gitPreview(cwd, args, limit) {
     }
     return { text: output.slice(0, limit), truncated: overflow || output.length > limit };
 }
-/** Writable workers share a snapshot; explicit read-only workers inspect the live cwd. */
+/** Each execution owns a fresh worktree derived from immutable predecessor checkpoints. */
 export class GitWorkspaces {
     cwd;
     onWorkspace;
@@ -99,12 +99,13 @@ export class GitWorkspaces {
     records = new Map();
     locations = new Map();
     allocated = new Set();
+    mergeParents = new Map();
     constructor(cwd, onWorkspace) {
         this.cwd = cwd;
         this.onWorkspace = onWorkspace;
     }
     report(workspace) {
-        this.records.set(workspace.nodeId, workspace);
+        this.records.set(workspace.executionId ?? workspace.nodeId, workspace);
         try {
             this.onWorkspace?.({ ...workspace });
         }
@@ -140,7 +141,7 @@ export class GitWorkspaces {
         }
         return realpath(sourceRoot);
     }
-    async snapshot() {
+    async snapshot(extraFiles = []) {
         const sourceRoot = await this.sourceRoot();
         if (!sourceRoot)
             return undefined;
@@ -179,6 +180,21 @@ 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
+            // caller's unrelated ignored build products or dependencies.
+            const existing = [];
+            for (const file of extraFiles) {
+                try {
+                    await access(join(sourceRoot, file));
+                    existing.push(file);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+            }
+            for (let index = 0; index < existing.length; index += 256)
+                await git(sourceRoot, ["add", "--force", "--all", "--", ...existing.slice(index, index + 256)], options);
             const tree = await git(sourceRoot, ["write-tree"], options);
             const baseTree = baseCommit ? await git(sourceRoot, ["rev-parse", `${baseCommit}^{tree}`]) : undefined;
             const snapshotCommit = tree === baseTree ? baseCommit : await git(sourceRoot, [
@@ -203,59 +219,78 @@ export class GitWorkspaces {
             await rm(`${index}.lock`, { force: true });
         }
     }
-    async prepare(request) {
-        request.signal.throwIfAborted();
-        if (request.node.type !== "merge" && request.node.workspace === "read-only") {
-            const sourceRoot = await this.sourceRoot();
-            request.signal.throwIfAborted();
-            const workspace = {
-                nodeId: request.node.id, mode: "read-only", workingDirectory: this.cwd, state: "ready",
-                ...(sourceRoot ? { sourceRoot } : {}),
-            };
-            this.report(workspace);
-            return workspace;
-        }
-        let pending = this.snapshots.get(request.execution.runId);
-        if (!pending) {
-            // Do not bind the shared snapshot to one node's cancellation signal.
-            pending = this.snapshot();
-            this.snapshots.set(request.execution.runId, pending);
+    /** Freeze the job's root snapshot before any invocation can write to the checkout. */
+    async initialize(runId) {
+        if (!this.snapshots.has(runId))
+            this.snapshots.set(runId, this.snapshot());
+        await this.snapshots.get(runId);
+    }
+    id(request) {
+        return request.execution.executionId ?? request.node.id;
+    }
+    async inputCommit(request, snapshot) {
+        const commits = [...new Set(request.predecessors.map(value => value.workspace?.checkpointCommit).filter((value) => !!value))];
+        if (!commits.length)
+            return snapshot.snapshotCommit;
+        const trees = await Promise.all(commits.map(commit => git(snapshot.sourceRoot, ["rev-parse", `${commit}^{tree}`])));
+        if (new Set(trees).size === 1)
+            return commits[0];
+        for (const candidate of commits) {
+            let containsAll = true;
+            for (const ancestor of commits) {
+                try {
+                    await git(snapshot.sourceRoot, ["merge-base", "--is-ancestor", ancestor, candidate]);
+                }
+                catch (error) {
+                    if (error.code !== 1)
+                        throw error;
+                    containsAll = false;
+                    break;
+                }
+            }
+            if (containsAll)
+                return candidate;
         }
-        const snapshot = await pending;
+        throw new WorkspaceInputError("Multiple independent predecessor snapshots require an explicit merge node");
+    }
+    async prepare(request, merge = false) {
         request.signal.throwIfAborted();
+        await this.initialize(request.execution.runId);
+        const snapshot = await this.snapshots.get(request.execution.runId);
+        const executionId = this.id(request);
         if (!snapshot) {
             const workspace = {
-                nodeId: request.node.id, mode: "read-only", workingDirectory: this.cwd, state: "ready",
+                nodeId: request.node.id, executionId, mode: "read-only", workingDirectory: this.cwd, state: "ready",
             };
             this.report(workspace);
             return workspace;
         }
+        const commit = merge ? snapshot.snapshotCommit : await this.inputCommit(request, snapshot);
+        request.signal.throwIfAborted();
         const worktreeRoot = join(snapshot.directory, crypto.randomUUID());
+        const readOnly = request.node.type !== "merge" && request.node.type !== "integrate" && request.node.workspace === "read-only";
         const workspace = {
-            nodeId: request.node.id, mode: "worktree", state: "preparing",
+            nodeId: request.node.id, executionId, mode: readOnly ? "read-only" : "worktree", state: "preparing",
             sourceRoot: snapshot.sourceRoot, worktreeRoot,
             workingDirectory: resolve(worktreeRoot, snapshot.cwdSuffix),
-            snapshotCommit: snapshot.snapshotCommit,
+            snapshotCommit: commit,
             ...(snapshot.baseCommit ? { baseCommit: snapshot.baseCommit } : {}),
         };
-        this.locations.set(request.node.id, snapshot);
+        this.locations.set(executionId, snapshot);
         this.report(workspace);
         try {
-            // Finish registration even if cancellation arrives during creation. Report
-            // the retained path before observing cancellation, so it can be recovered.
             await withWorktreeLock(snapshot.commonDirectory, async () => {
                 request.signal.throwIfAborted();
-                await git(snapshot.sourceRoot, ["worktree", "add", "--detach", worktreeRoot, snapshot.snapshotCommit], {
+                await git(snapshot.sourceRoot, ["worktree", "add", "--detach", worktreeRoot, commit], {
                     hooksDirectory: snapshot.hooksDirectory,
                 });
             });
-            // The original cwd may be an empty or ignored directory absent from Git.
             await mkdir(workspace.workingDirectory, { recursive: true });
             workspace.state = "ready";
         }
         catch (error) {
             workspace.state = "failed";
-            throw new Error(`Cannot prepare isolated node worktree at ${worktreeRoot}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+            throw new Error(`Cannot prepare isolated execution worktree at ${worktreeRoot}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
         }
         finally {
             this.report(workspace);
@@ -263,19 +298,58 @@ export class GitWorkspaces {
         request.signal.throwIfAborted();
         return workspace;
     }
+    /** Seal before releasing any downstream execution, including failures with partial writes. */
+    async seal(request) {
+        try {
+            await this.sealCheckpoint(request);
+        }
+        catch (error) {
+            throw new WorkspaceCheckpointError(error instanceof Error ? error.message : String(error), { cause: error });
+        }
+    }
+    async sealCheckpoint(request) {
+        const workspace = this.records.get(this.id(request));
+        if (!workspace || workspace.checkpointRef || workspace.state === "failed")
+            return;
+        if (workspace.mode === "integrate") {
+            const baseline = (await this.snapshots.get(request.execution.runId));
+            const selected = this.mergeParents.get(this.id(request)) ?? [];
+            const files = new Set();
+            for (const commit of selected) {
+                const paths = await git(baseline.sourceRoot, ["diff", "--name-only", "-z", baseline.snapshotCommit, commit, "--"]);
+                for (const path of paths.split("\0").filter(Boolean))
+                    files.add(path);
+            }
+            const after = await this.snapshot([...files]);
+            if (!after)
+                throw new Error("Integration checkout disappeared");
+            const parents = [...new Set([after.snapshotCommit, ...selected])];
+            const commit = parents.length === 1 ? after.snapshotCommit : await git(after.sourceRoot, [
+                "-c", "user.name=Braid", "-c", "user.email=braid@localhost", "-c", "commit.gpgsign=false",
+                "commit-tree", after.snapshotTree, ...parents.flatMap(parent => ["-p", parent]), "-m", "Braid integration checkpoint",
+            ], { hooksDirectory: after.hooksDirectory });
+            workspace.checkpointCommit = commit;
+            workspace.checkpointRef = `refs/braid/checkpoints/${crypto.randomUUID()}`;
+            await git(after.sourceRoot, ["update-ref", workspace.checkpointRef, commit]);
+            this.report(workspace);
+        }
+        else if (workspace.worktreeRoot) {
+            await this.checkpoint(workspace);
+        }
+    }
     all() {
-        return Object.fromEntries([...this.records].map(([id, workspace]) => [id, { ...workspace }]));
+        return structuredClone(Object.fromEntries(this.records));
     }
     pending() {
         return [...this.records.values()]
-            .filter(workspace => workspace.mode === "worktree" && ["preparing", "ready", "failed"].includes(workspace.state))
-            .map(workspace => workspace.nodeId);
+            .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. */
     async checkpoint(workspace) {
         if (workspace.checkpointRef)
             return;
-        const location = this.locations.get(workspace.nodeId);
+        const location = this.locations.get(workspace.executionId ?? workspace.nodeId);
         const cwd = workspace.worktreeRoot;
         const options = { hooksDirectory: location.hooksDirectory };
         // A Git tree stores only a submodule commit, never files written inside it.
@@ -294,9 +368,11 @@ export class GitWorkspaces {
         }
         await git(cwd, ["add", "--force", "--all", "--", "."], options);
         const tree = await git(cwd, ["write-tree"], options);
-        const commit = tree === location.snapshotTree ? workspace.snapshotCommit : await git(cwd, [
+        const baseTree = await git(cwd, ["rev-parse", `${workspace.snapshotCommit}^{tree}`]);
+        const parents = [...new Set([workspace.snapshotCommit, ...(this.mergeParents.get(workspace.executionId ?? workspace.nodeId) ?? [])])];
+        const commit = tree === baseTree && parents.length === 1 ? workspace.snapshotCommit : await git(cwd, [
             "-c", "user.name=Braid", "-c", "user.email=braid@localhost", "-c", "commit.gpgsign=false",
-            "commit-tree", tree, "-p", workspace.snapshotCommit, "-m", `Braid node checkpoint: ${workspace.nodeId}`,
+            "commit-tree", tree, ...parents.flatMap(parent => ["-p", parent]), "-m", `Braid node checkpoint: ${workspace.nodeId}`,
         ], options);
         const suffix = createHash("sha256").update(cwd).digest("hex");
         const ref = `refs/braid/checkpoints/${suffix}`;
@@ -305,27 +381,6 @@ export class GitWorkspaces {
         workspace.checkpointRef = ref;
         this.report(workspace);
     }
-    /** Run only after declared nodes settle, so consumers retain their source paths. */
-    async discardUnchanged() {
-        const errors = [];
-        for (const id of this.pending()) {
-            const workspace = this.records.get(id);
-            // Incomplete preparation must follow the existing failure/recovery path.
-            // A failed invocation with a successfully prepared workspace is still ready.
-            if (workspace.state !== "ready")
-                continue;
-            try {
-                await this.checkpoint(workspace);
-                if (workspace.checkpointCommit === workspace.snapshotCommit)
-                    await this.release(id, "discarded", "No changes from snapshot");
-            }
-            catch (error) {
-                errors.push(error);
-            }
-        }
-        if (errors.length)
-            throw new AggregateError(errors, "Some workspaces could not be checked or removed; their paths are retained in workspaces");
-    }
     async release(id, disposition, reason) {
         const workspace = this.records.get(id);
         const location = this.locations.get(id);
@@ -376,7 +431,7 @@ export class GitWorkspaces {
         for (const snapshot of this.allocated) {
             // Ownership is explicit; a POSIX path prefix would miss retained Windows
             // worktrees and recursively delete data after checkpoint/cleanup failure.
-            const live = [...this.records.values()].some(workspace => workspace.mode === "worktree" && this.locations.get(workspace.nodeId) === snapshot &&
+            const live = [...this.records.values()].some(workspace => !!workspace.worktreeRoot && this.locations.get(workspace.executionId ?? workspace.nodeId) === snapshot &&
                 ["ready", "preparing", "failed"].includes(workspace.state));
             if (!live) {
                 try {
@@ -398,8 +453,8 @@ export class GitWorkspaces {
             throw new Error("Git input must be a string");
         const mutate = ["add", "commit", "merge", "cherry-pick", "apply", "restore"];
         const command = args[0];
-        if (!gitCommands(request.node.type === "merge").includes(command))
-            throw unavailableGitCommand(command, request.node.type === "merge");
+        if (!gitCommands(request.node.type === "merge" || request.node.type === "integrate").includes(command))
+            throw unavailableGitCommand(command, request.node.type === "merge" || request.node.type === "integrate");
         const blockedOptions = ["--output", "--ext-diff", "--textconv", "--unsafe-paths", "--directory", "--strategy", "--gpg-sign", "--work-tree", "--git-dir"];
         // Git accepts abbreviated long options (e.g. --out) and attached short
         // values (-scustom). Apply the same boundary to those spellings.
@@ -411,8 +466,8 @@ export class GitWorkspaces {
             throw new Error("Git arguments cannot override filesystem boundaries, execute external helpers, or select external strategies");
         const workspace = request.workspace;
         const cwd = workspace.mode === "read-only" ? workspace.workingDirectory
-            : workspace.mode === "merge" ? workspace.sourceRoot : workspace.worktreeRoot;
-        const location = this.locations.get(request.node.id);
+            : workspace.mode === "integrate" ? workspace.sourceRoot : workspace.worktreeRoot;
+        const location = this.locations.get(this.id(request));
         const actualArgs = [command,
             ...(["diff", "show", "log"].includes(command) ? ["--no-ext-diff", "--no-textconv"] : []),
             ...args.slice(1),
@@ -437,51 +492,44 @@ export class GitWorkspaces {
         return mutate.includes(command) ? request.withWorkspaceWrite(execute) : execute();
     }
     async beginMerge(request, sourceIds) {
-        // Discover the source without allocating a merge worktree: agents integrate
-        // directly in the caller's checkout, under a repository-scoped mutex.
-        let pending = this.snapshots.get(request.execution.runId);
-        if (!pending) {
-            pending = this.snapshot();
-            this.snapshots.set(request.execution.runId, pending);
-        }
-        let snapshot = await pending;
-        const unlock = snapshot ? await lock(snapshot.sourceRoot, request.signal) : () => { };
+        await this.initialize(request.execution.runId);
+        const baseline = await this.snapshots.get(request.execution.runId);
+        const integrating = request.node.type === "integrate";
+        const unlock = integrating && baseline ? await lock(baseline.sourceRoot, request.signal) : () => { };
         let finished = false;
-        let resolutions;
-        const ids = sourceIds.filter(id => this.pending().includes(id));
+        let resolutions = [];
+        const ids = [...new Set(sourceIds)].filter(id => this.records.get(id)?.checkpointRef);
         try {
             request.signal.throwIfAborted();
-            if (snapshot) {
-                snapshot = await this.snapshot();
-                this.snapshots.set(request.execution.runId, Promise.resolve(snapshot));
+            if (integrating && baseline) {
+                const before = (await this.snapshot());
+                const workspace = {
+                    nodeId: request.node.id, executionId: this.id(request), mode: "integrate",
+                    workingDirectory: resolve(before.sourceRoot, before.cwdSuffix), sourceRoot: before.sourceRoot,
+                    snapshotCommit: before.snapshotCommit, state: "ready",
+                    backupRef: `refs/braid/merge-backups/${crypto.randomUUID()}`,
+                };
+                await git(before.sourceRoot, ["update-ref", workspace.backupRef, before.snapshotCommit]);
+                this.locations.set(this.id(request), before);
+                this.report(workspace);
+                request.workspace = workspace;
             }
-            for (const id of ids)
-                await this.checkpoint(this.records.get(id));
-            const workspace = snapshot ? {
-                nodeId: request.node.id, mode: "merge", workingDirectory: snapshot.sourceRoot,
-                sourceRoot: snapshot.sourceRoot, snapshotCommit: snapshot.snapshotCommit, state: "ready",
-            } : { nodeId: request.node.id, mode: "read-only", workingDirectory: this.cwd, state: "ready" };
-            if (snapshot) {
-                workspace.backupRef = `refs/braid/merge-backups/${crypto.randomUUID()}`;
-                await git(snapshot.sourceRoot, ["update-ref", workspace.backupRef, snapshot.snapshotCommit], { hooksDirectory: snapshot.hooksDirectory });
+            else {
+                request.workspace = await this.prepare(request, true);
             }
-            request.workspace = workspace;
-            if (snapshot)
-                this.locations.set(request.node.id, snapshot);
-            this.report(workspace);
-            const sourceStatus = snapshot ? await gitPreview(snapshot.sourceRoot, ["status", "--porcelain=v1", "--untracked-files=all"], 4_000) : undefined;
+            const target = request.workspace.worktreeRoot ?? request.workspace.sourceRoot;
             const sources = [];
             for (const id of ids) {
                 const source = this.records.get(id);
-                const diffArgs = ["diff", "--no-ext-diff", "--no-textconv", "--no-renames", source.snapshotCommit, source.checkpointRef, "--"];
+                const diffArgs = ["diff", "--no-ext-diff", "--no-textconv", "--no-renames", baseline.snapshotCommit, source.checkpointRef, "--"];
                 const count = Math.max(1, ids.length);
                 const files = await gitPreview(source.sourceRoot, [...diffArgs.slice(0, -1), "--name-only", "-z", "--"], Math.floor(8_000 / count));
                 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)));
-                // Truncated NUL output must not invent a partial filename.
                 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 } });
             }
+            const sourceStatus = integrating && target ? await gitPreview(target, ["status", "--porcelain=v1", "--untracked-files=all"], 4_000) : undefined;
             return {
                 sources,
                 ...(sourceStatus ? { sourceStatus: { ...sourceStatus, dirty: sourceStatus.text.length > 0 || sourceStatus.truncated } } : {}),
@@ -490,37 +538,30 @@ export class GitWorkspaces {
                     if (finished)
                         throw new Error("finish_merge must be called exactly once");
                     validateMergeDispositions(ids, decisions);
-                    if (snapshot && await git(snapshot.sourceRoot, ["ls-files", "--unmerged"]))
-                        throw new Error("Unresolved Git conflicts remain in the source checkout");
+                    if (target && await git(target, ["ls-files", "--unmerged"]))
+                        throw new Error("Unresolved Git conflicts remain in the target workspace");
                     resolutions = structuredClone(decisions);
+                    const workspace = this.records.get(this.id(request));
+                    workspace.dispositions = structuredClone(decisions);
+                    this.report(workspace);
                     finished = true;
                 },
                 complete: async (success) => {
                     try {
-                        const errors = [];
-                        // Check again after all tracked writes have drained: an adapter can
-                        // invoke more tools after finish_merge in the same model response.
-                        if (success && snapshot && await git(snapshot.sourceRoot, ["ls-files", "--unmerged"])) {
-                            success = false;
-                            errors.push(new Error("Unresolved Git conflicts remain in the source checkout"));
-                        }
-                        for (const id of ids) {
-                            const decision = success && finished ? resolutions.find(value => value.nodeId === id) : undefined;
-                            try {
-                                await this.release(id, decision?.disposition ?? "archived", decision?.reason ?? "Merge agent did not complete; changes preserved in checkpointRef");
-                            }
-                            catch (error) {
-                                errors.push(error);
-                            }
-                        }
-                        this.snapshots.delete(request.execution.runId);
-                        if (errors.length)
-                            throw new AggregateError(errors, "Some merge sources could not be cleaned up; their paths are retained in workspaces");
+                        if (target && await git(target, ["ls-files", "--unmerged"]))
+                            throw new Error("Unresolved Git conflicts remain in the target workspace");
                         if (success && (!finished || resolutions.some(value => value.disposition === "archived")))
-                            throw new Error("Merge agent did not integrate or explicitly discard every source; remaining changes were archived");
+                            throw new Error("Merge agent did not integrate or explicitly discard every source");
+                        if (success)
+                            this.mergeParents.set(this.id(request), resolutions.filter(value => value.disposition === "integrated").map(value => this.records.get(value.executionId).checkpointCommit));
                     }
                     finally {
-                        unlock();
+                        try {
+                            await this.seal(request);
+                        }
+                        finally {
+                            unlock();
+                        }
                     }
                 },
             };
@@ -531,3 +572,7 @@ export class GitWorkspaces {
         }
     }
 }
+export class WorkspaceInputError extends Error {
+}
+export class WorkspaceCheckpointError extends Error {
+}

package/docs/benchmark.md

@@ -13,6 +13,9 @@ garbage collection is requested before each run. Deadlines are disabled.
 
 ## Sample run — 2026-09-27
 
+These measurements predate 0.2 execution history and live controls; rerun before
+using them to estimate current overhead.
+
 Environment: Apple M5, darwin/arm64, Node v25.9.0.
 The following subset uses concurrency 4:
 

package/docs/compatibility.md

@@ -3,10 +3,10 @@
 | Surface | Supported / tested contract |
 | --- | --- |
 | Core runtime | Node.js 22+, ESM imports, TypeScript declarations, no runtime dependencies |
-| Pi package | Node.js 22.19+, Pi 0.87.1 is the pinned validation target |
+| 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 nodes require tool calling |
-| Browsers / CommonJS | No supported browser build or CommonJS entry point in 0.1 |
+| 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 |
 
 The CI matrix describes configured checks; see actual workflow results for each
 commit. Offline HTTP fixtures validate the adapter contract. They do not prove
@@ -14,26 +14,62 @@ that every provider advertising OpenAI compatibility supports its tool schema.
 Run a small opt-in live test with your chosen provider before relying on it.
 
 Pi's upstream packaging guide requires `*` peer dependencies for packages the
-host provides. Braid follows that convention and pins dev dependencies to 0.87.1.
+host provides. Braid follows that convention and pins dev dependencies to 1.0.1.
 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 when a job finishes during `agent_settled`.
+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
-Pi 0.85.1; the current checkout's pinned validation target is 0.87.1.
+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
 its runtime and does not need a source checkout.
 
 Git must be installed for workspace execution inside a Git checkout. Non-Git
 text-only runs do not require Git workspace management.
-Execute/decision nodes can opt into `workspace: "read-only"`; omitted or
-`"worktree"` values preserve the existing allocation behavior. Merge nodes reject
-this field. Explicit read-only nodes report workspace metadata/events even when
-the entire run is read-only; implicit non-Git runs keep their existing shapes.
-Older versions reject the new field during validation.
+## Migrating from 0.1 to 0.2
+
+This release deliberately changes the execution and workspace contracts:
+
+- Replace old source-checkout `merge` nodes with `integrate`. The new `merge`
+  combines inputs in a fresh isolated worktree.
+- Add explicit integrate nodes where a graph previously relied on automatic
+  final integration. Runs no longer append `__braid_merge__`.
+- Treat node IDs as definition identities. Read exact historical instances from
+  `executions[executionId]`; `nodes[nodeId]` returns the latest instance.
+- Key workspace lookups and `finish_merge` dispositions by `executionId`.
+  Source workspaces remain reusable; target `dispositions` records selections.
+- Read-only nodes now use isolated predecessor snapshots in Git. They receive
+  checkpoints and cleanup events. All non-Git allocations also report metadata.
+- Set `requireSuccess: true` on nodes whose failures must fail the whole job.
+  Optional failures now retain their error and artifacts while allowing recovery.
+- Handle repeated instance events and the new revision/loop/gate events. Use
+  `braid_status({jobId, executionId})` for precise Pi result retrieval.
+- Set finite `maxExecutions` (default 1000) and per-loop `maxIterations`. Deadlines
+  and execution limits span live graph updates and paused gates.
+
+Use `startBraid` for live updates or pause/resume. Existing `braid` callers can
+still await a static graph result. See [execution control](execution-control.md)
+for the full scheduling and update contract; there is no old-behavior mode.
+
+Graph submissions may include `promptTemplates` and template-reference prompts.
+`BraidInput.nodes` uses `BraidInputNode`, whose `NodePrompt` accepts a string or
+`PromptTemplateReference`. Code inspecting unrendered input prompts must narrow
+that union; use `satisfies BraidInput` to preserve the inferred types of a literal
+graph. Runner-facing `BraidNode` and `ModelRequest.node` retain string prompts,
+so existing runners need no template support. Rendering happens in core before
+execution, including for Pi submissions. Older versions reject template inputs.
+
+All node types accept optional `notifyOnCompletion: boolean` (default `false`).
+Core captures this preference per execution; Pi implements parent reminders for successful and failed executions.
+Skipped nodes do not notify. Pi's optional `braid_status` `nodeId` parameter
+requires `jobId` and retrieves full intermediate node results. Whole-job queries and reminders remain available. Paused executions send a
+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.
 
 ## Versioning
 

package/docs/examples.md

@@ -8,7 +8,8 @@ Replace a runner with the documented provider adapter for live use.
 | --- | --- | --- |
 | [Design comparison](../examples/basic.ts) | `npm run demo` | Decision chooses comparison, benefits/risks run concurrently, answer synthesizes them; brief branch skips |
 | [Code review](../examples/code-review.ts) | `npx tsx examples/code-review.ts` | Correctness and test reviews run independently; final review lists both findings |
-| [Failure handling](../examples/failure-handling.ts) | `npx tsx examples/failure-handling.ts` | `failed`; join completes with local findings and explicit `remote` error context |
+| [Failure handling](../examples/failure-handling.ts) | `npx tsx examples/failure-handling.ts` | `completed`; optional failure stays in history and join completes with local findings and explicit `remote` error context |
+| [Loop and live update](../examples/execution-control.ts) | `npx tsx examples/execution-control.ts` | Two refinement rounds, a pause, and an atomic graph update/resume |
 | [Custom runner](../examples/custom-runner.ts) | `npx tsx examples/custom-runner.ts` | `Received direct predecessors: route` |
 
 These text-only examples use temporary non-Git directories. The code-review