@chrok/braid 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 0.1.3 — 2026-09-29
+
+- Add per-node `workspace: "read-only" | "worktree"` for execute/decision nodes.
+  Read-only nodes inspect the live source directory with Git inspection, without
+  writable tools, snapshots, worktrees, or merge sources. Existing defaults are
+  preserved. Pi's braid tool guides analysis/review/routing/synthesis to read-only
+  nodes and implementation to worktrees; explicit read-only workspace metadata
+  is included in results and events (#22).
+- Skip the automatic merge agent when all remaining workspaces match their
+  snapshots, preserving analysis-only terminal outputs and original node errors.
+  Mixed runs pass only changed sources to the automatic merge. Unchanged sources
+  retain recovery refs pointing to their snapshots without empty checkpoint
+  commits; explicit merge nodes still run even for unchanged sources (#21).
+- Prevent Pi TUI crashes in narrow terminals by truncating the flowchart fallback
+  message to the terminal width.
+- Scan fork pull requests with CodeQL advanced setup so external contributions
+  can satisfy the required security checks.
+
+## 0.1.2 — 2026-09-27
+
+- Make Pi depend on the exact `@chrok/braid` version instead of bundling core.
+  Export shared model-adapter helpers from the existing root entry point.
+- Use one npm workspace lockfile and a development-only local core link; test
+  Pi-only installation against the unpublished core tarball outside the checkout.
+- Wait for core registry metadata and tarball availability before publishing Pi.
+
 ## 0.1.1 — 2026-09-27
 
 - Validate the Pi integration against Pi 0.87.1; update GitHub Actions and tsx.

package/CONTRIBUTING.md

@@ -12,13 +12,20 @@ Use Node.js 22.19+ and npm. From a fresh checkout:
 git clone https://github.com/Epsirom/braid.git
 cd braid
 npm ci
-npm ci --prefix integrations/pi
 npm run verify
 ```
 
-There are two packages and two lockfiles. The core has no runtime dependencies;
-Pi's dependencies belong in `integrations/pi`. Update and commit the corresponding
-lockfile when changing a dependency. Do not commit generated `dist` directories,
+The root npm workspace lockfile covers both packages. A development-only
+`@chrok/braid: file:.` dependency links the core checkout into `node_modules`;
+Pi's manifest still declares the exact release version. This lets CI test a
+new core before it is published. `check:pi`, `test:pi`, and `build:pi` rebuild
+core so package imports resolve current JavaScript and declarations. Consumers
+installing either published package do not install this development dependency.
+Use `npm install --workspace @chrok/pi-braid <dependency>` for Pi dependency
+updates; do not create a separate lockfile in `integrations/pi`.
+
+The core has no runtime dependencies. Pi's dependencies belong in its workspace
+manifest. Update and commit the root lockfile when changing a dependency. Do not commit generated `dist` directories,
 tarballs, credentials, or provider output containing private data.
 
 `verify` type-checks both packages, runs deterministic tests and offline examples,

package/README.md

@@ -164,9 +164,10 @@ output. The graph has no special fork, branch, or join nodes.
 
 ```ts
 type BraidNode =
-  | { type: "execute"; id: string; prompt: string; model?: string }
+  | { type: "execute"; id: string; prompt: string; model?: string;
+      workspace?: "read-only" | "worktree" }
   | { type: "decision"; id: string; prompt: string;
-      choices: readonly string[]; model?: string }
+      choices: readonly string[]; model?: string; workspace?: "read-only" | "worktree" }
   | { type: "merge"; id: string; prompt?: string; model?: string };
 
 type Edge = { from: string; to: string; choice?: string };
@@ -175,6 +176,11 @@ type BraidInput = { goal: string; nodes: readonly BraidNode[]; edges: readonly E
 
 IDs are unique, non-empty strings. Prompts, goals, models, and choices must be
 non-empty strings when present. Decision choices must be non-empty and unique.
+`workspace` is optional on execute/decision nodes and forbidden on merge nodes.
+Use `"read-only"` for analysis, review, routing, and synthesis. Omit it or use
+`"worktree"` for the existing behavior: an isolated writable worktree in Git,
+read-only access outside Git. Explicit read-only nodes read the live source
+directory, not a fixed snapshot; see [workspace semantics](#worktrees-and-merge-agents).
 Unknown fields, unsupported node types, missing references, duplicate exact
 edges, and cycles are rejected. Cycles are rejected even if a decision might
 make them inactive. Disconnected components are allowed; every root runs.
@@ -259,7 +265,8 @@ The event sequence includes:
 - `graph_created`, `node_created`, and `edge_created` when the submitted DAG is
   admitted; an appended final merge emits its own node/edge creation events.
 - `node_runnable` and `node_started` when scheduling admits a node.
-- `workspace_updated` for Git workspace preparation, checkpointing, and cleanup.
+- `workspace_updated` for Git workspace preparation, checkpointing, cleanup, and
+  explicitly requested read-only workspaces.
 - `handoff` for every direct predecessor output passed to a downstream node,
   including the upstream decision when present.
 - `node_completed`, `node_skipped`, and `node_failed`, including output,
@@ -281,8 +288,9 @@ render live topology, handoffs, failures, and active nodes without reconstructin
 scheduler state from final results. Tool selection remains the responsibility of
 the host agent; the optional Pi adapter supplies explicit proactive-use guidance
 so Braid is considered for complex multi-branch reasoning without forcing it for
-every prompt. In the Pi adapter, Git nodes can inspect and edit individual
-worktrees; nodes outside Git stay read-only. Merge agents handle integration; the parent reviews results and runs shell commands and tests.
+every prompt. In the Pi adapter, nodes can inspect the live source read-only or
+edit individual Git worktrees; nodes outside Git stay read-only. Merge agents
+handle integration; the parent reviews results and runs shell commands and tests.
 
 ## Context isolation and model runners
 
@@ -308,7 +316,8 @@ 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.
-Outside Git, adapters must provide read-only capabilities. Pi never provides
+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.
 
 `request.predecessors` contains direct active predecessors in incoming-edge
@@ -327,17 +336,39 @@ Read tools follow the host filesystem permissions and are not a security sandbox
 
 ### Worktrees and merge agents
 
-In a Git checkout, execute and decision nodes receive detached worktrees under
-`os.tmpdir()/braid-workspaces-*/<unique-id>`. The first node captures tracked
+By default, execute and decision nodes in a Git checkout receive detached worktrees
+under `os.tmpdir()/braid-workspaces-*/<unique-id>`. The first writable node captures tracked
 staged/unstaged changes, deletions, and non-ignored untracked files with a temporary
 index. Snapshot creation preserves the source index, branch, and files. Ignored
 files are not copied, and submodules are not initialized or recursively captured.
 Pi rejects writes inside submodules. If a custom runner populates one, core
 reports cleanup failure and retains the worktree rather than losing those files.
-Empty repositories are supported. Nodes share this baseline until a merge ends;
-subsequent nodes snapshot the current source checkout. Relative working directories
+Empty repositories are supported. Worktree nodes share this baseline until a merge
+ends; subsequent worktree nodes snapshot the current source checkout. Relative working directories
 are preserved. Code changes do not implicitly flow into successor worktrees.
 
+Set `workspace: "read-only"` on execute/decision nodes that only inspect or reason
+about files. They read the original `cwd`, including ignored files accessible to
+the adapter, without creating a snapshot, worktree, checkpoint, or merge source.
+In Git they retain inspection commands (`status`, `diff`, `show`, `log`,
+`ls-files`, `rev-parse`), with optional Git index writes disabled. Relative paths
+use the original `cwd`, including when it is a subdirectory of the repository.
+These reads observe the live checkout: parent edits or concurrent merge nodes
+may change files during execution. Use worktree mode when a fixed snapshot is
+needed. Predecessor edits are visible in the source only after integration;
+their worktrees/checkpoints can still be inspected explicitly.
+
+Explicit read-only allocations appear in `workspace_updated`, node/predecessor
+workspace metadata, and `result.workspaces` with mode `read-only` and state
+`ready`. They have no cleanup lifecycle or recovery refs. Implicit non-Git
+read-only runs retain their existing event/result behavior. A custom runner is
+trusted code and must honor the workspace capability; this is not an OS sandbox.
+
+For a mixed graph, give review branches `workspace: "read-only"` and leave
+implementation branches in worktree mode. Use a read-only execute node to
+summarize findings; a merge node integrates file changes and does not accept
+the `workspace` field.
+
 Add `{ type: "merge", id: "integrate" }` with incoming edges from any number of
 sources. The merge agent receives predecessor errors, workspace paths, and Git
 checkpoint refs and operates directly in the invoking checkout. **Core does not
@@ -376,13 +407,24 @@ including intentionally discarded changes and ignored node output files. A
 later consumer can inspect a removed source through `git show <checkpointRef>`.
 Core also records `backupRef` for the source checkout before each merge agent.
 
-When declared nodes settle and worktrees remain, core appends an ordinary merge
+When declared nodes settle, core releases worktrees whose contents match their
+own snapshot, including those from failed nodes, as `discarded` with reason
+`No changes from snapshot`. Their checkpoint refs point to the snapshot commit
+without creating empty checkpoint commits; original node errors remain visible.
+This comparison includes ignored output files. Explicit merge nodes still run
+even when their sources have no changes.
+
+When worktrees with changes remain, core appends an ordinary merge
 agent named `__braid_merge__` (with a suffix if needed), using the run's default
 model. It appears in results, events, usage, and terminal outputs. Merge nodes
 are exclusive within a graph and serialized per source checkout across runs in
 the same process. Avoid concurrent external edits to that checkout while merging;
 this lock does not coordinate other processes or the parent editor.
 
+Analysis-only graphs therefore keep their declared terminal outputs and do not
+incur an automatic merge model call. Consumers should not assume that every Git
+run includes `__braid_merge__`; use `terminalOutputs` for the completed endpoints.
+
 Cancellation or graph timeout prevents new merge agents from starting. Core waits
 for tracked writes, archives remaining work, and removes its worktrees. Merge
 agent failure follows the same archive/cleanup path. It does not reset the source

package/SECURITY.md

@@ -22,6 +22,10 @@ upgrade. Before the first release, report issues against the current main branch
   changes into the source checkout; 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
+  remains available. These nodes read the live source directory, not an isolated
+  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 merge agents run. A

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { braid } from "./runtime.js";
 export { validateGraph, GraphValidationError } from "./validate.js";
 export type { BraidInput, BraidNode, BraidOptions, BraidResult, DecisionNode, Edge, ExecuteNode, ExecutionContext, ExecutionError, ExecutionEvent, ModelRequest, ModelResponse, ModelRunner, MergeNode, MergeDisposition, MergeSource, GitPreview, SourceCheckoutStatus, NodeWorkspace, GitResult, NodeOutput, NodeResult, NodeStatus, PredecessorOutput, TokenUsage, } from "./types.js";
+export { formatBudgetReminder } from "./budgets.js";
+export { gitToolDefinition, finishMergeToolDefinition, mergeInstructions, parseGitToolArguments, parseFinishMergeArguments, } from "./merge-tools.js";

package/dist/index.js

@@ -1,2 +1,5 @@
 export { braid } from "./runtime.js";
 export { validateGraph, GraphValidationError } from "./validate.js";
+// Shared helpers for model adapters, including the Pi integration.
+export { formatBudgetReminder } from "./budgets.js";
+export { gitToolDefinition, finishMergeToolDefinition, mergeInstructions, parseGitToolArguments, parseFinishMergeArguments, } from "./merge-tools.js";

package/dist/runtime.js

@@ -179,6 +179,7 @@ async function runNode(request, result, runner, timeoutMs, graphSignal, graphDea
     });
     void aborted.catch(() => { });
     let acceptingWrites = true;
+    let writableWorkspace = false;
     const writes = new Set();
     let merge;
     let acceptingDecisions = true;
@@ -191,6 +192,8 @@ async function runNode(request, result, runner, timeoutMs, graphSignal, graphDea
         signal.throwIfAborted();
         if (!acceptingWrites)
             throw new Error("Node has finished; further writes are unavailable");
+        if (!writableWorkspace)
+            throw new Error("Node workspace is read-only; writes are unavailable");
         const pending = Promise.resolve().then(() => {
             signal.throwIfAborted();
             return operation();
@@ -249,6 +252,7 @@ async function runNode(request, result, runner, timeoutMs, graphSignal, graphDea
             invocation.workspace = await workspaces.prepare(invocation);
         }
         invocation.workspace = structuredClone(invocation.workspace);
+        writableWorkspace = invocation.workspace.mode !== "read-only";
         if (invocation.workspace?.sourceRoot) {
             const gitRequest = { ...invocation, node: structuredClone(invocation.node), workspace: structuredClone(invocation.workspace) };
             invocation.git = (args, input) => workspaces.git(gitRequest, args, input);
@@ -375,8 +379,11 @@ export async function braid(input, options) {
             result.model = model;
         return [node.id, result];
     }));
+    const explicitReadOnly = new Set(graph.nodes.filter(node => node.type !== "merge" && node.workspace === "read-only").map(node => node.id));
+    // Preserve the existing event/result shape for implicit non-Git read-only runs.
+    const reportWorkspace = (workspace) => workspace.mode !== "read-only" || explicitReadOnly.has(workspace.nodeId);
     const workspaces = new GitWorkspaces(resolve(options.cwd ?? process.cwd()), workspace => {
-        if (workspace.mode === "read-only")
+        if (!reportWorkspace(workspace))
             return;
         const node = results.get(workspace.nodeId);
         if (node)
@@ -438,6 +445,18 @@ export async function braid(input, options) {
                 running.set(node.id, task);
             }
             if (running.size === 0) {
+                if (!automaticMergeAdded) {
+                    try {
+                        await workspaces.discardUnchanged();
+                    }
+                    catch (error) {
+                        cleanupError = { code: "CLEANUP_FAILED", message: error instanceof Error ? error.message : String(error) };
+                        break;
+                    }
+                    // Checkpointing/cleanup can outlast the deadline or trigger cancellation.
+                    if (controller.signal.aborted || performance.now() >= graphDeadline)
+                        continue;
+                }
                 const pending = workspaces.pending();
                 if (!automaticMergeAdded && pending.length) {
                     automaticMergeAdded = true;
@@ -503,7 +522,7 @@ export async function braid(input, options) {
         terminalOutputs,
         events: [],
         nodes: Object.fromEntries(results),
-        ...(Object.values(workspaces.all()).some(value => value.mode !== "read-only") ? { workspaces: workspaces.all() } : {}),
+        ...(Object.values(workspaces.all()).some(reportWorkspace) ? { workspaces: workspaces.all() } : {}),
         metadata: {
             ...execution,
             startedAt,

package/dist/types.d.ts

@@ -3,6 +3,8 @@ export interface ExecuteNode {
     id: string;
     prompt: string;
     model?: string;
+    /** Read the live cwd without a worktree; defaults to worktree in Git, read-only elsewhere. */
+    workspace?: "read-only" | "worktree";
 }
 export interface DecisionNode {
     type: "decision";
@@ -10,6 +12,8 @@ export interface DecisionNode {
     prompt: string;
     choices: readonly string[];
     model?: string;
+    /** Read the live cwd without a worktree; defaults to worktree in Git, read-only elsewhere. */
+    workspace?: "read-only" | "worktree";
 }
 export interface MergeNode {
     type: "merge";
@@ -108,7 +112,7 @@ export interface ModelRequest {
         graph?: number;
     };
     workspace?: NodeWorkspace;
-    /** Adapters must wrap mutating file tools so cancellation and cleanup wait for in-flight writes. */
+    /** Rejects read-only writes; adapters must wrap mutating file tools so cleanup waits for in-flight writes. */
     withWorkspaceWrite?: <T>(operation: () => Promise<T>) => Promise<T>;
     /** Local Git operations: inspection for workers, integration commands for merge nodes. */
     git?: (args: string[], input?: string) => Promise<GitResult>;
@@ -189,7 +193,7 @@ export type ExecutionEvent = Readonly<{
 export interface BraidOptions {
     runner: ModelRunner;
     defaultModel?: string;
-    /** Source checkout. Git workspace management is automatic; outside Git, nodes are read-only. */
+    /** Source checkout. Nodes may opt into live read-only access; outside Git, all nodes are read-only. */
     cwd?: string;
     /** Positive integer. Defaults to 4. */
     maxConcurrency?: number;

package/dist/validate.js

@@ -34,16 +34,21 @@ export function compileGraph(input) {
         requireValid(isRecord(node), "Node must be an object");
         requireValid(node.type === "execute" || node.type === "decision" || node.type === "merge", "Unknown node type");
         fields(node, node.type === "decision"
-            ? ["type", "id", "prompt", "model", "choices"]
-            : ["type", "id", "prompt", "model"], "Node");
+            ? ["type", "id", "prompt", "model", "choices", "workspace"]
+            : node.type === "execute"
+                ? ["type", "id", "prompt", "model", "workspace"]
+                : ["type", "id", "prompt", "model"], "Node");
         requireValid(text(node.id), "Node id must be a non-empty string");
         requireValid(!byId.has(node.id), `Duplicate node id '${node.id}'`);
         requireValid(text(node.prompt) || (node.type === "merge" && node.prompt === undefined), `Node '${node.id}' needs a non-empty prompt`);
         requireValid(node.model === undefined || text(node.model), `Invalid model on '${node.id}'`);
+        const workspace = node.type === "merge" ? undefined : node.workspace;
+        requireValid(workspace === undefined || workspace === "read-only" || workspace === "worktree", `Invalid workspace on '${node.id}'`);
         const common = {
             id: node.id,
             prompt: node.prompt ?? "Review all predecessor changes, decide how to integrate them into the source repository, and account for every source with finish_merge.",
             ...(node.model !== undefined ? { model: node.model } : {}),
+            ...(workspace !== undefined ? { workspace } : {}),
         };
         if (node.type === "decision") {
             requireValid(Array.isArray(node.choices) && node.choices.length > 0, `Decision '${node.id}' needs at least one choice`);

package/dist/workspaces.d.ts

@@ -1,5 +1,5 @@
 import type { GitResult, MergeDisposition, MergeSource, ModelRequest, NodeWorkspace, SourceCheckoutStatus } from "./types.js";
-/** One source snapshot per graph; every invoked node gets its own detached worktree. */
+/** Writable workers share a snapshot; explicit read-only workers inspect the live cwd. */
 export declare class GitWorkspaces {
     private readonly cwd;
     private readonly onWorkspace?;
@@ -9,12 +9,15 @@ export declare class GitWorkspaces {
     private allocated;
     constructor(cwd: string, onWorkspace?: ((workspace: NodeWorkspace) => void) | undefined);
     private report;
+    private sourceRoot;
     private snapshot;
     prepare(request: ModelRequest): Promise<NodeWorkspace>;
     all(): Record<string, NodeWorkspace>;
     pending(): string[];
     /** Checkpoint every file, including ignored node outputs, before releasing a worktree. */
     private checkpoint;
+    /** Run only after declared nodes settle, so consumers retain their source paths. */
+    discardUnchanged(): Promise<void>;
     private release;
     /** Only archive/remove here. Choosing merge/cherry-pick/apply always belongs to the agent. */
     archivePending(reason: string): Promise<void>;

package/dist/workspaces.js

@@ -91,7 +91,7 @@ async function gitPreview(cwd, args, limit) {
     }
     return { text: output.slice(0, limit), truncated: overflow || output.length > limit };
 }
-/** One source snapshot per graph; every invoked node gets its own detached worktree. */
+/** Writable workers share a snapshot; explicit read-only workers inspect the live cwd. */
 export class GitWorkspaces {
     cwd;
     onWorkspace;
@@ -112,7 +112,7 @@ export class GitWorkspaces {
             // Observers cannot change permissions or fail node execution.
         }
     }
-    async snapshot() {
+    async sourceRoot() {
         let ancestor = resolve(this.cwd);
         while (true) {
             try {
@@ -138,7 +138,12 @@ export class GitWorkspaces {
                 return undefined;
             throw error;
         }
-        sourceRoot = await realpath(sourceRoot);
+        return realpath(sourceRoot);
+    }
+    async snapshot() {
+        const sourceRoot = await this.sourceRoot();
+        if (!sourceRoot)
+            return undefined;
         const commonDirectory = await realpath(resolve(sourceRoot, await git(sourceRoot, ["rev-parse", "--git-common-dir"])));
         const cwdSuffix = relative(sourceRoot, await realpath(this.cwd));
         // Git records canonical worktree paths. In particular, Windows tmpdir()
@@ -183,7 +188,7 @@ export class GitWorkspaces {
                 "-m", "Braid isolated workspace snapshot",
             ], options);
             const snapshot = {
-                directory, commonDirectory, sourceRoot, cwdSuffix, snapshotCommit, hooksDirectory,
+                directory, commonDirectory, sourceRoot, cwdSuffix, snapshotTree: tree, snapshotCommit, hooksDirectory,
                 ...(baseCommit ? { baseCommit } : {}),
             };
             this.allocated.add(snapshot);
@@ -200,6 +205,16 @@ export class GitWorkspaces {
     }
     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.
@@ -279,7 +294,7 @@ export class GitWorkspaces {
         }
         await git(cwd, ["add", "--force", "--all", "--", "."], options);
         const tree = await git(cwd, ["write-tree"], options);
-        const commit = await git(cwd, [
+        const commit = tree === location.snapshotTree ? 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}`,
         ], options);
@@ -290,6 +305,27 @@ 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);
@@ -374,7 +410,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 === "merge" ? workspace.sourceRoot : workspace.worktreeRoot;
+        const cwd = workspace.mode === "read-only" ? workspace.workingDirectory
+            : workspace.mode === "merge" ? workspace.sourceRoot : workspace.worktreeRoot;
         const location = this.locations.get(request.node.id);
         const actualArgs = [command,
             ...(["diff", "show", "log"].includes(command) ? ["--no-ext-diff", "--no-textconv"] : []),
@@ -382,7 +419,9 @@ export class GitWorkspaces {
         ];
         const execute = () => new Promise((resolve, reject) => {
             const child = execFile("git", [
-                "-c", `core.hooksPath=${location.hooksDirectory}`, "-c", "commit.gpgsign=false",
+                ...(location ? ["-c", `core.hooksPath=${location.hooksDirectory}`] : []),
+                ...(workspace.mode === "read-only" ? ["--no-optional-locks"] : []),
+                "-c", "commit.gpgsign=false",
                 "-c", "core.fsmonitor=false", "--no-pager", "-C", cwd, ...actualArgs,
             ], {
                 env: { ...gitEnvironment(), GIT_TERMINAL_PROMPT: "0", GIT_EDITOR: "true", GIT_SEQUENCE_EDITOR: "true", GIT_MERGE_AUTOEDIT: "no" },

package/docs/compatibility.md

@@ -23,11 +23,17 @@ exactly one automatic continuation when a job finishes during `agent_settled`.
 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.
-The Pi npm package compiles and includes the same core source as the matching
-core release, so it does not need another installed copy of Braid or a checkout.
+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.
 
 ## Versioning
 
@@ -36,8 +42,13 @@ preserve documented behavior; breaking API or semantic changes require a minor
 version bump, a changelog entry, and migration guidance. New optional fields or
 fixes that restore the documented contract may ship in a patch.
 
-Supported core entry points are `@chrok/braid` and `@chrok/braid/adapters/openai`. Internal
-files and Pi helper classes are not stable public APIs. Documented result/error
+Supported core entry points are `@chrok/braid` and `@chrok/braid/adapters/openai`.
+The root `@chrok/braid` entry point also exports adapter helpers:
+`formatBudgetReminder`, `gitToolDefinition`, `finishMergeToolDefinition`,
+`mergeInstructions`, `parseGitToolArguments`, and `parseFinishMergeArguments`.
+These helpers share the core's compatibility policy; Git workspace implementation
+classes remain internal. Internal files and Pi helper classes are not stable
+public APIs. Documented result/error
 fields, routing behavior, `ModelRunner`, and existing event meanings are part of
 the public contract. Consumers should ignore new diagnostic fields and provide a
 fallback for new event types; event sequence numbers order events within a run,

package/docs/releasing.md

@@ -1,8 +1,8 @@
 # Releasing
 
 Core and Pi are separate public npm packages built from one commit. Both use the
-same version. The core has no runtime dependencies. Pi bundles compiled core
-source so its installed extension never reaches outside its own package.
+same version. The core has no runtime dependencies. Pi declares an exact
+`@chrok/braid` dependency and includes only its own compiled integration code.
 
 ## Prepare a release
 
@@ -10,11 +10,14 @@ Version tags (`v*`) cannot be moved or deleted. New GitHub releases are immutabl
 prepare a draft and attach any assets before publishing. Published tag/asset
 corrections require a new version. See [repository settings](repository-settings.md).
 
-1. Update both `package.json` versions and both lockfiles. Use a minor version
+1. Update both `package.json` versions, Pi's exact `@chrok/braid` dependency,
+   and the root workspace lockfile (`npm install --package-lock-only`). Use a minor version
    for breaking 0.x changes, and describe migrations in the changelog.
-2. Run `npm ci`, `npm ci --prefix integrations/pi`, and `npm run verify`.
+2. Run `npm ci` and `npm run verify` from the repository root.
    The package check verifies clean builds, public ESM imports, declarations,
    licenses, and Pi registration in a temporary consumer outside the checkout.
+   A temporary local registry serves the unpublished core tarball; installing
+   only the Pi tarball must fetch core transitively through its version dependency.
 3. Update the changelog and supported Pi version. Commit and review the changes;
    require the CI matrix to pass before tagging that commit `vX.Y.Z`.
 4. Inspect `npm pack --dry-run` and `npm pack --dry-run` from `integrations/pi`.
@@ -64,7 +67,11 @@ npm trust list @chrok/pi-braid
 
 Publishing a non-prerelease GitHub release triggers `.github/workflows/release.yml`.
 It validates the tag/version relationship, repeats all checks, and publishes
-core then Pi using short-lived OIDC credentials. It does not require `NPM_TOKEN`.
+core then Pi using short-lived OIDC credentials. After each publish (or retry
+of an existing version), it waits for matching version/commit metadata and a
+successful tarball download. Pi is not published until core is available. npm
+processing is polled every 15 seconds for up to 10 minutes; a timeout fails the
+workflow with retry instructions. It does not require `NPM_TOKEN`.
 The workflow installs npm 11 and uses Node 24. See
 [npm's trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/).
 

package/docs/repository-settings.md

@@ -57,8 +57,13 @@ Use a new version for a correction. See [the release guide](releasing.md).
   before using it.
 - Workflows from all external fork contributors require maintainer approval
   before running. Inspect workflow and code changes before approving a run.
-- CodeQL default setup scans GitHub Actions and JavaScript/TypeScript with the
-  default query suite and remote threat model, including its weekly schedule.
+- CodeQL advanced setup in [.github/workflows/codeql.yml](../.github/workflows/codeql.yml)
+  scans GitHub Actions and JavaScript/TypeScript with the default query suite and
+  remote threat model. It runs on pushes to `main`, pull requests targeting
+  `main` (including forks), and a weekly schedule, with a manual trigger available.
+  Default setup must remain disabled because it skips fork pull requests and
+  prevents advanced-setup analysis uploads. Fork PR scans use `pull_request`
+  and remain subject to the contributor approval policy above.
 - Dependabot alerts/security updates, secret scanning, secret push protection,
   and private vulnerability reporting are enabled. Dependency updates remain
   configured in [.github/dependabot.yml](../.github/dependabot.yml).
@@ -68,7 +73,8 @@ sign-off nor a CLA is required for contributions.
 
 ## Dependency maintenance
 
-Dependabot checks both npm manifests weekly. Pi host packages stay in a separate
+Dependabot checks both npm workspace manifests through the root lockfile weekly.
+The internal `@chrok/braid` dependency is updated by the coordinated release process. Pi host packages stay in a separate
 group because even 0.x minor releases can change extension contracts. Other npm
 minor/patch updates are grouped; GitHub Actions updates are grouped monthly and
 retain full commit SHA pins. Grouping does not enable automatic merging.

package/docs/resource-limits.md

@@ -44,8 +44,10 @@ after exporting needed results. Reloading also cancels outstanding work.
 Git worktree preparation, checkpointing, tracked writes, and cleanup add disk,
 Git-process, and elapsed-time overhead. Cleanup may extend wall time beyond a
 model deadline. Automatically appended merge agents are additional model calls
-and share the graph's remaining time. Benchmark results measured outside Git do
-not include this lifecycle. Recoverable refs retain Git objects until removed.
+and share the graph's remaining time; unchanged worktrees are released without
+an automatic merge call, but still incur workspace and checkpoint overhead.
+Benchmark results measured outside Git do not include this lifecycle. Recoverable
+refs retain Git objects until removed.
 
 An aborted runtime slot can be reused even if an uncooperative provider continues
 working. Runners must forward `signal`; neither Braid nor JavaScript can forcibly

package/examples/code-review.ts

@@ -6,9 +6,9 @@ const diff = "- return cache[key];\n+ return cache[key] ?? await load(key);";
 const graph: BraidInput = {
   goal: `Review this proposed cache change:\n${diff}`,
   nodes: [
-    { type: "execute", id: "correctness", prompt: "Review cache semantics and concurrent misses." },
-    { type: "execute", id: "tests", prompt: "Identify regression cases worth testing." },
-    { type: "execute", id: "review", prompt: "Synthesize actionable findings from both reviews." },
+    { type: "execute", id: "correctness", workspace: "read-only", prompt: "Review cache semantics and concurrent misses." },
+    { type: "execute", id: "tests", workspace: "read-only", prompt: "Identify regression cases worth testing." },
+    { type: "execute", id: "review", workspace: "read-only", prompt: "Synthesize actionable findings from both reviews." },
   ],
   edges: [{ from: "correctness", to: "review" }, { from: "tests", to: "review" }],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrok/braid",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "MIT",
   "description": "A small, framework-agnostic DAG runtime for isolated model invocations",
   "type": "module",
@@ -32,12 +32,12 @@
   "scripts": {
     "build": "node scripts/build.mjs",
     "check": "tsc --noEmit",
-    "test": "tsx --test test/*.test.ts",
+    "test": "tsx --test test/*.test.ts test/*.test.mjs",
     "demo": "tsx examples/basic.ts",
-    "check:pi": "npm --prefix integrations/pi run check",
-    "test:pi": "npm --prefix integrations/pi test",
+    "check:pi": "npm run build && npm run check --workspace @chrok/pi-braid",
+    "test:pi": "npm run build && npm test --workspace @chrok/pi-braid",
     "prepack": "npm run build",
-    "build:pi": "npm --prefix integrations/pi run build",
+    "build:pi": "npm run build --workspace @chrok/pi-braid",
     "test:package": "node scripts/package-smoke.mjs",
     "verify": "npm run check && npm test && npm run check:pi && npm run test:pi && npm run examples && npm run test:package",
     "examples": "tsx examples/basic.ts && tsx examples/code-review.ts && tsx examples/failure-handling.ts && tsx examples/custom-runner.ts",
@@ -48,7 +48,8 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsx": "^4.23.15",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "@chrok/braid": "file:."
   },
   "repository": {
     "type": "git",
@@ -68,5 +69,8 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
-  }
+  },
+  "workspaces": [
+    "integrations/pi"
+  ]
 }