@henryqw/pi-subagent 4.1.2 → 6.0.0

package/CONTEXT.md

@@ -2,18 +2,21 @@
 
 ## Purpose
 
-Provide validated built-in and user Roles, shared task-model Pi launch policy, generic managed Herdr Subagent hosting, a `delegate_task` extension that runs one selected bounded workflow in one or more ephemeral child processes, and a bundled Main-side `pi-subagent-delegated-development` policy Skill. The Skill requires a clean committed Git `HEAD`, exact clean committed-diff review through a private byte-verified patch file reference, and post-validation recovery cleanup; it adds no runtime behavior or changes generic fallback.
+Provide validated built-in and user Roles, shared task-model Pi launch policy, generic managed Herdr Subagent hosting, generic `delegate_task` delegation, and package-owned `delegate_flow` Git orchestration. Main plans and orchestrates; `delegate_task` remains a flat bounded delegation tool, while Flow uses the effective Implementer and only invokes its effective Reviewer for explicit judgment criteria after authoritative validation. The bundled Main-side Skill adds no runtime behavior or changes generic fallback.
 
 ## Domain glossary
 
-- **Main**: Pi session delegating work.
+- **Main**: Pi session that plans and orchestrates delegated work.
 - **Subagent**: isolated Pi child process handling one task.
-- **Role**: package-shipped built-in or user-owned Markdown definition of a reusable responsibility, with a name, description, system instructions, optional base tool allowlist, extensions, and Skill names.
-- **Model Class**: `fast`, `balanced`, `frontier`, or `fav`, assigned in shared task-model settings or overridden by Main from task complexity.
+- **Role**: package-shipped built-in or user-owned Markdown definition of a reusable responsibility, with a name, description, system instructions, required `tools`, `extensions`, and `skills` arrays, and optional isolation.
+- **Model Class**: `fast`, `balanced`, `frontier`, or `fav`, resolved through shared task-model settings; Main normally selects `fast`, may select `balanced` upfront for obvious complexity, and leaves direct model/thinking overrides to explicit user requests.
 - **Route**: configured model and thinking-level pair selected from a shared Model Class profile; the primary route precedes its optional fallback.
 - **Delegated Task**: one bounded work request sent from Main to one Role.
-- **Workflow**: orchestration of one or more Delegated Tasks; `delegate_task` owns its selected mode, while library callers compose executor runs in JavaScript.
+- **Workflow**: generic orchestration of one or more Delegated Tasks; `delegate_task` owns its selected mode, while library callers compose executor runs in JavaScript.
 - **Workflow Mode**: `delegate_task` tool policy selected per call for `single`, `parallel`, or `chain` execution; not a Role property or executor API.
+- **Flow**: package-owned, memory-only Git implementation and integration workflow started by `delegate_flow`.
+- **Unit Worktree**: one Flow-owned worktree and branch for one Flow unit; it is reused for rebase, validation, optional exact review, and one repair.
+- **Review Packet**: exact `{base, tip, patchPath}` evidence delivered to the Flow Reviewer only for a unit's explicit `review` criterion.
 - **Resource Policy**: Role ownership of base tools, extensions, and Skill names, plus explicit caller additions of tools, extensions, and environment through `createRoleLaunch`.
 - **Pi Launch**: reusable `{env,args}` policy for one Role, resolved model route, explicit caller resources, and project trust.
 - **Ephemeral Executor**: mechanism that receives a prepared Pi Launch, runs one bounded Delegated Task in one no-session child process, and returns its result without discovering resources or composing a Workflow.
@@ -21,12 +24,15 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 
 ## Invariants
 
-- One Delegated Task creates one ephemeral child process and no saved session. Timeout behavior: `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). Configurable via the `timeout` object in `~/.pi/agent/config/pi-subagent/pi-subagent.json` (`idleMinutes`, `maxMinutes`; defaults 10/30).
+- One Delegated Task creates one ephemeral child process and no saved session. Timeout behavior: `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). After direct Pi exits, inherited stdout/stderr drain until EOF unless an escaped descendant holds them past short inactivity or a one-second hard deadline. Configurable via the `timeout` object in `~/.pi/agent/config/pi-subagent/pi-subagent.json` (`idleMinutes`, `maxMinutes`; defaults 10/30).
 - Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/pi-subagent/pi-subagent.json` or the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable; excess calls wait FIFO. Queued calls do not start a child or consume child timeout. Managed Herdr workers are unaffected.
-- Ambient child extensions and Skills stay disabled; Role explicitly selects extension sources and named Skills. Pi loads Skills supplied by those extension packages or their resource discovery. With Role and caller tools omitted, no allowlist is installed and Pi uses its defaults. Caller tools with omitted Role tools snapshot Main's effective active built-ins into the installed policy; explicit Role tools set the base. Loaded extension tools activate automatically in every case.
-- Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation.
-- Main selects Role and may override Model Class and thinking level per task; omitted class uses shared `pi-subagent/delegateTask` assignment, initially `balanced`. Library callers select Role plus their own shared task ID.
+- Ambient child extensions and Skills stay disabled. Every Role requires `tools`, `extensions`, and `skills` YAML arrays, and every launch installs the Role tool policy. `tools: []` activates no base built-ins but does activate all tools from explicitly selected trusted extension bundles and explicit caller tool additions; `skills: []` selects no separately named Role Skills but trusted selected extension Skills still load; `extensions: []` selects no Role extension bundle. A Role/caller explicitly selected extension is a trusted atomic capability bundle: all tools it registers and all Skills supplied through its Pi package metadata or dynamic `resources_discover` load alongside separately named Role Skills. This intentionally includes the extension's executable lifecycle/prompt behavior; pi-subagent does not infer or externally narrow undocumented dependencies, and loading an extension is not sandboxing. Scope children by selecting fewer trusted extensions; finer granularity requires separate entry points/configuration or an upstream split. Explicit Role/caller tool names still verify against the final filtered registry, while parent-only recursive orchestration tools remain excluded.
+- Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation. Explicit Role/caller tool names verify against the final filtered child registry after explicit provider `session_start` handlers, and unavailable names fail before the first turn.
+- Main policy populates direct `model` and `thinking` only for explicit user overrides; otherwise it selects only `modelClass` (`fast` normally, `balanced` upfront for obvious complexity). This has no provenance tracking or runtime enforcement. An omitted class uses the shared `pi-subagent/delegateTask` assignment; library callers select a Role plus their own shared task ID.
 - The selected profile resolves primary then fallback only before launch when a route, model, or thinking level is unavailable. If neither route is usable, launch rejects with `Run /task-models`; a started child is never retried by this package.
-- User Role Markdown files and Subagent JSON config live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models.json`. Package-shipped built-in Roles (`implementer`, `reviewer`) resolve from the package's own `examples/roles/` Markdown through the same parser; a same-named user file explicitly overrides a built-in.
+- User Role Markdown files and Subagent JSON config live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models.json`. Package-shipped built-in Roles (`implementer`, `reviewer`) resolve from the package's own `examples/roles/` Markdown through the same parser; a same-named user file explicitly overrides a built-in for `delegate_task` and `delegate_flow`.
+- `delegate_flow` accepts 1–8 independent units with direct validation commands, optional `modelClass`, and optional non-empty `review` judgment text. Omitted classes use the shared `pi-subagent/delegateTask` assignment; each unit's current class resolves through its shared profile route for its Implementer and, when `review` exists, Reviewer. At Flow start it always resolves/freezes the effective Implementer and resolves/freezes a Reviewer only when at least one requested unit has `review`. One active Flow creates every Unit Worktree before launching Implementers in parallel, then processes settled units in declared order. For each unit Flow rebases in place when earlier units advanced Main, inspects committed Git state, and runs declared validation. Validation is authoritative for objective verification: units without `review` fast-forward their exact validated tip; units with `review` send the exact Review Packet to the Reviewer in the same worktree and require exact `PASS` before the same guarded `git merge --ff-only` path.
+- Flow is memory-only. Only a post-rebase commit drop produces a no-op (`base === tip`); it validates, skips Reviewer and merge, then cleans up ordinarily. Initial zero-commit implementations block. Implementer, validation, or reviewer blocks allow one `delegate_flow_continue({ guidance, modelClass? })` repair in the same worktree; omission retains the Unit's current class and presence replaces it for that repair. A second block is terminal. Rebase and evidence/Reviewer/infrastructure failures retain worktrees. A reported fast-forward failure retains its worktree unless Main is clean at the exact integrated tip, which completes with the merge diagnostic as a warning. Cleanup uses non-forced worktree removal and branch deletion; cleanup refusal is a completion warning.
+- Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge validation. It never changes generic `delegate_task` Role resolution, isolation, non-Git fallback, or ordinary direct plan/file review.
 - Numbered Codex routes prefer Main's active account slot and explicitly load the multi-Codex child extension.
 - Generic Herdr host functions validate workspace ownership and provisioning identity while callers retain domain state, prompts, and lifecycle decisions.

package/README.md

@@ -1,11 +1,11 @@
 # `@henryqw/pi-subagent`
 
-Delegate bounded work to isolated Pi child processes. The `delegate_task` tool has one flat contract with exactly one selected mode: single, parallel, or chain. Package authors can reuse the same Role launch policy and active-Pi executor from JavaScript.
+Delegate bounded work to isolated Pi child processes. Main plans and orchestrates; generic `delegate_task` selects one flat single, parallel, or chain mode. Package-owned `delegate_flow` runs a fixed Git implementation-and-verification Flow. Package authors can reuse the same Role launch policy and active-Pi executor from JavaScript.
 
 ## Why
 
 - **Created for**: Pi users who need to delegate bounded work to isolated child Pi processes without losing Main's context.
-- **Advantage**: One flat `delegate_task` tool contract with single, parallel, and chain modes, plus reusable Role launch policies for package authors.
+- **Advantage**: Generic bounded delegation plus a deterministic package-owned Git Flow, with reusable Role launch policies for package authors.
 
 ## Install
 
@@ -26,7 +26,9 @@ pi install npm:@henryqw/pi-subagent
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
-| `delegate_task` | tool | Delegate bounded work to one or more isolated Pi child processes. |
+| `delegate_task` | tool | Generic bounded delegation in one single, parallel, or chain mode. |
+| `delegate_flow` | tool | Package-owned parallel implementation and declared-order Git integration for 1–8 independent units. |
+| `delegate_flow_continue` | tool | Repair the blocked Flow unit once in its existing worktree. |
 
 ### `delegate_task`
 
@@ -43,15 +45,34 @@ Select exactly one shape:
 { chain: [{ role, task, model?, modelClass?, thinking? }], background? }
 ```
 
-`model` is `provider/modelId` and overrides `modelClass`. `modelClass` is `fast`, `balanced`, `frontier`, or `fav`; omission uses the shared `pi-subagent/delegateTask` assignment. `background` applies to the entire selected mode and is never a per-delegation field.
+`model` is `provider/modelId` and overrides `modelClass`. Main populates `model` and `thinking` only for an explicit user override; otherwise it chooses only `modelClass`—`fast` normally, or `balanced` upfront for obviously complex work. This is Main policy only: the runtime records no provenance and does not enforce it. `modelClass` is `fast`, `balanced`, `frontier`, or `fav`; omission uses the shared `pi-subagent/delegateTask` assignment. `background` applies to the entire selected mode and is never a per-delegation field.
 
 Parallel mode starts entries concurrently, waits for every entry, and reports them in input order. Chain mode is sequential and fail-fast; every literal `{previous}` receives only the immediately preceding successful assistant output. Foreground failures throw after retaining bounded sibling and recovery evidence. One tool call has one aggregate 50 KiB Main-visible transport cap, not 50 KiB per child.
 
 Background workflows are session-scoped. Session shutdown or reload aborts them and may deliver only recoverable-work evidence or no follow-up message.
 
+The transient status widget owns live progress: spinner or terminal state, wrapped task summary, model, thinking level, tokens, and duration; at capacity, it evicts the oldest terminal row so new active work remains visible, and terminal rows otherwise clear on the next real user input. The final `delegate_task` block is deliberately minimal: bounded final summaries, role attribution for parallel/chain, and only retained-worktree recovery paths. It has no expanded view.
+
 Each delegation resolves its own Role, resources, route, and optional worktree request. When available, `isolation: worktree` gives each entry a deterministic separate worktree; non-Git or unborn-`HEAD` contexts may use Main's cwd. Siblings and chain steps never implicitly share one created worktree.
 
-See [Orchestration, isolation, and the public API](./docs/orchestration.md) for the complete contract and JavaScript composition examples.
+See [Orchestration, isolation, and the public API](./docs/orchestration.md) for generic delegation, Flow behavior, and JavaScript composition examples.
+
+### `delegate_flow`
+
+Use Flow only for independent, commuting Git changes. It accepts 1–8 uniquely identified units, each with a bounded task, optional `modelClass`, direct command/argument validation gate, and optional non-empty `review` judgment criterion:
+
+```text
+delegate_flow({ units: [{ id, task, modelClass?, validation: [{ command, args }], review? }] })
+delegate_flow_continue({ guidance, modelClass? })
+```
+
+Objective verification is authoritative. Flow always inspects committed Git state and runs declared validation. A unit without `review` skips review evidence and Reviewer launch, then fast-forwards its exact validated tip through the existing guarded `git merge --ff-only` path. Add `review` only for an explicit judgment that automation cannot establish; that unit retains the exact `{base, tip, patchPath}` protocol and requires exact `PASS` before the same integration path.
+
+One memory-only Flow may be active. At start it resolves/freezes the effective `implementer` Role, including a same-named user override, and resolves/freezes the effective `reviewer` only if at least one requested unit has `review`. Omitted `modelClass` uses the shared `pi-subagent/delegateTask` assignment; a selected class resolves through its shared profile model-and-thinking route for the unit's Implementer and, when applicable, Reviewer. It creates one Unit Worktree per unit, runs Implementers in parallel, then processes settled results in declared order. It removes the worktree and branch non-forcibly after integration; a refusal is a completion warning with the retained worktree path and/or branch.
+
+A rebase that drops all unit commits is a no-op: Flow validates it, skips Reviewer and merge, then cleans up ordinarily. Implementer, validation, or review blocks can be repaired once through `delegate_flow_continue` in the same worktree. Omitted continuation `modelClass` retains the blocked unit's current class; a supplied class replaces it for that one repair. Rebase and infrastructure failures are terminal. A reported fast-forward failure completes with its diagnostic as a warning only when Git left Main clean at the exact integrated tip; otherwise it is terminal and retains the affected worktree. Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge gate.
+
+`delegate_task` remains generic with its ordinary isolation behavior. Flow uses the package-shipped Implementer by default and the package-shipped Reviewer only when a unit requests review; same-named user Roles remain supported overrides.
 
 ## Config
 
@@ -77,10 +98,10 @@ Each Role `.md` file in the same directory accepts these frontmatter fields:
 | --- | --- | --- | --- |
 | `name` | Yes | Non-empty text; unique across roles | — |
 | `description` | Yes | Non-empty text | — |
-| `tools` | No | Array or comma-separated string of tool names | Omitted: caller tools win, else Pi defaults apply |
+| `tools` | Yes | YAML array of non-empty tool names | `[]` activates no base built-ins; trusted extension tools and caller additions still activate |
 | `isolation` | No | `worktree` | None |
-| `extensions` | No | Absolute paths, `~/…`, `file://`, or package sources (`npm:`, `git:`, `github:`, `https?:`, `ssh:`) | None |
-| `skills` | No | Array or comma-separated string of skill names | None; unavailable names warn and skip |
+| `extensions` | Yes | YAML array of absolute paths, `~/…`, `file://`, or package sources (`npm:`, `git:`, `github:`, `https?:`, `ssh:`) | `[]` selects no Role extension bundle |
+| `skills` | Yes | YAML array of non-empty Skill names | `[]` selects no separately named Role Skills; trusted extension Skills still load |
 | body | Yes | System-prompt Markdown after the frontmatter | — |
 
 An unreadable or invalid Role file fails role loading fast; duplicate role names are rejected.
@@ -90,7 +111,7 @@ An unreadable or invalid Role file fails role loading fast; duplicate role names
 The package ships two working built-in Roles, always available without any configuration:
 
 - `implementer`: focused edits requesting worktree isolation; commits completed scoped changes locally and never pushes or opens PRs without authorization
-- `reviewer`: read-only correctness review from a supplied exact patch file reference (path, bytes, SHA-256) and referenced files; never edits or commits
+- `reviewer`: read-only correctness review of supplied plans/files, or—only when a Flow unit declares `review`—of Flow's exact `{base, tip, patchPath}` packet in its Unit Worktree; never edits or commits
 
 A same-named Markdown file in `~/.pi/agent/config/pi-subagent/` explicitly overrides the built-in default.
 
@@ -112,12 +133,12 @@ The package never installs or writes Role configuration. Sample names are not bu
 
 ## Skill
 
-The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill is opinionated orchestration policy for Main. It fails before delegation unless Main's cwd is a clean Git working tree with a committed `HEAD`; then it requires a clean retained implementer worktree, a verified base/branch/tip committed diff, and review from a privately generated, byte-verified exact patch file reference (path, bytes, SHA-256) plus referenced files—not inline patch text. It re-checks Main before integrating the reviewed commit, preserves artifacts on integration or validation failure, and removes eligible retained worktrees, task branches, and temporary patch files only after focused validation passes. Dirty or incomplete work goes to a fresh repair delegation. This leaves the generic `delegate_task` non-Git/unborn-`HEAD` fallback unchanged. All model and agent work stays in Pi via `delegate_task`; deterministic developer tools remain allowed. It is guidance only — it adds no runtime code, config, or Role installation, and preserves the [composition-outside-the-executor](./docs/adr/001-composable-ephemeral-execution.md) boundary.
+The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill is Main-side planner/orchestrator policy only. `delegate_flow` owns its fixed Git mechanics and validation authority; the Skill adds no runtime code, configuration, or Role installation. Generic orchestration remains outside the executor under [ADR 001](./docs/adr/001-composable-ephemeral-execution.md).
 
-A Role owns its base tools, extensions, named Skills, instructions, and optional `isolation: worktree`. Ambient extension and Skill discovery is disabled in children. With neither Role tools nor caller tools, Pi defaults remain; caller tools with omitted Role tools snapshot Main's effective active built-ins and install the child policy. Loaded Role/caller extension tools still activate, parent-only tools stay excluded, and unavailable named Skills warn and skip.
+A Role explicitly owns base tools, extensions, named Skills, instructions, and optional `isolation: worktree`. Every launch installs its Role tool policy: `tools: []` activates no base built-ins, while trusted selected extension tools and explicit caller tool additions still activate. `skills: []` selects no separately named Role Skills, while trusted selected extension Skills still load; `extensions: []` selects no Role extension bundle. Ambient extension and Skill discovery is disabled in children. Selecting an extension explicitly is selecting a trusted atomic capability bundle, not just a provider path: every tool it registers and every Skill supplied through its Pi package metadata or dynamic `resources_discover` loads alongside separately named Role Skills. This is intentional because an extension may depend on its own tools, Skills, lifecycle, and prompt behavior; loading it permits that executable behavior and is not sandboxing. To scope a child, select fewer trusted extensions. Finer-grained selection requires separate extension entry points/configuration or an upstream split—pi-subagent does not infer or externally narrow undocumented dependencies. Parent-only recursive orchestration tools stay excluded. Explicit Role or caller tool names are verified against the child’s final filtered active registry after provider extensions finish `session_start`; all unavailable names fail before the first model turn with provider-extension guidance, while unavailable named Skills warn and skip.
 
 ## Library API
 
-The package root exports Role loading and launch resolution, `createEphemeralSubagentExecutor`, worktree helpers, and generic managed Herdr lifecycle helpers. The ephemeral executor is for code already running inside active Pi; it does not provide standalone Node.js Pi discovery or launch support.
+The package root exports Role loading and launch resolution, `createEphemeralSubagentExecutor`, worktree helpers, and generic managed Herdr lifecycle helpers. The ephemeral executor is for code already running inside active Pi; it does not provide standalone Node.js Pi discovery or launch support. After Pi itself exits, it drains inherited stdout/stderr normally but destroys streams still held by escaped descendants after a short inactivity deadline or one-second hard deadline, so they cannot retain a pool permit.
 
 Use [`docs/orchestration.md`](./docs/orchestration.md#public-role-and-executor-api) for exact API behavior and a post-permit `prepare` example using `resolveRoleLaunch` against the latest Pi context.

package/dist/ephemeral.js

@@ -5,6 +5,8 @@ import { StringDecoder } from "node:string_decoder";
 const MAX_OUTPUT_BYTES = 50 * 1024;
 const MAX_JSON_EVENT_BYTES = 1024 * 1024;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const POST_EXIT_STDIO_IDLE_MS = 250;
+const POST_EXIT_STDIO_HARD_MS = 1_000;
 const PI_JSON_EVENTS = {
     agent_start: true,
     agent_end: true,
@@ -373,10 +375,95 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
         const accumulatedUsage = () => addUsage(completedUsage, currentUsage);
         let deadlineTimer;
         let killTimer;
+        let postExitIdleTimer;
+        let postExitHardTimer;
+        let callbackDrainTimer;
+        let stdoutEnded = false;
+        let stderrEnded = false;
+        let settled = false;
+        let cleaned = false;
         let callbackFailure;
         const pendingCallbacks = new Set();
         let signalCallbackFailure;
         const callbackFailed = new Promise((resolve) => { signalCallbackFailure = resolve; });
+        let onStdoutData;
+        let onStderrData;
+        let onStdoutEnd;
+        let onStderrEnd;
+        let onStdoutClose;
+        let onStderrClose;
+        let onChildError;
+        let onChildExit;
+        let onChildClose;
+        const clearTimer = (timer) => {
+            if (timer)
+                clearTimeout(timer);
+        };
+        const clearLifecycle = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            clearTimer(deadlineTimer);
+            clearTimer(killTimer);
+            clearTimer(postExitIdleTimer);
+            clearTimer(postExitHardTimer);
+            clearTimer(callbackDrainTimer);
+            input.signal?.removeEventListener("abort", abort);
+            if (onStdoutData)
+                child.stdout.off("data", onStdoutData);
+            if (onStderrData)
+                child.stderr.off("data", onStderrData);
+            if (onStdoutEnd)
+                child.stdout.off("end", onStdoutEnd);
+            if (onStderrEnd)
+                child.stderr.off("end", onStderrEnd);
+            if (onStdoutClose)
+                child.stdout.off("close", onStdoutClose);
+            if (onStderrClose)
+                child.stderr.off("close", onStderrClose);
+            if (onChildError)
+                child.off("error", onChildError);
+            if (onChildExit)
+                child.off("exit", onChildExit);
+            if (onChildClose)
+                child.off("close", onChildClose);
+        };
+        const complete = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearLifecycle();
+            if (callbackFailure) {
+                reject(new EphemeralSubagentError("callback", callbackFailure.message, callbackFailure.cause, accumulatedUsage()));
+            }
+            else if (aborted)
+                reject(abortError(input.signal, input.signal?.reason, accumulatedUsage()));
+            else if (timedOutAfterMs !== undefined) {
+                const message = timeoutReason === "maximum"
+                    ? `Subagent reached its maximum runtime after ${formatDuration(timedOutAfterMs)}.`
+                    : `Subagent timed out after ${formatDuration(timeoutPolicy.idleMs)} without a recognized Pi event.`;
+                reject(new EphemeralSubagentError("timeout", message, new Error(message), accumulatedUsage()));
+            }
+            else if (protocolError) {
+                reject(new EphemeralSubagentError("protocol", protocolError.message, protocolError, accumulatedUsage()));
+            }
+            else if (spawnError) {
+                reject(new EphemeralSubagentError("spawn", spawnError.message, spawnError));
+            }
+            else {
+                const exitCode = code ?? 1;
+                const outcome = exitCode !== 0 || stopReason === "error" || stopReason === "aborted" ? "failure" : "success";
+                resolve({
+                    outcome,
+                    exitCode,
+                    output,
+                    stderr: boundedText(stderr),
+                    stopReason,
+                    errorMessage,
+                    usage: addUsage(completedUsage, currentUsage),
+                });
+            }
+        };
         const failCallback = (name, cause) => {
             if (callbackFailure)
                 return;
@@ -507,7 +594,32 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
                 child.kill(force ? "SIGKILL" : "SIGTERM");
             }
         }
-        child.stdout.on("data", (data) => {
+        // `close` waits for stdio EOF, which an escaped descendant can retain after Pi exits.
+        const clearPostExitTimers = () => {
+            clearTimer(postExitIdleTimer);
+            clearTimer(postExitHardTimer);
+            postExitIdleTimer = undefined;
+            postExitHardTimer = undefined;
+        };
+        const destroyOpenStdio = () => {
+            if (!stdoutEnded)
+                child.stdout.destroy();
+            if (!stderrEnded)
+                child.stderr.destroy();
+        };
+        const armPostExitIdleDeadline = () => {
+            if (!childExited || (stdoutEnded && stderrEnded))
+                return;
+            clearTimer(postExitIdleTimer);
+            postExitIdleTimer = setTimeout(destroyOpenStdio, POST_EXIT_STDIO_IDLE_MS);
+            postExitIdleTimer.unref();
+        };
+        const endStdio = () => {
+            if (stdoutEnded && stderrEnded)
+                clearPostExitTimers();
+        };
+        onStdoutData = (data) => {
+            armPostExitIdleDeadline();
             if (callbackFailure || protocolError)
                 return;
             let offset = 0;
@@ -549,11 +661,27 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
                 ignoreLine = false;
                 offset = newline + 1;
             }
-        });
-        child.stderr.on("data", (data) => {
+        };
+        onStderrData = (data) => {
+            armPostExitIdleDeadline();
             appendBounded(stderr, data);
-        });
-        child.on("error", (error) => { spawnError = error; });
+        };
+        onStdoutEnd = () => {
+            stdoutEnded = true;
+            endStdio();
+        };
+        onStderrEnd = () => {
+            stderrEnded = true;
+            endStdio();
+        };
+        onStdoutClose = onStdoutEnd;
+        onStderrClose = onStderrEnd;
+        child.stdout.on("data", onStdoutData);
+        child.stderr.on("data", onStderrData);
+        child.stdout.on("end", onStdoutEnd);
+        child.stderr.on("end", onStderrEnd);
+        child.stdout.on("close", onStdoutClose);
+        child.stderr.on("close", onStderrClose);
         function stop(force = false) {
             if (force) {
                 void killTree(true);
@@ -586,66 +714,41 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
             timeoutReason = reason;
             stop();
         }
-        scheduleDeadline();
-        input.signal?.addEventListener("abort", abort, { once: true });
-        if (input.signal?.aborted)
-            abort();
-        // `close` waits for stdio EOF, which descendants can hold after Pi exits.
-        // Kill the process group at Pi's exit boundary so `close` can settle.
-        child.once("exit", () => {
+        onChildError = (error) => {
+            spawnError = error;
+            if (input.signal?.aborted)
+                aborted = true;
+        };
+        onChildExit = () => {
             childExited = true;
-            if (deadlineTimer)
-                clearTimeout(deadlineTimer);
-            input.signal?.removeEventListener("abort", abort);
+            clearTimer(deadlineTimer);
+            clearTimer(killTimer);
             void killTree(true);
-        });
-        child.on("close", async (code) => {
+            armPostExitIdleDeadline();
+            postExitHardTimer = setTimeout(destroyOpenStdio, POST_EXIT_STDIO_HARD_MS);
+            postExitHardTimer.unref();
+        };
+        onChildClose = async (code) => {
+            if (settled)
+                return;
             if (!callbackFailure && !protocolError && lineBytes)
                 processLine(lineParts.join(""));
             await killTree(true);
             // A caller callback that never settles must not hold `run()` or its permit
             // past child exit; bound the drain by what remains of the maximum runtime.
-            const drainTimer = setTimeout(() => {
+            callbackDrainTimer = setTimeout(() => {
                 callbackFailure ??= new EphemeralSubagentError("callback", "Subagent callback did not settle before the post-exit drain deadline.");
                 signalCallbackFailure();
             }, Math.min(5_000, Math.max(0, maxDeadline - Date.now())));
             await Promise.race([Promise.all(pendingCallbacks), callbackFailed]);
-            clearTimeout(drainTimer);
-            if (deadlineTimer)
-                clearTimeout(deadlineTimer);
-            if (killTimer)
-                clearTimeout(killTimer);
-            input.signal?.removeEventListener("abort", abort);
-            if (callbackFailure) {
-                reject(new EphemeralSubagentError("callback", callbackFailure.message, callbackFailure.cause, accumulatedUsage()));
-            }
-            else if (aborted)
-                reject(abortError(input.signal, input.signal?.reason, accumulatedUsage()));
-            else if (timedOutAfterMs !== undefined) {
-                const message = timeoutReason === "maximum"
-                    ? `Subagent reached its maximum runtime after ${formatDuration(timedOutAfterMs)}.`
-                    : `Subagent timed out after ${formatDuration(timeoutPolicy.idleMs)} without a recognized Pi event.`;
-                reject(new EphemeralSubagentError("timeout", message, new Error(message), accumulatedUsage()));
-            }
-            else if (protocolError) {
-                reject(new EphemeralSubagentError("protocol", protocolError.message, protocolError, accumulatedUsage()));
-            }
-            else if (spawnError) {
-                reject(new EphemeralSubagentError("spawn", spawnError.message, spawnError));
-            }
-            else {
-                const exitCode = code ?? 1;
-                const outcome = exitCode !== 0 || stopReason === "error" || stopReason === "aborted" ? "failure" : "success";
-                resolve({
-                    outcome,
-                    exitCode,
-                    output,
-                    stderr: boundedText(stderr),
-                    stopReason,
-                    errorMessage,
-                    usage: addUsage(completedUsage, currentUsage),
-                });
-            }
-        });
+            complete(code);
+        };
+        child.once("error", onChildError);
+        child.once("exit", onChildExit);
+        child.once("close", onChildClose);
+        scheduleDeadline();
+        input.signal?.addEventListener("abort", abort, { once: true });
+        if (input.signal?.aborted)
+            abort();
     });
 }

package/dist/index.d.ts

@@ -2,13 +2,15 @@ import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-cod
 import { type HerdrExecutor } from "@henryqw/pi-herdr";
 import { type AvailableModel, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, EphemeralSubagentError, formatDuration, type EphemeralSubagentErrorCode, type EphemeralSubagentExecutor, type EphemeralSubagentExecutorOptions, type EphemeralSubagentResult, type EphemeralSubagentRunInput, type EphemeralSubagentTimeout, } from "./ephemeral.ts";
-export { createChildWorktree, finalizeChildWorktree, worktreeContextNote, type WorktreeInfo, type WorktreePayload, } from "./worktree.ts";
+export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, worktreeContextNote, type WorktreeDirtyInspection, type WorktreeInfo, type WorktreePayload, } from "./worktree.ts";
+export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, type PreparedReviewEvidence, type PrepareExactReviewEvidenceInput, } from "./review-evidence.ts";
 export declare const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
-export declare const CHILD_EXCLUDED_TOOLS = "delegate_task,ask_question";
+export declare const CHILD_EXCLUDED_TOOL_NAMES: readonly ["delegate_task", "delegate_flow", "delegate_flow_continue", "ask_question"];
+export declare const CHILD_EXCLUDED_TOOLS: string;
 export interface Role {
     name: string;
     description: string;
-    tools?: string[];
+    tools: string[];
     isolation?: string;
     extensions: string[];
     skills: string[];
@@ -38,6 +40,9 @@ export interface ResolvedRoleSkills {
     paths: string[];
     missing: string[];
 }
+declare const BUILTIN_ROLE_NAMES: readonly ["implementer", "reviewer"];
+export type BuiltinRoleName = (typeof BUILTIN_ROLE_NAMES)[number];
+export declare function loadBuiltinRole(name: BuiltinRoleName): Role;
 /**
  * Validated built-in implementer/reviewer Roles plus valid user roles from
  * `config/pi-subagent`. A user role with a built-in name overrides the default;
@@ -47,8 +52,8 @@ export interface ResolvedRoleSkills {
 export declare function loadRoles(agentDir?: string): Role[];
 export declare function resolveTaskRoute(ctx: ExtensionContext, profileName: ProfileName, agentDir?: string, thinking?: ThinkingLevel): ResolvedTaskRoute;
 export declare function resolveRoleSkills(pi: Pick<ExtensionAPI, "getCommands">, role: Role): ResolvedRoleSkills;
-export declare function createRoleLaunch(pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools" | "getCommands">, ctx: Pick<ExtensionContext, "isProjectTrusted">, input: CreateRoleLaunchInput): ResolvedRoleLaunch;
-export declare function resolveRoleLaunch(pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools" | "getCommands">, ctx: ExtensionContext, input: ResolveRoleLaunchInput): ResolvedRoleLaunch;
+export declare function createRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: Pick<ExtensionContext, "isProjectTrusted">, input: CreateRoleLaunchInput): ResolvedRoleLaunch;
+export declare function resolveRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: ExtensionContext, input: ResolveRoleLaunchInput): ResolvedRoleLaunch;
 export interface ManagedSubagentHost {
     cwd: string;
     workspaceId: string;

package/dist/index.js

@@ -6,12 +6,14 @@ import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { createHerdrClient, herdrCommandFailure, hasHerdrErrorCode, startPiAgent } from "@henryqw/pi-herdr";
 import { modelReference, orderedProfileRoutes, readTaskModelsConfig, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, EphemeralSubagentError, formatDuration, } from "./ephemeral.js";
-export { createChildWorktree, finalizeChildWorktree, worktreeContextNote, } from "./worktree.js";
+export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, worktreeContextNote, } from "./worktree.js";
+export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, } from "./review-evidence.js";
 const CODEX_ALIAS = /^openai-codex-(?:[2-9]|[1-9]\d+)$/;
 const MULTI_CODEX_EXTENSION = fileURLToPath(import.meta.resolve("@henryqw/pi-multi-codex/extensions/multi-codex.ts"));
 const ROLE_TOOLS_EXTENSION = fileURLToPath(new URL("../extensions/role-tools.ts", import.meta.url));
 export const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
-export const CHILD_EXCLUDED_TOOLS = "delegate_task,ask_question";
+export const CHILD_EXCLUDED_TOOL_NAMES = ["delegate_task", "delegate_flow", "delegate_flow_continue", "ask_question"];
+export const CHILD_EXCLUDED_TOOLS = CHILD_EXCLUDED_TOOL_NAMES.join(",");
 const CHILD_IDENTITY_POLICY = "You are a delegated Pi Subagent, not Main. Execute the assigned Role and task directly. Main-only delegation rules do not apply. Recursive delegation is unavailable; do not seek or invoke delegation tools.";
 const cleanText = (value, field, source) => {
     if (typeof value !== "string" || !value.trim() || value.includes("\0")) {
@@ -19,17 +21,13 @@ const cleanText = (value, field, source) => {
     }
     return value.trim();
 };
-const stringList = (value, field, source, required = false) => {
-    if (value === undefined) {
-        if (required)
-            throw new Error(`${source}: ${field} is required.`);
-        return [];
-    }
-    const values = typeof value === "string" ? value.split(",") : value;
-    if (!Array.isArray(values) || values.some((item) => typeof item !== "string" || !item.trim() || item.includes("\0"))) {
+const stringList = (value, field, source) => {
+    if (value === undefined)
+        throw new Error(`${source}: ${field} is required.`);
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim() || item.includes("\0"))) {
         throw new Error(`${source}: ${field} must be an array of strings.`);
     }
-    return values.map((item) => item.trim());
+    return value.map((item) => item.trim());
 };
 function validateExtension(extension, source) {
     const value = cleanText(extension, "extension", source);
@@ -45,7 +43,7 @@ function extensionList(value, source) {
 }
 // Built-in Roles required by the bundled pi-subagent-delegated-development Skill;
 // resolved from the package-shipped Markdown relative to this module.
-const BUILTIN_ROLE_FILES = ["implementer.md", "reviewer.md"];
+const BUILTIN_ROLE_NAMES = ["implementer", "reviewer"];
 /** Single-file Role parser shared by built-in and user roles. */
 function parseRoleFile(file, raw) {
     let parsed;
@@ -62,7 +60,7 @@ function parseRoleFile(file, raw) {
     return {
         name: cleanText(frontmatter.name, "name", file),
         description: cleanText(frontmatter.description, "description", file),
-        tools: frontmatter.tools === undefined ? undefined : stringList(frontmatter.tools, "tools", file, true),
+        tools: stringList(frontmatter.tools, "tools", file),
         isolation,
         extensions: extensionList(frontmatter.extensions, file),
         skills: stringList(frontmatter.skills, "skills", file),
@@ -79,8 +77,11 @@ function readRoleFile(file) {
         throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+export function loadBuiltinRole(name) {
+    return readRoleFile(fileURLToPath(new URL(`../examples/roles/${name}.md`, import.meta.url)));
+}
 function builtinRoles() {
-    return BUILTIN_ROLE_FILES.map((name) => readRoleFile(fileURLToPath(new URL(`../examples/roles/${name}`, import.meta.url))));
+    return BUILTIN_ROLE_NAMES.map(loadBuiltinRole);
 }
 /**
  * Validated built-in implementer/reviewer Roles plus valid user roles from
@@ -151,21 +152,12 @@ export function resolveRoleSkills(pi, role) {
 export function createRoleLaunch(pi, ctx, input) {
     const role = input.role;
     const skills = resolveRoleSkills(pi, role);
-    let baseTools = role.tools;
-    if (baseTools === undefined && input.tools !== undefined) {
-        const builtins = new Set(pi.getAllTools()
-            .filter((tool) => tool.sourceInfo.source === "builtin")
-            .map((tool) => tool.name));
-        baseTools = pi.getActiveTools().filter((tool) => builtins.has(tool));
-    }
-    const tools = baseTools === undefined
-        ? undefined
-        : [...new Set([...baseTools, ...(input.tools ?? [])].map((tool) => cleanText(tool, "tool", `Role ${role.name}`)))];
+    const tools = [...new Set([...role.tools, ...(input.tools ?? [])].map((tool) => cleanText(tool, "tool", `Role ${role.name}`)))];
     const extensions = [
         ...role.extensions,
         ...(input.extensions ?? []),
         ...(CODEX_ALIAS.test(input.route.model.provider) ? [MULTI_CODEX_EXTENSION] : []),
-        ...(tools === undefined ? [] : [ROLE_TOOLS_EXTENSION]),
+        ROLE_TOOLS_EXTENSION,
     ].map((extension) => validateExtension(extension, `Role ${role.name}`));
     const env = Object.fromEntries(Object.entries(input.env ?? {}).map(([key, value]) => {
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
@@ -179,8 +171,7 @@ export function createRoleLaunch(pi, ctx, input) {
         args.push("--extension", extension);
     for (const skill of skills.paths)
         args.push("--skill", skill);
-    if (tools !== undefined)
-        args.push(`--${ROLE_TOOL_POLICY_FLAG}`, JSON.stringify(tools));
+    args.push(`--${ROLE_TOOL_POLICY_FLAG}`, JSON.stringify(tools));
     args.push("--model", modelReference(input.route.model));
     if (input.route.thinkingLevel)
         args.push("--thinking", input.route.thinkingLevel);

package/dist/review-evidence.d.ts

@@ -0,0 +1,17 @@
+export declare const REVIEW_MAX_PATHS = 1000;
+export declare const REVIEW_MAX_PATCH_BYTES: number;
+export interface PrepareExactReviewEvidenceInput {
+    base: string;
+    tip: string;
+    worktree: string;
+}
+export interface PreparedReviewEvidence {
+    base: string;
+    tip: string;
+    worktree: string;
+    changedPaths: string[];
+    patchPath: string;
+    cleanup: () => Promise<void>;
+}
+/** Prepares the one exact private patch Flow supplies to its Reviewer. */
+export declare function prepareExactReviewEvidence(request: PrepareExactReviewEvidenceInput, signal?: AbortSignal): Promise<PreparedReviewEvidence>;