@henryqw/pi-subagent 4.1.2 → 6.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. Main plans and orchestrates; `delegate_task` selects its flat `single`, `parallel`, or `chain` tool policy, while 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,14 @@ 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.
+
+Main populates direct `model` and `thinking` only for explicit user overrides; otherwise it chooses only `modelClass` (`fast` normally, `balanced` upfront for obvious complexity). This is tool policy, not executor provenance tracking or runtime enforcement.
+
+## 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). Main plans and orchestrates; `delegate_flow` is a separate package-owned Git workflow with this fixed interface:
+
+```ts
+delegate_flow({ units: [{ id, task, modelClass?, validation: [{ command, args }], review? }] });
+delegate_flow_continue({ guidance, modelClass? });
+```
+
+A Flow accepts 1–8 independent units with unique IDs. `modelClass` is optional and otherwise uses the shared `pi-subagent/delegateTask` assignment; its class resolves through the existing `pi-task-models` profile model-and-thinking route for the unit's Implementer and, when applicable, Reviewer. `review` is optional non-empty text for the explicit judgment that declared validation cannot establish.
+
+Only one memory-only Flow may be active. At start it resolves/freezes the effective `implementer` Role, including a same-named user override. It resolves/freezes the effective `reviewer` Role only when at least one requested unit has `review`. 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, inspects committed Git state, and runs declared validation. Validation is authoritative for objective verification. Without `review`, Flow skips exact evidence and Reviewer launch, then fast-forwards the exact validated tip through the existing guarded `git merge --ff-only` path. With `review`, it gives the Reviewer the exact `{base, tip, patchPath}` packet in that same worktree; only trimmed output exactly equal to `PASS` permits the same full-OID fast-forward. Cleanup uses non-forced worktree removal and branch deletion; cleanup refusal does not undo integration and returns completion with retained-work 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, modelClass? })` launches a fresh ephemeral child with the frozen Implementer Role in that same Unit Worktree once, with original requirements, authoritative validation, previous block evidence, and Main guidance. Omitted continuation class retains the Unit's current class; a supplied class replaces it for that one repair, including any subsequent Reviewer launch. A second block is terminal. Failed rebase, evidence/Reviewer, and other infrastructure failures retain worktrees. A reported fast-forward failure completes with its diagnostic as a warning only when Main is clean at the exact integrated tip; otherwise it is terminal. Earlier integrations are never rolled back.
+
+## Consequences
+
+Flow owns narrow deterministic Git mechanics while allowing user-owned Implementer and conditional Reviewer policy through same-named Role overrides. Overrides do not change validation authority, exact review protocol, approval, integration, or cleanup. Flow has no dependency graph, saved recovery, automatic retry, aggregate review, post-merge validation, Planner Role, or generic-role restriction. 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.
+Main plans and orchestrates. `delegate_task` owns its flat single/parallel/chain policy, while 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` Role and, only for explicit judgment review, the effective `reviewer` Role through the same prepared-child runner; its contract is below.
 
 ## Frozen `delegate_task` contract
 
@@ -65,11 +67,11 @@ Single mode puts one delegation's fields at the top level.
 | --- | --- | --- |
 | `role` | yes | Name of a Role in the user's effective `config/pi-subagent` directory or a package-shipped built-in (`implementer`, `reviewer`); a same-named user file overrides the built-in. |
 | `task` | yes | Non-empty bounded task packet. |
-| `model` | no | Designated `provider/modelId`; takes precedence over `modelClass`. |
-| `modelClass` | no | `fast`, `balanced`, `frontier`, or `fav`; omission uses shared task assignment. |
-| `thinking` | no | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`; route selection skips models that cannot honor it. |
+| `model` | no | Designated `provider/modelId`; takes precedence over `modelClass`, and Main supplies it only for an explicit user override. |
+| `modelClass` | no | `fast`, `balanced`, `frontier`, or `fav`; Main normally chooses `fast`, may choose `balanced` upfront for obvious complexity, and omission uses shared task assignment. |
+| `thinking` | no | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`; Main supplies it only for an explicit user override. Route selection skips models that cannot honor it. |
 
-Those five fields are the complete delegation object. `tasks`, `chain`, and `background` cannot be nested. Route fallback occurs only before launch; a started child is never retried by this package.
+Those five fields are the complete delegation object. The direct-model/thinking rule is Main-facing policy only: the runtime adds no provenance tracking or enforcement. `tasks`, `chain`, and `background` cannot be nested. Route fallback occurs only before launch; a started child is never retried by this package.
 
 ### Background, failures, and transport
 
@@ -79,16 +81,43 @@ 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`, one or more direct `{command, args}` validation commands, optional `modelClass`, and optional non-empty `review` text. `delegate_flow_continue({ guidance, modelClass? })` 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 always resolves/freezes the effective `implementer` Role, including a same-named user override. It resolves/freezes the effective `reviewer` only if at least one requested unit declares `review`. Omitted unit classes use the shared `pi-subagent/delegateTask` assignment; a selected class resolves through its existing `pi-task-models` profile model-and-thinking route for the unit's Implementer and, when applicable, Reviewer. 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
+  inspect committed state; run declared validation (objective authority)
+  ├─ no review: git merge --ff-only <exact validated tip>
+  └─ review: Reviewer receives exact {base, tip, patchPath}
+             exact PASS → git merge --ff-only <full reviewed OID>
+  git worktree remove; git branch -d
+```
+
+Flow derives identity from Git, not child output. Add `review` only for an explicit judgment criterion that automated validation cannot establish; it is not a second generic verification pass. The 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, modelClass? })` reruns the Flow's frozen Implementer Role in that same worktree once, then repeats derivation, validation, and conditional review with fresh exact evidence. Omitting continuation `modelClass` retains the blocked unit's current class; providing it replaces that class for the one repair. 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 integrated 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 package-shipped Roles as defaults while retaining same-named user Role overrides; the Reviewer is needed only for a requested review criterion.
+
 ## 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 +127,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` and `ask_question`.
+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 +154,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 +167,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 +357,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—when a Flow unit declares `review`—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 +377,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 planner/orchestrator policy only. `delegate_flow` owns its fixed Git mechanics and objective validation authority; 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.