@chrok/pi-braid 0.1.2 → 0.1.3

package/README.md

@@ -57,8 +57,8 @@ an explicit per-turn planning policy to Pi's system prompt and tool metadata:
 
 - for code reviews, bug investigations, design comparisons, test planning, or
   changes spanning multiple files, call Braid first when two or more concerns
-  can be handled independently; nodes can inspect the project and edit isolated
-  worktrees in Git repositories;
+  can be handled independently; use `workspace: "read-only"` for analysis,
+  review, routing, and synthesis, and worktrees for implementation;
 - do not use Braid for simple one-step answers, trivial direct edits, or shell
   work; keep tests and shell commands in the parent agent;
 - the user does not need to say “Braid” or design the graph;
@@ -164,15 +164,41 @@ They make no provider requests.
 
 Core owns workspace preparation, checkpointing, serialization, and cleanup for
 all integrations. Pi exposes `read` and `ls` in all directories, plus search tools whose local dependencies are available.
-In Git, execute and decision nodes also get `write`/`edit` restricted to their own
-detached worktree, plus local Git inspection. Outside Git, filesystem tools stay
-read-only. Nodes never receive shell commands or a test runner.
+In Git, execute and decision nodes default to `write`/`edit` restricted to their
+own detached worktree, plus local Git inspection. Set `workspace: "read-only"`
+to keep read tools and Git inspection without write/edit tools or a worktree.
+Omit `workspace` or use `"worktree"` for implementation or a fixed snapshot.
+Outside Git, both modes remain read-only. Nodes never receive shell commands or
+a test runner. The `workspace` field is forbidden on merge nodes.
+
+Read-only nodes inspect the live source directory at the original `cwd`, including
+accessible ignored files. They create no snapshot, checkpoint, or merge source.
+Parent edits and concurrent merges may change what they read during execution.
+Implementation changes reach the source only through integration; a downstream
+review can inspect a predecessor worktree/checkpoint explicitly, or run after a
+merge to review the integrated source. Use a read-only execute node to summarize
+findings, and a merge node to integrate file changes.
+
+For example, this graph reviews two concerns before implementing a fix. Core
+invokes an automatic merge only if the implementation leaves file changes:
+
+```json
+{
+  "goal": "Review the cache and fix confirmed problems.",
+  "nodes": [
+    { "type": "execute", "id": "correctness", "workspace": "read-only", "prompt": "Review cache correctness." },
+    { "type": "execute", "id": "tests", "workspace": "read-only", "prompt": "Inspect test coverage and identify missing cases; do not run tests." },
+    { "type": "execute", "id": "fix", "prompt": "Implement confirmed fixes and regression tests from both reviews." }
+  ],
+  "edges": [{ "from": "correctness", "to": "fix" }, { "from": "tests", "to": "fix" }]
+}
+```
 
 The initial snapshot includes tracked staged/unstaged changes, deletions, and
 non-ignored untracked files. It preserves the source index and files. Ignored
 files are not copied; submodules are not initialized or recursively snapshotted,
 and Pi rejects writes inside them to keep checkpoint recovery complete.
-Every worker shares that baseline until a merge ends, after which new workers
+Workers using worktrees share that baseline until a merge ends, after which new workers
 snapshot the current source checkout. Uncommitted predecessor changes are not
 implicitly applied to downstream workers. Their paths and checkpoint refs are
 available as context for inspection.
@@ -186,8 +212,12 @@ Core never automatically merges or cherry-picks. The agent must call
 source. Tool errors and conflicts go back to the agent for recovery. Failed
 predecessors pass errors and partial work along unconditional edges.
 
-Core removes processed source worktrees after the merge agent finishes. If any
-worktrees remain after declared nodes settle, core appends a final merge agent.
+Core removes processed source worktrees after the merge agent finishes. After
+declared nodes settle, unchanged worktrees are released as `discarded` with reason
+`No changes from snapshot`, retaining recovery refs. Only remaining worktrees
+with changes trigger a final merge agent, so analysis-only graphs keep their
+declared terminal outputs without an extra model call. Explicit merge nodes run
+even for unchanged sources.
 Its model, tool calls, budgets, events, and usage behave like any other node.
 Missing finish calls, unresolved conflicts, or archived sources fail the merge.
 Cancellation, timeout, and failure archive remaining changes and clean worktrees;
@@ -200,6 +230,8 @@ worktrees from cleaned workspaces. Worktrees use
 recoverable from `refs/braid/checkpoints/*`. Use `git show <checkpointRef>:<path>`
 or `git diff <snapshotCommit> <checkpointRef>` to inspect archived changes.
 Remove individual recovery refs with `git update-ref -d <ref>` once reviewed.
+Explicit read-only nodes appear with mode `read-only` and state `ready`, without
+checkpoint or backup refs; their files stay in the source directory.
 
 A failed merge does not reset partial changes or conflict state in the source
 checkout. Its `backupRef` preserves the pre-agent snapshot. Cleanup errors report

package/dist/display.js

@@ -19,7 +19,7 @@ class FixedLines {
         const chartOutput = chartWidth <= width
             ? chart
             : [
-                `[Flowchart needs ${chartWidth} columns; terminal width is ${width}. Expand your terminal to see it.]`,
+                truncateToWidth(`[Flowchart needs ${chartWidth} columns; terminal width is ${width}. Expand your terminal to see it.]`, width, ""),
             ];
         const output = [];
         let chartInserted = false;

package/dist/index.js

@@ -25,9 +25,12 @@ const braidParameters = Type.Object({
         model: Type.Optional(Type.String({
             description: "Exact provider/modelId; default is the current Pi model",
         })),
+        workspace: Type.Optional(StringEnum(["read-only", "worktree"], {
+            description: "Execute/decision only; forbidden on merge nodes. Use read-only for analysis, review, routing, and synthesis: reads the live source directory with Git inspection, no writes or worktree. Omit or use worktree for implementation or a fixed snapshot in Git. Outside Git, both modes are read-only.",
+        })),
         choices: Type.Optional(Type.Array(text(), {
             minItems: 1,
-            description: "Required on decision nodes; forbidden on execute nodes",
+            description: "Required on decision nodes; forbidden on execute and merge nodes",
         })),
     }, { additionalProperties: false }), { minItems: 1 }),
     edges: Type.Array(Type.Object({
@@ -43,9 +46,10 @@ const braidParameters = Type.Object({
         maxToolCalls: toolBudget("calls"),
     }, { additionalProperties: false })),
 }, { additionalProperties: false });
-const BRAID_FILESYSTEM_GUIDANCE = "In a Git repository, execute and decision nodes get individual writable worktrees with read, ls, write, edit, and Git inspection. Search tools grep/find are exposed only when their local rg/fd dependencies are available. " +
+const BRAID_FILESYSTEM_GUIDANCE = "Set workspace=read-only on execute/decision nodes for analysis, review, routing, and synthesis that do not need file edits. These nodes read the live source directory with read, ls, and Git inspection in Git repositories; they get no write/edit tools, snapshot, worktree, or merge source. Reads can observe parent edits or concurrent merges. " +
+    "Omit workspace or use workspace=worktree for implementation or when a fixed snapshot is needed. In a Git repository, these execute and decision nodes get individual writable worktrees with read, ls, write, edit, and Git inspection. Search tools grep/find are exposed only when their local rg/fd dependencies are available. " +
     "Worktrees include tracked changes and non-ignored untracked files. Merge nodes operate in the source checkout and decide whether to merge, cherry-pick, apply, or discard predecessor changes; core never makes that choice. " +
-    "Merge agents must call finish_merge for every source; core checkpoints changes and removes processed worktrees. Core appends a final merge agent for remaining worktrees. Failed predecessors pass their errors and partial work along unconditional edges. " +
+    "Do not set workspace on merge nodes. Use a read-only execute node to summarize findings; use a merge node only to integrate file changes. Merge agents must call finish_merge for every source; core checkpoints changes and removes processed worktrees. Core releases unchanged worktrees and appends a final merge agent only for remaining changed worktrees; explicit merge nodes always run. Failed predecessors pass their errors and partial work along unconditional edges. " +
     "Outside Git, nodes have read and ls, plus grep/find when their local dependencies are available. Shell commands and tests remain unavailable in all nodes. " +
     "Inspect braid_status for integration outcomes and recovery checkpoint refs, then run tests in the parent. Avoid concurrent parent edits while a merge agent owns the source checkout.";
 const BRAID_USAGE_GUIDANCE = [
@@ -69,7 +73,7 @@ export function createBraidTools(jobs) {
             "Do not use it for a simple one-step answer or trivial direct edit. " +
             "Use braid_status(jobId) for progress and results, or braid_cancel(jobId) to stop it. A completion reminder resumes the agent if idle; do independent work or end your turn instead of polling. Humans can open /braid for the live flow panel. " +
             "Read result.status: failed graphs can still return successful terminal outputs.",
-        promptSnippet: "Use FIRST for nontrivial code review/debug/design/implementation work; parallelize analysis or edits in isolated Git worktrees and use merge nodes to integrate changes",
+        promptSnippet: "Use FIRST for nontrivial code review/debug/design/implementation work; set workspace=read-only for analysis/synthesis, use worktrees for edits and merge nodes for integration",
         promptGuidelines: [
             "Call braid before direct repository inspection when a code task has two or more separable review, debugging, design, test-planning, or implementation concerns; the Braid nodes can inspect the project and edit isolated Git worktrees.",
             "Use parallel execute nodes for independent analysis or implementation, execute nodes to synthesize findings, and merge nodes to integrate file changes. The user does not need to mention Braid or design the graph.",

package/dist/runner.js

@@ -97,7 +97,9 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
                         ? "You may write and edit files inside your own isolated Git worktree. Use workingDirectory as your cwd; do not write to sourceRoot or any other node's worktree. " +
                             "Nodes start from the current core snapshot of tracked changes and non-ignored untracked files. After merge nodes, newly started workers see the updated source checkout. Inspect predecessor checkpoints with git show when their worktrees have been removed. " +
                             "Describe your changes in your final answer. A merge agent will review your checkpoint and core will clean up the worktree. "
-                        : "This node has no writable workspace assigned. Its filesystem tools are read-only; you cannot write or edit files. ") +
+                        : "This node has no writable workspace assigned. Its filesystem tools are read-only; you cannot write or edit files. " +
+                            "Read workingDirectory directly; it is a live directory, not an isolated snapshot, and may change during execution. " +
+                            (request.git ? "Use Git inspection to review changes or predecessor checkpoints; predecessor edits are not automatically applied to this directory. " : "")) +
                 mergeInstructions(request) +
                 "You cannot run shell commands, run tests, or call arbitrary tools. " +
                 (request.node.type === "merge" && workspace.mode === "read-only"

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chrok/pi-braid",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "MIT",
   "description": "Pi extension for Braid: background DAG jobs and a live flow panel",
   "type": "module",
   "dependencies": {
     "grok-mermaid": "^0.2.2",
-    "@chrok/braid": "0.1.2"
+    "@chrok/braid": "0.1.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",