Prepare Braid 0.3.0 release

CHANGELOG.md

@@ -2,52 +2,71 @@
 
 ## Unreleased
 
-### Features and behavior changes
+## 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.
+  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.
+  force-added files remain tracked
+  ([#41](https://github.com/Epsirom/braid/pull/41)) — @Epsirom.
 
-These changes require the next minor release under the compatibility policy.
-See [migration guidance](docs/compatibility.md#upcoming-workspace-capability-changes)
-for callers relying on shell-free workers or preservation of ignored outputs.
+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.
+  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.
+  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.
+  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.
+  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.
+  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.
+  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.
+  `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.
+  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
 

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,

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

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,9 +71,9 @@ 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.
 
-## Upcoming workspace capability changes
+## Migrating from 0.2 to 0.3
 
-The Unreleased changes target the next minor release; they are not part of 0.2.1:
+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
@@ -94,7 +94,11 @@ The Unreleased changes target the next minor release; they are not part of 0.2.1
   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 changes are required.
+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
 

integrations/pi/README.md

@@ -5,11 +5,15 @@
 This optional Pi extension runs Braid agent graphs as background jobs with
 bounded loops, live updates, pause/resume, and a live flow panel.
 
-**0.2 API:** The npm badge shows the published version; see
+**0.3 API:** The npm badge shows the published version; see
 [GitHub releases](https://github.com/Epsirom/braid/releases) for release notes.
-Review the [migration guide](https://github.com/Epsirom/braid/blob/v0.2.0/docs/compatibility.md#migrating-from-01-to-02)
-before upgrading an existing graph. For the previous API, use the
-[0.1.3 guide](https://github.com/Epsirom/braid/blob/v0.1.3/integrations/pi/README.md).
+Review the [0.2 → 0.3 migration guide](https://github.com/Epsirom/braid/blob/v0.3.0/docs/compatibility.md#migrating-from-02-to-03)
+before upgrading: writable nodes now have shell tools, checkpoints exclude
+untracked ignored outputs, and reminders can interrupt work between model steps.
+Users coming from 0.1 also need the
+[0.1 → 0.2 guide](https://github.com/Epsirom/braid/blob/v0.3.0/docs/compatibility.md#migrating-from-01-to-02).
+For the previous release, use the
+[0.2.1 guide](https://github.com/Epsirom/braid/blob/v0.2.1/integrations/pi/README.md).
 
 It registers:
 

integrations/pi/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chrok/pi-braid",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "Pi extension for Braid: background agent graphs, bounded loops, live updates, and a flow panel",
   "type": "module",
   "dependencies": {
     "grok-mermaid": "^0.2.2",
-    "@chrok/braid": "0.2.1"
+    "@chrok/braid": "0.3.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

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",