@henryqw/pi-subagent 4.1.1 → 5.0.0

package/dist/review-evidence.js

@@ -0,0 +1,229 @@
+import { execFile, spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { inspectIndexFlags } from "./worktree.js";
+const GIT_TIMEOUT_MS = 30_000;
+export const REVIEW_MAX_PATHS = 1_000;
+export const REVIEW_MAX_PATCH_BYTES = 512 * 1024;
+const STDERR_LIMIT = 200;
+const git = (args, cwd, signal) => new Promise((resolve) => {
+    execFile("git", ["--no-pager", ...args], { cwd, signal, timeout: GIT_TIMEOUT_MS }, (error, stdout, stderr) => {
+        resolve({
+            code: error ? (typeof error.code === "number" ? error.code : -1) : 0,
+            stdout: String(stdout),
+            stderr: String(stderr).slice(0, STDERR_LIMIT),
+        });
+    });
+});
+function failure(args, result) {
+    const detail = result.stderr.trim();
+    return new Error(`git ${args.join(" ")} failed with exit ${result.code}${detail ? `: ${detail}` : ""}`);
+}
+async function runGit(args, cwd, signal) {
+    signal?.throwIfAborted();
+    const result = await git(args, cwd, signal);
+    signal?.throwIfAborted();
+    if (result.code !== 0)
+        throw failure(args, result);
+    return result.stdout;
+}
+function line(value, field) {
+    const result = value.replace(/\r?\n$/, "");
+    if (!result || /[\r\n\0]/.test(result))
+        throw new Error(`Git returned malformed ${field}.`);
+    return result;
+}
+function oid(value, field) {
+    const result = line(value, field);
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(result))
+        throw new Error(`Git returned invalid ${field}.`);
+    return result;
+}
+function requestText(value, field) {
+    if (typeof value !== "string" || !value || value.includes("\0"))
+        throw new TypeError(`${field} must be non-empty text without NUL bytes.`);
+    return value;
+}
+async function resolveCommit(reference, cwd, signal) {
+    requestText(reference, "review ref");
+    return oid(await runGit(["rev-parse", "--verify", "--end-of-options", `${reference}^{commit}`], cwd, signal), `commit for ${reference}`);
+}
+function validatePath(path) {
+    if (!path || path.includes("\0") || path.includes("�") || isAbsolute(path) || path.split(/[\\/]/).some((part) => !part || part === "." || part === "..")) {
+        throw new Error(`Git returned malformed or unsupported path: ${JSON.stringify(path)}`);
+    }
+    return path;
+}
+function parsePaths(value) {
+    if (!value)
+        return [];
+    if (!value.endsWith("\0") || value.includes("�"))
+        throw new Error("Git returned malformed changed paths.");
+    const paths = value.slice(0, -1).split("\0");
+    if (paths.length > REVIEW_MAX_PATHS)
+        throw new Error(`Review evidence exceeds ${REVIEW_MAX_PATHS} paths; split the review.`);
+    return paths.map(validatePath);
+}
+function assertSupportedChanges(value) {
+    if (!value)
+        return;
+    if (!value.endsWith("\0") || value.includes("�"))
+        throw new Error("Git returned malformed raw diff.");
+    const fields = value.slice(0, -1).split("\0");
+    for (let index = 0; index < fields.length;) {
+        const header = fields[index++];
+        const match = /^:(\d{6}) (\d{6}) [0-9a-f]+ [0-9a-f]+ ([A-Z][0-9]*)$/.exec(header);
+        if (!match)
+            throw new Error("Git returned malformed raw diff.");
+        for (const mode of [match[1], match[2]]) {
+            if (mode === "160000")
+                throw new Error("Review evidence rejects changed gitlinks.");
+            if (!new Set(["000000", "100644", "100755", "120000"]).has(mode)) {
+                throw new Error(`Review evidence rejects unsupported file mode: ${mode}.`);
+            }
+        }
+        const paths = /^[RC]/.test(match[3]) ? 2 : 1;
+        for (let count = 0; count < paths; count++) {
+            if (fields[index] === undefined)
+                throw new Error("Git returned malformed raw diff paths.");
+            validatePath(fields[index++]);
+        }
+    }
+}
+function registeredWorktrees(value) {
+    if (!value.endsWith("\0") || value.includes("�"))
+        throw new Error("Git returned malformed worktree list.");
+    const result = [];
+    let record = {};
+    for (const field of [...value.slice(0, -1).split("\0"), ""]) {
+        if (!field) {
+            if (Object.keys(record).length)
+                result.push(record);
+            record = {};
+        }
+        else if (field.startsWith("worktree "))
+            record.path = field.slice("worktree ".length);
+        else if (field.startsWith("HEAD "))
+            record.head = oid(`${field.slice("HEAD ".length)}\n`, "worktree HEAD");
+    }
+    return result;
+}
+async function assertCleanRegisteredWorktree(worktree, tip, signal) {
+    const root = await fs.realpath(line(await runGit(["rev-parse", "--show-toplevel"], worktree, signal), "worktree root"));
+    if (root !== worktree)
+        throw new Error("Review evidence requires a registered worktree root.");
+    const registrations = registeredWorktrees(await runGit(["worktree", "list", "--porcelain", "-z"], worktree, signal));
+    const registered = await Promise.all(registrations
+        .filter((entry) => entry.path === worktree)
+        .map(async (entry) => ({ ...entry, path: await fs.realpath(entry.path) })));
+    if (!registered.some((entry) => entry.head === tip)) {
+        throw new Error("Review evidence worktree is not registered at the requested tip.");
+    }
+    if (oid(await runGit(["rev-parse", "HEAD"], worktree, signal), "worktree HEAD") !== tip) {
+        throw new Error("Review evidence worktree moved from the requested tip.");
+    }
+    if (await runGit(["status", "--porcelain=v1", "--untracked-files=all", "--ignore-submodules=none"], worktree, signal)) {
+        throw new Error("Review evidence worktree is not clean.");
+    }
+    const flags = await inspectIndexFlags(worktree, git, signal);
+    if (flags.failure)
+        throw new Error(`Review evidence index inspection failed: ${flags.failure}`);
+    if (flags.hidden)
+        throw new Error("Review evidence rejects assume-unchanged or skip-worktree index entries.");
+}
+async function streamPatch(base, tip, worktree, path, signal) {
+    const file = await fs.open(path, "wx", 0o600);
+    try {
+        await fs.chmod(path, 0o600);
+        signal?.throwIfAborted();
+        const args = ["--no-pager", "diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--binary", base, tip];
+        const child = spawn("git", args, { cwd: worktree, signal, timeout: GIT_TIMEOUT_MS, stdio: ["ignore", "pipe", "pipe"] });
+        let stderr = Buffer.alloc(0);
+        let childError;
+        child.stderr.on("data", (chunk) => {
+            if (stderr.length < STDERR_LIMIT)
+                stderr = Buffer.concat([stderr, chunk.subarray(0, STDERR_LIMIT - stderr.length)]);
+        });
+        child.once("error", (error) => { childError = error; });
+        const closed = new Promise((resolve) => child.once("close", resolve));
+        let bytes = 0;
+        let overflow = false;
+        let outputError;
+        try {
+            for await (const chunk of child.stdout) {
+                const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                const available = REVIEW_MAX_PATCH_BYTES - bytes;
+                if (data.length > available) {
+                    if (available > 0)
+                        await file.writeFile(data.subarray(0, available));
+                    bytes += Math.max(available, 0);
+                    overflow = true;
+                    child.kill();
+                    break;
+                }
+                await file.writeFile(data);
+                bytes += data.length;
+            }
+        }
+        catch (error) {
+            outputError = error;
+            child.kill();
+        }
+        const code = await closed;
+        signal?.throwIfAborted();
+        if (overflow)
+            throw new Error(`Review evidence exceeds ${REVIEW_MAX_PATCH_BYTES} bytes; split the review.`);
+        if (outputError)
+            throw outputError;
+        if (childError)
+            throw childError;
+        if (code !== 0)
+            throw failure(args, { code: code ?? -1, stdout: "", stderr: stderr.toString() });
+    }
+    finally {
+        await file.close();
+    }
+}
+async function makeEvidenceDirectory() {
+    const directory = await fs.mkdtemp(join(tmpdir(), "pi-subagent-review-"));
+    try {
+        await fs.chmod(directory, 0o700);
+    }
+    catch (error) {
+        await fs.rm(directory, { recursive: true, force: true });
+        throw error;
+    }
+    let cleanup;
+    return {
+        directory,
+        cleanup: () => cleanup ??= fs.rm(directory, { recursive: true, force: true }),
+    };
+}
+/** Prepares the one exact private patch Flow supplies to its Reviewer. */
+export async function prepareExactReviewEvidence(request, signal) {
+    const requestedWorktree = requestText(request.worktree, "review worktree");
+    const worktree = await fs.realpath(requestedWorktree);
+    const [base, tip] = await Promise.all([
+        resolveCommit(request.base, worktree, signal),
+        resolveCommit(request.tip, worktree, signal),
+    ]);
+    await assertCleanRegisteredWorktree(worktree, tip, signal);
+    const changedPaths = parsePaths(await runGit([
+        "diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--name-only", "-z", base, tip,
+    ], worktree, signal));
+    assertSupportedChanges(await runGit([
+        "diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--raw", "-z", base, tip,
+    ], worktree, signal));
+    const owned = await makeEvidenceDirectory();
+    const patchPath = join(owned.directory, "review.patch");
+    try {
+        await streamPatch(base, tip, worktree, patchPath, signal);
+        await assertCleanRegisteredWorktree(worktree, tip, signal);
+        return { base, tip, worktree, changedPaths, patchPath, cleanup: owned.cleanup };
+    }
+    catch (error) {
+        await owned.cleanup();
+        throw error;
+    }
+}

package/dist/worktree.d.ts

@@ -19,6 +19,11 @@ export type GitRunner = (args: string[], cwd: string, signal?: AbortSignal) => P
     stdout: string;
     stderr: string;
 }>;
+export declare class WorktreeSetupError extends Error {
+    name: string;
+    readonly worktree: WorktreeInfo;
+    constructor(message: string, worktree: WorktreeInfo);
+}
 /**
  * Creates one worktree per child from parent HEAD. Returns undefined only when
  * the workspace is not a git repository or HEAD is unborn — callers degrade
@@ -27,6 +32,17 @@ export type GitRunner = (args: string[], cwd: string, signal?: AbortSignal) => P
  * role never silently loses its isolation.
  */
 export declare function createChildWorktree(cwd: string, childId: string, run?: GitRunner, signal?: AbortSignal): Promise<WorktreeInfo | undefined>;
+export interface WorktreeDirtyInspection {
+    dirty: boolean;
+    failure?: string;
+    initializedSubmodules?: boolean;
+}
+export declare function inspectIndexFlags(cwd: string, run?: GitRunner, signal?: AbortSignal): Promise<{
+    hidden: boolean;
+    failure?: string;
+}>;
+/** Proves a worktree has no tracked, untracked, ignored, index-hidden, or nested submodule work. */
+export declare function inspectWorktreeDirty(cwd: string, run?: GitRunner): Promise<WorktreeDirtyInspection>;
 /**
  * Inspects and possibly prunes a child worktree after it finishes. Commit count
  * reads the dedicated branch and refuses to prune when checkout HEAD no longer

package/dist/worktree.js

@@ -6,8 +6,13 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
 const GIT_TIMEOUT_MS = 30_000;
 const WORKTREES_DIRNAME = ".worktrees";
 const BRANCH_NAMESPACE = "pi-subagent";
-class WorktreeSetupError extends Error {
+export class WorktreeSetupError extends Error {
     name = "WorktreeSetupError";
+    worktree;
+    constructor(message, worktree) {
+        super(message);
+        this.worktree = worktree;
+    }
 }
 /** Runs git, capturing output; never throws on non-zero exit or spawn failure. */
 const runGit = (args, cwd, signal) => new Promise((resolve) => {
@@ -54,7 +59,7 @@ async function ensureLocalExclude(gitDir) {
         await appendFile(exclude, `${existing && !existing.endsWith("\n") ? "\n" : ""}${entry}\n`);
     }
     catch (error) {
-        throw new WorktreeSetupError(`Could not update ${exclude}: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Could not update ${exclude}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
 /**
@@ -137,11 +142,12 @@ export async function createChildWorktree(cwd, childId, run = runGit, signal) {
     }
     await ensureLocalExclude(gitDir);
     signal?.throwIfAborted();
+    const worktree = { path, cwd: join(path, relativeCwd), branch, repoRoot: stableRepoRoot, baseCommit };
     const added = await run(["worktree", "add", path, "-b", branch, baseCommit], repoRoot, signal);
     if (added.code !== 0) {
-        throw new WorktreeSetupError(`git worktree add failed; preserved ${path} and ${branch}: ${added.stderr.trim().slice(0, 200)}`);
+        throw new WorktreeSetupError(`git worktree add failed after attempting path=${JSON.stringify(path)} branch=${JSON.stringify(branch)} base=${baseCommit}: ${added.stderr.trim().slice(0, 200)}`, worktree);
     }
-    return { path, cwd: join(path, relativeCwd), branch, repoRoot: stableRepoRoot, baseCommit };
+    return worktree;
 }
 /** Flags a payload whose state could not be measured (#88113): unmeasured is not zero. */
 function markUnproven(payload, reason, unmeasured = "commits/dirty") {
@@ -151,6 +157,12 @@ function markUnproven(payload, reason, unmeasured = "commits/dirty") {
             + `Any remaining worktree or branch was preserved — inspect ${payload.path} (branch ${payload.branch}) before assuming no work.`;
     return payload;
 }
+export async function inspectIndexFlags(cwd, run = runGit, signal) {
+    const flags = await run(["ls-files", "-v", "-z"], cwd, signal);
+    if (flags.code !== 0)
+        return { hidden: false, failure: `ls-files exit ${flags.code}: ${flags.stderr.trim().slice(0, 200)}` };
+    return { hidden: flags.stdout.split("\0").some((entry) => /^(?:[a-z]|S) /.test(entry)) };
+}
 async function inspectDirty(run, cwd) {
     const refreshed = await run(["update-index", "--really-refresh"], cwd);
     if (refreshed.code !== 0 && refreshed.code !== 1) {
@@ -161,14 +173,40 @@ async function inspectDirty(run, cwd) {
         return { dirty: false, failure: `status exit ${status.code}: ${status.stderr.trim().slice(0, 200)}` };
     if (refreshed.code === 1 || status.stdout.trim())
         return { dirty: true };
-    const flags = await run(["ls-files", "-v", "-z"], cwd);
-    if (flags.code !== 0)
-        return { dirty: false, failure: `ls-files exit ${flags.code}: ${flags.stderr.trim().slice(0, 200)}` };
-    if (flags.stdout.split("\0").some((entry) => /^(?:[a-z]|S) /.test(entry))) {
+    const flags = await inspectIndexFlags(cwd, run);
+    if (flags.failure)
+        return { dirty: false, failure: flags.failure };
+    if (flags.hidden)
         return { dirty: false, failure: "assume-unchanged or skip-worktree index entries remain" };
-    }
     return { dirty: false };
 }
+/** Proves a worktree has no tracked, untracked, ignored, index-hidden, or nested submodule work. */
+export async function inspectWorktreeDirty(cwd, run = runGit) {
+    const root = await inspectDirty(run, cwd);
+    if (root.dirty || root.failure)
+        return root;
+    const modules = await run(["submodule", "status", "--recursive"], cwd);
+    if (modules.code !== 0)
+        return { dirty: false, failure: `submodule list exit ${modules.code}: ${modules.stderr.trim().slice(0, 200)}` };
+    const initializedSubmodules = modules.stdout.split("\n").some((line) => line && !line.startsWith("-"));
+    if (initializedSubmodules) {
+        const listed = await run(["submodule", "foreach", "--recursive", "--quiet", "printf '%s\\0' \"$PWD\""], cwd);
+        if (listed.code !== 0)
+            return { dirty: false, failure: `submodule list exit ${listed.code}: ${listed.stderr.trim().slice(0, 200)}` };
+        const paths = listed.stdout.split("\0").filter(Boolean);
+        if (!paths.length)
+            return { dirty: false, failure: "initialized submodule paths unavailable" };
+        for (const path of paths) {
+            const nested = await inspectDirty(run, path);
+            if (nested.failure)
+                return { dirty: false, failure: `submodule ${path}: ${nested.failure}` };
+            if (nested.dirty)
+                return { dirty: true };
+        }
+    }
+    const rechecked = await inspectDirty(run, cwd);
+    return initializedSubmodules ? { ...rechecked, initializedSubmodules } : rechecked;
+}
 /**
  * Inspects and possibly prunes a child worktree after it finishes. Commit count
  * reads the dedicated branch and refuses to prune when checkout HEAD no longer
@@ -205,34 +243,14 @@ export async function finalizeChildWorktree(info, run = runGit) {
         if (head.code !== 0 || head.stdout.trim() !== `refs/heads/${info.branch}`) {
             return markUnproven(payload, "HEAD is detached, switched, or unreadable", "checked-out commits");
         }
-        const modules = await run(["submodule", "status", "--recursive"], info.path);
-        if (modules.code !== 0)
-            return markUnproven(payload, `submodule list exit ${modules.code}: ${modules.stderr.trim().slice(0, 200)}`, "dirty");
-        forceRemove = modules.stdout.split("\n").some((line) => line && !line.startsWith("-"));
-        if (forceRemove) {
-            const listed = await run(["submodule", "foreach", "--recursive", "--quiet", "printf '%s\\0' \"$PWD\""], info.path);
-            if (listed.code !== 0)
-                return markUnproven(payload, `submodule list exit ${listed.code}: ${listed.stderr.trim().slice(0, 200)}`, "dirty");
-            const paths = listed.stdout.split("\0").filter(Boolean);
-            if (!paths.length)
-                return markUnproven(payload, "initialized submodule paths unavailable", "dirty");
-            for (const path of paths) {
-                const nested = await inspectDirty(run, path);
-                if (nested.failure)
-                    return markUnproven(payload, `submodule ${path}: ${nested.failure}`, "dirty");
-                if (nested.dirty) {
-                    payload.dirty = true;
-                    return payload;
-                }
-            }
-        }
-        const rechecked = await inspectDirty(run, info.path);
+        const rechecked = await inspectWorktreeDirty(info.path, run);
         if (rechecked.failure)
             return markUnproven(payload, `final ${rechecked.failure}`, "dirty");
         if (rechecked.dirty) {
             payload.dirty = true;
             return payload;
         }
+        forceRemove = Boolean(rechecked.initializedSubmodules);
     }
     else if (payload.commits > 0)
         return payload;

package/docs/adr/001-composable-ephemeral-execution.md

@@ -1,10 +1,10 @@
-# Compose workflows outside the ephemeral executor
+# Compose generic workflows outside the ephemeral executor
 
 ## Decision
 
-The public task executor is an execution mechanism: it receives a prepared Pi Launch, runs one bounded Delegated Task, and returns the result. `single`, `parallel`, and `chain` are tool policy selected by a downstream caller, not executor workflow primitives.
+The public task executor is an execution mechanism: it receives a prepared Pi Launch, runs one bounded Delegated Task, and returns the result. `delegate_task` selects its flat `single`, `parallel`, or `chain` tool policy; those modes are not executor primitives.
 
-Downstream callers compose Workflows directly with JavaScript. Fan-out and fan-in use promises and collections; sequencing uses ordinary control flow; review loops use explicit iteration and caller-owned bounds. This package will not define or interpret a recursive workflow AST.
+Generic callers compose workflows with JavaScript. Fan-out and fan-in use promises and collections; sequencing uses ordinary control flow; review loops use explicit caller-owned bounds. The package does not define a recursive workflow AST.
 
 Resource Policy is split at launch preparation:
 
@@ -12,8 +12,12 @@ Resource Policy is split at launch preparation:
 - Caller may add explicit tools, extensions, and environment through `createRoleLaunch`.
 - The executor receives the resulting Pi Launch and does not discover resources.
 
-Built-in `implementer` and `reviewer` Roles ship with the package as Markdown in `examples/roles/` and resolve through the same single-file parser at load time; a same-named user file in `~/.pi/agent/config/pi-subagent/` explicitly overrides a built-in. Other repository samples are inert and user-owned only after manual copying to `~/.pi/agent/config/pi-subagent/`. This package does not install, copy, or write user configuration; copy instructions belong in downstream user documentation.
+Built-in `implementer` and `reviewer` Roles ship as Markdown in `examples/roles/` and use the same parser as user Roles. For generic delegation, a same-named user Role explicitly overrides a built-in. The package does not install, copy, or write user configuration.
+
+## Scope boundary
+
+`delegate_flow` is a fixed package-owned Git workflow, documented in [ADR 002](./002-package-owned-delegate-flow-orchestration.md). It reuses the prepared-child runner but is not a general executor workflow primitive: it has its own fixed unit, worktree, validation, review, integration, and cleanup contract. `delegate_task` and library callers remain generic.
 
 ## Consequences
 
-The executor remains a stable mechanism while callers own orchestration, state, retry decisions, concurrency, fan-in, and review bounds. Callers can express the required Workflow without coupling this package to a recursive schema, validation language, or migration surface.
+The executor remains a stable mechanism while generic callers own semantic protocols, shared workspace/state, retry decisions, and bounds. The package-owned Flow removes only its repeated deterministic Git mechanics; it does not turn the executor into a workflow language.

package/docs/adr/002-package-owned-delegate-flow-orchestration.md

@@ -0,0 +1,22 @@
+# Package-owned `delegate_flow` orchestration
+
+## Decision
+
+`delegate_task` remains the generic bounded Role tool described by [ADR 001](./001-composable-ephemeral-execution.md). `delegate_flow` is a separate package-owned Git workflow with this fixed interface:
+
+```ts
+delegate_flow({ units: [{ id, task, validation: [{ command, args }] }] });
+delegate_flow_continue({ guidance });
+```
+
+A Flow accepts 1–8 independent units with unique IDs. Only one memory-only Flow may be active. At start it resolves the effective `implementer` and `reviewer` Roles, including same-named user overrides, and freezes them through any continuation. It requires a clean committed attached Main branch and creates one Unit Worktree per unit before launching Implementers in parallel. All started Implementers settle; Flow then processes units in declared order.
+
+For each unit, Flow verifies Main, rebases the Unit Worktree in place when earlier Flow units advanced Main, runs the declared validation commands there, and gives the Reviewer the exact `{base, tip, patchPath}` packet in that same worktree. Reviewer output whose trimmed text equals `PASS` approves. Flow then fast-forwards Main with the full reviewed OID and uses non-forced worktree removal and branch deletion. Cleanup refusal does not undo integration; it returns completion with retained worktree path and/or branch warnings.
+
+If rebase drops all unit commits, `base === tip` is a no-op. Flow validates the state, skips Reviewer and merge, then cleans up ordinarily.
+
+Implementer failure, dirty or missing committed work, validation failure, and reviewer findings block the first affected declared unit. `delegate_flow_continue({ guidance })` reruns the Flow's frozen Implementer Role in that same Unit Worktree once and derives, validates, and reviews again. A second block is terminal. A failed rebase is aborted and terminates as an infrastructure failure with Git diagnostics; other infrastructure failures also terminate it. A reported fast-forward failure completes with its diagnostic as a warning only when Main is clean at the exact reviewed tip; otherwise it is terminal. Terminal outcomes retain worktrees for Main to reslice, and earlier integrations are never rolled back.
+
+## Consequences
+
+Flow owns its narrow deterministic Git protocol while allowing user-owned Implementer and Reviewer policy through same-named Role overrides. Overrides do not change Flow's validation, exact review packet, approval, integration, or cleanup protocol. Flow has no dependency graph, saved recovery, automatic retry, aggregate review, or post-merge validation. Units that overlap files, APIs, schemas, generated output, package metadata, lockfiles, or invariants must be combined or sequenced outside Flow.

package/docs/orchestration.md

@@ -1,6 +1,6 @@
 # Orchestration and package-author API
 
-`pi-subagent` separates tool policy from execution mechanism:
+`pi-subagent` separates generic delegation from its execution mechanism:
 
 ```text
 Role (built-in or user override) + latest Pi registries ── resolveRoleLaunch ──> PiLaunch
@@ -10,7 +10,9 @@ caller-owned task, cwd, signal ────────────────
                                      active-Pi ephemeral executor
 ```
 
-The `delegate_task` tool owns its flat single/parallel/chain policy. The public executor runs one prepared delegation. Downstream packages compose additional workflows with ordinary JavaScript and own semantic protocols, shared workspace/state, retry decisions, and bounds. There is no recursive workflow AST.
+`delegate_task` owns its flat single/parallel/chain policy. The public executor runs one prepared delegation. Downstream packages compose their own workflows with ordinary JavaScript and own semantic protocols, shared workspace/state, retry decisions, and bounds. There is no recursive workflow AST.
+
+`delegate_flow` is the exception: it is a fixed package-owned Git workflow, not an executor primitive or general workflow language. It uses the effective `implementer` and `reviewer` Roles and the same prepared-child runner; its contract is below.
 
 ## Frozen `delegate_task` contract
 
@@ -79,16 +81,42 @@ Any foreground entry failure makes the tool call throw. Parallel mode first sett
 
 All Main-visible text for one tool call shares one aggregate 50 KiB UTF-8 transport cap, including child output, sibling failures, and worktree/recovery evidence. Parallel execution does not multiply the cap by its entry count. Truncation is explicit; internal bookkeeping is not made visible by bypassing the cap.
 
+## `delegate_flow`
+
+`delegate_flow({ units })` accepts 1–8 units with unique non-empty `id` and `task` fields plus one or more direct `{command, args}` validation commands. `delegate_flow_continue({ guidance })` is available only for the one blocked unit of the active Flow.
+
+A Flow is memory-only and permits one active Flow. At start it resolves the effective `implementer` and `reviewer` Roles, including same-named user overrides, and freezes them through any continuation. Overrides must preserve the Flow Role protocols: Implementers commit scoped work, and Reviewers inspect the exact packet and emit exactly `PASS` only with zero findings. It requires clean committed Git Main and creates every Unit Worktree before launching work; setup failure launches no Implementer. Each unit gets exactly one worktree and one Implementer. Implementers run in parallel and all settle. Flow then processes units in declared order:
+
+```text
+Implementers (parallel, one Unit Worktree each)
+                 │ all settle
+                 v
+for each declared unit:
+  rebase in its Unit Worktree when earlier units advanced Main
+  run declared validation in that worktree
+  read-only Reviewer receives exact {base, tip, patchPath} there
+  exact PASS → git merge --ff-only <full reviewed OID>
+  git worktree remove; git branch -d
+```
+
+Flow derives identity from Git, not child output. Reviewer reads the exact patch as authoritative and may use the same worktree only for referenced context. A full-OID fast-forward is the only integration path. Cleanup is non-forced; after a successful integration, cleanup refusal returns `completed` with a retained path/branch warning.
+
+If rebase drops all unit commits, `base === tip` is a no-op: Flow validates current state, skips Reviewer and merge, then cleans up ordinarily. Implementer failure, dirty or missing committed work, validation failure, or reviewer findings block the first affected declared unit. `delegate_flow_continue({ guidance })` reruns the Flow's frozen Implementer Role in that same worktree once, then repeats derivation, validation, and review with fresh exact evidence. A second block is terminal. A failed rebase is aborted and terminates as an infrastructure failure with Git diagnostics; other infrastructure failures are terminal. A reported fast-forward failure completes with its diagnostic as a warning only when Main is clean at the exact reviewed tip; otherwise it is terminal. Terminal outcomes retain worktrees for Main to reslice. Earlier integrated units are never rolled back.
+
+Flow has no dependency graph, saved state, automatic retry, aggregate review, or post-merge validation. Use it only for commuting changes; combine or sequence units that overlap files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.
+
+`delegate_task` remains generic: its optional worktree isolation, non-Git behavior, and direct plan/file review are unchanged. Flow uses the same effective Role resolution for `implementer` and `reviewer`, with package-shipped Roles as defaults.
+
 ## Per-delegation resources and isolation
 
-Every single entry, parallel sibling, and chain step independently:
+For `delegate_task`, every single entry, parallel sibling, and chain step independently:
 
 1. loads its selected Role;
 2. resolves its route and named Skills from the latest effective Pi context after receiving an executor permit;
 3. creates its Role launch policy; and
 4. when the Role requests `isolation: worktree`, creates a worktree identified by the tool call, mode, and input index.
 
-Separate deterministic identities produce separate hashed worktree paths and branches. Parallel siblings cannot collide, and a chain does not base one step's worktree on the preceding step's branch. `{previous}` passes text only. There is no implicit shared worktree or hidden workflow state.
+Separate deterministic identities produce separate worktree paths and branches. Parallel siblings cannot collide, and a chain does not base one step's worktree on the preceding step's branch. `{previous}` passes text only. There is no implicit shared worktree or hidden workflow state.
 
 A worktree starts from Main's current `HEAD`. Clean worktrees with no child commits are pruned; committed, dirty, switched, unmeasurable, or otherwise recoverable work is preserved and reported. Non-git directories and repositories with an unborn `HEAD` use Main's working directory. Git submodules reject worktree isolation, and setup failure in a real repository throws rather than silently sharing Main's checkout. This generic fallback remains unchanged: the bundled delegated-development Skill separately refuses to begin without a committed Git `HEAD`.
 
@@ -98,17 +126,17 @@ If steps must share files, make that an explicit caller decision: use an intenti
 
 Every Role launch centrally prepends this child identity contract to its system instructions before the Role prompt: the child is a delegated Pi Subagent, not Main; it executes its assigned Role and task directly; Main-only delegation rules do not apply; recursive delegation is unavailable and it must not seek or invoke delegation tools.
 
-A Role file owns:
+A Role file requires:
 
-- base tools (`tools` omitted does not itself define an allowlist; `tools: []` means extension tools only);
-- explicit extension paths or package sources;
-- additional effective Pi Skill names;
+- base tools: a YAML array; `tools: []` activates no base built-ins, while trusted selected extension tools still activate;
+- explicit extension paths or package sources: a YAML array; `extensions: []` selects no Role extension bundle;
+- additional effective Pi Skill names: a YAML array; `skills: []` selects no separately named Role Skills, while trusted selected extension Skills still load;
 - system instructions; and
 - optional `isolation: worktree` for the tool layer.
 
-At launch, a package caller may add `tools`, `extensions`, and `env`. With an explicit Role tool list, caller tools are unioned into that base list. When Role tools and caller tools are both omitted, no allowlist is installed and Pi defaults remain active. When Role tools are omitted but caller tools are supplied, launch snapshots Main's effective active built-ins, unions the caller tools, and installs that policy. Loaded extension tools activate in every case. Caller `env` adds to or overrides the active Pi process environment for the child.
+Every launch installs the Role tool policy. At launch, a package caller may add `tools`, `extensions`, and `env`; caller tools are unioned into the Role base list and loaded extension tools activate in every case. Caller `env` adds to or overrides the active Pi process environment for the child.
 
-Children start with ambient extension and Skill discovery disabled. Only explicit Role/caller extensions, explicitly resolved Skill paths, resources supplied by those extension packages, and any required internal tool-policy or Codex adapter load. Loaded extension tools activate even when the Role base list is empty. Child-inappropriate parent tools are always excluded: `delegate_task`, `ask_question`, `auto_dag_execute`, and `auto_dag_acknowledge`.
+Children start with ambient extension and Skill discovery disabled. Only explicit Role/caller extensions, explicitly resolved Skill paths, resources supplied by those extension packages, and any required internal tool-policy or Codex adapter load. Loaded extension tools activate even when the Role base list is empty. Child-inappropriate parent tools are always excluded: `delegate_task`, `delegate_flow`, `delegate_flow_continue`, and `ask_question`. Explicit Role/caller tool names are verified against the final filtered active child registry after every explicit provider extension completes `session_start`; unavailable names fail before the first model turn and identify the missing names with provider-extension guidance.
 
 Role Skill names resolve through Main's effective Pi Skill registry at launch. Missing names are returned in `ResolvedRoleLaunch.missingSkills`; `delegate_task` warns and skips them. Library callers must surface that warning themselves. Missing Skills do not block launch.
 
@@ -125,7 +153,7 @@ The package root exports the following mechanism-level APIs:
 | `createEphemeralSubagentExecutor(options)` | Queue and run one prepared no-session child per `run`. |
 | `createChildWorktree` / `finalizeChildWorktree` | Optional caller-managed worktree lifecycle. |
 
-A loaded `Role` contains `name`, `description`, optional `tools` and `isolation`, plus normalized `extensions`, `skills`, and `systemPrompt`. `resolveRoleLaunch` accepts `role`, `taskId`, and optional `agentDir`, `extensions`, `tools`, and `env`. Its result is a `PiLaunch` (`{ env, args }`) plus the selected `model`, `thinkingLevel`, and `missingSkills`.
+A loaded `Role` contains `name`, `description`, required normalized `tools`, `extensions`, and `skills` arrays, optional `isolation`, and `systemPrompt`. `resolveRoleLaunch` accepts `role`, `taskId`, and optional caller `agentDir`, `extensions`, `tools`, and `env`. Its result is a `PiLaunch` (`{ env, args }`) plus the selected `model`, `thinkingLevel`, and `missingSkills`.
 
 `createEphemeralSubagentExecutor` requires:
 
@@ -138,7 +166,7 @@ const executorOptions = {
 
 Concurrency is FIFO. `run` accepts optional `signal`, `onUpdate(text)`, and `onTokens(number)` callbacks plus required `prepare()`. A queued run receives its permit before `prepare` executes, so resource and route resolution can use the latest Pi state. Queued time does not consume child timeout. `maxConcurrency`, `idleMs`, and `maxMs` must be positive; `maxMs` must exceed `idleMs`.
 
-The executor is **active-Pi-only**. It reuses the currently running Pi invocation and does not locate or support a standalone Node.js Pi installation.
+The executor is **active-Pi-only**. It reuses the currently running Pi invocation and does not locate or support a standalone Node.js Pi installation. Once direct Pi exits, stdout/stderr drain normally until EOF; an escaped descendant retaining either stream is cut off after short output inactivity or a one-second hard deadline so it cannot retain the FIFO permit.
 
 ### Prepare after the permit
 
@@ -328,7 +356,7 @@ The package ships two working built-in Roles, validated by the same parser as us
 | Built-in | Behavior |
 | --- | --- |
 | `implementer` | Focused implementation requesting `isolation: worktree`; commits scoped changes locally, never pushes or opens PRs without authorization. Non-Git or unborn-`HEAD` contexts may use Main's cwd. |
-| `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 Flow's exact `{base, tip, patchPath}` packet in its Unit Worktree; never edits or commits. |
 
 A same-named Markdown file in `config/pi-subagent/` explicitly overrides the built-in default.
 
@@ -348,6 +376,6 @@ cp <package-install-dir>/examples/roles/scout.md ~/.pi/agent/config/pi-subagent/
 
 The package never creates, copies, updates, or removes files in `~/.pi/agent/config/pi-subagent/`. Once copied, the files and their names are entirely user-owned.
 
-The bundled [`pi-subagent-delegated-development`](../skills/pi-subagent-delegated-development/SKILL.md) Skill is Main-side orchestration policy only. It prescribes an implement → review → merge loop over the built-in `implementer` and `reviewer` Roles, with private byte-verified exact-patch file references rather than inline patch text and cleanup only after integration validation. It defines no workflow AST, runtime code, or configuration; `delegate_task` remains the flat single/parallel/chain mechanism.
+The bundled [`pi-subagent-delegated-development`](../skills/pi-subagent-delegated-development/SKILL.md) Skill is Main-side policy only. `delegate_flow` owns its fixed Git mechanics; the Skill defines no runtime code or configuration. `delegate_task` remains the generic flat single/parallel/chain mechanism.
 
-See the architectural decision: [Compose workflows outside the ephemeral executor](./adr/001-composable-ephemeral-execution.md).
+See [ADR 001](./adr/001-composable-ephemeral-execution.md) for the executor boundary and [ADR 002](./adr/002-package-owned-delegate-flow-orchestration.md) for Flow.

package/examples/roles/implementer.md

@@ -9,15 +9,17 @@ tools:
   - grep
   - find
   - ls
+extensions: []
+skills: []
 isolation: worktree
 ---
 
 Implement one bounded task.
 
-Read applicable repository instructions and domain context first. Inspect the existing flow and its callers before editing. Work only in explicitly assigned files and preserve unrelated changes. Fix the root cause with the smallest complete diff, reusing existing patterns and dependencies.
+Read applicable repository instructions and domain context first. Inspect the existing flow and its callers before editing. Work only in the assigned cwd and explicitly assigned files; preserve unrelated changes. Fix the root cause with the smallest complete diff, reusing existing patterns and dependencies.
 
-Run focused validation that would fail if the change were wrong. Do not access credentials, use the network, generate artifacts, or broaden scope unless the task explicitly requires it. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs; deterministic developer tools remain allowed.
+For ordinary delegation, run the focused validation needed to establish that the change is correct. When a Flow packet declares an authoritative validation gate, treat that gate as the final validation: run only narrow development checks needed while implementing, and do not duplicate the declared gate. Do not access credentials, use the network, generate artifacts, or broaden scope unless the task explicitly requires it. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs; deterministic developer tools remain allowed.
 
-Commit completed scoped changes locally unless the task forbids it. Never push or open pull requests without explicit authorization.
+Commit completed scoped changes locally unless the task forbids it. Never create or manage another worktree. Never push or open pull requests without explicit authorization.
 
-Return the retained worktree path, branch, base commit, tip commit, changed files from the base-to-tip committed diff, clean `git status --porcelain=v1 --untracked-files=all` result, validation results, and remaining risks. Do not remove the retained worktree or task branch; Main cleans them only after successful integration and validation.
+For ordinary delegation, report the completed change, validation, and remaining risks. For Flow, return the retained assigned cwd, branch, base commit, tip commit, changed files from the base-to-tip committed diff, clean `git status --porcelain=v1 --untracked-files=all` result, and validation results. Do not remove the retained worktree or task branch; Main cleans them only after successful integration and validation.

package/examples/roles/reviewer.md

@@ -6,14 +6,19 @@ tools:
   - grep
   - find
   - ls
+extensions: []
+skills: []
 ---
 
 Perform a read-only correctness review of one bounded change.
 
-Refuse review unless the task supplies the base commit, tip commit, complete exact base-to-tip patch file reference (path, byte count, SHA-256), and explicit review context: `{type:'child_branch', branch}` or `{type:'integration_head'}`. Review from that supplied file and the files it references only; do not infer a diff from a branch or worktree. Read the patch in bounded chunks when needed and use only `read`, `grep`, `find`, or `ls` for referenced files.
+Support exactly two review modes:
 
-Review only the supplied requirements, exact patch file, and explicitly referenced files, including any relevant callers, contracts, and tests. Check correctness, regressions, trust-boundary validation, error handling, and missing high-value tests. Do not run commands or tests. Never edit files, commit, push, or otherwise modify state.
+1. For ordinary delegation, review the supplied plan and explicitly named files directly. Do not prepare Git, require commits, or require a patch packet.
+2. For Flow exact review, require a Review Packet `{base, tip, patchPath}` and the same assigned Unit Worktree context. Read that exact patch as authoritative, then read only the files it references and relevant contract context. Do not infer a diff from a branch or another worktree.
+
+In either mode, review only the supplied requirements and explicitly referenced context. Use only `read`, `grep`, `find`, or `ls` for that review. Check correctness, regressions, trust-boundary validation, error handling, and missing high-value tests. Do not run commands or tests. Never manage Main, Git, or tests; never edit or write files, commit, push, or otherwise modify state.
 
 Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
 
-Return findings first, ordered by severity. Every finding must include file and line evidence, impact, and the smallest valid fix. If there are no findings, say so and list any unvalidated risk.
+Emit exactly `PASS` when there are zero findings. Any finding must block approval: return findings first, ordered by severity, with file and line evidence, impact, and the smallest valid fix. Do not emit `PASS` alongside findings.