pi-herdr-agents 2.0.4 → 3.0.0

package/{pi-extension/subagents → maestro/adapters/pi}/launch.ts

@@ -1,20 +1,34 @@
-import { execFileSync } from "node:child_process";
-import {
-	existsSync,
-	mkdirSync,
-	readFileSync,
-	renameSync,
-	writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { getSubagentActivityFile } from "./activity.ts";
-import { createLifecycle, type SubagentLifecycle } from "./lifecycle.ts";
-import type { ResolvedRuntimePlan } from "./runtime-routing.ts";
-import { createSubagentPaneFactory, loadPaneConfig } from "./pane-config.ts";
-import { HerdrWorktreeCreateError } from "./herdr.ts";
-import { isNonEmptyString, isRecord, type JsonObject } from "./type-guards.ts";
+import { getSubagentActivityFile } from "./activity-file.ts";
+import {
+	createLifecycle,
+	type SubagentLifecycle,
+} from "../../core/lifecycle.ts";
+import type { ResolvedRuntimePlan } from "../../core/routing.ts";
+import type { PaneConfig } from "../../core/config/pane-config.ts";
+import { isNonEmptyString } from "../../core/config/type-guards.ts";
+import { shellQuote } from "../../core/shell.ts";
+import type {
+	SurfaceProvider,
+	WorktreeSurface,
+} from "../../core/surface-provider.ts";
+import { WorktreeProvisioningError } from "../../core/surface-provider.ts";
+import type {
+	FailedWorktreeManifest,
+	WorktreeLaunch,
+	WorktreeOperations,
+} from "../../core/worktree.ts";
+import {
+	getSubagentProcessIdentityFile,
+	linuxProcessProbe,
+	readProcessIdentityRecord,
+	verifyProcessIdentityRecord,
+	type PiProcessIdentity,
+	type ProcessIdentityProbe,
+} from "./process-identity.ts";
 import {
 	createWorktreeSessionFork,
 	getNewEntries,
@@ -22,61 +36,11 @@ import {
 	seedSubagentSessionFile,
 	writeSubagentSessionPolicy,
 } from "./session.ts";
-import {
-	closePane,
-	createSubagentPane,
-	createGroupedSubagentPane,
-	createSubagentWorktree,
-	splitCurrentPane,
-	runScriptInPane,
-	shellQuote,
-	waitForPiReady,
-	waitForShellReady,
-	focusWorkspace,
-	type HerdrWorktreeSurface,
-} from "./terminal.ts";
 
 const SUBAGENTS_DIR = dirname(fileURLToPath(import.meta.url));
 
 type SubagentSessionMode = "standalone" | "lineage-only" | "fork";
 
-export interface WorktreeLaunch {
-	path: string;
-	workspaceId: string;
-	paneId: string;
-	branch: string;
-	baseRef: string;
-	baseSha: string;
-	manifestFile: string;
-	sessionFile?: string;
-	sourceSessionFile?: string;
-	handoffMessage?: string;
-}
-
-interface FailedWorktreeManifest extends JsonObject {
-	state: "failed";
-	id: string;
-	name: string;
-	sourceCwd: string;
-	branch: string;
-	baseRef: string;
-	baseSha: string;
-	createdAt: number;
-	path?: string;
-	workspaceId?: string;
-	error?: string;
-}
-
-export interface WorktreeHandoff extends WorktreeLaunch {
-	headSha: string | null;
-	commitsAhead: number | null;
-	clean: boolean | null;
-	conflicted: boolean | null;
-	changedFiles: string[] | null;
-	untrackedFiles: string[] | null;
-	gitError?: string;
-}
-
 export interface FreshPiLaunchRequest {
 	kind: "fresh";
 	id?: string;
@@ -84,7 +48,7 @@ export interface FreshPiLaunchRequest {
 	task: string;
 	agent?: string;
 	cwd?: string;
-	worktree?: { branch: string; base?: string };
+	worktree?: { branch: string; base?: string } | null;
 	fork?: boolean;
 	handoff?: { leafId: string };
 	surface?: string;
@@ -159,47 +123,265 @@ export interface PiRunningChild {
 	stopState?: "requested" | "pending" | "failed";
 	stopFailure?: string;
 	crashNotified?: boolean;
+	/** Managed worktree children: where the child records its own process identity. */
+	processIdentityFile?: string;
+	/** Verified at launch readiness; a worktree cancel's only signal and exit evidence. */
+	processIdentity?: PiProcessIdentity;
+	/** Settles when launch-readiness capture verifies or gives up; never rejects. */
+	processIdentityCapture?: Promise<PiProcessIdentity | undefined>;
+	processIdentityError?: string;
+}
+
+/** What a captured identity must match: this run, its session, and its pane. */
+export interface ProcessIdentityExpectation {
+	file: string;
+	id: string;
+	sessionFile: string;
+}
+
+type MaybePromise<T> = T | Promise<T>;
+
+interface WorktreeSurfaceForLaunch {
+	path: string;
+	branch: string;
+	workspaceId: string;
+	paneId: string;
 }
 
 export interface PiLaunchOperations {
-	createPane(name: string, cwd?: string): string;
+	/** Required for managed worktree launches; ordinary panes need no Git effects. */
+	worktree?: WorktreeOperations;
+	createPane(name: string, cwd?: string): MaybePromise<string>;
 	createWorktree(
 		name: string,
 		cwd: string,
 		branch: string,
 		base: string,
-	): HerdrWorktreeSurface;
+	): MaybePromise<WorktreeSurfaceForLaunch>;
 	waitForShellReady(surface: string): Promise<void>;
 	runScript(
 		surface: string,
 		command: string,
 		options: { scriptPath: string; scriptPreamble: string },
-	): string;
-	closePane(pane: string): void;
+	): MaybePromise<string>;
+	closePane(pane: string): MaybePromise<void>;
 	waitForPiReady?(
 		surface: string,
 		sessionFile: string,
 		cwd: string,
 	): Promise<void>;
-	focusWorkspace?(workspaceId: string): void;
+	focusWorkspace?(workspaceId: string): MaybePromise<void>;
+	/** Bounded readiness capture of a worktree child's verified process identity. */
+	captureProcessIdentity?(
+		surface: string,
+		expected: ProcessIdentityExpectation,
+		options?: { timeoutMs?: number },
+	): Promise<PiProcessIdentity>;
+}
+
+function placementFromPaneConfig(config: PaneConfig) {
+	if (config.mode === "split") {
+		return { kind: "split" as const, direction: config.direction };
+	}
+	if (config.mode === "tab") return { kind: "tab" as const };
+	return { kind: "grouped" as const };
+}
+
+function worktreeSurfaceForLaunch(
+	worktree: WorktreeSurface,
+): WorktreeSurfaceForLaunch {
+	return {
+		path: worktree.path,
+		branch: worktree.branch,
+		workspaceId: worktree.workspaceId,
+		paneId: worktree.surfaceId,
+	};
+}
+
+export function isExpectedPiProcess(
+	process: {
+		name?: string;
+		argv0?: string;
+		argv?: string[];
+		cwd?: string;
+	},
+	sessionFile: string,
+	cwd: string,
+): boolean {
+	const sessionIndex = process.argv?.indexOf("--session") ?? -1;
+	return (
+		(process.name === "pi" || process.argv0?.split("/").pop() === "pi") &&
+		sessionIndex >= 0 &&
+		process.argv?.[sessionIndex + 1] === sessionFile &&
+		process.cwd === cwd
+	);
+}
+
+async function waitForSurfacePiReady(
+	provider: SurfaceProvider,
+	surface: string,
+	sessionFile: string,
+	cwd: string,
+	options: { timeoutMs?: number; intervalMs?: number } = {},
+): Promise<void> {
+	const timeoutMs = options.timeoutMs ?? 10_000;
+	const intervalMs = options.intervalMs ?? 50;
+	const deadline = Date.now() + timeoutMs;
+	let lastError = "expected Pi process not observed";
+
+	while (Date.now() <= deadline) {
+		try {
+			const info = await Promise.resolve(provider.getProcessInfo(surface));
+			if (
+				info.foregroundProcesses.some((process) =>
+					isExpectedPiProcess(process, sessionFile, cwd),
+				)
+			) {
+				return;
+			}
+		} catch (error) {
+			lastError = error instanceof Error ? error.message : String(error);
+		}
+		if (Date.now() >= deadline) break;
+		await new Promise((resolve) => setTimeout(resolve, intervalMs));
+	}
+	throw new Error(
+		`Timed out waiting for Pi session ${sessionFile} in Herdr pane ${surface}: ${lastError}`,
+	);
+}
+
+/**
+ * Wait for the child to publish its own identity, then accept it only while
+ * that process is alive in this host's namespace as the Herdr pane shell or a
+ * descendant of it. Command-line text is never consulted: Pi rewrites it.
+ */
+export async function captureSurfacePiProcessIdentity(
+	provider: Pick<SurfaceProvider, "getProcessInfo">,
+	surface: string,
+	expected: ProcessIdentityExpectation,
+	options: {
+		timeoutMs?: number;
+		intervalMs?: number;
+		probe?: ProcessIdentityProbe;
+	} = {},
+): Promise<PiProcessIdentity> {
+	const timeoutMs = options.timeoutMs ?? 15_000;
+	const intervalMs = options.intervalMs ?? 100;
+	const deadline = Date.now() + timeoutMs;
+	let lastError = "the child has not recorded its process identity";
+	let answered = false;
+	for (;;) {
+		try {
+			const record = readProcessIdentityRecord(expected.file);
+			if (record) {
+				// The deadline bounds Herdr too; a late answer is dropped, never accepted.
+				const info = await settleBefore(
+					Promise.resolve().then(() => provider.getProcessInfo(surface)),
+					deadline,
+					{ unref: true },
+				);
+				if (!info) {
+					// The deadline passed; an earlier answer's refusal says more.
+					if (!answered)
+						lastError = `Herdr process info for pane ${surface} timed out`;
+					break;
+				}
+				answered = true;
+				if (info.shellPid === undefined)
+					throw new Error(`Herdr reports no shell for pane ${surface}`);
+				return verifyProcessIdentityRecord(
+					record,
+					{ ...expected, shellPid: info.shellPid },
+					options.probe ?? linuxProcessProbe,
+				);
+			}
+		} catch (error) {
+			lastError = errorMessage(error);
+		}
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) break;
+		// Background capture must never hold the parent process open.
+		await new Promise((resolve) =>
+			setTimeout(resolve, Math.min(intervalMs, remaining)).unref(),
+		);
+	}
+	throw new Error(
+		`Process identity not captured within ${timeoutMs}ms: ${lastError}`,
+	);
 }
 
-const paneConfig = loadPaneConfig();
+/**
+ * The pending value if it settles before the deadline; otherwise undefined.
+ * A value that arrives after the deadline is dropped, never reported, even
+ * when a delayed event loop runs it before the overdue timer.
+ */
+export async function settleBefore<T>(
+	pending: Promise<T> | undefined,
+	deadline: number,
+	options: { unref?: boolean } = {},
+): Promise<T | undefined> {
+	if (!pending) return undefined;
+	let expire!: () => void;
+	const expired = new Promise<undefined>((resolve) => {
+		expire = () => resolve(undefined);
+	});
+	const timer = setTimeout(expire, Math.max(0, deadline - Date.now()));
+	if (options.unref) timer.unref();
+	try {
+		const onTime = pending.then((value) =>
+			Date.now() > deadline ? undefined : value,
+		);
+		return await Promise.race([onTime, expired]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
 
-const defaultOperations: PiLaunchOperations = {
-	createPane: createSubagentPaneFactory(
-		paneConfig,
-		createSubagentPane,
-		splitCurrentPane,
-		createGroupedSubagentPane,
-	),
-	createWorktree: createSubagentWorktree,
-	waitForShellReady,
-	runScript: runScriptInPane,
-	closePane,
-	waitForPiReady,
-	focusWorkspace,
-};
+export function launchOperationsFromSurface(
+	provider: SurfaceProvider,
+	config: PaneConfig,
+	worktree?: WorktreeOperations,
+): PiLaunchOperations {
+	return {
+		worktree,
+		createPane(name, cwd) {
+			return provider.createSurface({
+				name,
+				cwd: cwd ?? process.cwd(),
+				placement: placementFromPaneConfig(config),
+			});
+		},
+		async createWorktree(name, cwd, branch, base) {
+			const worktree = await Promise.resolve(
+				provider.createWorktreeSurface({ name, cwd, branch, base }),
+			);
+			return worktreeSurfaceForLaunch(worktree);
+		},
+		waitForShellReady(surface) {
+			return provider.waitForShellReady(surface);
+		},
+		runScript(surface, command, options) {
+			return provider.runScript(surface, command, options);
+		},
+		closePane(pane) {
+			return provider.closeSurface(pane);
+		},
+		waitForPiReady(surface, sessionFile, cwd) {
+			return waitForSurfacePiReady(provider, surface, sessionFile, cwd);
+		},
+		focusWorkspace(workspaceId) {
+			return provider.focusWorkspace(workspaceId);
+		},
+		captureProcessIdentity(surface, expected, options) {
+			return captureSurfacePiProcessIdentity(
+				provider,
+				surface,
+				expected,
+				options,
+			);
+		},
+	};
+}
 
 interface ResolvedLaunch {
 	request: FreshPiLaunchRequest;
@@ -224,6 +406,7 @@ interface PreparedSurface {
 interface PreparedSession extends PreparedSurface {
 	sessionFile: string;
 	activityFile: string;
+	processIdentityFile?: string;
 }
 
 interface PreparedArtifacts extends PreparedSession {
@@ -237,7 +420,7 @@ interface PreparedArtifacts extends PreparedSession {
  */
 export async function launchPiSubagent(
 	request: PiLaunchRequest,
-	operations: PiLaunchOperations = defaultOperations,
+	operations: PiLaunchOperations,
 ): Promise<PiRunningChild> {
 	return request.kind === "resume"
 		? launchResumedPiSubagent(request, operations)
@@ -246,7 +429,7 @@ export async function launchPiSubagent(
 
 export async function launchPiWorktreeHandoff(
 	request: FreshPiLaunchRequest,
-	operations: PiLaunchOperations = defaultOperations,
+	operations: PiLaunchOperations,
 ): Promise<{ running: PiRunningChild; focusError?: string }> {
 	if (!request.worktree || !request.handoff) {
 		throw new Error("A worktree handoff requires a worktree and active leaf");
@@ -256,13 +439,16 @@ export async function launchPiWorktreeHandoff(
 		throw new Error("Worktree handoff did not create a managed worktree");
 	}
 	try {
-		operations.focusWorkspace?.(running.worktree.workspaceId);
+		await operations.focusWorkspace?.(running.worktree.workspaceId);
 	} catch (error) {
 		const focusError = errorMessage(error);
-		writeWorktreeManifest(running.worktree.manifestFile, {
-			state: "running",
-			focusError,
-		});
+		requireWorktreeOperations(operations).writeWorktreeManifest(
+			running.worktree.manifestFile,
+			{
+				state: "running",
+				focusError,
+			},
+		);
 		return {
 			running,
 			focusError,
@@ -279,16 +465,16 @@ async function launchFreshPiSubagent(
 	let surface: PreparedSurface | undefined;
 
 	try {
-		surface = prepareLaunchSurface(resolved, operations);
-		const session = prepareChildSession(resolved, surface);
+		surface = await prepareLaunchSurface(resolved, operations);
+		const session = prepareChildSession(resolved, surface, operations);
 		const handoffArtifacts = request.handoff
-			? prepareTaskArtifacts(resolved, session)
+			? prepareTaskArtifacts(resolved, session, operations)
 			: undefined;
 		await confirmShellReady(session, operations);
 		const artifacts =
-			handoffArtifacts ?? prepareTaskArtifacts(resolved, session);
+			handoffArtifacts ?? prepareTaskArtifacts(resolved, session, operations);
 		const command = buildPiCommand(resolved, artifacts);
-		const launchScriptFile = startPiProcess(
+		const launchScriptFile = await startPiProcess(
 			resolved,
 			artifacts,
 			command,
@@ -304,25 +490,31 @@ async function launchFreshPiSubagent(
 				artifacts.targetCwd,
 			);
 			if (artifacts.worktree) {
-				persistWorktreeResult(artifacts.worktree, "running");
+				requireWorktreeOperations(operations).persistWorktreeResult(
+					artifacts.worktree,
+					"running",
+				);
 			}
 		}
-		return createRunningChild(resolved, artifacts, launchScriptFile);
+		const running = createRunningChild(resolved, artifacts, launchScriptFile);
+		startProcessIdentityCapture(running, operations);
+		return running;
 	} catch (error) {
 		if (!surface) throw error;
 		if (!surface.worktree) {
 			if (!request.surface) {
 				try {
-					operations.closePane(surface.surface);
+					await operations.closePane(surface.surface);
 				} catch {
 					// The launch error remains authoritative when cleanup also fails.
 				}
 			}
 			throw error;
 		}
-		const handoff = captureWorktreeHandoff(surface.worktree);
+		const worktreeOps = requireWorktreeOperations(operations);
+		const handoff = worktreeOps.captureWorktreeHandoff(surface.worktree);
 		try {
-			persistWorktreeResult(surface.worktree, "failed", handoff);
+			worktreeOps.persistWorktreeResult(surface.worktree, "failed", handoff);
 		} catch {
 			// The launch error remains authoritative when persistence also fails.
 		}
@@ -371,16 +563,16 @@ function resolveLaunchRequest(request: FreshPiLaunchRequest): ResolvedLaunch {
 	};
 }
 
-function prepareLaunchSurface(
+async function prepareLaunchSurface(
 	resolved: ResolvedLaunch,
 	operations: PiLaunchOperations,
-): PreparedSurface {
+): Promise<PreparedSurface> {
 	const { request } = resolved;
 	if (!request.worktree) {
 		return {
 			surface:
 				request.surface ??
-				operations.createPane(request.name, resolved.sourceCwd),
+				(await operations.createPane(request.name, resolved.sourceCwd)),
 			targetCwd: resolved.sourceCwd,
 			effectiveAgentDir: resolved.localAgentDir ?? resolved.agentDir,
 			localAgentDir: resolved.localAgentDir,
@@ -389,8 +581,12 @@ function prepareLaunchSurface(
 	if (request.surface)
 		throw new Error("A worktree subagent cannot use a pre-created pane");
 
+	const worktreeOps = requireWorktreeOperations(operations);
 	const baseRef = request.worktree.base ?? "HEAD";
-	const baseSha = resolveGitCommit(resolved.sourceCwd, baseRef);
+	const baseSha = worktreeOps.resolveGitCommit(resolved.sourceCwd, baseRef);
+	const provisionCwd = worktreeOps.resolveWorktreeProvisionCwd(
+		resolved.sourceCwd,
+	);
 	const manifestFile = join(
 		resolved.artifactDir,
 		"worktree-runs",
@@ -405,16 +601,16 @@ function prepareLaunchSurface(
 		baseSha,
 		createdAt: resolved.startTime,
 	};
-	writeWorktreeManifest(manifestFile, {
+	worktreeOps.writeWorktreeManifest(manifestFile, {
 		state: "provisioning",
 		...ownership,
 	});
 
-	let created: HerdrWorktreeSurface;
+	let created: WorktreeSurfaceForLaunch;
 	try {
-		created = operations.createWorktree(
+		created = await operations.createWorktree(
 			request.name,
-			resolved.sourceCwd,
+			provisionCwd,
 			request.worktree.branch,
 			baseSha,
 		);
@@ -423,11 +619,11 @@ function prepareLaunchSurface(
 			state: "failed",
 			...ownership,
 		};
-		if (error instanceof HerdrWorktreeCreateError) {
+		if (error instanceof WorktreeProvisioningError) {
 			Object.assign(failedManifest, error.recoveredWorktree);
 		}
 		failedManifest.error = errorMessage(error);
-		writeWorktreeManifest(manifestFile, failedManifest);
+		worktreeOps.writeWorktreeManifest(manifestFile, failedManifest);
 		throw error;
 	}
 
@@ -440,7 +636,7 @@ function prepareLaunchSurface(
 		baseSha,
 		manifestFile,
 	};
-	writeWorktreeManifest(manifestFile, {
+	worktreeOps.writeWorktreeManifest(manifestFile, {
 		state: "provisioned",
 		...ownership,
 		...worktree,
@@ -461,6 +657,7 @@ function prepareLaunchSurface(
 function prepareChildSession(
 	resolved: ResolvedLaunch,
 	surface: PreparedSurface,
+	operations: PiLaunchOperations,
 ): PreparedSession {
 	const sessionDir = getDefaultSessionDirFor(
 		surface.targetCwd,
@@ -476,7 +673,10 @@ function prepareChildSession(
 	const sessionFile = join(sessionDir, `${timestamp}_${uuid}.jsonl`);
 	if (surface.worktree) {
 		surface.worktree.sessionFile = sessionFile;
-		writeWorktreeManifest(surface.worktree.manifestFile, { sessionFile });
+		requireWorktreeOperations(operations).writeWorktreeManifest(
+			surface.worktree.manifestFile,
+			{ sessionFile },
+		);
 	}
 	writeSubagentSessionPolicy(sessionFile, {
 		owner: surface.worktree ? "managed-worktree" : "public",
@@ -498,7 +698,16 @@ function prepareChildSession(
 		resolved.artifactDir,
 		resolved.id,
 	);
-	return { ...surface, sessionFile, activityFile };
+	return {
+		...surface,
+		sessionFile,
+		activityFile,
+		// A handoff Pi loads no child protocol extension, so it records nothing.
+		processIdentityFile:
+			surface.worktree && !resolved.request.handoff
+				? getSubagentProcessIdentityFile(sessionFile)
+				: undefined,
+	};
 }
 
 async function confirmShellReady(
@@ -530,6 +739,7 @@ function buildWorktreeHandoffMessage(
 function prepareTaskArtifacts(
 	resolved: ResolvedLaunch,
 	session: PreparedSession,
+	operations: PiLaunchOperations,
 ): PreparedArtifacts {
 	const { request } = resolved;
 	if (request.handoff) {
@@ -550,10 +760,13 @@ function prepareTaskArtifacts(
 		});
 		session.worktree.sourceSessionFile = request.parent.sessionFile;
 		session.worktree.handoffMessage = handoffMessage;
-		writeWorktreeManifest(session.worktree.manifestFile, {
-			sourceSessionFile: request.parent.sessionFile,
-			handoffMessage,
-		});
+		requireWorktreeOperations(operations).writeWorktreeManifest(
+			session.worktree.manifestFile,
+			{
+				sourceSessionFile: request.parent.sessionFile,
+				handoffMessage,
+			},
+		);
 	} else if (resolved.sessionMode !== "standalone") {
 		seedSubagentSessionFile({
 			mode: resolved.sessionMode,
@@ -615,7 +828,7 @@ function buildPiCommand(
 		shellQuote(artifacts.sessionFile),
 		...(request.handoff
 			? []
-			: ["-e", shellQuote(join(SUBAGENTS_DIR, "subagent-done.ts"))]),
+			: ["-e", shellQuote(join(SUBAGENTS_DIR, "child", "subagent-done.ts"))]),
 		"--model",
 		shellQuote(request.runtimePlan.model),
 		"--thinking",
@@ -675,6 +888,10 @@ function buildPiCommand(
 		env.push(`PI_SUBAGENT_ID=${shellQuote(resolved.id)}`);
 		env.push(`PI_SUBAGENT_ACTIVITY_FILE=${shellQuote(artifacts.activityFile)}`);
 		env.push(`PI_SUBAGENT_SURFACE=${shellQuote(artifacts.surface)}`);
+		if (artifacts.processIdentityFile)
+			env.push(
+				`PI_SUBAGENT_PROCESS_FILE=${shellQuote(artifacts.processIdentityFile)}`,
+			);
 	}
 
 	const piCommand =
@@ -685,21 +902,24 @@ function buildPiCommand(
 		: `${piCommand}; echo '__SUBAGENT_DONE_'$?'__'`;
 }
 
-function startPiProcess(
+async function startPiProcess(
 	resolved: ResolvedLaunch,
 	artifacts: PreparedArtifacts,
 	command: string,
 	operations: PiLaunchOperations,
-): string {
+): Promise<string> {
 	const launchScriptFile = join(
 		resolved.artifactDir,
 		"subagent-scripts",
 		`${safeName(resolved.request.name) || "subagent"}-${resolved.id}.sh`,
 	);
 	if (artifacts.worktree && !resolved.request.handoff) {
-		persistWorktreeResult(artifacts.worktree, "running");
+		requireWorktreeOperations(operations).persistWorktreeResult(
+			artifacts.worktree,
+			"running",
+		);
 	}
-	return operations.runScript(artifacts.surface, command, {
+	return await operations.runScript(artifacts.surface, command, {
 		scriptPath: launchScriptFile,
 		scriptPreamble: [
 			shellComment(`Subagent launch script for ${resolved.request.name}`),
@@ -729,9 +949,43 @@ function createRunningChild(
 		runtimePlan: resolved.request.runtimePlan,
 		worktree: artifacts.worktree,
 		lifecycle: createLifecycle(resolved.startTime),
+		processIdentityFile: artifacts.processIdentityFile,
 	};
 }
 
+// Capture runs beside the launch so readiness never delays the acknowledgement;
+// a cancel awaits it, and without a verified identity nothing is signalled. A
+// cancel after an expired capture starts a fresh one bounded by its own budget.
+export function startProcessIdentityCapture(
+	child: PiRunningChild,
+	operations: PiLaunchOperations,
+	options?: { timeoutMs?: number },
+): void {
+	const file = child.processIdentityFile;
+	if (!file) return;
+	const capture = operations.captureProcessIdentity;
+	if (!capture) {
+		child.processIdentityError = "process identity capture is unavailable";
+		return;
+	}
+	child.processIdentityError = undefined;
+	child.processIdentityCapture = Promise.resolve()
+		.then(() =>
+			capture(
+				child.surface,
+				{ file, id: child.id, sessionFile: child.sessionFile },
+				options,
+			),
+		)
+		.then(
+			(identity) => (child.processIdentity = identity),
+			(error) => {
+				child.processIdentityError = errorMessage(error);
+				return undefined;
+			},
+		);
+}
+
 async function launchResumedPiSubagent(
 	request: ResumePiLaunchRequest,
 	operations: PiLaunchOperations,
@@ -761,7 +1015,7 @@ async function launchResumedPiSubagent(
 		(entry) => entry.type === "session",
 	);
 	const cwd = isNonEmptyString(header?.cwd) ? header.cwd : process.cwd();
-	const surface = operations.createPane(request.name, cwd);
+	const surface = await operations.createPane(request.name, cwd);
 	try {
 		await operations.waitForShellReady(surface);
 		const activityFile = getSubagentActivityFile(artifactDir, id);
@@ -802,10 +1056,10 @@ async function launchResumedPiSubagent(
 			shellQuote(request.sessionFile),
 			...(toolAllowlist ? ["--tools", shellQuote(toolAllowlist)] : []),
 			"-e",
-			shellQuote(join(SUBAGENTS_DIR, "subagent-done.ts")),
+			shellQuote(join(SUBAGENTS_DIR, "child", "subagent-done.ts")),
 			...(messageFile ? [shellQuote(`@${messageFile}`)] : []),
 		].join(" ");
-		const launchScriptFile = operations.runScript(
+		const launchScriptFile = await operations.runScript(
 			surface,
 			`${command}; echo '__SUBAGENT_DONE_'$?'__'`,
 			{
@@ -840,7 +1094,7 @@ async function launchResumedPiSubagent(
 		};
 	} catch (error) {
 		try {
-			operations.closePane(surface);
+			await operations.closePane(surface);
 		} catch {
 			// The launch error remains authoritative when cleanup also fails.
 		}
@@ -911,163 +1165,12 @@ function safeName(name: string): string {
 		.replace(/^-|-$/g, "");
 }
 
-function resolveGitCommit(cwd: string, ref: string): string {
-	return execFileSync("git", ["rev-parse", "--verify", `${ref}^{commit}`], {
-		cwd,
-		encoding: "utf8",
-	}).trim();
-}
-
-export function readWorktreeManifest(path: string): JsonObject | undefined {
-	try {
-		const value: unknown = JSON.parse(readFileSync(path, "utf8"));
-		if (
-			isRecord(value) &&
-			value.version === 1 &&
-			value.kind === "worktree-run" &&
-			value.owner === "pi-herdr-subagents"
-		)
-			return value;
-	} catch {
-		// Unreachable or malformed manifests do not establish ownership.
-	}
-	return undefined;
-}
-
-export function writeWorktreeManifest(path: string, value: JsonObject): void {
-	mkdirSync(dirname(path), { recursive: true });
-	let existing: JsonObject = {};
-	if (existsSync(path)) {
-		try {
-			existing = JSON.parse(readFileSync(path, "utf8"));
-		} catch {
-			existing = {};
-		}
-	}
-	const tempPath = `${path}.tmp`;
-	writeFileSync(
-		tempPath,
-		`${JSON.stringify(
-			{
-				...existing,
-				...value,
-				version: 1,
-				kind: "worktree-run",
-				owner: "pi-herdr-subagents",
-				updatedAt: Date.now(),
-			},
-			null,
-			2,
-		)}\n`,
-	);
-	renameSync(tempPath, path);
-}
-
-function gitPathList(cwd: string, args: string[]): string[] {
-	return execFileSync("git", args, { cwd, encoding: "utf8" })
-		.split("\0")
-		.filter(Boolean);
-}
-
-export function captureWorktreeHandoff(
-	worktree: WorktreeLaunch,
-): WorktreeHandoff {
-	try {
-		const headSha = resolveGitCommit(worktree.path, "HEAD");
-		const status = execFileSync(
-			"git",
-			["status", "--porcelain=v1", "--untracked-files=all", "-z"],
-			{ cwd: worktree.path, encoding: "utf8" },
-		);
-		const untrackedFiles = gitPathList(worktree.path, [
-			"ls-files",
-			"--others",
-			"--exclude-standard",
-			"-z",
-		]);
-		const conflictedFiles = gitPathList(worktree.path, [
-			"diff",
-			"--name-only",
-			"--diff-filter=U",
-			"-z",
-		]);
-		const changedFiles = new Set([
-			...gitPathList(worktree.path, [
-				"diff",
-				"--name-only",
-				"-z",
-				`${worktree.baseSha}...HEAD`,
-			]),
-			...gitPathList(worktree.path, ["diff", "--name-only", "-z"]),
-			...gitPathList(worktree.path, ["diff", "--cached", "--name-only", "-z"]),
-			...untrackedFiles,
-		]);
-		const commitsAhead = Number.parseInt(
-			execFileSync(
-				"git",
-				["rev-list", "--count", `${worktree.baseSha}..HEAD`],
-				{ cwd: worktree.path, encoding: "utf8" },
-			).trim(),
-			10,
-		);
-		return {
-			...worktree,
-			headSha,
-			commitsAhead: Number.isFinite(commitsAhead) ? commitsAhead : 0,
-			clean: status.length === 0,
-			conflicted: conflictedFiles.length > 0,
-			changedFiles: [...changedFiles].sort(),
-			untrackedFiles: untrackedFiles.sort(),
-		};
-	} catch (error) {
-		return {
-			...worktree,
-			headSha: null,
-			commitsAhead: null,
-			clean: null,
-			conflicted: null,
-			changedFiles: null,
-			untrackedFiles: null,
-			gitError: errorMessage(error),
-		};
-	}
-}
-
-export function persistWorktreeResult(
-	worktree: WorktreeLaunch,
-	state: "running" | "ready_for_review" | "failed" | "needs_help" | "removed",
-	handoff?: WorktreeHandoff,
-): void {
-	writeWorktreeManifest(worktree.manifestFile, {
-		state,
-		...worktree,
-		...handoff,
-	});
-}
-
-export function runSubagentScript(
-	surface: string,
-	command: string,
-	options: Parameters<typeof runScriptInPane>[2],
-	worktree?: WorktreeLaunch,
-	run: typeof runScriptInPane = runScriptInPane,
-): string {
-	if (worktree) persistWorktreeResult(worktree, "running");
-	try {
-		return run(surface, command, options);
-	} catch (error) {
-		if (!worktree) throw error;
-		const handoff = captureWorktreeHandoff(worktree);
-		try {
-			persistWorktreeResult(worktree, "failed", handoff);
-		} catch {
-			// The launch error remains authoritative when persistence also fails.
-		}
-		throw new Error(
-			`Failed to launch subagent; worktree retained at ${worktree.path} ` +
-				`(workspace ${worktree.workspaceId}): ${errorMessage(error)}`,
-		);
-	}
+function requireWorktreeOperations(
+	operations: PiLaunchOperations,
+): WorktreeOperations {
+	if (!operations.worktree)
+		throw new Error("Worktree operations are unavailable");
+	return operations.worktree;
 }
 
 function errorMessage(error: any): string {