pi-subagents 0.65.1 → 0.67.0

package/src/runs/shared/run-fanout-budget.ts

@@ -11,14 +11,14 @@ import {
 
 const RUN_FANOUT_ROOT = path.join(TEMP_ROOT_DIR, "run-fanout-budgets");
 
-interface ManifestV1 {
+interface FanoutBudgetManifest {
 	version: 1;
 	rootRunId: string;
 	limit: number;
 	createdAt: number;
 }
 
-interface ClaimV1 {
+interface FanoutBudgetClaim {
 	version: 1;
 	claimId: string;
 	path: string;
@@ -41,16 +41,16 @@ function safeRootRunId(rootRunId: string): string {
 	return rootRunId.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 120) || randomUUID();
 }
 
-function parseManifest(value: unknown): ManifestV1 | undefined {
+function parseManifest(value: unknown): FanoutBudgetManifest | undefined {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const manifest = value as Partial<ManifestV1>;
+	const manifest = value as Partial<FanoutBudgetManifest>;
 	if (manifest.version !== 1 || typeof manifest.rootRunId !== "string" || !manifest.rootRunId
 		|| !Number.isInteger(manifest.limit) || (manifest.limit ?? 0) <= 0
 		|| typeof manifest.createdAt !== "number" || !Number.isFinite(manifest.createdAt)) return undefined;
-	return manifest as ManifestV1;
+	return manifest as FanoutBudgetManifest;
 }
 
-function readManifest(directory: string): ManifestV1 {
+function readManifest(directory: string): FanoutBudgetManifest {
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(fs.readFileSync(path.join(directory, "manifest.json"), "utf-8"));
@@ -84,7 +84,7 @@ export function createRunFanoutBudget(rootRunId: string, limit: number): RunFano
 	do directory = path.join(RUN_FANOUT_ROOT, `${safeRootRunId(rootRunId)}-${randomUUID()}`);
 	while (fs.existsSync(directory));
 	fs.mkdirSync(path.join(directory, "claims"), { recursive: true, mode: 0o700 });
-	const manifest: ManifestV1 = { version: 1, rootRunId, limit, createdAt: Date.now() };
+	const manifest: FanoutBudgetManifest = { version: 1, rootRunId, limit, createdAt: Date.now() };
 	fs.writeFileSync(path.join(directory, "manifest.json"), `${JSON.stringify(manifest)}\n`, { mode: 0o600, flag: "wx" });
 	return { version: 1, rootRunId, directory, limit };
 }
@@ -230,7 +230,7 @@ function commitRunFanoutBatch<T>(descriptor: RunFanoutBudgetDescriptor, paths: s
 						const fd = fs.openSync(slotPath, "wx", 0o600);
 						created.push(slotPath);
 						try {
-							const claim: ClaimV1 = { version: 1, claimId: randomUUID(), path: claimPath, claimedAt: Date.now() };
+							const claim: FanoutBudgetClaim = { version: 1, claimId: randomUUID(), path: claimPath, claimedAt: Date.now() };
 							fs.writeFileSync(fd, `${JSON.stringify(claim)}\n`, "utf-8");
 						} finally { fs.closeSync(fd); }
 						break;

package/src/runs/shared/runtime-acknowledged-extensions.ts

@@ -1,4 +1,4 @@
-import type { RuntimeAcknowledgedChildExtensionsV1 } from "../../shared/types.ts";
+import type { RuntimeAcknowledgedChildExtensions } from "../../shared/types.ts";
 
 export const RUNTIME_EXTENSION_ACK_EVENT = "subagent:acknowledge-extension";
 export const MAX_RUNTIME_ACKNOWLEDGED_EXTENSION_IDS = 32;
@@ -14,7 +14,7 @@ export function isRuntimeAcknowledgedExtensionId(value: unknown): value is strin
 		&& !value.includes("\\");
 }
 
-export function projectRuntimeAcknowledgedExtensions(ids: Iterable<unknown>): RuntimeAcknowledgedChildExtensionsV1 | undefined {
+export function projectRuntimeAcknowledgedExtensions(ids: Iterable<unknown>): RuntimeAcknowledgedChildExtensions | undefined {
 	const unique: string[] = [];
 	const seen = new Set<string>();
 	for (const id of ids) {
@@ -31,7 +31,7 @@ export function projectRuntimeAcknowledgedExtensions(ids: Iterable<unknown>): Ru
 	};
 }
 
-export function sanitizeRuntimeAcknowledgedExtensions(value: unknown): RuntimeAcknowledgedChildExtensionsV1 | undefined {
+export function sanitizeRuntimeAcknowledgedExtensions(value: unknown): RuntimeAcknowledgedChildExtensions | undefined {
 	if (!value || typeof value !== "object") return undefined;
 	const raw = value as Record<string, unknown>;
 	if (raw.version !== 1 || raw.source !== "child-runtime" || !Array.isArray(raw.ids)) return undefined;

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -441,15 +441,21 @@ function registerStructuredOutputTool(pi: ExtensionAPI, structured: NonNullable<
 }
 
 /** Register every child-side hook the prompt runtime owns for one child session. */
-export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config: ChildRuntimeConfig): void {
+export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?: ChildRuntimeConfig, drainObservation?: import("./readonly-drain-observation.ts").ReadonlyDrainObservation): void {
+	// A path-based load has no ChildRuntimeConfig. This can happen if an
+	// ambient-extension discovery path finds the runtime module in addition to
+	// the configured inline factory. It must be inert rather than crashing the
+	// child before startup; the inline factory remains the real registration path.
+	if (!config) return;
 	registerRuntimeExtensionAcknowledgements(pi, config.runtimeAcknowledgements);
 	registerPermissionGate(pi, config.permissions, config.childWatchdog);
 	registerToolBudget(pi, config.toolBudget);
 	registerChildWatchdog(pi, config.childWatchdog, config.watchdogStatus);
-	const waitState = {
+	const waitState = config.runtimeState ?? {
 		baseCwd: "",
 		currentSessionId: null,
 		asyncJobs: new Map(),
+		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
 		lastForegroundControlId: null,
 		cleanupTimers: new Map(),
@@ -481,8 +487,18 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config:
 		if (diagnostic) throw new Error(formatChildToolDiagnostic(diagnostic));
 	});
 	onRuntimeEvent("agent_end", async (_event: unknown, ctx: unknown) => {
-		if ((ctx as { hasUI?: boolean } | undefined)?.hasUI === true) return;
-		await drainOutstandingWork({ state: waitState, events: pi.events });
+		if ((ctx as { hasUI?: boolean } | undefined)?.hasUI === true) drainObservation?.deny();
+		if (drainObservation) {
+			try {
+				if ((ctx as ExtensionContext)?.sessionManager?.getSessionFile() !== waitState.currentSessionId) drainObservation.deny();
+			} catch { drainObservation.deny(); }
+		}
+		config.holdFinalDrain?.(true);
+		try {
+			await drainOutstandingWork({ state: waitState, events: pi.events }, drainObservation);
+		} finally {
+			config.holdFinalDrain?.(false);
+		}
 	});
 	if (config.structuredOutput) registerStructuredOutputTool(pi, config.structuredOutput);
 

package/src/runs/shared/task-intent.ts

@@ -7,6 +7,7 @@
  * - `classifyTaskMutationIntent` / `expectsImplementationMutation`: does the
  *   task REQUIRE file changes? Consumed by the completion mutation guard,
  *   which blocks completion, so its vocabulary is deliberately narrow.
+ *   Verbs inside filenames and path-like tokens do not count.
  * - `taskMayMutate`: COULD the task plausibly change files? Consumed by
  *   acceptance level inference, which only raises evidence gates, so its
  *   vocabulary is deliberately broad (any bare write verb).
@@ -18,16 +19,20 @@
  */
 
 const REVIEW_ONLY_PATTERNS = [
-	/\breview only\b/i,
+	/\b(?:review|read)[- ]only\b/i,
+	/\bno\s+(?:source\s+)?edits?\b/i,
+	/\bwithout\s+edits?\b/i,
 	/\bsuggest fixes only\b/i,
 	/\bonly return findings\b/i,
 	/\breturn findings only\b/i,
 ];
 
+const NO_EDIT_BOUNDARY_ASSERTION_PATTERN = /\bno\s+(?:source\s+)?edits?\s*,\s*(?:commits?|pushes?|merges?|installs?|changes?|writes?)\b/i;
+
 const REVIEWER_REQUIRED_EDIT_PATTERNS = [
 	/\bmust\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
 	/\brequired\s+to\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
-	/(?:^|[.!?\n]\s*)implement\s+(?:the\s+)?(?:approved|requested|specified|file|code|source|fix(?:es)?|changes?)\b/i,
+	/(?:^|[.!?:;,\n]\s*)implement\s+(?:the\s+)?(?:approved|requested|specified|file|code|source|fix(?:es)?|changes?)\b/i,
 	/\bregardless\s+of\s+findings\b/i,
 	/\balways\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
 	/\bapply\s+(?:the\s+)?fix(?:es)?\s+directly\b/i,
@@ -40,7 +45,7 @@ const REVIEWER_REQUIRED_EDIT_PATTERNS = [
 // being swallowed as the object.
 // Accept serialized line separators too: workflow prompts can carry literal
 // `\\n`/`\\r\\n` between clauses instead of decoded newlines.
-const NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b((?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
+const NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change|implement)\b((?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
 const COORDINATED_NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+((?=(?:(?!\\(?:r\\n|n))[^.;:!?\n–—-])*\b(?:and|or)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b)(?:(?!\\(?:r\\n|n))[^.;:!?\n–—-])*?\b(?:and|or)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b(?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
 
 /** Objects of a no-edit prohibition that mean "the codebase in general" rather than a named scope. */
@@ -85,13 +90,25 @@ const RESEARCH_AGENT_PATTERNS = [
 // CLI flags like "--fix" and genuine clause-level dashes like "branch—fix it"),
 // strip the known severity compounds (must|should|needs + dash + verb) from the
 // task text before matching. Dash coverage: ASCII hyphen + U+2010..U+2015.
-const SEVERITY_COMPOUND_PATTERN = /\b(?:must|should|needs)[\-\u2010-\u2015](?:fix|edit|update|add|remove|replace|create|apply|make|do|implement|modify|delete|patch)\b/gi;
+const SEVERITY_COMPOUND_PATTERN = /\b(?:must|should|needs)[-\u2010-\u2015](?:fix|edit|update|add|remove|replace|create|apply|make|do|implement|modify|delete|patch)\b/gi;
 
 function stripSeverityCompounds(task: string): string {
 	return task.replace(SEVERITY_COMPOUND_PATTERN, " ");
 }
 export { stripSeverityCompounds };
 
+// Quoted categories in a finding-classification request describe fixes, not
+// instructions to perform them. Strip only that request, leaving sibling
+// imperatives (including another "must fix") subject to the normal guards.
+const FINDING_CLASSIFICATION_PATTERN = /\b(?:classify|categorize|weigh)\s+(?:(?:the|remaining)\s+)*(?:findings?|items?|issues?)\s+as\s+["“]must\s+fix\s+before\s+[^"”\n]+["”]\s+(?:vs\.?|versus)\s+["“]must\s+fix\s+before\s+[^"”\n]+["”]/gi;
+
+const PATH_LIKE_TOKEN_PATTERN = /[^\s]+[/\\][^\s]+|[^\s/\\]+\.[A-Za-z][A-Za-z0-9]{0,9}\b/g;
+const PATH_INTERNAL_IMPLEMENTATION_VERB = /\b(?:implement|edit|modify|refactor|delete|update|add|remove|replace|create)\b/i;
+
+function stripPathLikeTokens(task: string): string {
+	return task.replace(PATH_LIKE_TOKEN_PATTERN, (token) => (PATH_INTERNAL_IMPLEMENTATION_VERB.test(token) ? " " : token));
+}
+
 const FIX_OR_PATCH_IMPLEMENTATION_PATTERN = /\b(?:fix|patch)\s+(?:(?:it|this|that|them|each|any|all|these|those)\b|(?:(?:a|an|the|any|all)\s+)?(?:(?:failing|failed|broken|flaky|red|cold|start|current|existing|reported|approved|known|regression|unit|integration|e2e|source|typescript|type-?script|ts|type-?check|compiler)\s+)*(?:bug|defect|issues?|problems?|failures?|regressions?|tests?|errors?|items?|typos?|code|source|implementation|component|function|module|class|method|logic|file|files|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command|lint(?:ing)?|build|ci|type-?check|type\s+checking)\b)/i;
 
 const WORKER_IMPLEMENTATION_PATTERNS = [
@@ -103,12 +120,18 @@ const WORKER_IMPLEMENTATION_PATTERNS = [
 	/\bdo those fixes\b/i,
 ];
 
-const GENERAL_IMPLEMENTATION_PATTERNS = [
+const FOLLOW_ON_IMPLEMENTATION_PATTERN = /(?:^|[.!?:;,\n])\s*(?:fix|patch|update|add|remove|replace|create|delete)\s+(?:(?:the|a|an|this|that|these|those|requested|specified|current|existing|approved|your|our)\s+)(?!(?:report|summary|findings?|analysis|recommendations?|answer|response|proposal|plan|issue|bug report)\b)[a-z][\w./-]*/i;
+const ADVISORY_INFINITIVE_PATTERN = /\b(?:explain|recommend|describe)\s+how\s+to\s+(?:fix|patch|update|add|remove|replace|create|delete|implement|edit|modify|refactor)\b/i;
+const EXPLICIT_IMPLEMENTATION_PATTERNS = [
 	/\b(?:implement|edit|modify|refactor)\b/i,
-	FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
 	/\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
 	/\bmake\s+(?:the\s+)?changes\b/i,
 	/\bdo those fixes\b/i,
+];
+
+const GENERAL_IMPLEMENTATION_PATTERNS = [
+	...EXPLICIT_IMPLEMENTATION_PATTERNS,
+	FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
 	/\b(?:update|add|remove|replace|delete|create)\s+(?:the\s+)?(?:file|files|code|source|implementation|test|tests|component|function|module|class|method|logic|import|imports|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command)\b/i,
 ];
 
@@ -141,10 +164,13 @@ interface NoEditProhibitionAnalysis {
 }
 
 function analyzeNoEditProhibitions(taskText: string): NoEditProhibitionAnalysis {
+	const readOnlyBoundary = NO_EDIT_BOUNDARY_ASSERTION_PATTERN.test(taskText);
 	let present = REVIEW_ONLY_PATTERNS.some((pattern) => pattern.test(taskText))
-		|| NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText));
-	let blanket = present;
-	let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS]);
+		|| NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText))
+		|| readOnlyBoundary;
+	let blanket = false;
+	let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS, ADVISORY_INFINITIVE_PATTERN]);
+	if (readOnlyBoundary) strippedText = stripPatterns(strippedText, [NO_EDIT_BOUNDARY_ASSERTION_PATTERN]);
 	const stripNoEditProhibition = (match: string, object: string, offset: number, source: string): string => {
 		present = true;
 		if (GENERIC_PROHIBITION_OBJECT.test(object) && !hasScopedProhibitionContinuation(source.slice(offset + match.length))) blanket = true;
@@ -172,16 +198,23 @@ function hasImplementationIntent(agent: string, taskText: string): boolean {
 }
 
 export function classifyTaskMutationIntent(agent: string, task: string): TaskMutationIntent {
-	const taskText = stripSeverityCompounds(stripFrameworkInstructions(task));
+	const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), [FINDING_CLASSIFICATION_PATTERN]);
 	const taskTextWithoutScopedConstraints = stripPatterns(taskText, SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
 	const prohibitions = analyzeNoEditProhibitions(taskTextWithoutScopedConstraints);
 	if (prohibitions.present) {
 		if (prohibitions.blanket) return { kind: "read-only" };
-		return hasImplementationIntent(agent, prohibitions.strippedText) ? { kind: "implementation" } : { kind: "read-only" };
+		const remaining = stripPathLikeTokens(prohibitions.strippedText);
+		if (isReviewerStyleAgent(agent)) {
+			return hasImplementationIntent(agent, remaining) ? { kind: "implementation" } : { kind: "read-only" };
+		}
+		return EXPLICIT_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(remaining))
+			|| FOLLOW_ON_IMPLEMENTATION_PATTERN.test(remaining)
+			? { kind: "implementation" }
+			: { kind: "read-only" };
 	}
 
 	if (RESEARCH_AGENT_PATTERNS.some((pattern) => pattern.test(agent))) return { kind: "read-only" };
-	if (hasImplementationIntent(agent, taskText)) return { kind: "implementation" };
+	if (hasImplementationIntent(agent, stripPathLikeTokens(taskText))) return { kind: "implementation" };
 	if (isReviewerStyleAgent(agent)) return { kind: "read-only" };
 	return taskHasReadOnlyDeliverable(taskTextWithoutScopedConstraints) ? { kind: "read-only" } : { kind: "unknown" };
 }
@@ -204,7 +237,7 @@ const MAY_MUTATE_VERB_PATTERN = /\b(?:fix|implement|update|write|edit|modify|mig
  * does.
  */
 export function taskMayMutate(task: string): boolean {
-	const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
+	const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), [FINDING_CLASSIFICATION_PATTERN, ...SCOPED_NO_EDIT_CONSTRAINT_PATTERNS]);
 	const prohibitions = analyzeNoEditProhibitions(taskText);
 	if (prohibitions.blanket) return false;
 	return MAY_MUTATE_VERB_PATTERN.test(stripPatterns(prohibitions.strippedText, READ_ONLY_DELIVERABLE_PATTERNS));

package/src/runs/shared/workflow-async-child-guidance.ts

@@ -0,0 +1,18 @@
+import type { AsyncStatus, SubagentState } from "../../shared/types.ts";
+
+/** Projection-only guidance, not a control route or proof of current child liveness. */
+export function workflowAsyncChildSteeringGuidance(status: AsyncStatus, state?: SubagentState): string[] {
+	if (status.mode !== "workflow" || (status.state !== "running" && status.state !== "queued")
+		|| !state?.currentSessionId || status.sessionId !== state.currentSessionId
+		|| !state.workflowControllers?.has(status.runId)) return [];
+	const ids = new Set((status.steps ?? []).flatMap((step) =>
+		step.async === true && step.status === "running"
+		&& step.runner?.type !== "external-cli" && step.runner?.type !== "external-job"
+		&& typeof step.runId === "string" && /^[A-Za-z0-9_-]+$/.test(step.runId) && step.runId !== status.runId
+			? [step.runId] : []));
+	if (ids.size === 0) return [];
+	return [
+		"Async children recorded as running; direct steering rechecks controls. Choose an exact child ID (queued does not mean consumed):",
+		...[...ids].map((id) => `  subagent({ action: "steer", id: "${id}", mode: "follow_up", message: "..." })`),
+	];
+}

package/src/runs/shared/worktree-setup-command.ts

@@ -0,0 +1,190 @@
+import { spawn } from "node:child_process";
+import { createOwnedProcessTreeController } from "../background/owned-process-tree.ts";
+import type { ProcessTreeTerminal } from "../../shared/types.ts";
+
+export interface SetupCommandOptions {
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	input?: string;
+	/** Worktrunk uses 128 KiB; Git and hooks use spawnSync's 1 MiB default. */
+	maxBuffer?: number;
+	signal?: AbortSignal;
+	deadlineAt?: number;
+	/** Only the existing configured setup-hook timeout, not a new Git budget. */
+	hookTimeoutMs?: number;
+	/** Read-only probes may define negative answers as completed commands. */
+	acceptedExitCodes?: readonly number[];
+	onSpawn?: (process: { pid: number; processGroupId?: number }) => void;
+}
+
+export interface SetupCommandResult {
+	stdout: string;
+	stderr: string;
+	status: number | null;
+	signal: NodeJS.Signals | null;
+	error?: Error;
+	pid?: number;
+	processGroupId?: number;
+	/** Absent on normal completion: trusted command completion is NOT tree proof. */
+	processTree?: ProcessTreeTerminal;
+	outputIncomplete: boolean;
+}
+
+function commandError(message: string, code: string): NodeJS.ErrnoException {
+	return Object.assign(new Error(message), { code });
+}
+
+/**
+ * Setup I/O only. Commands must await their descendants before reporting success.
+ * Exit 0 + natural close + complete output still requires caller JSON/path validation.
+ * Invalid output is NOT accepted completion: retain unknown ownership, never signal
+ * this completed command's PID later. Callers own compensation and admission.
+ */
+export async function runSetupCommand(
+	command: string,
+	args: string[],
+	options: SetupCommandOptions,
+): Promise<SetupCommandResult> {
+	const result: SetupCommandResult = {
+		stdout: "", stderr: "", status: null, signal: null, outputIncomplete: false,
+	};
+	const maxBuffer = options.maxBuffer ?? 1024 * 1024;
+	if (!Number.isSafeInteger(maxBuffer) || maxBuffer <= 0) throw new Error("Invalid setup command maxBuffer");
+	if (options.deadlineAt !== undefined && !Number.isFinite(options.deadlineAt)) throw new Error("Invalid setup deadline");
+	if (options.hookTimeoutMs !== undefined && (!Number.isSafeInteger(options.hookTimeoutMs) || options.hookTimeoutMs <= 0)) {
+		throw new Error("Invalid setup hook timeout");
+	}
+	const cancellation = (): Error | undefined => {
+		if (options.signal?.aborted) return commandError("Worktree setup aborted", "ABORT_ERR");
+		if (options.deadlineAt !== undefined && Date.now() >= options.deadlineAt) {
+			return commandError("Worktree setup deadline exceeded", "ETIMEDOUT");
+		}
+		return undefined;
+	};
+	result.error = cancellation();
+	if (result.error) return result;
+
+	let child;
+	try {
+		child = spawn(command, args, {
+			cwd: options.cwd,
+			env: options.env ? { ...process.env, ...options.env } : process.env,
+			stdio: "pipe", shell: false, windowsHide: true,
+			// Isolated owned POSIX group, never unref'd or fire-and-forget.
+			detached: process.platform !== "win32",
+		});
+	} catch (error) {
+		result.error = error instanceof Error ? error : new Error(String(error));
+		return result;
+	}
+	result.pid = child.pid;
+	if (child.pid !== undefined && process.platform !== "win32") result.processGroupId = child.pid;
+	const tree = child.pid === undefined ? undefined : createOwnedProcessTreeController(child.pid);
+	let termination: Promise<ProcessTreeTerminal> | undefined;
+	let directSettled = false;
+	const releaseUnknownIO = () => {
+		if (!directSettled || result.processTree?.state !== "unknown") return;
+		result.error ??= commandError("Worktree setup process tree settlement is unverified", "PROCESS_TREE_UNVERIFIED");
+		result.outputIncomplete = true;
+		// Only local I/O is released; unknown descendant ownership remains retained.
+		child.stdin.destroy();
+		child.stdout.destroy();
+		child.stderr.destroy();
+	};
+	const terminate = () => {
+		if (termination || !tree) return;
+		if (directSettled) {
+			result.processTree = {
+				state: "unknown", reason: "verification-failed",
+				diagnostic: "Command exited before termination began; no longer safe to signal its recorded PID.",
+			};
+			releaseUnknownIO();
+			return;
+		}
+		termination = tree.terminate().then((proof) => {
+			result.processTree = proof;
+			releaseUnknownIO();
+			return proof;
+		});
+	};
+	const fail = (error: Error) => {
+		result.error ??= error;
+		terminate();
+	};
+	const onAbort = () => fail(commandError("Worktree setup aborted", "ABORT_ERR"));
+	const stdout: Buffer[] = [];
+	const stderr: Buffer[] = [];
+	let capturedBytes = 0;
+	const capture = (chunks: Buffer[], chunk: Buffer) => {
+		const remaining = maxBuffer - capturedBytes;
+		if (remaining > 0) {
+			const saved = Buffer.from(chunk.subarray(0, remaining));
+			chunks.push(saved);
+			capturedBytes += saved.length;
+		}
+		if (chunk.length > remaining) {
+			result.outputIncomplete = true;
+			fail(commandError("Worktree setup command output exceeds maxBuffer", "ENOBUFS"));
+		}
+	};
+	const onStdout = (chunk: Buffer) => capture(stdout, chunk);
+	const onStderr = (chunk: Buffer) => capture(stderr, chunk);
+	child.stdout.on("data", onStdout);
+	child.stderr.on("data", onStderr);
+	child.stdin.on("error", fail);
+	const close = new Promise<void>((resolve) => child.once("close", () => resolve()));
+	const directExit = new Promise<void>((resolve) => {
+		child.once("exit", (status, signal) => {
+			directSettled = true;
+			result.status = status;
+			result.signal = signal;
+			if (status === null || !(options.acceptedExitCodes ?? [0]).includes(status)) terminate();
+			releaseUnknownIO();
+			resolve();
+		});
+		child.once("error", (error) => {
+			fail(error);
+			// A failed spawn has no direct process to await. Other errors do not prove exit.
+			if (child.pid === undefined) {
+				directSettled = true;
+				resolve();
+			}
+		});
+	});
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const deadlineAt = Math.min(options.deadlineAt ?? Infinity,
+		options.hookTimeoutMs === undefined ? Infinity : Date.now() + options.hookTimeoutMs);
+	const armDeadline = () => {
+		if (deadlineAt === Infinity) return;
+		const remaining = deadlineAt - Date.now();
+		if (remaining <= 0) fail(commandError("Worktree setup command timed out", "ETIMEDOUT"));
+		else timer = setTimeout(armDeadline, Math.min(remaining, 2 ** 31 - 1));
+	};
+	options.signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		armDeadline();
+		if (options.signal?.aborted) onAbort();
+		if (child.pid !== undefined) {
+			try { options.onSpawn?.({ pid: child.pid, processGroupId: result.processGroupId }); }
+			catch (error) { fail(error instanceof Error ? error : new Error(String(error))); }
+		}
+		child.stdin.end(options.input);
+		await directExit;
+		if (termination) result.processTree = await termination;
+		releaseUnknownIO();
+		await close;
+		// Abort/overflow may arrive while draining stdio after direct exit.
+		if (termination) result.processTree = await termination;
+		const cancelled = cancellation();
+		if (cancelled) fail(cancelled);
+		result.stdout = Buffer.concat(stdout).toString("utf8");
+		result.stderr = Buffer.concat(stderr).toString("utf8");
+		return result;
+	} finally {
+		if (timer) clearTimeout(timer);
+		options.signal?.removeEventListener("abort", onAbort);
+		child.stdout.removeListener("data", onStdout);
+		child.stderr.removeListener("data", onStderr);
+		child.stdin.removeListener("error", fail);
+	}
+}