@selesai/code 0.9.10 → 0.9.12

package/dist/extensions/pi-subagents/src/runs/shared/mutation-evidence.ts

@@ -0,0 +1,145 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ArtifactPaths, TimeoutRecoverySummary, TrackedMutationEvidence, TrackedMutationFingerprint, TrackedMutationSnapshot } from "../../shared/types.ts";
+
+const MAX_TRACKED_PATHS = 500;
+const MAX_HASH_BYTES = 1024 * 1024;
+const MAX_TIMEOUT_FILES = 20;
+
+function gitOutput(cwd: string, args: string[], maxBuffer = MAX_HASH_BYTES): string {
+	return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer });
+}
+
+function splitNul(output: string): string[] {
+	return output.split("\0").filter((part) => part.length > 0);
+}
+
+function hashLargeDiff(cwd: string, relativePath: string): string {
+	const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tracked-diff-"));
+	const diffPath = path.join(tempDir, "diff.patch");
+	try {
+		execFileSync("git", ["diff", "--no-ext-diff", "--binary", `--output=${diffPath}`, "HEAD", "--", relativePath], { cwd, stdio: "ignore" });
+		const hash = createHash("sha256");
+		const buffer = Buffer.allocUnsafe(64 * 1024);
+		const fd = fs.openSync(diffPath, "r");
+		try {
+			for (;;) {
+				const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, null);
+				if (bytesRead === 0) break;
+				hash.update(buffer.subarray(0, bytesRead));
+			}
+		} finally {
+			fs.closeSync(fd);
+		}
+		return hash.digest("hex");
+	} finally {
+		fs.rmSync(tempDir, { recursive: true, force: true });
+	}
+}
+
+function listChangedTrackedFiles(cwd: string): { paths: string[]; truncated: boolean } {
+	const paths = splitNul(gitOutput(cwd, ["diff", "--no-ext-diff", "--name-only", "-z", "HEAD", "--"], MAX_HASH_BYTES));
+	return { paths: paths.slice(0, MAX_TRACKED_PATHS), truncated: paths.length > MAX_TRACKED_PATHS };
+}
+
+function fingerprintPath(cwd: string, relativePath: string): TrackedMutationFingerprint {
+	try {
+		const diff = gitOutput(cwd, ["diff", "--no-ext-diff", "--binary", "HEAD", "--", relativePath], MAX_HASH_BYTES);
+		return { kind: "diff", digest: createHash("sha256").update(diff).digest("hex") };
+	} catch {
+		return { kind: "diff", digest: hashLargeDiff(cwd, relativePath) };
+	}
+}
+
+function sameFingerprint(left: TrackedMutationFingerprint | undefined, right: TrackedMutationFingerprint): boolean {
+	if (!left || left.kind !== "diff" || right.kind !== "diff") return false;
+	return left.digest === right.digest;
+}
+
+export function snapshotTrackedMutations(cwd: string): TrackedMutationSnapshot {
+	try {
+		const changed = listChangedTrackedFiles(cwd);
+		const fingerprints: Record<string, TrackedMutationFingerprint> = {};
+		for (const file of changed.paths) fingerprints[file] = fingerprintPath(cwd, file);
+		return { source: "tracked-files", trackedOnly: true, cwd, dirtyFiles: changed.paths, fingerprints, truncated: changed.truncated };
+	} catch (error) {
+		return { source: "tracked-files", trackedOnly: true, cwd, dirtyFiles: [], fingerprints: {}, unavailable: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+export function collectTrackedMutationEvidence(snapshot: TrackedMutationSnapshot, cwd = snapshot.cwd): TrackedMutationEvidence {
+	if (snapshot.unavailable) {
+		return { source: "tracked-files", trackedOnly: true, changedFiles: [], attemptedMutation: false, unavailable: snapshot.unavailable };
+	}
+	try {
+		const current = listChangedTrackedFiles(cwd);
+		const startDirty = new Set(snapshot.dirtyFiles);
+		const candidates = new Set([...snapshot.dirtyFiles, ...current.paths]);
+		const changedFiles: string[] = [];
+		for (const file of candidates) {
+			if (!startDirty.has(file)) {
+				if (!snapshot.truncated) changedFiles.push(file);
+				continue;
+			}
+			if (!sameFingerprint(snapshot.fingerprints[file], fingerprintPath(cwd, file))) changedFiles.push(file);
+		}
+		changedFiles.sort();
+		return {
+			source: "tracked-files",
+			trackedOnly: true,
+			changedFiles,
+			attemptedMutation: changedFiles.length > 0,
+			truncated: snapshot.truncated || current.truncated || undefined,
+		};
+	} catch (error) {
+		return { source: "tracked-files", trackedOnly: true, changedFiles: [], attemptedMutation: false, unavailable: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function formatPathList(paths: string[]): string {
+	if (paths.length === 0) return "none";
+	const shown = paths.slice(0, MAX_TIMEOUT_FILES).join(", ");
+	return paths.length > MAX_TIMEOUT_FILES ? `${shown}, ... (${paths.length - MAX_TIMEOUT_FILES} more)` : shown;
+}
+
+export function buildTimeoutRecoverySummary(input: {
+	termination: "timed-out" | "stopped";
+	evidence: TrackedMutationEvidence;
+	currentTool?: string;
+	currentToolArgs?: string;
+	currentPath?: string;
+	sessionFile?: string;
+	transcriptPath?: string;
+	artifactPaths?: ArtifactPaths;
+}): TimeoutRecoverySummary {
+	const warning = "Inspect partial changes before retrying or resuming the child.";
+	const changedFiles = input.evidence.changedFiles.slice(0, MAX_TIMEOUT_FILES);
+	const lines = [
+		"Recovery summary:",
+		`- termination: ${input.termination}`,
+		`- changed tracked files: ${input.evidence.unavailable ? `unavailable (${input.evidence.unavailable})` : formatPathList(input.evidence.changedFiles)}`,
+	];
+	if (input.currentTool) lines.push(`- active tool: ${input.currentTool}${input.currentToolArgs ? ` — ${input.currentToolArgs}` : ""}`);
+	if (input.currentPath) lines.push(`- active path: ${input.currentPath}`);
+	if (input.sessionFile) lines.push(`- session file: ${input.sessionFile}`);
+	if (input.transcriptPath) lines.push(`- transcript: ${input.transcriptPath}`);
+	if (input.artifactPaths?.outputPath) lines.push(`- output artifact: ${input.artifactPaths.outputPath}`);
+	if (input.artifactPaths?.metadataPath) lines.push(`- metadata artifact: ${input.artifactPaths.metadataPath}`);
+	lines.push(`Warning: ${warning}`);
+	return {
+		termination: input.termination,
+		changedFiles,
+		truncated: input.evidence.changedFiles.length > changedFiles.length || input.evidence.truncated || undefined,
+		currentTool: input.currentTool,
+		currentToolArgs: input.currentToolArgs,
+		currentPath: input.currentPath,
+		sessionFile: input.sessionFile,
+		transcriptPath: input.transcriptPath,
+		artifactPaths: input.artifactPaths,
+		warning,
+		message: lines.join("\n"),
+	};
+}

package/dist/extensions/pi-subagents/src/runs/shared/orca-progress-tabs.ts

@@ -1,10 +1,10 @@
 import { spawn } from "node:child_process";
-import { readSubagentEnv } from "../../shared/env.ts";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import type { Message } from "@earendil-works/pi-ai";
 import { resolveNodeExecutable } from "../../shared/node-executable.ts";
+import { getProjectSubagentsDir } from "../../shared/artifacts.ts";
 import { TEMP_ROOT_DIR, type OrcaProgressTabsConfig } from "../../shared/types.ts";
 import { extractTextFromContent, extractToolArgsPreview, getAgentDir } from "../../shared/utils.ts";
 
@@ -18,16 +18,31 @@ const MIRROR_FOOTER_RESERVE_BYTES = 16 * 1024;
 const COUNTER_LOCK_STALE_MS = 30_000;
 const COUNTER_LOCK_RETRIES = 200;
 const COUNTER_LOCK_RETRY_MS = 10;
+const ORCA_CREATE_WAIT_TIMEOUT_MS = ORCA_CREATE_TIMEOUT_MS + ORCA_KILL_GRACE_MS + 3_000;
 
 const ORCA_CREATE_WATCHDOG_SCRIPT = [
 	"const {spawn}=require('node:child_process');",
-	"const timeout=Number(process.argv[1]),grace=Number(process.argv[2]),command=process.argv[3],args=process.argv.slice(4);",
-	"const child=spawn(command,args,{stdio:'ignore',windowsHide:true});",
-	"let hardKill;",
-	"const timer=setTimeout(()=>{child.kill('SIGTERM');hardKill=setTimeout(()=>child.kill('SIGKILL'),grace)},timeout);",
-	"const clear=()=>{clearTimeout(timer);if(hardKill)clearTimeout(hardKill)};",
-	"child.once('error',()=>{clear();process.exitCode=1});",
-	"child.once('close',code=>{clear();process.exitCode=code===0?0:1});",
+	"const fs=require('node:fs');",
+	"const timeout=Number(process.argv[1]),grace=Number(process.argv[2]),waitTimeout=Number(process.argv[3]);",
+	"const previous=process.argv[4],done=process.argv[5],manifest=process.argv[6],command=process.argv[7],args=process.argv.slice(8);",
+	"function mark(){try{fs.writeFileSync(done.replace(/\\.pending$/,'.ready'),'')}catch{}}",
+	"function exists(file){try{return fs.existsSync(file)}catch{return false}}",
+	"function keepQueued(){try{const now=new Date();fs.utimesSync(done,now,now)}catch{}}",
+	"function predecessorReady(){if(previous==='-')return true;if(exists(previous.replace(/\\.pending$/,'.ready')))return true;try{return Date.now()-fs.statSync(previous).mtimeMs>=waitTimeout}catch{return true}}",
+	"function updateManifest(state,stdout=''){if(manifest==='-')return;try{const payload=JSON.parse(fs.readFileSync(manifest,'utf8'));payload.state=state;payload.updatedAt=new Date().toISOString();const raw=stdout.trim().split(/\\r?\\n/).filter(Boolean).at(-1);if(raw){try{payload.orca=JSON.parse(raw)}catch{payload.orcaRaw=raw.slice(0,4096)}}fs.writeFileSync(manifest,JSON.stringify(payload,null,2)+'\\n')}catch{}}",
+	"function start(){",
+	" try{",
+	"  const child=spawn(command,args,{stdio:['ignore','pipe','ignore'],windowsHide:true});",
+	"  let hardKill,stdout='';",
+	"  if(child.stdout)child.stdout.on('data',chunk=>{stdout+=String(chunk);if(stdout.length>65536)stdout=stdout.slice(-65536)});",
+	"  const timer=setTimeout(()=>{child.kill('SIGTERM');hardKill=setTimeout(()=>child.kill('SIGKILL'),grace)},timeout);",
+	"  const clear=()=>{clearTimeout(timer);if(hardKill)clearTimeout(hardKill);mark()};",
+	"  child.once('error',()=>{updateManifest('failed');clear();process.exitCode=1});",
+	"  child.once('close',code=>{updateManifest(code===0?'open':'failed',stdout);clear();process.exitCode=code===0?0:1});",
+	" }catch{updateManifest('failed');mark();process.exitCode=1}",
+	"}",
+	"if(predecessorReady())start();",
+	"else{(function waitPrev(){keepQueued();if(predecessorReady())return start();setTimeout(waitPrev,20)})();}",
 ].join("");
 
 const ORCA_CLEANUP_WATCHDOG_SCRIPT = [
@@ -39,6 +54,7 @@ const ORCA_CLEANUP_WATCHDOG_SCRIPT = [
 
 export interface OrcaProgressTab {
 	append(text: string): void;
+	section(input: { agent: string; index: number; count: number }): void;
 	event(event: { type?: string; message?: Message; toolName?: string; args?: unknown }): void;
 	finish(status: "completed" | "failed" | "stopped", sessionFile?: string): void;
 }
@@ -62,7 +78,7 @@ function executableNames(command: string, env: NodeJS.ProcessEnv): string[] {
 }
 
 export function resolveOrcaCommand(env: NodeJS.ProcessEnv = process.env): string | undefined {
-	const override = readSubagentEnv(env, "SELESAI_SUBAGENT_ORCA_BINARY")?.trim();
+	const override = env.SELESAI_SUBAGENT_ORCA_BINARY?.trim();
 	if (override) return executableFile(override) ? override : undefined;
 	for (const directory of (env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
 		for (const name of executableNames("orca", env)) {
@@ -115,7 +131,7 @@ function progressRoot(): string {
 function pruneStaleProgressFiles(root: string, now = Date.now()): void {
 	try {
 		for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-			if (!entry.isFile() || (!entry.name.endsWith(".log") && !entry.name.endsWith(".done"))) continue;
+			if (!entry.isFile() || (!entry.name.endsWith(".log") && !entry.name.endsWith(".done") && !entry.name.endsWith(".ready") && !entry.name.endsWith(".pending"))) continue;
 			const file = path.join(root, entry.name);
 			try {
 				if (now - fs.statSync(file).mtimeMs > STALE_PROGRESS_MAX_AGE_MS) fs.rmSync(file, { force: true });
@@ -131,6 +147,41 @@ function safeSegment(value: unknown, fallback = "subagent"): string {
 	return value.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || fallback;
 }
 
+interface OrcaObserverManifest {
+	schemaVersion: 1;
+	kind: "orca-observer-view";
+	observer: "orca";
+	role: "run";
+	runId: string;
+	title: string;
+	worktree: string;
+	state: "opening" | "open" | "failed";
+	createdAt: string;
+	updatedAt?: string;
+	logPath: string;
+	orca?: unknown;
+	orcaRaw?: string;
+}
+
+function observerManifestPath(cwd: string, stem: string): string | undefined {
+	try {
+		const dir = path.join(getProjectSubagentsDir(resolveSequenceScope(cwd)), "views", "orca");
+		fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+		return path.join(dir, `${stem}.json`);
+	} catch {
+		return undefined;
+	}
+}
+
+function writeObserverManifest(manifestPath: string | undefined, manifest: OrcaObserverManifest): void {
+	if (!manifestPath) return;
+	try {
+		fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+	} catch {
+		// The Orca observer stays display-only when project-local manifests cannot be written.
+	}
+}
+
 function sleepSync(ms: number): void {
 	const signal = new Int32Array(new SharedArrayBuffer(4));
 	Atomics.wait(signal, 0, 0, ms);
@@ -149,10 +200,12 @@ function resolveSequenceScope(cwd: string): string {
 	}
 }
 
-function reserveTabSequence(root: string, cwd: string): number | undefined {
-	const key = createHash("sha256").update(resolveSequenceScope(cwd)).digest("hex").slice(0, 20);
-	const counterPath = path.join(root, `counter-${key}`);
-	const lockPath = `${counterPath}.lock`;
+function sequenceKey(cwd: string): string {
+	return createHash("sha256").update(resolveSequenceScope(cwd)).digest("hex").slice(0, 20);
+}
+
+function withSequenceLock<T>(root: string, key: string, fn: () => T): T | undefined {
+	const lockPath = path.join(root, `counter-${key}.lock`);
 	let locked = false;
 	for (let attempt = 0; attempt < COUNTER_LOCK_RETRIES; attempt++) {
 		try {
@@ -172,21 +225,44 @@ function reserveTabSequence(root: string, cwd: string): number | undefined {
 	}
 	if (!locked) return undefined;
 	try {
+		return fn();
+	} finally {
+		try { fs.rmSync(lockPath, { recursive: true, force: true }); } catch { /* stale lock cleanup handles crashes */ }
+	}
+}
+
+function predecessorMarker(pathValue: string | undefined): string | undefined {
+	if (!pathValue) return undefined;
+	const ready = pathValue.endsWith(".pending") ? pathValue.replace(/\.pending$/, ".ready") : pathValue;
+	const pending = ready.replace(/\.ready$/, ".pending");
+	if (fs.existsSync(ready) || fs.existsSync(pending)) return pending;
+	return undefined;
+}
+
+function reserveTabSequence(root: string, cwd: string): { sequence: number; previousCreateDone?: string; createDone: string } | undefined {
+	const key = sequenceKey(cwd);
+	const counterPath = path.join(root, `counter-${key}`);
+	const createDone = path.join(root, `create-${key}-${randomUUID()}.pending`);
+	return withSequenceLock(root, key, () => {
 		let current = 0;
+		let previousCreateDone: string | undefined;
 		try {
-			const parsed = Number.parseInt(fs.readFileSync(counterPath, "utf-8"), 10);
+			const raw = fs.readFileSync(counterPath, "utf-8");
+			const [countLine, previousLine] = raw.split("\n");
+			const parsed = Number.parseInt(countLine ?? "", 10);
 			if (Number.isSafeInteger(parsed) && parsed >= 0) current = parsed;
+			previousCreateDone = predecessorMarker(previousLine?.trim());
 		} catch { /* first tab for this worktree */ }
 		const next = current + 1;
 		try {
-			fs.writeFileSync(counterPath, `${next}\n`, { encoding: "utf-8", mode: 0o600 });
-			return next;
+			fs.writeFileSync(createDone, "", { encoding: "utf-8", mode: 0o600 });
+			fs.writeFileSync(counterPath, `${next}\n${createDone}\n`, { encoding: "utf-8", mode: 0o600 });
+			return { sequence: next, previousCreateDone, createDone };
 		} catch {
+			try { fs.rmSync(createDone, { force: true }); } catch { /* best effort */ }
 			return undefined;
 		}
-	} finally {
-		try { fs.rmSync(lockPath, { recursive: true, force: true }); } catch { /* stale lock cleanup handles crashes */ }
-	}
+	});
 }
 
 export function resolvePiSessionId(sessionFile: string | undefined): string | undefined {
@@ -243,6 +319,7 @@ export function createOrcaProgressTab(input: {
 	runId: string;
 	agent: string;
 	index: number;
+	stepCount?: number;
 	config?: OrcaProgressTabsConfig;
 	env?: NodeJS.ProcessEnv;
 	command?: string;
@@ -264,16 +341,35 @@ export function createOrcaProgressTab(input: {
 	const agent = safeSegment(input.agent, "subagent");
 	const index = typeof input.index === "number" && Number.isInteger(input.index) && input.index >= 0 ? input.index : 0;
 	const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
-	const tabSequence = reserveTabSequence(root, cwd);
-	if (tabSequence === undefined) return undefined;
+	const reservation = reserveTabSequence(root, cwd);
+	if (reservation === undefined) return undefined;
+	const tabSequence = reservation.sequence;
 	const stem = `${runId}-${index}-${randomUUID()}`;
+	const stepCount = typeof input.stepCount === "number" && Number.isInteger(input.stepCount) && input.stepCount > 0 ? input.stepCount : 1;
 	const logPath = path.join(root, `${stem}.log`);
 	const donePath = path.join(root, `${stem}.done`);
-	const title = `subagent · ${agent} · ${tabSequence}`;
+	const title = `subagents · ${agent} · ${tabSequence}`;
+	const markCreateReady = () => {
+		try { fs.writeFileSync(reservation.createDone.replace(/\.pending$/, ".ready"), ""); } catch { /* unblock later tabs */ }
+	};
+	const manifestPath = observerManifestPath(cwd, stem);
+	writeObserverManifest(manifestPath, {
+		schemaVersion: 1,
+		kind: "orca-observer-view",
+		observer: "orca",
+		role: "run",
+		runId,
+		title,
+		worktree: path.resolve(cwd),
+		state: "opening",
+		createdAt: new Date().toISOString(),
+		logPath,
+	});
 	try {
-		fs.writeFileSync(logPath, `pi-subagents / ${agent}\nrun ${runId} · child ${index + 1}\n${"─".repeat(48)}\n`, { encoding: "utf-8", mode: 0o600 });
+		fs.writeFileSync(logPath, `pi-subagents / ${agent}\nrun ${runId} · ${stepCount === 1 ? "1 child" : `${stepCount} children`}\n${"─".repeat(48)}\n`, { encoding: "utf-8", mode: 0o600 });
 		fs.rmSync(donePath, { force: true });
 	} catch {
+		markCreateReady();
 		return undefined;
 	}
 
@@ -304,11 +400,22 @@ export function createOrcaProgressTab(input: {
 			failObserver();
 		}
 	};
+	let createSettled = false;
+	let cleanupPaths: string[] | undefined;
+	const scheduleDeferredCleanup = () => {
+		if (!createSettled || cleanupPaths === undefined) return;
+		scheduleCleanup(nodeExecutable, cleanupPaths);
+		cleanupPaths = undefined;
+	};
 	try {
 		const watchdog = spawn(nodeExecutable, [
 			"-e", ORCA_CREATE_WATCHDOG_SCRIPT,
 			String(ORCA_CREATE_TIMEOUT_MS),
 			String(ORCA_KILL_GRACE_MS),
+			String(ORCA_CREATE_WAIT_TIMEOUT_MS),
+			reservation.previousCreateDone ?? "-",
+			reservation.createDone,
+			manifestPath ?? "-",
 			command,
 			"terminal", "create",
 			"--worktree", `path:${path.resolve(cwd)}`,
@@ -323,11 +430,19 @@ export function createOrcaProgressTab(input: {
 			env: input.env ?? process.env,
 		});
 		watchdog.once("close", (code) => {
+			createSettled = true;
 			if (code !== 0) failObserver();
+			scheduleDeferredCleanup();
+		});
+		watchdog.once("error", () => {
+			markCreateReady();
+			createSettled = true;
+			failObserver();
+			scheduleDeferredCleanup();
 		});
-		watchdog.once("error", failObserver);
 		watchdog.unref();
 	} catch {
+		markCreateReady();
 		failObserver();
 		return undefined;
 	}
@@ -338,6 +453,13 @@ export function createOrcaProgressTab(input: {
 			if (finished) return;
 			writeProgress(text);
 		},
+		section(section) {
+			if (finished) return;
+			const label = safeSegment(section.agent, "subagent");
+			const count = Number.isInteger(section.count) && section.count > 0 ? section.count : 1;
+			const index = Number.isInteger(section.index) && section.index >= 0 ? section.index : 0;
+			writeProgress(`\n${"─".repeat(16)} child ${index + 1}/${count} · ${label} ${"─".repeat(16)}\n`);
+		},
 		event(event) {
 			if (!available || finished) return;
 			if (event.type === "tool_execution_start" && event.toolName) {
@@ -361,7 +483,7 @@ export function createOrcaProgressTab(input: {
 				try { verifiedSessionFile = fs.realpathSync(sessionFile); } catch { /* the session is no longer available */ }
 			}
 			const terminalMessage = verifiedSessionFile
-				? `completed. To remove the Pi session of this subagent, run rm -- ${shellQuote(verifiedSessionFile)}`
+				? `completed. To remove the Pi session for this run, run rm -- ${shellQuote(verifiedSessionFile)}`
 				: status;
 			const truncation = truncated ? `\n[progress mirror truncated at ${MAX_MIRROR_BYTES} bytes]\n` : "";
 			let footer = `${truncation}\n${"─".repeat(48)}\n${terminalMessage}\n`;
@@ -369,7 +491,8 @@ export function createOrcaProgressTab(input: {
 			logStream.end(footer, () => {
 				if (!available) return;
 				try { fs.writeFileSync(donePath, `${status}\n`, { encoding: "utf-8", mode: 0o600 }); } catch { /* best effort */ }
-				scheduleCleanup(nodeExecutable, [logPath, donePath]);
+				cleanupPaths = [logPath, donePath];
+				scheduleDeferredCleanup();
 			});
 		},
 	};

package/dist/extensions/pi-subagents/src/runs/shared/parallel-handoff.ts

@@ -34,6 +34,48 @@ function readManifest(manifestPath: string): ParallelHandoffManifest | undefined
 	return parsed;
 }
 
+function resolveExistingPath(candidate: string): string {
+	try {
+		return fs.realpathSync(candidate);
+	} catch {
+		return path.resolve(candidate);
+	}
+}
+
+function pathInside(root: string, candidate: string): boolean {
+	const relative = path.relative(root, candidate);
+	return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+export function resolveRetainedWorktreeCwd(manifestPath: string, runId: string, childIndex: number): string | undefined {
+	const manifest = readManifest(manifestPath);
+	if (!manifest) return undefined;
+	if (manifest.runId !== runId) throw new Error(`Managed worktree handoff belongs to run '${manifest.runId}', not '${runId}'.`);
+	const match = manifest.groups
+		.flatMap((group) => group.children.map((child) => ({ group, child })))
+		.find(({ child }) => child.index === childIndex);
+	if (!match) return undefined;
+	const cleanup = match.group.cleanup.tasks.find((task) => task.index === match.child.taskIndex);
+	if (!cleanup) throw new Error(`Async run '${runId}' child ${childIndex} has no managed worktree cleanup record.`);
+	const relativeCwd = path.relative(resolveExistingPath(match.group.repoRoot), resolveExistingPath(manifest.cwd));
+	if (path.isAbsolute(relativeCwd) || relativeCwd === ".." || relativeCwd.startsWith(`..${path.sep}`)) throw new Error(`Async run '${runId}' has an invalid managed worktree cwd.`);
+	const requiredCwd = path.join(cleanup.path, relativeCwd);
+	if (cleanup.worktreeRemoved || cleanup.branchRemoved) throw new Error(`Async run '${runId}' required managed worktree was removed: ${requiredCwd}`);
+	let worktreeRoot = "";
+	let resolvedRequiredCwd = "";
+	try {
+		const rootStat = fs.lstatSync(cleanup.path);
+		if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error("worktree root is not a directory");
+		worktreeRoot = fs.realpathSync(cleanup.path);
+		if (!fs.statSync(requiredCwd).isDirectory()) throw new Error("path is not a directory");
+		resolvedRequiredCwd = fs.realpathSync(requiredCwd);
+	} catch (error) {
+		throw new Error(`Async run '${runId}' required managed worktree cwd is missing: ${requiredCwd}`, { cause: error instanceof Error ? error : undefined });
+	}
+	if (!pathInside(worktreeRoot, resolvedRequiredCwd)) throw new Error(`Async run '${runId}' has an invalid managed worktree cwd.`);
+	return requiredCwd;
+}
+
 function referenceFor(manifestPath: string, manifest: ParallelHandoffManifest): ParallelHandoffReference {
 	const children = manifest.groups.flatMap((group) => group.children);
 	return {
@@ -74,7 +116,7 @@ function missingDiff(input: { manifestPath: string; stepIndex: number; taskIndex
 export function writeParallelHandoffGroup(input: {
 	manifestPath: string;
 	runId: string;
-	mode: "parallel" | "chain";
+	mode: "single" | "parallel" | "chain";
 	source: "foreground" | "async";
 	cwd: string;
 	stepIndex: number;
@@ -162,7 +204,7 @@ export function parallelHandoffPath(baseDir: string, runId?: string): string {
 export function writePendingParallelHandoff(input: {
 	manifestPath: string;
 	runId: string;
-	mode: "parallel" | "chain";
+	mode: "single" | "parallel" | "chain";
 	source: "foreground" | "async";
 	cwd: string;
 	stepIndex: number;
@@ -173,11 +215,11 @@ export function writePendingParallelHandoff(input: {
 }
 
 export function formatParallelHandoffReference(reference: ParallelHandoffReference): string {
-	return `Parallel handoff: ${reference.path} (${reference.childCount} children, ${reference.changedPatches} changed patches, cleanup ${reference.cleanupState})`;
+	return `Worktree handoff: ${reference.path} (${reference.childCount} children, ${reference.changedPatches} changed patches, cleanup ${reference.cleanupState})`;
 }
 
 export function formatParallelHandoffError(error: unknown): string {
-	return `Parallel handoff unavailable: ${error instanceof Error ? error.message : String(error)}`;
+	return `Worktree handoff unavailable: ${error instanceof Error ? error.message : String(error)}`;
 }
 
 export function discardPreservedWorktrees(

package/dist/extensions/pi-subagents/src/runs/shared/parallel-utils.ts

@@ -8,6 +8,13 @@ export interface RunnerSubagentStep {
 	agent: string;
 	task: string;
 	runner?: ResolvedRunnerConfig;
+	externalJobFollowUp?: {
+		sourceRunId: string;
+		sourceStepIndex: number;
+		parentProviderJobId: string;
+		requestId: string;
+		requestDigest: string;
+	};
 	/** Resolved launch context for this child. */
 	context?: "fresh" | "fork";
 	importAsyncRoot?: {
@@ -22,8 +29,13 @@ export interface RunnerSubagentStep {
 	structured?: boolean;
 	cwd?: string;
 	model?: string;
+	fast?: boolean;
 	thinking?: string;
+	thinkingCeiling?: import("../../shared/model-info.ts").ThinkingLevel;
 	modelCandidates?: string[];
+	/** The primary model is inherited from the parent session and should not be verified against the child-reported active registry model. */
+	skipPrimaryModelVerification?: boolean;
+	modelVerificationRegistry?: Array<{ provider: string; id: string; fullId: string }>;
 	tools?: string[];
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
@@ -48,12 +60,14 @@ export interface RunnerSubagentStep {
 		schema: import("../../shared/types.ts").JsonSchemaObject;
 		schemaPath: string;
 		outputPath: string;
+		acceptanceReportPath?: string;
 	};
 	structuredOutputSchema?: import("../../shared/types.ts").JsonSchemaObject;
 	agentContract?: import("../../shared/types.ts").AgentContract;
 	definitionDigest?: string;
 	launchBindingTask?: string;
 	launchContractDigest?: string;
+	extensionBindings?: import("./extension-bindings.ts").ExtensionBindings;
 	launchResolvedExtensions?: import("../../shared/types.ts").LaunchResolvedChildExtensionsV1;
 	runtimeAcknowledgedExtensions?: import("../../shared/types.ts").RuntimeAcknowledgedChildExtensionsV1;
 	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;
@@ -65,13 +79,8 @@ export interface RunnerSubagentStep {
 	capabilityAudit?: import("./capability-ceiling.ts").SubagentCapabilityAudit;
 	/** Private stable logical-child path for inherited run fan-out accounting. */
 	runFanoutPath?: string;
-}
-
-export interface RunnerCheckpointStep {
-	checkpoint: string;
-	message?: string;
-	phase?: string;
-	label?: string;
+	/** Run this single child in one managed worktree. */
+	worktree?: boolean;
 }
 
 export interface ParallelStepGroup {
@@ -98,13 +107,10 @@ export interface DynamicRunnerGroup {
 	gateOn?: import("../../shared/types.ts").ChainGateLayer;
 	capabilityCeiling?: import("./capability-ceiling.ts").ResolvedSubagentCapabilityCeiling;
 	capabilityAudit?: import("./capability-ceiling.ts").SubagentCapabilityAudit;
+	thinkingCeiling?: import("../../shared/model-info.ts").ThinkingLevel;
 }
 
-export type RunnerStep = RunnerSubagentStep | ParallelStepGroup | DynamicRunnerGroup | RunnerCheckpointStep;
-
-export function isCheckpointRunnerStep(step: RunnerStep): step is RunnerCheckpointStep {
-	return "checkpoint" in step;
-}
+export type RunnerStep = RunnerSubagentStep | ParallelStepGroup | DynamicRunnerGroup;
 
 export function isParallelGroup(step: RunnerStep): step is ParallelStepGroup {
 	return "parallel" in step && Array.isArray(step.parallel);
@@ -117,9 +123,7 @@ export function isDynamicRunnerGroup(step: RunnerStep): step is DynamicRunnerGro
 export function flattenSteps(steps: RunnerStep[]): RunnerSubagentStep[] {
 	const flat: RunnerSubagentStep[] = [];
 	for (const step of steps) {
-		if (isCheckpointRunnerStep(step)) {
-			continue;
-		} else if (isParallelGroup(step)) {
+		if (isParallelGroup(step)) {
 			for (const task of step.parallel) flat.push(task);
 		} else if (isDynamicRunnerGroup(step)) {
 			continue;

package/dist/extensions/pi-subagents/src/runs/shared/permissions.ts

@@ -14,6 +14,10 @@ const MAX_PREVIEW_BYTES = 2048;
 const SECRET_KEY = /(?:authorization|cookie|credential|password|secret|token|api[-_]?key)/i;
 const SECRET_VALUE = /\b(?:Bearer\s+\S+|(?:sk|ghp|github_pat|xox[baprs])[-_A-Za-z0-9]{8,})\b/gi;
 
+export function redactSecretValues(value: string): string {
+	return value.replace(SECRET_VALUE, "[redacted]");
+}
+
 export function validatePermissionRules(value: unknown, label: string): PermissionRules | undefined {
 	if (value === undefined) return undefined;
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object mapping tool names to allow, ask, or deny.`);
@@ -66,7 +70,7 @@ function redact(value: unknown, key = "", depth = 0): unknown {
 	if (Array.isArray(value)) return value.slice(0, 10).map((item) => redact(item, "", depth + 1));
 	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value as Record<string, unknown>).slice(0, 20).map(([entryKey, entryValue]) => [entryKey, redact(entryValue, entryKey, depth + 1)]));
 	if (typeof value === "string") {
-		const redacted = value.replace(SECRET_VALUE, "[redacted]");
+		const redacted = redactSecretValues(value);
 		return redacted.length > 500 ? `${redacted.slice(0, 500)}…` : redacted;
 	}
 	return value;