@ai-hero/sandcastle 0.6.5 → 0.7.0

package/README.md

@@ -234,6 +234,12 @@ const result = await run({
   // Idle timeout in seconds — resets whenever the agent produces output. Default: 600 (10 minutes)
   idleTimeoutSeconds: 600,
 
+  // Grace window in seconds after the agent emits a completion signal but
+  // before its process has exited (a "hanging process" — typically a spawned
+  // `gh`/git child or MCP server keeping stdout open). Resets on every
+  // subsequent output line so trailing data is still captured. Default: 60
+  completionTimeoutSeconds: 60,
+
   // Structured output — extract a typed payload from the agent's stdout.
   // Requires maxIterations === 1 and the tag must appear in the prompt.
   // output: Output.object({ tag: "result", schema: z.object({ answer: z.number() }) }),
@@ -341,18 +347,19 @@ if (closeResult.preservedWorktreePath) {
 
 #### `SandboxRunOptions`
 
-| Option               | Type               | Default                       | Description                                                         |
-| -------------------- | ------------------ | ----------------------------- | ------------------------------------------------------------------- |
-| `agent`              | AgentProvider      | —                             | **Required.** Agent provider (e.g. `claudeCode("claude-opus-4-7")`) |
-| `prompt`             | string             | —                             | Inline prompt (mutually exclusive with `promptFile`)                |
-| `promptFile`         | string             | —                             | Path to prompt file (mutually exclusive with `prompt`)              |
-| `promptArgs`         | PromptArgs         | —                             | Key-value map for `{{KEY}}` placeholder substitution                |
-| `maxIterations`      | number             | `1`                           | Maximum iterations to run                                           |
-| `completionSignal`   | string \| string[] | `<promise>COMPLETE</promise>` | String(s) the agent emits to stop the iteration loop early          |
-| `idleTimeoutSeconds` | number             | `600`                         | Idle timeout in seconds — resets on each agent output event         |
-| `name`               | string             | —                             | Display name for the run                                            |
-| `logging`            | object             | file (auto-generated)         | `{ type: 'file', path }` or `{ type: 'stdout' }`                    |
-| `signal`             | AbortSignal        | —                             | Cancels the run when aborted; handle stays usable afterward         |
+| Option                     | Type               | Default                       | Description                                                                          |
+| -------------------------- | ------------------ | ----------------------------- | ------------------------------------------------------------------------------------ |
+| `agent`                    | AgentProvider      | —                             | **Required.** Agent provider (e.g. `claudeCode("claude-opus-4-7")`)                  |
+| `prompt`                   | string             | —                             | Inline prompt (mutually exclusive with `promptFile`)                                 |
+| `promptFile`               | string             | —                             | Path to prompt file (mutually exclusive with `prompt`)                               |
+| `promptArgs`               | PromptArgs         | —                             | Key-value map for `{{KEY}}` placeholder substitution                                 |
+| `maxIterations`            | number             | `1`                           | Maximum iterations to run                                                            |
+| `completionSignal`         | string \| string[] | `<promise>COMPLETE</promise>` | String(s) the agent emits to stop the iteration loop early                           |
+| `idleTimeoutSeconds`       | number             | `600`                         | Idle timeout in seconds — resets on each agent output event                          |
+| `completionTimeoutSeconds` | number             | `60`                          | Grace window after the completion signal is seen but the agent process hasn't exited |
+| `name`                     | string             | —                             | Display name for the run                                                             |
+| `logging`                  | object             | file (auto-generated)         | `{ type: 'file', path }` or `{ type: 'stdout' }`                                     |
+| `signal`                   | AbortSignal        | —                             | Cancels the run when aborted; handle stays usable afterward                          |
 
 #### `SandboxRunResult`
 
@@ -459,22 +466,23 @@ await sandbox.close();
 
 #### `WorktreeRunOptions`
 
-| Option               | Type                   | Default | Description                                                                                                                          |
-| -------------------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `agent`              | AgentProvider          | —       | **Required.** Agent provider                                                                                                         |
-| `sandbox`            | SandboxProvider        | —       | **Required.** Sandbox provider (AFK agents must be sandboxed)                                                                        |
-| `prompt`             | string                 | —       | Inline prompt (mutually exclusive with `promptFile`)                                                                                 |
-| `promptFile`         | string                 | —       | Path to prompt file                                                                                                                  |
-| `maxIterations`      | number                 | 1       | Maximum iterations to run                                                                                                            |
-| `completionSignal`   | string \| string[]     | —       | Substring(s) to stop the iteration loop early                                                                                        |
-| `idleTimeoutSeconds` | number                 | 600     | Idle timeout in seconds                                                                                                              |
-| `name`               | string                 | —       | Optional run name                                                                                                                    |
-| `logging`            | LoggingOption          | file    | Logging mode                                                                                                                         |
-| `hooks`              | SandboxHooks           | —       | Lifecycle hooks (`host.*`, `sandbox.*`)                                                                                              |
-| `promptArgs`         | PromptArgs             | —       | Key-value map for `{{KEY}}` placeholder substitution                                                                                 |
-| `env`                | Record<string, string> | —       | Environment variables to inject into the sandbox                                                                                     |
-| `resumeSession`      | string                 | —       | Resume a prior session by ID for agents that support resume. Incompatible with `maxIterations > 1`. Session file must exist on host. |
-| `signal`             | AbortSignal            | —       | Cancel the run when aborted. Kills the in-flight agent subprocess; the worktree is preserved on disk. Rejects with `signal.reason`.  |
+| Option                     | Type                   | Default | Description                                                                                                                          |
+| -------------------------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `agent`                    | AgentProvider          | —       | **Required.** Agent provider                                                                                                         |
+| `sandbox`                  | SandboxProvider        | —       | **Required.** Sandbox provider (AFK agents must be sandboxed)                                                                        |
+| `prompt`                   | string                 | —       | Inline prompt (mutually exclusive with `promptFile`)                                                                                 |
+| `promptFile`               | string                 | —       | Path to prompt file                                                                                                                  |
+| `maxIterations`            | number                 | 1       | Maximum iterations to run                                                                                                            |
+| `completionSignal`         | string \| string[]     | —       | Substring(s) to stop the iteration loop early                                                                                        |
+| `idleTimeoutSeconds`       | number                 | 600     | Idle timeout in seconds                                                                                                              |
+| `completionTimeoutSeconds` | number                 | 60      | Grace window after completion signal is seen but agent process hasn't exited                                                         |
+| `name`                     | string                 | —       | Optional run name                                                                                                                    |
+| `logging`                  | LoggingOption          | file    | Logging mode                                                                                                                         |
+| `hooks`                    | SandboxHooks           | —       | Lifecycle hooks (`host.*`, `sandbox.*`)                                                                                              |
+| `promptArgs`               | PromptArgs             | —       | Key-value map for `{{KEY}}` placeholder substitution                                                                                 |
+| `env`                      | Record<string, string> | —       | Environment variables to inject into the sandbox                                                                                     |
+| `resumeSession`            | string                 | —       | Resume a prior session by ID for agents that support resume. Incompatible with `maxIterations > 1`. Session file must exist on host. |
+| `signal`                   | AbortSignal            | —       | Cancel the run when aborted. Kills the in-flight agent subprocess; the worktree is preserved on disk. Rejects with `signal.reason`.  |
 
 #### `WorktreeRunResult`
 
@@ -502,7 +510,7 @@ Sandcastle uses a **branch strategy** configured on the sandbox provider to cont
 
 - **Head** (`{ type: "head" }`) — The agent writes directly to the host working directory. No worktree, no branch indirection. This is the default for bind-mount providers like `docker()`.
 - **Merge-to-head** (`{ type: "merge-to-head" }`) — Sandcastle creates a temporary branch in a git worktree. The agent works on the temp branch, and changes are merged back to HEAD when done. The temp branch is cleaned up after merge.
-- **Branch** (`{ type: "branch", branch: "foo" }`) — Commits land on an explicitly named branch in a git worktree.
+- **Branch** (`{ type: "branch", branch: "foo" }`) — Commits land on an explicitly named branch in a git worktree. Re-running with the same branch reuses the existing worktree and fast-forwards it from `origin` when safe — see [ADR 0003](docs/adr/0003-reuse-worktree-by-default.md).
 
 For bind-mount providers (like Docker), the worktree directory is bind-mounted into the container — the agent writes directly to the host filesystem through the mount, so no sync is needed.
 
@@ -614,6 +622,25 @@ await run({
 
 Tell the agent to output your chosen string(s) in the prompt, and the orchestrator will stop when it detects any of them. The matched signal is returned as `result.completionSignal`.
 
+#### Hanging processes after the completion signal
+
+The agent process is expected to exit shortly after emitting the completion signal. When a child it spawned — a `gh`/git subprocess, a long-lived MCP server, etc. — inherits the agent's stdout pipe and keeps it open, the parent process can linger long past its logical end. Sandcastle would otherwise wait for the full `idleTimeoutSeconds` and fail with `AgentIdleTimeoutError`, throwing away the commits the agent already made.
+
+Instead, once the completion signal is observed in the output buffer, Sandcastle swaps in a short **completion timeout** (default 60 s). When it expires, the run resolves successfully with a warning that the process was hanging; `result.commits` and `result.completionSignal` are populated as if the process had exited cleanly. The timer resets on every subsequent output line, so trailing data emitted after the signal — token-usage events, terminal `result` events, a structured-output `<tag>` — is still captured.
+
+A clean process exit always wins the race, so healthy runs gain zero added latency. The completion timeout only matters when the process hangs.
+
+Tune the window with `completionTimeoutSeconds`:
+
+```ts
+await run({
+  // ...
+  completionTimeoutSeconds: 30, // shorter grace window
+});
+```
+
+This is independent of `idleTimeoutSeconds`. They cover different phases: `idleTimeoutSeconds` runs **before** any signal is seen (genuinely stuck agent → fail); `completionTimeoutSeconds` runs **after** the signal is seen (hanging process → succeed with warning). See [ADR 0019](docs/adr/0019-completion-timeout-for-hanging-process.md).
+
 ### Structured output
 
 Use `Output.object()` to extract a typed, schema-validated JSON payload from the agent's stdout. The agent emits its answer inside an XML tag you specify, and Sandcastle parses, validates, and returns it on `result.output`. The schema can be any [Standard Schema](https://standardschema.dev) validator — the examples below use [Zod](https://zod.dev), but Valibot, ArkType, and others work identically. See [ADR 0010](docs/adr/0010-structured-output.md) for design rationale.
@@ -684,13 +711,19 @@ Scaffolds the `.sandcastle/` config directory and builds the container image. Th
 
 Init detects your host package manager (npm, pnpm, yarn, or bun) from a `packageManager` field or lockfile, defaulting to npm. Templates whose `main` file imports a host dependency — the planner templates import [Zod](https://zod.dev) for their `<plan>` output schema — prompt you to install it with that package manager when it isn't already in your `package.json`, so the first `npx tsx .sandcastle/main.ts` doesn't fail with `ERR_MODULE_NOT_FOUND`.
 
-| Option         | Required | Default                      | Description                                                                  |
-| -------------- | -------- | ---------------------------- | ---------------------------------------------------------------------------- |
-| `--image-name` | No       | `sandcastle:<repo-dir-name>` | Docker image name                                                            |
-| `--agent`      | No       | Interactive prompt           | Agent to use (`claude-code`, `pi`, `codex`, `cursor`, `opencode`, `copilot`) |
-| `--model`      | No       | Agent's default model        | Model to use (e.g. `claude-sonnet-4-6`). Defaults to agent's default         |
-| `--sandbox`    | No       | Interactive prompt           | Sandbox provider to use (`docker`, `podman`)                                 |
-| `--template`   | No       | Interactive prompt           | Template to scaffold (e.g. `blank`, `simple-loop`)                           |
+Every interactive prompt has a paired `--flag` so the entire init can run non-interactively (e.g. in CI or a scripted setup). When stdin is not a TTY and a required flag is missing, init fails fast with a clear error rather than wedging on a prompt.
+
+| Option                    | Required | Default                      | Description                                                                                                    |
+| ------------------------- | -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `--image-name`            | No       | `sandcastle:<repo-dir-name>` | Docker image name                                                                                              |
+| `--agent`                 | No       | Interactive prompt           | Agent to use (`claude-code`, `pi`, `codex`, `cursor`, `opencode`, `copilot`)                                   |
+| `--model`                 | No       | Agent's default model        | Model to use (e.g. `claude-sonnet-4-6`). Defaults to agent's default                                           |
+| `--sandbox`               | No       | Interactive prompt           | Sandbox provider to use (`docker`, `podman`)                                                                   |
+| `--template`              | No       | Interactive prompt           | Template to scaffold (e.g. `blank`, `simple-loop`)                                                             |
+| `--issue-tracker`         | No       | Interactive prompt           | Issue tracker to use (`github-issues`, `beads`, `custom`)                                                      |
+| `--create-label`          | No       | Interactive prompt           | `true` / `false` — whether to create the `Sandcastle` GitHub label (only with `--issue-tracker github-issues`) |
+| `--build-image`           | No       | Interactive prompt           | `true` / `false` — whether to build the sandbox image now (silently ignored with `--issue-tracker custom`)     |
+| `--install-template-deps` | No       | Interactive prompt           | `true` / `false` — whether to install template host deps (e.g. `zod` for the planner templates)                |
 
 Creates the following files:
 
@@ -740,26 +773,27 @@ Removes the Podman image.
 
 ### `RunOptions`
 
-| Option               | Type               | Default                       | Description                                                                                                                                                                                                        |
-| -------------------- | ------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `agent`              | AgentProvider      | —                             | **Required.** Agent provider (e.g. `claudeCode("claude-opus-4-7")`, `pi("claude-sonnet-4-6")`, `codex("gpt-5.4-mini")`, `cursor("composer-2")`, `opencode("opencode/big-pickle")`, `copilot("claude-sonnet-4.5")`) |
-| `sandbox`            | SandboxProvider    | —                             | **Required.** Sandbox provider (e.g. `docker()`, `podman()`, `docker({ imageName: "sandcastle:local" })`)                                                                                                          |
-| `cwd`                | string             | `process.cwd()`               | Host repo directory — anchor for `.sandcastle/` artifacts and git operations. Relative paths resolve against `process.cwd()`.                                                                                      |
-| `prompt`             | string             | —                             | Inline prompt (mutually exclusive with `promptFile`)                                                                                                                                                               |
-| `promptFile`         | string             | —                             | Path to prompt file (mutually exclusive with `prompt`). Resolves against `process.cwd()`, **not** `cwd`.                                                                                                           |
-| `maxIterations`      | number             | `1`                           | Maximum iterations to run                                                                                                                                                                                          |
-| `hooks`              | SandboxHooks       | —                             | Lifecycle hooks (`host.*`, `sandbox.*`)                                                                                                                                                                            |
-| `name`               | string             | —                             | Display name for the run, shown as a prefix in log output                                                                                                                                                          |
-| `promptArgs`         | PromptArgs         | —                             | Key-value map for `{{KEY}}` placeholder substitution                                                                                                                                                               |
-| `branchStrategy`     | BranchStrategy     | per-provider default          | Branch strategy: `{ type: 'head' }`, `{ type: 'merge-to-head' }`, or `{ type: 'branch', branch: '…' }`                                                                                                             |
-| `copyToWorktree`     | string[]           | —                             | Host-relative file paths to copy into the sandbox before start (not supported with `branchStrategy: { type: 'head' }`)                                                                                             |
-| `logging`            | object             | file (auto-generated)         | `{ type: 'file', path }` or `{ type: 'stdout' }`                                                                                                                                                                   |
-| `completionSignal`   | string \| string[] | `<promise>COMPLETE</promise>` | String or array of strings the agent emits to stop the iteration loop early                                                                                                                                        |
-| `idleTimeoutSeconds` | number             | `600`                         | Idle timeout in seconds — resets on each agent output event                                                                                                                                                        |
-| `resumeSession`      | string             | —                             | Resume a prior session by ID for agents that support resume. Incompatible with `maxIterations > 1`. Session file must exist on host.                                                                               |
-| `signal`             | AbortSignal        | —                             | Cancel the run when aborted. Kills the in-flight agent subprocess and cancels lifecycle hooks; the worktree is preserved on disk. Rejects with `signal.reason`.                                                    |
-| `timeouts`           | Timeouts           | —                             | Override default timeouts for built-in lifecycle steps: `copyToWorktreeMs` (60 000), `gitSetupMs` (10 000), `commitCollectionMs` (30 000), `mergeToHostMs` (30 000).                                               |
-| `output`             | OutputDefinition   | —                             | Structured output definition (`Output.object(…)` or `Output.string(…)`). Requires `maxIterations === 1`. See [Structured output](#structured-output).                                                              |
+| Option                     | Type               | Default                       | Description                                                                                                                                                                                                                  |
+| -------------------------- | ------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent`                    | AgentProvider      | —                             | **Required.** Agent provider (e.g. `claudeCode("claude-opus-4-7")`, `pi("claude-sonnet-4-6")`, `codex("gpt-5.4-mini")`, `cursor("composer-2")`, `opencode("opencode/big-pickle")`, `copilot("claude-sonnet-4.5")`)           |
+| `sandbox`                  | SandboxProvider    | —                             | **Required.** Sandbox provider (e.g. `docker()`, `podman()`, `docker({ imageName: "sandcastle:local" })`)                                                                                                                    |
+| `cwd`                      | string             | `process.cwd()`               | Host repo directory — anchor for `.sandcastle/` artifacts and git operations. Relative paths resolve against `process.cwd()`.                                                                                                |
+| `prompt`                   | string             | —                             | Inline prompt (mutually exclusive with `promptFile`)                                                                                                                                                                         |
+| `promptFile`               | string             | —                             | Path to prompt file (mutually exclusive with `prompt`). Resolves against `process.cwd()`, **not** `cwd`.                                                                                                                     |
+| `maxIterations`            | number             | `1`                           | Maximum iterations to run                                                                                                                                                                                                    |
+| `hooks`                    | SandboxHooks       | —                             | Lifecycle hooks (`host.*`, `sandbox.*`)                                                                                                                                                                                      |
+| `name`                     | string             | —                             | Display name for the run, shown as a prefix in log output                                                                                                                                                                    |
+| `promptArgs`               | PromptArgs         | —                             | Key-value map for `{{KEY}}` placeholder substitution                                                                                                                                                                         |
+| `branchStrategy`           | BranchStrategy     | per-provider default          | Branch strategy: `{ type: 'head' }`, `{ type: 'merge-to-head' }`, or `{ type: 'branch', branch: '…' }`                                                                                                                       |
+| `copyToWorktree`           | string[]           | —                             | Host-relative file paths to copy into the sandbox before start (not supported with `branchStrategy: { type: 'head' }`)                                                                                                       |
+| `logging`                  | object             | file (auto-generated)         | `{ type: 'file', path }` or `{ type: 'stdout' }`                                                                                                                                                                             |
+| `completionSignal`         | string \| string[] | `<promise>COMPLETE</promise>` | String or array of strings the agent emits to stop the iteration loop early                                                                                                                                                  |
+| `idleTimeoutSeconds`       | number             | `600`                         | Idle timeout in seconds — resets on each agent output event                                                                                                                                                                  |
+| `completionTimeoutSeconds` | number             | `60`                          | Grace window in seconds after the completion signal is observed but the agent process has not exited (hanging process). See [Hanging processes after the completion signal](#hanging-processes-after-the-completion-signal). |
+| `resumeSession`            | string             | —                             | Resume a prior session by ID for agents that support resume. Incompatible with `maxIterations > 1`. Session file must exist on host.                                                                                         |
+| `signal`                   | AbortSignal        | —                             | Cancel the run when aborted. Kills the in-flight agent subprocess and cancels lifecycle hooks; the worktree is preserved on disk. Rejects with `signal.reason`.                                                              |
+| `timeouts`                 | Timeouts           | —                             | Override default timeouts for built-in lifecycle steps: `copyToWorktreeMs` (60 000), `gitSetupMs` (10 000), `commitCollectionMs` (30 000), `mergeToHostMs` (30 000).                                                         |
+| `output`                   | OutputDefinition   | —                             | Structured output definition (`Output.object(…)` or `Output.string(…)`). Requires `maxIterations === 1`. See [Structured output](#structured-output).                                                                        |
 
 ### `RunResult`
 
@@ -792,13 +826,13 @@ Removes the Podman image.
 
 ### Session capture
 
-After each resumable provider iteration, Sandcastle automatically captures the agent's session file from the sandbox to the host. Claude Code sessions are stored under `~/.claude/projects/<encoded-path>/<session-id>.jsonl`; Codex sessions are stored under `~/.codex/sessions/YYYY/MM/DD/rollout-*-<session-id>.jsonl`. Any provider-specific `cwd` fields are rewritten to match the host repo root, so the provider's native resume command works.
+After each resumable provider iteration, Sandcastle automatically captures the agent's session file from the sandbox to the host. Claude Code sessions are stored under `~/.claude/projects/<encoded-path>/<session-id>.jsonl`; Codex sessions are stored under `~/.codex/sessions/YYYY/MM/DD/rollout-*-<session-id>.jsonl`; Pi sessions are stored under `~/.pi/agent/sessions/--<encoded-cwd>--/<timestamp>_<session-id>.jsonl`. Any provider-specific `cwd` fields are rewritten to match the host repo root, so the provider's native resume command works.
 
-Session capture is enabled by default for `claudeCode()` and `codex()` and can be opted out via `captureSessions: false`. Providers without `sessionStorage` do not attempt capture. Capture failure fails the run.
+Session capture is enabled by default for `claudeCode()`, `codex()`, and `pi()` and can be opted out via `captureSessions: false`. Providers without `sessionStorage` do not attempt capture. Capture failure fails the run.
 
 ### Session resume
 
-Pass `resumeSession` to `run()` to continue a prior Claude Code or Codex conversation inside a new sandbox:
+Pass `resumeSession` to `run()` to continue a prior Claude Code, Codex, or Pi conversation inside a new sandbox:
 
 ```typescript
 const result = await run({
@@ -821,9 +855,9 @@ const first = await run({
 const second = await first.resume?.("Now implement the plan");
 ```
 
-`resume` is present only on results from resumable providers (Claude Code, Codex) — hence the optional-chaining call.
+`resume` is present only on results from resumable providers (Claude Code, Codex, Pi) — hence the optional-chaining call.
 
-Before the sandbox starts, Sandcastle validates that the session file exists on the host and transfers it into the sandbox with `cwd` fields rewritten to match the sandbox-side path. Claude Code receives `--resume <id>`; Codex receives `codex exec resume <id>` with the prompt piped over stdin.
+Before the sandbox starts, Sandcastle validates that the session file exists on the host and transfers it into the sandbox with `cwd` fields rewritten to match the sandbox-side path. Claude Code receives `--resume <id>`; Codex receives `codex exec resume <id>` with the prompt piped over stdin; Pi receives `--session <id>`.
 
 Constraints:
 
@@ -832,6 +866,33 @@ Constraints:
 - Only iteration 1 receives the resume flag; subsequent iterations (if any) start fresh.
 - Providers without resume support reject `resumeSession`.
 
+### Session fork
+
+`RunResult.fork(prompt, options?)` is the sibling of `.resume()`: it continues from the last captured session but leaves the parent session JSONL untouched and writes the child under a new session id. The mechanism is the agent's native fork flag — `claude --resume <id> --fork-session` for Claude Code, `codex exec fork <id>` for Codex.
+
+Fork enables fan-out workflows where a single parent run is the starting point for several independent children:
+
+```typescript
+const parent = await run({
+  agent: claudeCode("claude-opus-4-7"),
+  sandbox: docker(),
+  prompt: "Read the codebase and summarise the data model",
+});
+
+const [reviewA, reviewB] = await Promise.all([
+  parent.fork?.("Review the migration plan", {
+    branchStrategy: { type: "branch", branch: "review-a" },
+  }),
+  parent.fork?.("Audit the auth layer", {
+    branchStrategy: { type: "branch", branch: "review-b" },
+  }),
+]);
+```
+
+**Fork is session-only.** `--fork-session` and `codex exec fork` isolate the agent session JSONL — they do **not** isolate the branch, worktree, or sandbox. Safe concurrent fan-out (`Promise.all([r.fork(a), r.fork(b)])`) requires the caller to give each child a distinct `branch` via `branchStrategy: { type: "branch", branch: "..." }`. The default `head` and `merge-to-head` strategies are **not** safe for concurrent forks: `head` shares the host working directory across all children, and `merge-to-head` races `git merge` against the same HEAD. See [ADR 0018](docs/adr/0018-fork-is-session-only.md).
+
+`fork` is present only on results from providers with `sessionStorage` (Claude Code, Codex) — hence the optional-chaining call. The same single-iteration and session-file constraints as `.resume()` apply.
+
 ### `ClaudeCodeOptions`
 
 The `claudeCode()` factory accepts an optional second argument for provider-specific options:
@@ -860,6 +921,20 @@ agent: codex("gpt-5.4", { effort: "high" });
 | `env`             | `Record<string, string>`                       | `{}`    | Environment variables injected by this agent provider     |
 | `captureSessions` | `boolean`                                      | `true`  | Capture Codex rollout JSONL to host for resume            |
 
+### `PiOptions`
+
+The `pi()` factory accepts an optional second argument for provider-specific options:
+
+```typescript
+agent: pi("claude-sonnet-4-6", { thinking: "high" });
+```
+
+| Option            | Type                                                                     | Default | Description                                              |
+| ----------------- | ------------------------------------------------------------------------ | ------- | -------------------------------------------------------- |
+| `thinking`        | `"off"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` | —       | Pi reasoning effort level via the `--thinking` flag      |
+| `env`             | `Record<string, string>`                                                 | `{}`    | Environment variables injected by this agent provider    |
+| `captureSessions` | `boolean`                                                                | `true`  | Capture pi session JSONL to host for `pi --session <id>` |
+
 ### Provider `env`
 
 Both **agent providers** and **sandbox providers** accept an optional `env: Record<string, string>` in their options. These environment variables are merged with the `.sandcastle/.env` resolver output at launch time:
@@ -1252,7 +1327,7 @@ hooks: {
 
 ```bash
 npm install
-npm run build    # Build with tsgo
+npm run build    # Bundle with tsup
 npm test         # Run tests with vitest
 npm run typecheck # Type-check
 ```

package/dist/{MountConfig.d.ts → MountConfig-CmXclHA5.d.ts}

@@ -4,7 +4,7 @@
  * Each entry describes a host directory to mount into the sandbox container.
  */
 /** A single bind-mount descriptor for docker()/podman() providers. */
-export interface MountConfig {
+interface MountConfig {
     /**
      * Path on the host. Supports:
      * - Absolute paths (`/data/cache`)
@@ -22,4 +22,5 @@ export interface MountConfig {
     /** Mount as read-only. Defaults to `false`. */
     readonly readonly?: boolean;
 }
-//# sourceMappingURL=MountConfig.d.ts.map
+
+export type { MountConfig as M };

package/dist/{SandboxProvider.d.ts → SandboxProvider-EkSMuBp8.d.ts}

@@ -5,20 +5,20 @@
  * handles worktree creation, git mount resolution, and commit extraction.
  */
 /** Result of executing a command inside a sandbox. */
-export interface ExecResult {
+interface ExecResult {
     readonly stdout: string;
     readonly stderr: string;
     readonly exitCode: number;
 }
 /** Options for interactiveExec — the streams the provider should wire to the spawned process. */
-export interface InteractiveExecOptions {
+interface InteractiveExecOptions {
     readonly stdin: NodeJS.ReadableStream;
     readonly stdout: NodeJS.WritableStream;
     readonly stderr: NodeJS.WritableStream;
     readonly cwd?: string;
 }
 /** Handle to a running bind-mount sandbox. */
-export interface BindMountSandboxHandle {
+interface BindMountSandboxHandle {
     /** Absolute path to the worktree inside the sandbox. */
     readonly worktreePath: string;
     /**
@@ -56,7 +56,7 @@ export interface BindMountSandboxHandle {
     close(): Promise<void>;
 }
 /** Options passed to a bind-mount provider's `create` function. */
-export interface BindMountCreateOptions {
+interface BindMountCreateOptions {
     /** Host-side path to the worktree directory. */
     readonly worktreePath: string;
     /** Host-side path to the original repo root. */
@@ -71,7 +71,7 @@ export interface BindMountCreateOptions {
     readonly env: Record<string, string>;
 }
 /** Configuration for createBindMountSandboxProvider. */
-export interface BindMountSandboxProviderConfig {
+interface BindMountSandboxProviderConfig {
     /** Human-readable name for this provider (e.g. "docker", "podman"). */
     readonly name: string;
     /** Environment variables injected by this provider. Merged at launch time. */
@@ -86,7 +86,7 @@ export interface BindMountSandboxProviderConfig {
     readonly create: (options: BindMountCreateOptions) => Promise<BindMountSandboxHandle>;
 }
 /** Handle to a running isolated sandbox (extends bind-mount with file transfer). */
-export interface IsolatedSandboxHandle {
+interface IsolatedSandboxHandle {
     /** Absolute path to the worktree inside the sandbox. */
     readonly worktreePath: string;
     /**
@@ -124,12 +124,12 @@ export interface IsolatedSandboxHandle {
     close(): Promise<void>;
 }
 /** Options passed to an isolated provider's `create` function. */
-export interface IsolatedCreateOptions {
+interface IsolatedCreateOptions {
     /** Environment variables to inject into the sandbox. */
     readonly env: Record<string, string>;
 }
 /** Configuration for createIsolatedSandboxProvider. */
-export interface IsolatedSandboxProviderConfig {
+interface IsolatedSandboxProviderConfig {
     /** Human-readable name for this provider (e.g. "daytona", "e2b"). */
     readonly name: string;
     /** Environment variables injected by this provider. Merged at launch time. */
@@ -138,9 +138,7 @@ export interface IsolatedSandboxProviderConfig {
     readonly create: (options: IsolatedCreateOptions) => Promise<IsolatedSandboxHandle>;
 }
 /** A bind-mount sandbox provider. */
-export interface BindMountSandboxProvider {
-    /** @internal Discriminator for internal dispatch. */
-    readonly tag: "bind-mount";
+interface BindMountSandboxProvider {
     /** Human-readable provider name. */
     readonly name: string;
     /** Environment variables injected by this provider. */
@@ -150,22 +148,16 @@ export interface BindMountSandboxProvider {
      * `undefined` when the provider does not declare a sandbox home directory.
      */
     readonly sandboxHomedir: string | undefined;
-    /** @internal Create a sandbox handle. */
-    readonly create: (options: BindMountCreateOptions) => Promise<BindMountSandboxHandle>;
 }
 /** An isolated sandbox provider. */
-export interface IsolatedSandboxProvider {
-    /** @internal Discriminator for internal dispatch. */
-    readonly tag: "isolated";
+interface IsolatedSandboxProvider {
     /** Human-readable provider name. */
     readonly name: string;
     /** Environment variables injected by this provider. */
     readonly env: Record<string, string>;
-    /** @internal Create an isolated sandbox handle. */
-    readonly create: (options: IsolatedCreateOptions) => Promise<IsolatedSandboxHandle>;
 }
 /** Handle to a no-sandbox session — runs commands directly on the host. */
-export interface NoSandboxHandle {
+interface NoSandboxHandle {
     /** Absolute path to the worktree on the host. */
     readonly worktreePath: string;
     /**
@@ -194,29 +186,22 @@ export interface NoSandboxHandle {
     close(): Promise<void>;
 }
 /** A no-sandbox provider — runs the agent directly on the host with no container isolation. */
-export interface NoSandboxProvider {
-    /** @internal Discriminator for internal dispatch. */
-    readonly tag: "none";
+interface NoSandboxProvider {
     /** Human-readable provider name. */
     readonly name: string;
     /** Environment variables injected by this provider. */
     readonly env: Record<string, string>;
-    /** @internal Create a no-sandbox handle. */
-    readonly create: (options: {
-        readonly worktreePath: string;
-        readonly env: Record<string, string>;
-    }) => Promise<NoSandboxHandle>;
 }
 /** Head strategy: agent writes directly to host working directory. Bind-mount only. */
-export interface HeadBranchStrategy {
+interface HeadBranchStrategy {
     readonly type: "head";
 }
 /** Merge-to-head strategy: temp branch, merge back to HEAD, delete temp branch. */
-export interface MergeToHeadBranchStrategy {
+interface MergeToHeadBranchStrategy {
     readonly type: "merge-to-head";
 }
 /** Branch strategy: commits land on an explicit named branch. */
-export interface NamedBranchStrategy {
+interface NamedBranchStrategy {
     readonly type: "branch";
     readonly branch: string;
     /**
@@ -228,30 +213,31 @@ export interface NamedBranchStrategy {
     readonly baseBranch?: string;
 }
 /** Branch strategy for bind-mount providers (all three variants). */
-export type BindMountBranchStrategy = HeadBranchStrategy | MergeToHeadBranchStrategy | NamedBranchStrategy;
+type BindMountBranchStrategy = HeadBranchStrategy | MergeToHeadBranchStrategy | NamedBranchStrategy;
 /** Branch strategy for isolated providers (no head — can't write to host). */
-export type IsolatedBranchStrategy = MergeToHeadBranchStrategy | NamedBranchStrategy;
+type IsolatedBranchStrategy = MergeToHeadBranchStrategy | NamedBranchStrategy;
 /** Branch strategy for no-sandbox providers (all three — same as bind-mount). */
-export type NoSandboxBranchStrategy = HeadBranchStrategy | MergeToHeadBranchStrategy | NamedBranchStrategy;
+type NoSandboxBranchStrategy = HeadBranchStrategy | MergeToHeadBranchStrategy | NamedBranchStrategy;
 /** Union of all branch strategy variants. */
-export type BranchStrategy = BindMountBranchStrategy | IsolatedBranchStrategy | NoSandboxBranchStrategy;
+type BranchStrategy = BindMountBranchStrategy | IsolatedBranchStrategy | NoSandboxBranchStrategy;
 /**
  * A sandbox provider — the pluggable unit that `run()`, `interactive()`, and
  * `createSandbox()` accept. Tagged for internal dispatch: "bind-mount",
  * "isolated", or "none". When `NoSandboxProvider` is used, the agent runs
  * directly on the host with no container isolation — opt in at your own risk.
  */
-export type SandboxProvider = BindMountSandboxProvider | IsolatedSandboxProvider | NoSandboxProvider;
+type SandboxProvider = BindMountSandboxProvider | IsolatedSandboxProvider | NoSandboxProvider;
 /** @deprecated Use `SandboxProvider` — it now includes `NoSandboxProvider`. */
-export type AnySandboxProvider = SandboxProvider;
+type AnySandboxProvider = SandboxProvider;
 /**
  * Create a bind-mount sandbox provider from a config object.
  * The returned provider can be passed to `run()` or `createSandbox()`.
  */
-export declare const createBindMountSandboxProvider: (config: BindMountSandboxProviderConfig) => BindMountSandboxProvider;
+declare const createBindMountSandboxProvider: (config: BindMountSandboxProviderConfig) => BindMountSandboxProvider;
 /**
  * Create an isolated sandbox provider from a config object.
  * The returned provider can be passed to `run()` or `createSandbox()`.
  */
-export declare const createIsolatedSandboxProvider: (config: IsolatedSandboxProviderConfig) => IsolatedSandboxProvider;
-//# sourceMappingURL=SandboxProvider.d.ts.map
+declare const createIsolatedSandboxProvider: (config: IsolatedSandboxProviderConfig) => IsolatedSandboxProvider;
+
+export { type AnySandboxProvider as A, type BindMountSandboxHandle as B, type ExecResult as E, type HeadBranchStrategy as H, type IsolatedSandboxProvider as I, type MergeToHeadBranchStrategy as M, type NoSandboxProvider as N, type SandboxProvider as S, type BranchStrategy as a, type NamedBranchStrategy as b, type BindMountBranchStrategy as c, type BindMountCreateOptions as d, type BindMountSandboxProvider as e, type BindMountSandboxProviderConfig as f, type InteractiveExecOptions as g, type IsolatedBranchStrategy as h, type IsolatedCreateOptions as i, type IsolatedSandboxHandle as j, type IsolatedSandboxProviderConfig as k, type NoSandboxBranchStrategy as l, type NoSandboxHandle as m, createBindMountSandboxProvider as n, createIsolatedSandboxProvider as o };