@henryqw/pi-subagent 18.0.1 → 22.0.0

package/dist/store.d.ts

@@ -0,0 +1,50 @@
+import { type RunState } from "./schema.ts";
+declare const productiveRunLeaseBrand: unique symbol;
+export interface ProductiveRunLease {
+    readonly [productiveRunLeaseBrand]: true;
+}
+export type LifecycleLockOptions = {
+    readonly purpose?: "productive";
+    readonly productiveRunLease?: ProductiveRunLease;
+} | {
+    readonly purpose: "status" | "abort";
+    readonly productiveRunLease?: never;
+};
+export interface LifecycleLock {
+    readonly productiveRunLeaseActive: boolean;
+}
+export declare class RunStateHandle {
+    state: RunState;
+    readonly path: string;
+    private writes;
+    private readonly root;
+    private readonly requestId;
+    private readonly replace;
+    constructor(state: RunState, path: string, replace: (contents: string) => Promise<void>);
+    save(): Promise<void>;
+}
+export declare class FileRunStore {
+    private readonly agentDir?;
+    private readonly onStateSaved?;
+    private readonly productiveRunLeases;
+    constructor(agentDir?: string, onStateSaved?: (state: RunState) => void);
+    stateDirectory(root: string): string;
+    statePath(root: string, id: string): string;
+    private lockPath;
+    private productiveRunPath;
+    private assertSafeDestination;
+    withProductiveRunLease<T>(root: string, operation: (lease: ProductiveRunLease) => Promise<T>): Promise<T>;
+    hasProductiveRunLease(root: string): Promise<boolean>;
+    withLock<T>(root: string, operation: (lifecycle: LifecycleLock) => Promise<T>, options?: LifecycleLockOptions): Promise<T>;
+    create(state: RunState): Promise<RunStateHandle>;
+    load(root: string, id: string): Promise<RunStateHandle>;
+    private stateEntries;
+    /** Read only version and request status; never migrate or interpret v4 worker evidence. */
+    assertLegacyAdmissionSafe(root: string): Promise<void>;
+    list(root: string): Promise<{
+        states: RunStateHandle[];
+        invalidIds: string[];
+    }>;
+    private handle;
+}
+export {};

package/dist/store.js

@@ -0,0 +1,288 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { mkdir, open, readdir, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { extensionConfigDir, readTextFileBounded, writePrivateTextFileAtomically } from "@henryqw/pi-config-store";
+import { check, lock } from "proper-lockfile";
+import { parseRunState, RUN_STATE_VERSION } from "./schema.js";
+const INITIAL_STATE_MAX_BYTES = 2 * 1024 * 1024;
+/*
+ * create() caps the complete initial serialization at 2 MiB. Loaded requests
+ * are independently bounded by parseExecuteRequest.
+ *
+ * Saves validate and reject atomically instead of dropping valid evidence.
+ * Reads use the same finite ceiling and preserve rejected files.
+ */
+const STATE_MAX_BYTES = 128 * 1024 * 1024;
+const ADMISSION_MAX_FILES = 256;
+const ADMISSION_MAX_BYTES = STATE_MAX_BYTES;
+const V4_TERMINAL_STATUSES = new Set(["completed", "final_failed", "superseded", "aborted"]);
+const V4_UNFINISHED_STATUSES = new Set(["pending", "running", "needs_attention"]);
+const LOCK_OPTIONS = { realpath: false, stale: 30_000, update: 5_000, retries: 0 };
+const LIFECYCLE_LOCK_OPTIONS = {
+    ...LOCK_OPTIONS,
+    retries: { forever: true, factor: 1, minTimeout: 25, maxTimeout: 25 },
+};
+const productiveRunLeaseBrand = Symbol("productiveRunLease");
+function isMissing(error) {
+    return Boolean(error && typeof error === "object" && error.code === "ENOENT");
+}
+function isAlreadyPresent(error) {
+    return Boolean(error && typeof error === "object" && error.code === "EEXIST");
+}
+function isLocked(error) {
+    return Boolean(error && typeof error === "object" && error.code === "ELOCKED");
+}
+function isWithin(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    return fromRoot === "" || (fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot));
+}
+async function canonicalPlannedPath(path) {
+    let ancestor = resolve(path);
+    const suffix = [];
+    for (;;) {
+        try {
+            return resolve(await realpath(ancestor), ...suffix.reverse());
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+            const parent = dirname(ancestor);
+            if (parent === ancestor)
+                throw error;
+            suffix.push(basename(ancestor));
+            ancestor = parent;
+        }
+    }
+}
+function serialize(state, maxBytes = STATE_MAX_BYTES) {
+    const validated = parseRunState(structuredClone(state));
+    const contents = `${JSON.stringify(validated, null, 2)}\n`;
+    if (Buffer.byteLength(contents, "utf8") > maxBytes) {
+        throw new Error(`pi-subagent state exceeds ${maxBytes} bytes.`);
+    }
+    return contents;
+}
+export class RunStateHandle {
+    state;
+    path;
+    writes = Promise.resolve();
+    root;
+    requestId;
+    replace;
+    constructor(state, path, replace) {
+        this.state = state;
+        this.path = path;
+        this.root = state.root;
+        this.requestId = state.request.id;
+        this.replace = replace;
+    }
+    async save() {
+        if (this.state.root !== this.root || this.state.request.id !== this.requestId) {
+            throw new Error("A state handle cannot change its owned repository or request ID.");
+        }
+        const contents = serialize(this.state);
+        this.writes = this.writes.then(async () => await this.replace(contents));
+        await this.writes;
+    }
+}
+export class FileRunStore {
+    agentDir;
+    onStateSaved;
+    productiveRunLeases = new WeakMap();
+    constructor(agentDir, onStateSaved) {
+        this.agentDir = agentDir;
+        this.onStateSaved = onStateSaved;
+    }
+    stateDirectory(root) {
+        const canonicalRoot = realpathSync.native(root);
+        const directory = join(extensionConfigDir("pi-subagent", this.agentDir), "state", createHash("sha256").update(canonicalRoot).digest("hex"));
+        if (isWithin(canonicalRoot, resolve(directory))) {
+            throw new Error("Pi Subagent state directory must be outside the Git workspace.");
+        }
+        return directory;
+    }
+    statePath(root, id) {
+        return join(this.stateDirectory(root), `${id}.json`);
+    }
+    lockPath(root) {
+        return join(this.stateDirectory(root), "lifecycle.lock");
+    }
+    productiveRunPath(root) {
+        return join(this.stateDirectory(root), "productive-run");
+    }
+    async assertSafeDestination(root, destination) {
+        if (isWithin(realpathSync.native(root), await canonicalPlannedPath(destination))) {
+            throw new Error("Pi Subagent state directory must be outside the Git workspace.");
+        }
+    }
+    async withProductiveRunLease(root, operation) {
+        const directory = this.stateDirectory(root);
+        await this.assertSafeDestination(root, directory);
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const path = this.productiveRunPath(root);
+        let release;
+        try {
+            release = await lock(path, { ...LOCK_OPTIONS, lockfilePath: `${path}.lock` });
+        }
+        catch (error) {
+            if (isLocked(error)) {
+                throw new Error("Another Pi Subagent productive request is active in this repository.");
+            }
+            throw error;
+        }
+        const lease = { [productiveRunLeaseBrand]: true };
+        this.productiveRunLeases.set(lease, path);
+        try {
+            return await operation(lease);
+        }
+        finally {
+            this.productiveRunLeases.delete(lease);
+            await release();
+        }
+    }
+    async hasProductiveRunLease(root) {
+        const directory = this.stateDirectory(root);
+        await this.assertSafeDestination(root, directory);
+        const path = this.productiveRunPath(root);
+        return await check(path, { realpath: false, stale: LOCK_OPTIONS.stale, lockfilePath: `${path}.lock` });
+    }
+    async withLock(root, operation, options = {}) {
+        const directory = this.stateDirectory(root);
+        await this.assertSafeDestination(root, directory);
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const path = this.lockPath(root);
+        const release = await lock(path, { ...LIFECYCLE_LOCK_OPTIONS, lockfilePath: `${path}.lock` });
+        try {
+            const productiveRunLeaseActive = await this.hasProductiveRunLease(root);
+            const ownedProductiveRunPath = options.productiveRunLease
+                ? this.productiveRunLeases.get(options.productiveRunLease)
+                : undefined;
+            if (productiveRunLeaseActive
+                && (options.purpose ?? "productive") === "productive"
+                && ownedProductiveRunPath !== this.productiveRunPath(root)) {
+                throw new Error("Another Pi Subagent productive request is active in this repository.");
+            }
+            const lifecycle = { productiveRunLeaseActive };
+            return await operation(lifecycle);
+        }
+        finally {
+            await release();
+        }
+    }
+    async create(state) {
+        const path = this.statePath(state.root, state.request.id);
+        await this.assertSafeDestination(state.root, path);
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        const contents = serialize(state, INITIAL_STATE_MAX_BYTES);
+        let file;
+        try {
+            file = await open(path, "wx", 0o600);
+            await file.writeFile(contents, "utf8");
+            await file.sync();
+            await file.close();
+            file = undefined;
+        }
+        catch (error) {
+            await file?.close();
+            if (isAlreadyPresent(error))
+                throw new Error(`Pi Subagent request ${state.request.id} already exists.`);
+            throw error;
+        }
+        const saved = parseRunState(structuredClone(state));
+        this.onStateSaved?.(structuredClone(saved));
+        return this.handle(saved, path);
+    }
+    async load(root, id) {
+        const path = this.statePath(root, id);
+        let raw;
+        try {
+            raw = await readTextFileBounded(path, STATE_MAX_BYTES);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === `Text file exceeds ${STATE_MAX_BYTES} bytes: ${path}`) {
+                throw new Error(`pi-subagent state exceeds ${STATE_MAX_BYTES} bytes.`);
+            }
+            throw error;
+        }
+        const state = parseRunState(JSON.parse(raw));
+        if (state.root !== realpathSync.native(root) || state.request.id !== id) {
+            throw new Error("pi-subagent state identity does not match its repository and filename.");
+        }
+        return this.handle(state, path);
+    }
+    async stateEntries(root) {
+        try {
+            return (await readdir(this.stateDirectory(root), { withFileTypes: true }))
+                .filter((item) => item.name.endsWith(".json"))
+                .sort((a, b) => a.name.localeCompare(b.name));
+        }
+        catch (error) {
+            if (isMissing(error))
+                return [];
+            throw error;
+        }
+    }
+    /** Read only version and request status; never migrate or interpret v4 worker evidence. */
+    async assertLegacyAdmissionSafe(root) {
+        const directory = this.stateDirectory(root);
+        await this.assertSafeDestination(root, directory);
+        const entries = await this.stateEntries(root);
+        if (entries.length > ADMISSION_MAX_FILES) {
+            throw new Error(`Pi Subagent cannot inventory more than ${ADMISSION_MAX_FILES} state files for safe admission; recover older requests with their owning version first.`);
+        }
+        let remainingBytes = ADMISSION_MAX_BYTES;
+        for (const entry of entries) {
+            const id = entry.name.slice(0, -5);
+            const path = join(directory, entry.name);
+            const recovery = `State preserved at ${path}. Inspect and recover any retained workers with their compatible owner before starting new isolated work.`;
+            let value;
+            try {
+                if (!entry.isFile())
+                    throw new Error("State is not a regular file.");
+                if (remainingBytes === 0)
+                    throw new Error("Admission inventory byte limit reached.");
+                const raw = await readTextFileBounded(path, remainingBytes);
+                remainingBytes -= Buffer.byteLength(raw, "utf8");
+                value = JSON.parse(raw);
+            }
+            catch {
+                throw new Error(`Pi Subagent cannot read state ${id} for safe admission. ${recovery}`);
+            }
+            if (!value || typeof value !== "object" || Array.isArray(value) || !("version" in value)) {
+                throw new Error(`Pi Subagent malformed state ${id} blocks safe admission. ${recovery}`);
+            }
+            if (value.version === RUN_STATE_VERSION)
+                continue;
+            if (value.version !== 4 || !("status" in value) || typeof value.status !== "string"
+                || (!V4_TERMINAL_STATUSES.has(value.status) && !V4_UNFINISHED_STATUSES.has(value.status))) {
+                throw new Error(`Pi Subagent malformed or unsupported legacy state ${id} blocks safe admission. ${recovery}`);
+            }
+            if (V4_UNFINISHED_STATUSES.has(value.status)) {
+                throw new Error(`Pi Subagent unfinished v4 request ${id} (${value.status}) blocks new isolated work. ${recovery}`);
+            }
+        }
+    }
+    async list(root) {
+        const entries = await this.stateEntries(root);
+        const states = [];
+        const invalidIds = [];
+        for (const entry of entries.filter((item) => item.isFile())) {
+            const id = entry.name.slice(0, -5);
+            try {
+                states.push(await this.load(root, id));
+            }
+            catch {
+                invalidIds.push(id);
+            }
+        }
+        return { states, invalidIds };
+    }
+    handle(state, path) {
+        return new RunStateHandle(state, path, async (contents) => {
+            await this.assertSafeDestination(state.root, path);
+            await writePrivateTextFileAtomically(path, contents);
+            this.onStateSaved?.(parseRunState(JSON.parse(contents)));
+        });
+    }
+}

package/dist/working-evidence.d.ts

@@ -0,0 +1,25 @@
+export interface WorkingCheckoutState {
+    head: string;
+    indexHash: string;
+    rawManifestHash: string;
+}
+export interface WorkingSnapshotIdentity extends WorkingCheckoutState {
+    tree: string;
+}
+export interface WorkingCheckoutBaseline extends WorkingSnapshotIdentity {
+    worktree: string;
+}
+export interface PreparedWorkingChangeEvidence {
+    baseline: WorkingCheckoutBaseline;
+    identity: WorkingSnapshotIdentity;
+    changedPaths: string[];
+    patchPath: string;
+    rawEvidencePath: string;
+    cleanup(): Promise<void>;
+}
+/** Capture mutation-detection identity without requiring a clean checkout or constructing Git objects. */
+export declare function captureWorkingCheckoutState(cwd: string, signal?: AbortSignal): Promise<WorkingCheckoutState>;
+export declare function captureWorkingCheckoutBaseline(cwd: string, signal?: AbortSignal): Promise<WorkingCheckoutBaseline>;
+export declare function prepareWorkingChangeEvidence(baseline: WorkingCheckoutBaseline, signal?: AbortSignal): Promise<PreparedWorkingChangeEvidence>;
+export declare function sameWorkingCheckoutState(left: WorkingCheckoutState, right: WorkingCheckoutState): boolean;
+export declare function sameWorkingSnapshot(left: WorkingSnapshotIdentity, right: WorkingSnapshotIdentity): boolean;

package/dist/working-evidence.js

@@ -0,0 +1,261 @@
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { chmod, copyFile, lstat, mkdir, mkdtemp, open, readFile, readlink, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { inspectIndexFlags } from "./worktree.js";
+import { runGit as runCapturedGit } from "./git-process.js";
+import { REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS } from "./review-evidence.js";
+const GIT_TIMEOUT_MS = 30_000;
+const OUTPUT_LIMIT = REVIEW_MAX_PATCH_BYTES + 1;
+const MANIFEST_MAX_BYTES = 512 * 1024;
+function hash(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function line(value, field) {
+    const text = value.toString("utf8").replace(/\r?\n$/, "");
+    if (!text || text.includes("�") || /[\r\n\0]/.test(text))
+        throw new Error(`Git returned malformed ${field}.`);
+    return text;
+}
+function oid(value, field) {
+    const result = line(value, field);
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(result))
+        throw new Error(`Git returned invalid ${field}.`);
+    return result;
+}
+async function command(args, cwd, env = process.env, signal, limit = OUTPUT_LIMIT) {
+    signal?.throwIfAborted();
+    const child = spawn("git", args, { cwd, env, signal, timeout: GIT_TIMEOUT_MS, stdio: ["ignore", "pipe", "pipe"] });
+    const stdout = [];
+    const stderr = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let overflow = false;
+    const collect = (chunks, chunk, current) => {
+        const available = limit - current;
+        if (available <= 0) {
+            overflow = true;
+            return 0;
+        }
+        chunks.push(chunk.subarray(0, available));
+        if (chunk.length > available)
+            overflow = true;
+        return Math.min(chunk.length, available);
+    };
+    child.stdout.on("data", (chunk) => { stdoutBytes += collect(stdout, chunk, stdoutBytes); if (overflow)
+        child.kill(); });
+    child.stderr.on("data", (chunk) => { stderrBytes += collect(stderr, chunk, stderrBytes); if (overflow)
+        child.kill(); });
+    const code = await new Promise((resolveCode, reject) => {
+        child.once("error", reject);
+        child.once("close", resolveCode);
+    });
+    signal?.throwIfAborted();
+    if (overflow)
+        throw new Error(`Working-change evidence exceeds ${limit - 1} bytes.`);
+    return { code: code ?? -1, stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr) };
+}
+async function git(args, cwd, env, signal) {
+    const result = await command(args, cwd, env, signal);
+    if (result.code !== 0) {
+        const detail = result.stderr.toString("utf8").slice(0, 200).trim();
+        throw new Error(`git ${args.join(" ")} failed with exit ${result.code}${detail ? `: ${detail}` : ""}`);
+    }
+    return result.stdout;
+}
+function paths(value) {
+    if (!value.length)
+        return [];
+    const text = value.toString("utf8");
+    if (text.includes("�") || value.at(-1) !== 0)
+        throw new Error("Git returned malformed working-change paths.");
+    const result = text.slice(0, -1).split("\0");
+    if (result.length > REVIEW_MAX_PATHS)
+        throw new Error(`Working-change evidence exceeds ${REVIEW_MAX_PATHS} paths.`);
+    for (const path of result) {
+        if (!path || path.includes("\0") || isAbsolute(path) || path.split(/[\\/]/).some((part) => !part || part === "." || part === "..")) {
+            throw new Error(`Git returned malformed or unsupported path: ${JSON.stringify(path)}`);
+        }
+    }
+    return result;
+}
+async function indexPath(worktree, signal) {
+    const raw = line(await git(["rev-parse", "--git-path", "index"], worktree, undefined, signal), "index path");
+    const path = isAbsolute(raw) ? raw : resolve(worktree, raw);
+    return await realpath(path);
+}
+async function repositoryObjects(worktree, signal) {
+    const raw = line(await git(["rev-parse", "--git-common-dir"], worktree, undefined, signal), "common Git directory");
+    const directory = isAbsolute(raw) ? raw : resolve(worktree, raw);
+    return await realpath(join(directory, "objects"));
+}
+async function assertNoExternalFilters(worktree, signal) {
+    const result = await command(["config", "--get-regexp", "^filter\\..*\\.(clean|process)$"], worktree, process.env, signal, 64 * 1024);
+    if (result.code === 1 && result.stdout.length === 0)
+        return;
+    if (result.code !== 0)
+        throw new Error("Could not inspect effective Git content filters.");
+    throw new Error("Checked direct changesets reject configured Git clean/process filters; use isolated mode or remove the filter configuration before retrying.");
+}
+async function assertSupportedIndex(worktree, signal) {
+    const flags = await inspectIndexFlags(worktree, runCapturedGit, signal);
+    if (flags.failure)
+        throw new Error(`Working-change index inspection failed: ${flags.failure}`);
+    if (flags.hidden)
+        throw new Error("Checked direct changesets reject assume-unchanged or skip-worktree index entries.");
+    const stage = (await git(["ls-files", "--stage", "-z"], worktree, undefined, signal)).toString("utf8");
+    if (stage.includes("�") || /(?:^|\0)160000 /.test(stage))
+        throw new Error("Checked direct changesets reject Git links.");
+}
+async function rawManifest(worktree, signal) {
+    const listed = paths(await git(["ls-files", "-z", "--cached", "--others", "--exclude-standard"], worktree, undefined, signal));
+    const entries = [];
+    for (const path of [...new Set(listed)].sort()) {
+        signal?.throwIfAborted();
+        const absolute = join(worktree, path);
+        let info;
+        try {
+            info = await lstat(absolute);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                entries.push({ path, kind: "absent" });
+                continue;
+            }
+            throw error;
+        }
+        if (info.isSymbolicLink()) {
+            const target = await readlink(absolute, { encoding: "buffer" });
+            entries.push({ path, kind: "symlink", mode: info.mode & 0o7777, size: target.length, hash: hash(target) });
+        }
+        else if (info.isFile()) {
+            const contents = await readFile(absolute);
+            entries.push({ path, kind: "file", mode: info.mode & 0o7777, size: contents.length, hash: hash(contents) });
+        }
+        else {
+            throw new Error(`Checked direct evidence rejects unsupported working path type: ${path}`);
+        }
+    }
+    const json = `${JSON.stringify(entries)}\n`;
+    if (Buffer.byteLength(json, "utf8") > MANIFEST_MAX_BYTES)
+        throw new Error(`Working-change raw manifest exceeds ${MANIFEST_MAX_BYTES} bytes.`);
+    return { json, digest: hash(json) };
+}
+async function actualIdentity(worktree, signal) {
+    const [head, index] = await Promise.all([
+        git(["rev-parse", "--verify", "HEAD"], worktree, undefined, signal),
+        readFile(await indexPath(worktree, signal)),
+    ]);
+    return { head: oid(head, "HEAD"), indexHash: hash(index) };
+}
+async function privateSnapshot(worktree, directory, signal) {
+    const privateIndex = join(directory, "index");
+    const objectDirectory = join(directory, "objects");
+    await mkdir(objectDirectory, { mode: 0o700 });
+    await copyFile(await indexPath(worktree, signal), privateIndex, constants.COPYFILE_EXCL);
+    await chmod(privateIndex, 0o600);
+    const env = {
+        ...process.env,
+        GIT_INDEX_FILE: privateIndex,
+        GIT_OBJECT_DIRECTORY: objectDirectory,
+        GIT_ALTERNATE_OBJECT_DIRECTORIES: await repositoryObjects(worktree, signal),
+        GIT_CONFIG_NOSYSTEM: "1",
+    };
+    await git(["add", "-A", "--", "."], worktree, env, signal);
+    const tree = oid(await git(["write-tree"], worktree, env, signal), "private working tree");
+    const manifest = await rawManifest(worktree, signal);
+    return { tree, manifest };
+}
+async function makeDirectory() {
+    const directory = await mkdtemp(join(tmpdir(), "pi-subagent-working-review-"));
+    await chmod(directory, 0o700);
+    let cleaning;
+    return { directory, cleanup: () => cleaning ??= rm(directory, { recursive: true, force: true }) };
+}
+async function capture(worktree, directory, signal) {
+    await assertNoExternalFilters(worktree, signal);
+    await assertSupportedIndex(worktree, signal);
+    const before = await actualIdentity(worktree, signal);
+    const snapshot = await privateSnapshot(worktree, directory, signal);
+    const afterManifest = await rawManifest(worktree, signal);
+    const after = await actualIdentity(worktree, signal);
+    if (before.head !== after.head || before.indexHash !== after.indexHash || snapshot.manifest.digest !== afterManifest.digest) {
+        throw new Error("Working checkout changed while direct evidence was being captured.");
+    }
+    return {
+        identity: { ...before, tree: snapshot.tree, rawManifestHash: snapshot.manifest.digest },
+        manifest: snapshot.manifest.json,
+    };
+}
+async function canonicalRoot(cwd, signal) {
+    const canonical = await realpath(cwd);
+    return await realpath(line(await git(["rev-parse", "--show-toplevel"], canonical, undefined, signal), "checkout root"));
+}
+/** Capture mutation-detection identity without requiring a clean checkout or constructing Git objects. */
+export async function captureWorkingCheckoutState(cwd, signal) {
+    const worktree = await canonicalRoot(cwd, signal);
+    const before = await actualIdentity(worktree, signal);
+    const manifest = await rawManifest(worktree, signal);
+    const after = await actualIdentity(worktree, signal);
+    if (before.head !== after.head || before.indexHash !== after.indexHash) {
+        throw new Error("Working checkout changed while direct state was being captured.");
+    }
+    return { ...before, rawManifestHash: manifest.digest };
+}
+export async function captureWorkingCheckoutBaseline(cwd, signal) {
+    const worktree = await canonicalRoot(cwd, signal);
+    const branch = await command(["symbolic-ref", "-q", "HEAD"], worktree, process.env, signal, 64 * 1024);
+    if (branch.code !== 0)
+        throw new Error("Checked direct changesets require an attached branch.");
+    if ((await git(["status", "--porcelain=v1", "--untracked-files=all", "--ignore-submodules=none"], worktree, undefined, signal)).length) {
+        throw new Error("Checked direct changesets require a clean initial checkout; settle existing work or choose authorized isolated mode. No files were stashed, reset, or deleted.");
+    }
+    const owned = await makeDirectory();
+    try {
+        const captured = await capture(worktree, owned.directory, signal);
+        return { worktree, ...captured.identity };
+    }
+    finally {
+        await owned.cleanup();
+    }
+}
+export async function prepareWorkingChangeEvidence(baseline, signal) {
+    const owned = await makeDirectory();
+    try {
+        const captured = await capture(baseline.worktree, owned.directory, signal);
+        if (captured.identity.head !== baseline.head)
+            throw new Error("Checked direct changesets cannot move HEAD or create commits.");
+        const env = {
+            ...process.env,
+            GIT_OBJECT_DIRECTORY: join(owned.directory, "objects"),
+            GIT_ALTERNATE_OBJECT_DIRECTORIES: await repositoryObjects(baseline.worktree, signal),
+            GIT_CONFIG_NOSYSTEM: "1",
+        };
+        const raw = await git(["diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--raw", "-z", baseline.tree, captured.identity.tree], baseline.worktree, env, signal);
+        if (raw.toString("utf8").includes("160000"))
+            throw new Error("Checked direct changesets reject changed Git links.");
+        const changedPaths = paths(await git(["diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--name-only", "-z", baseline.tree, captured.identity.tree], baseline.worktree, env, signal));
+        const patch = await git(["--no-pager", "diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--binary", baseline.tree, captured.identity.tree], baseline.worktree, env, signal);
+        if (patch.length > REVIEW_MAX_PATCH_BYTES)
+            throw new Error(`Working-change evidence exceeds ${REVIEW_MAX_PATCH_BYTES} bytes.`);
+        const patchPath = join(owned.directory, "review.patch");
+        const rawEvidencePath = join(owned.directory, "raw-manifest.json");
+        const patchFile = await open(patchPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        await patchFile.writeFile(patch);
+        await patchFile.close();
+        await writeFile(rawEvidencePath, captured.manifest, { mode: 0o600, flag: "wx" });
+        return { baseline, identity: captured.identity, changedPaths, patchPath, rawEvidencePath, cleanup: owned.cleanup };
+    }
+    catch (error) {
+        await owned.cleanup();
+        throw error;
+    }
+}
+export function sameWorkingCheckoutState(left, right) {
+    return left.head === right.head && left.indexHash === right.indexHash && left.rawManifestHash === right.rawManifestHash;
+}
+export function sameWorkingSnapshot(left, right) {
+    return sameWorkingCheckoutState(left, right) && left.tree === right.tree;
+}

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

@@ -2,7 +2,7 @@
 
 ## Decision
 
-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.
+The public task executor is an execution mechanism: it receives a prepared Pi Launch, runs one bounded Delegated Task, and returns the result. The `delegate_task` extension composes it for direct workflows and isolated checked graphs; those modes are not executor primitives.
 
 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.
 
@@ -21,8 +21,8 @@ An explicit call `modelClass` selects a task-model route. Without one, an option
 
 ## Scope boundary
 
-`delegate_task` and library callers remain generic. The package does not own checked implementation orchestration.
+The executor remains generic and policy-free beyond child execution limits. Direct and isolated workflow policy belongs to the extension and checked runner, not the executor. External library callers may still compose the mechanism with their own protocols.
 
 ## Consequences
 
-The executor remains a stable mechanism while callers own semantic protocols, shared workspace and state, validation, review, retry decisions, integration, cleanup, and bounds.
+The executor remains stable while pi-subagent owns its direct and checked-isolated semantics. Mechanism callers continue to own any protocol they build outside those surfaces.