pi-agent-replicate 0.0.0-stage → 1.4.1

package/pi-extension/subagents/launch.ts

@@ -0,0 +1,1124 @@
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import {
+  appendLineageEvent,
+  hasLineageEvent,
+  lineageFromEnvironment,
+  lineageEnvironment,
+  registerLineage,
+  isLineageNodeDrained,
+  reduceLineage,
+  type LineageRegistration,
+} from "./lineage.ts";
+import {
+  getSubagentActivityFile,
+  getSubagentSettledEventsFile,
+} from "./activity.ts";
+import { createLifecycle, type SubagentLifecycle } from "./lifecycle.ts";
+import type { ResolvedRuntimePlan } from "./runtime-routing.ts";
+import { HerdrWorktreeCreateError } from "./herdr.ts";
+import {
+	captureSessionBaseline,
+	seedStandaloneSessionFile,
+	seedSubagentSessionFile,
+	seedReplicationSessionFile,
+} from "./session.ts";
+import type { SessionBaselineCursor } from "./settled-contract.ts";
+import {
+	createSubagentPane,
+
+	createSubagentPaneInWorkspace,
+	closePane,
+	getPaneTabId,
+	getPaneProcessInfo,
+	createSubagentWorktree,
+	runScriptInPane,
+	shellQuote,
+	waitForShellReady,
+	type HerdrWorktreeSurface,
+} from "./terminal.ts";
+
+import { readSessionBinding, registerSessionLineage, seedSessionBinding, sessionBindingStore, captureLaunchPaneOwnership, type LaunchPaneOwnership } from "./session-binding.ts";
+import type { ReplicationSnapshot } from "./replication.ts";
+import type { ExecutionOwner } from "./execution-owner.ts";
+import { attachReplicaWork, attachSharedReplicaPane, captureReplicaLaunchPane, cleanupReplicaWork, failReplicaLaunch } from "./replica-work.ts";
+import { sourceRepositoryAnchor } from "./source-state.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;
+}
+
+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";
+	/** Real initiating tool ownership; absent for command/API launches. */
+	executionOwner?: ExecutionOwner;
+	id?: string;
+	name: string;
+	task: string;
+	agent?: string;
+	cwd?: string;
+	worktree?: { branch: string; base?: string };
+	fork?: boolean;
+	/** Captured current-branch state for a role-free replication. */
+	replication?: ReplicationSnapshot;
+	surface?: string;
+	parent: {
+		cwd: string;
+		invocationCwd?: string;
+		sessionFile: string;
+		sessionId: string;
+		sessionDir: string;
+		agentDir?: string;
+	};
+	runtimePlan: ResolvedRuntimePlan;
+	lineage?: LineageRegistration;
+
+	behavior: {
+		tools?: string;
+		skills?: string;
+		deniedTools: readonly string[];
+		autoExit: boolean;
+		interactive: boolean;
+		/** Keep the public child tool list exact instead of adding control tools. */
+		includeControlTools?: boolean;
+		identity?: string;
+		systemPromptMode?: "append" | "replace";
+		sessionMode: SubagentSessionMode;
+		cwd?: string;
+	};
+	environment?: Readonly<Record<string, string>>;
+	signal?: AbortSignal;
+}
+
+export interface ResumePiLaunchRequest {
+	kind: "resume";
+	/** Explicit continuations get a new owner; watchdog recovery preserves the old one. */
+	executionOwner?: ExecutionOwner;
+	id?: string;
+	name: string;
+	sessionFile: string;
+	message?: string;
+
+	/** Existing pane to reuse after a verified child-process crash. */
+	surface?: string;
+	/** Exact workspace used when recovery needs a replacement pane. */
+	workspace?: { id: string; cwd: string };
+	parent: {
+		sessionId: string;
+		sessionFile: string;
+		sessionDir: string;
+	};
+	behavior?: {
+		autoExit?: boolean;
+		interactive?: boolean;
+	};
+}
+
+export type PiLaunchRequest = FreshPiLaunchRequest | ResumePiLaunchRequest;
+
+export interface PiRunningChild {
+	executionOwner?: ExecutionOwner;
+	lineage?: LineageRegistration;
+	/** Distinguish replication settlement from retained role-based launches. */
+	replication?: boolean;
+	/** Durable work pointer, independent of any moved session file. */
+	replicaWorkFile?: string;
+	launchPane?: LaunchPaneOwnership;
+	id: string;
+	name: string;
+	task: string;
+	agent?: string;
+	surface: string;
+	startTime: number;
+	tabId?: string;
+	sessionFile: string;
+	launchScriptFile: string;
+	activityFile: string;
+  settledEventsFile: string;
+	interactive: boolean;
+	sessionBaseline: SessionBaselineCursor;
+	runtimePlan: ResolvedRuntimePlan | undefined;
+	worktree?: WorktreeLaunch;
+	/** Exact Herdr workspace used for replacement-pane recovery. */
+	recoveryWorkspace?: { id: string; cwd: string };
+	lifecycle: SubagentLifecycle;
+}
+
+export interface PiLaunchOperations {
+	createPane(name: string, workspace?: { id: string; cwd: string }): string;
+	createWorktree(
+		name: string,
+		cwd: string,
+		branch: string,
+		base: string,
+	): HerdrWorktreeSurface;
+	waitForShellReady(surface: string, options?: { signal?: AbortSignal }): Promise<void>;
+	closePane?(surface: string): void;
+	getPaneProcessInfo?: (surface: string) => ReturnType<typeof getPaneProcessInfo>;
+	runScript(
+		surface: string,
+		command: string,
+		options: { scriptPath: string; scriptPreamble: string },
+	): string;
+}
+
+const defaultOperations: PiLaunchOperations = {
+	createPane: (name, workspace) => workspace
+		? createSubagentPaneInWorkspace(name, workspace.cwd, workspace.id)
+		: createSubagentPane(name),
+	closePane,
+	getPaneProcessInfo,
+	createWorktree: createSubagentWorktree,
+	waitForShellReady,
+	runScript: runScriptInPane,
+};
+
+interface ResolvedLaunch {
+	launchPane?: LaunchPaneOwnership;
+	request: FreshPiLaunchRequest;
+	id: string;
+	startTime: number;
+	agentDir: string;
+	localAgentDir: string | null;
+	sourceCwd: string;
+	artifactDir: string;
+	lineage?: LineageRegistration;
+	sessionMode: SubagentSessionMode;
+	taskDelivery: "direct" | "artifact";
+}
+
+interface PreparedSurface {
+	surface: string;
+	tabId?: string;
+	targetCwd: string;
+	effectiveAgentDir: string;
+	localAgentDir: string | null;
+	worktree?: WorktreeLaunch;
+}
+
+interface PreparedSession extends PreparedSurface {
+	sessionFile: string;
+	activityFile: string;
+  settledEventsFile: string;
+}
+
+interface PreparedArtifacts extends PreparedSession {
+	taskArg: string;
+	systemPromptFile?: string;
+	replicationPromptFile?: string;
+}
+
+/**
+ * Launch one validated Pi-backed request. Lifecycle watching and parent
+ * delivery begin only after this transaction returns the running child.
+ */
+export async function launchPiSubagent(
+	request: PiLaunchRequest,
+	operations: PiLaunchOperations = defaultOperations,
+): Promise<PiRunningChild> {
+	return request.kind === "resume"
+		? launchResumedPiSubagent(request, operations)
+		: launchFreshPiSubagent(request, operations);
+}
+
+async function launchFreshPiSubagent(
+	request: FreshPiLaunchRequest,
+	operations: PiLaunchOperations,
+): Promise<PiRunningChild> {
+	const resolved = resolveLaunchRequest(request);
+	// Registration is the ownership boundary: publish lineage before Herdr creates resources.
+	const inherited = readSessionBinding(request.parent.sessionFile)?.child?.lineage ?? lineageFromEnvironment();
+	resolved.lineage = request.lineage ?? registerLineage({
+		artifactDir: resolved.artifactDir,
+		nodeId: resolved.id,
+		parentNodeId: inherited?.nodeId,
+		parentSessionId: request.parent.sessionId,
+		parentSessionFile: request.parent.sessionFile,
+		launchKind: request.worktree ? "worktree" : request.fork ? "fork" : "fresh",
+		inheritedRootDir: inherited?.rootDir,
+		inheritedRootId: inherited?.rootId,
+	});
+	const storeDir = sessionBindingStore(request.parent.sessionFile, resolved.agentDir);
+	registerSessionLineage(storeDir, request.parent.sessionId, resolved.lineage.rootDir);
+	let surface: PreparedSurface | undefined;
+	const abort = new AbortController();
+	const signal = request.signal ?? abort.signal;
+	try {
+		if (request.replication) {
+			const metadataId = `metadata:${resolved.id}:reserved`;
+			if (!appendLineageEvent(resolved.lineage.rootDir, metadataId, "launch_metadata", resolved.id, {
+				name: request.name,
+				task: request.task,
+				startTime: resolved.startTime,
+				executionOwner: request.executionOwner,
+				replication: true,
+				replicaWorkFile: request.replication.recordFile,
+			}) && !hasLineageEvent(resolved.lineage.rootDir, metadataId, "launch_metadata")) {
+				throw new Error("Unable to publish replica launch recovery metadata.");
+			}
+		}
+		surface = prepareLaunchSurface(resolved, operations);
+		if (request.replication?.recordFile) {
+			if (surface.worktree) attachReplicaWork(request.replication.recordFile, surface.worktree);
+			else attachSharedReplicaPane(request.replication.recordFile, surface.surface);
+			captureLaunchSurface(resolved, surface, operations);
+		}
+		const session = prepareChildSession(resolved, surface);
+		const artifacts = prepareTaskArtifacts(resolved, session);
+		seedSessionBinding(artifacts.sessionFile, {
+			version: 1, storeDir,
+			child: {
+				lineage: resolved.lineage,
+				environment: {
+					...lineageEnvironment(resolved.lineage),
+					PI_SUBAGENT_ID: resolved.id,
+					PI_SUBAGENT_NAME: request.name,
+					PI_SUBAGENT_AGENT: request.agent ?? "",
+					PI_SUBAGENT_AUTO_EXIT: request.behavior.autoExit ? "1" : "0",
+					PI_SUBAGENT_SKILLS: normalizeSkillNames(request.behavior.skills ?? "").join(","),
+					PI_DENY_TOOLS: request.behavior.deniedTools.join(","),
+					PI_SUBAGENT_TOOLS: buildSubagentToolAllowlist(request.behavior.tools, request.behavior.autoExit, request.behavior.includeControlTools ?? true) ?? "",
+					PI_SUBAGENT_ACTIVITY_FILE: artifacts.activityFile,
+					PI_SUBAGENT_SETTLED_EVENTS_FILE: artifacts.settledEventsFile,
+					...(request.replication ? {
+						PI_SUBAGENT_REPLICATION: "1",
+						...(request.replication.recordFile ? { PI_SUBAGENT_REPLICA_WORK_FILE: request.replication.recordFile } : {}),
+						PI_SUBAGENT_REPLICATION_PROMPT_FILE: artifacts.replicationPromptFile!,
+						PI_SUBAGENT_REPLICATION_EXTENSIONS: JSON.stringify(request.replication.extensionArgs),
+						PI_SUBAGENT_REPLICATION_ASSISTANTS: JSON.stringify(request.replication.entries.filter((entry) => entry.type === "message" && (entry.message as any)?.role === "assistant").map((entry) => entry.id)),
+					} : {}),
+					...Object.fromEntries(Object.entries(request.environment ?? {}).filter(([key]) => key.startsWith("PI_SUBAGENT_TREE_"))),
+				},
+			},
+		});
+		const sessionBaseline = captureSessionBaseline(artifacts.sessionFile);
+		if (resolved.lineage) {
+			appendLineageEvent(resolved.lineage.rootDir, `metadata:${resolved.id}:${resolved.startTime}`, "launch_metadata", resolved.id, {
+				name: request.name,
+				executionOwner: request.executionOwner,
+				task: request.task,
+				agent: request.agent,
+				surface: artifacts.surface,
+				tabId: artifacts.tabId,
+				sessionFile: artifacts.sessionFile,
+				activityFile: artifacts.activityFile,
+				settledEventsFile: artifacts.settledEventsFile,
+				startTime: resolved.startTime,
+
+				interactive: request.behavior.interactive,
+				autoExit: request.behavior.autoExit,
+				...(request.replication ? { replication: true, replicaWorkFile: request.replication.recordFile } : {}),
+				cwd: artifacts.targetCwd,
+				...(artifacts.worktree ? { worktree: artifacts.worktree } : {}),
+				...(artifacts.worktree?.workspaceId ? { workspaceId: artifacts.worktree.workspaceId } : {}),
+			});
+		}
+		// Publish recovery evidence before waiting on external shell startup.
+		await confirmShellReady(session, operations, signal);
+		captureLaunchSurface(resolved, surface, operations);
+		if (request.replication?.recordFile && !surface.worktree && !resolved.launchPane) throw new Error("Cannot verify shared replica pane ownership.");
+		if (signal.aborted) throw new Error("subagent launch aborted");
+		const command = buildPiCommand(resolved, artifacts);
+		const launchScriptFile = startPiProcess(resolved, artifacts, command, operations);
+		return createRunningChild(resolved, artifacts, launchScriptFile, sessionBaseline);
+	} catch (error) {
+		abort.abort();
+		if (request.replication?.recordFile) {
+			try { failReplicaLaunch(request.replication.recordFile, error); } catch { /* Preserve the original launch failure. */ }
+		}
+		if (surface && !surface.worktree) {
+			if (request.replication?.recordFile) {
+				try { captureLaunchSurface(resolved, surface, operations); cleanupReplicaWork(request.replication.recordFile, resolved.sourceCwd); } catch { /* Unknown ownership stays recoverable. */ }
+			} else {
+				try { operations.closePane?.(surface.surface); } catch { /* best effort */ }
+			}
+		}
+		if (!surface?.worktree) throw error;
+		if (request.replication?.recordFile) {
+			try {
+				captureLaunchSurface(resolved, surface, operations);
+				cleanupReplicaWork(request.replication.recordFile, resolved.sourceCwd);
+			} catch { /* Unknown ownership keeps the failed work recoverable. */ }
+			try { persistWorktreeResult(surface.worktree, "failed"); } catch { /* The work record also retains the failure. */ }
+			throw new Error(`Failed to launch replica; worktree retained at ${surface.worktree.path}: ${errorMessage(error)}`);
+		}
+		const handoff = captureWorktreeHandoff(surface.worktree);
+		try { persistWorktreeResult(surface.worktree, "failed", handoff); } catch { /* launch error remains authoritative */ }
+		throw new Error(`Failed to launch subagent; worktree retained at ${surface.worktree.path} (workspace ${surface.worktree.workspaceId}): ${errorMessage(error)}`);
+	}
+}
+
+/** Record the shell before dispatch; child startup may never reach session_start. */
+function captureLaunchSurface(resolved: ResolvedLaunch, surface: PreparedSurface, operations: PiLaunchOperations): void {
+	const file = resolved.request.replication?.recordFile;
+	if (!file || !operations.getPaneProcessInfo) return;
+	let shellPid: number | undefined;
+	try { shellPid = operations.getPaneProcessInfo(surface.surface).shellPid; }
+	catch { return; } // A shell may still be starting; retry after readiness.
+	const owner = captureLaunchPaneOwnership(surface.surface, shellPid);
+	if (owner) {
+		captureReplicaLaunchPane(file, owner);
+		resolved.launchPane = owner;
+	}
+}
+function resolveLaunchRequest(request: FreshPiLaunchRequest): ResolvedLaunch {
+	const id = request.id ?? randomUUID();
+	const agentDir =
+		request.parent.agentDir ??
+		process.env.PI_CODING_AGENT_DIR ??
+		join(homedir(), ".pi", "agent");
+	const rawCwd = request.cwd ?? request.behavior.cwd;
+	const cwdBase =
+		request.cwd == null && request.behavior.cwd != null
+			? agentDir
+			: (request.parent.invocationCwd ?? request.parent.cwd);
+	const sourceCwd = rawCwd
+		? rawCwd.startsWith("/")
+			? rawCwd
+			: join(cwdBase, rawCwd)
+		: request.parent.cwd;
+	const localAgentDir = rawCwd ? join(sourceCwd, ".pi", "agent") : null;
+	const sessionMode = request.fork ? "fork" : request.behavior.sessionMode;
+	return {
+		request,
+		id,
+		startTime: Date.now(),
+		agentDir,
+		localAgentDir:
+			localAgentDir && existsSync(localAgentDir) ? localAgentDir : null,
+		sourceCwd,
+		artifactDir: request.replication?.recordFile ? join(request.replication.recordFile + ".artifacts", "launch") : join(
+			request.parent.sessionDir,
+			"artifacts",
+			request.parent.sessionId,
+		),
+		sessionMode,
+		taskDelivery: sessionMode === "fork" ? "direct" : "artifact",
+	};
+}
+
+function prepareLaunchSurface(
+	resolved: ResolvedLaunch,
+	operations: PiLaunchOperations,
+): PreparedSurface {
+	const { request } = resolved;
+	if (!request.worktree) {
+		const surface = request.surface ?? operations.createPane(request.name);
+		const tabId = getPaneTabId(surface);
+		return {
+			surface,
+			...(tabId ? { tabId } : {}),
+			targetCwd: resolved.sourceCwd,
+			effectiveAgentDir: resolved.localAgentDir ?? resolved.agentDir,
+			localAgentDir: resolved.localAgentDir,
+		};
+	}
+	if (request.surface)
+		throw new Error("A worktree subagent cannot use a pre-created pane");
+
+	const baseRef = request.worktree.base ?? "HEAD";
+	const baseSha = resolveGitCommit(resolved.sourceCwd, baseRef);
+	const manifestFile = join(
+		resolved.artifactDir,
+		"worktree-runs",
+		`${resolved.id}.json`,
+	);
+	const ownership = {
+		id: resolved.id,
+		name: request.name,
+		sourceCwd: resolved.sourceCwd,
+		branch: request.worktree.branch,
+		baseRef,
+		baseSha,
+		createdAt: resolved.startTime,
+	};
+	writeWorktreeManifest(manifestFile, {
+		state: "provisioning",
+		...ownership,
+	});
+
+	let created: HerdrWorktreeSurface;
+	try {
+		created = operations.createWorktree(
+			request.name,
+			request.replication ? sourceRepositoryAnchor(resolved.sourceCwd) : resolved.sourceCwd,
+			request.worktree.branch,
+			baseSha,
+		);
+	} catch (error) {
+		writeWorktreeManifest(manifestFile, {
+			state: "failed",
+			...ownership,
+			...(error instanceof HerdrWorktreeCreateError
+				? error.recoveredWorktree
+				: {}),
+			error: errorMessage(error),
+		});
+		throw error;
+	}
+
+	const worktree: WorktreeLaunch = {
+		path: created.path,
+		workspaceId: created.workspaceId,
+		paneId: created.paneId,
+		branch: created.branch,
+		baseRef,
+		baseSha,
+		manifestFile,
+	};
+	writeWorktreeManifest(manifestFile, {
+		state: "provisioned",
+		...ownership,
+		...worktree,
+	});
+	const isolatedAgentDir = join(created.path, ".pi", "agent");
+	const hasIsolatedAgentDir = existsSync(isolatedAgentDir);
+	return {
+		surface: created.paneId,
+		targetCwd: created.path,
+		effectiveAgentDir: hasIsolatedAgentDir
+			? isolatedAgentDir
+			: resolved.agentDir,
+		localAgentDir: hasIsolatedAgentDir ? isolatedAgentDir : null,
+		worktree,
+	};
+}
+
+function prepareChildSession(
+	resolved: ResolvedLaunch,
+	surface: PreparedSurface,
+): PreparedSession {
+	const sessionDir = resolved.request.replication?.recordFile
+		? join(resolved.request.replication.recordFile + ".artifacts", "sessions")
+		: getDefaultSessionDirFor(surface.targetCwd, surface.effectiveAgentDir);
+	mkdirSync(sessionDir, { recursive: true });
+	const timestamp = timestampForFile();
+	const uuid = [resolved.id, randomUUID(), randomUUID(), randomUUID()].join("-");
+	const sessionFile = join(sessionDir, `${timestamp}_${uuid}.jsonl`);
+	if (resolved.sessionMode === "standalone") {
+		seedStandaloneSessionFile({ childSessionFile: sessionFile, childCwd: surface.targetCwd });
+	}
+	if (surface.worktree) {
+		surface.worktree.sessionFile = sessionFile;
+		writeWorktreeManifest(surface.worktree.manifestFile, { sessionFile });
+		if (resolved.request.replication?.recordFile) attachReplicaWork(resolved.request.replication.recordFile, surface.worktree, sessionFile);
+	} else if (resolved.request.replication?.recordFile) {
+		attachSharedReplicaPane(resolved.request.replication.recordFile, surface.surface, sessionFile);
+	}
+	const activityFile = getSubagentActivityFile(
+		resolved.artifactDir,
+		resolved.id,
+	);
+  const settledEventsFile = getSubagentSettledEventsFile(
+    resolved.artifactDir,
+    resolved.id,
+  );
+	if (resolved.lineage) {
+		writeFileSync(`${sessionFile}.lineage.json`, JSON.stringify(resolved.lineage), "utf8");
+	}
+  return { ...surface, sessionFile, activityFile, settledEventsFile };
+}
+
+async function confirmShellReady(
+	session: PreparedSession,
+	operations: PiLaunchOperations,
+	signal?: AbortSignal,
+): Promise<void> {
+	await operations.waitForShellReady(session.surface, { signal });
+}
+
+function prepareTaskArtifacts(
+	resolved: ResolvedLaunch,
+	session: PreparedSession,
+): PreparedArtifacts {
+	const { request } = resolved;
+	if (request.replication) {
+		seedReplicationSessionFile({ parentSessionFile: request.parent.sessionFile, childSessionFile: session.sessionFile, childCwd: session.targetCwd, entries: request.replication.entries, contextMessages: request.replication.contextMessages, resumeSessionId: request.replication.resumeSessionId, name: request.name });
+	} else if (resolved.sessionMode !== "standalone") {
+		seedSubagentSessionFile({
+			mode: resolved.sessionMode,
+			parentSessionFile: request.parent.sessionFile,
+			childSessionFile: session.sessionFile,
+			childCwd: session.targetCwd,
+		});
+	}
+	mkdirSync(dirname(session.activityFile), { recursive: true });
+
+	const identityInSystemPrompt =
+		request.behavior.systemPromptMode && request.behavior.identity;
+	const roleBlock =
+		request.behavior.identity && !identityInSystemPrompt
+			? `\n\n${request.behavior.identity}`
+			: "";
+	const modeHint = request.behavior.autoExit
+		? "Complete your task autonomously."
+		: "Complete your task. The user can interact with you at any time.";
+	const summaryInstruction = "Your FINAL assistant message should summarize what you accomplished.";
+	const fullTask = resolved.sessionMode === "fork"
+		? request.task
+		: `${roleBlock}\n\n${modeHint}\n\n${request.task}\n\n${summaryInstruction}`;
+	let taskArg = fullTask;
+	if (resolved.taskDelivery === "artifact") {
+		const artifactPath = join(
+			resolved.artifactDir,
+			`context/${safeName(request.name) || "subagent"}-${timestampForFile(false)}.md`,
+		);
+		mkdirSync(dirname(artifactPath), { recursive: true });
+		writeFileSync(artifactPath, fullTask, "utf8");
+		taskArg = `@${artifactPath}`;
+	}
+
+	let systemPromptFile: string | undefined;
+	if (identityInSystemPrompt) {
+		systemPromptFile = join(
+			resolved.artifactDir,
+			`context/${safeName(request.name) || "subagent"}-sysprompt-${timestampForFile(false)}.md`,
+		);
+		mkdirSync(dirname(systemPromptFile), { recursive: true });
+		writeFileSync(systemPromptFile, identityInSystemPrompt, "utf8");
+	}
+	let replicationPromptFile: string | undefined;
+	if (request.replication) {
+		replicationPromptFile = join(resolved.artifactDir, "replication", `${resolved.id}.system.txt`);
+		mkdirSync(dirname(replicationPromptFile), { recursive: true });
+		writeFileSync(replicationPromptFile, request.replication.systemPrompt, { mode: 0o600 });
+	}
+	return { ...session, taskArg, systemPromptFile, replicationPromptFile };
+}
+
+function buildPiCommand(
+	resolved: ResolvedLaunch,
+	artifacts: PreparedArtifacts,
+): string {
+	const { request } = resolved;
+	const parts = [
+		"pi",
+		"--session",
+		shellQuote(artifacts.sessionFile),
+		...(!request.replication ? ["-e", shellQuote(join(SUBAGENTS_DIR, "subagent-done.ts"))] : []),
+		...(process.env.HERDR_ENV === "1" && existsSync(join(process.env.HOME ?? "", ".pi/agent/extensions/herdr-agent-state.ts"))
+			? ["-e", shellQuote(join(process.env.HOME ?? "", ".pi/agent/extensions/herdr-agent-state.ts"))]
+			: []),
+		"--model",
+		shellQuote(request.runtimePlan.model),
+		"--thinking",
+		shellQuote(request.runtimePlan.thinking),
+	];
+	if (request.replication) parts.push(...request.replication.extensionArgs.map(shellQuote), "-e", shellQuote(join(SUBAGENTS_DIR, "subagent-done.ts")));
+	if (artifacts.systemPromptFile) {
+		parts.push(
+			request.behavior.systemPromptMode === "replace"
+				? "--system-prompt"
+				: "--append-system-prompt",
+			shellQuote(artifacts.systemPromptFile),
+		);
+	}
+	const toolAllowlist = buildSubagentToolAllowlist(
+		request.behavior.tools,
+		request.behavior.autoExit,
+		request.behavior.includeControlTools ?? true,
+	);
+	if (toolAllowlist) parts.push("--tools", shellQuote(toolAllowlist));
+	parts.push(shellQuote(artifacts.taskArg));
+
+	const env: string[] = [];
+	if (!request.replication) env.push("PI_SUBAGENT_REPLICATION=''", "PI_SUBAGENT_REPLICA_WORK_FILE=''", "PI_SUBAGENT_REPLICATION_PROMPT_FILE=''");
+	if (request.replication) {
+		env.push("PI_SUBAGENT_REPLICATION=1", "PI_DENY_TOOLS=''", "PI_SUBAGENT_AGENT=''", `PI_SUBAGENT_REPLICATION_PROMPT_FILE=${shellQuote(artifacts.replicationPromptFile!)}`);
+		if (request.replication.recordFile) env.push(`PI_SUBAGENT_REPLICA_WORK_FILE=${shellQuote(request.replication.recordFile)}`);
+	}
+	for (const [key, value] of Object.entries(request.environment ?? {})) {
+		if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) env.push(`${key}=${shellQuote(value)}`);
+	}
+	if (resolved.lineage) {
+		env.push("PI_SUBAGENT_LAUNCHER_PID=$$");
+		for (const [key, value] of Object.entries(lineageEnvironment(resolved.lineage))) {
+			env.push(`${key}=${shellQuote(value)}`);
+		}
+	}
+	if (artifacts.localAgentDir) {
+		env.push(`PI_CODING_AGENT_DIR=${shellQuote(artifacts.localAgentDir)}`);
+	} else if (process.env.PI_CODING_AGENT_DIR) {
+		env.push(
+			`PI_CODING_AGENT_DIR=${shellQuote(process.env.PI_CODING_AGENT_DIR)}`,
+		);
+	}
+	if (request.behavior.deniedTools.length > 0) {
+			env.push(
+				`PI_DENY_TOOLS=${shellQuote(request.behavior.deniedTools.join(","))}`,
+			);
+	}
+	env.push(`PI_SUBAGENT_NAME=${shellQuote(request.name)}`);
+		if (request.agent)
+			env.push(`PI_SUBAGENT_AGENT=${shellQuote(request.agent)}`);
+		env.push(
+			`PI_SUBAGENT_SKILLS=${shellQuote(normalizeSkillNames(request.behavior.skills ?? "").join(","))}`,
+		);
+    env.push(`PI_SUBAGENT_AUTO_EXIT=${request.behavior.autoExit ? "1" : "0"}`);
+		env.push(`PI_SUBAGENT_SESSION=${shellQuote(artifacts.sessionFile)}`);
+		env.push(`PI_SUBAGENT_ID=${shellQuote(resolved.id)}`);
+		env.push(`PI_SUBAGENT_ACTIVITY_FILE=${shellQuote(artifacts.activityFile)}`);
+    env.push(
+      `PI_SUBAGENT_SETTLED_EVENTS_FILE=${shellQuote(artifacts.settledEventsFile)}`,
+    );
+		env.push(`PI_SUBAGENT_SURFACE=${shellQuote(artifacts.surface)}`);
+
+	const piCommand =
+		`cd ${shellQuote(artifacts.targetCwd)} && ` +
+		`${env.join(" ")} ${parts.join(" ")}`;
+	return `${piCommand}; echo '__SUBAGENT_DONE_'$?'__'`;
+}
+
+function startPiProcess(
+	resolved: ResolvedLaunch,
+	artifacts: PreparedArtifacts,
+	command: string,
+	operations: PiLaunchOperations,
+): string {
+	const launchScriptFile = join(
+		resolved.artifactDir,
+		"subagent-scripts",
+		`${safeName(resolved.request.name) || "subagent"}-${resolved.id}.sh`,
+	);
+	if (artifacts.worktree) {
+		persistWorktreeResult(artifacts.worktree, "running");
+	}
+	return operations.runScript(artifacts.surface, command, {
+		scriptPath: launchScriptFile,
+		scriptPreamble: [
+			`# Subagent launch script for ${resolved.request.name}`,
+			`# Generated: ${new Date().toISOString()}`,
+			`# Session: ${artifacts.sessionFile}`,
+			`# Surface: ${artifacts.surface}`,
+		].join("\n"),
+	});
+}
+
+function createRunningChild(
+	resolved: ResolvedLaunch,
+	artifacts: PreparedArtifacts,
+	launchScriptFile: string,
+	sessionBaseline: SessionBaselineCursor,
+): PiRunningChild {
+	return {
+		lineage: resolved.lineage,
+		executionOwner: resolved.request.executionOwner,
+		...(resolved.launchPane ? { launchPane: resolved.launchPane } : {}),
+		...(resolved.request.replication ? { replication: true, replicaWorkFile: resolved.request.replication.recordFile } : {}),
+		id: resolved.id,
+		name: resolved.request.name,
+		task: resolved.request.task,
+		agent: resolved.request.agent,
+		surface: artifacts.surface,
+		startTime: resolved.startTime,
+		...(artifacts.tabId ? { tabId: artifacts.tabId } : {}),
+		sessionFile: artifacts.sessionFile,
+		launchScriptFile,
+		activityFile: artifacts.activityFile,
+    settledEventsFile: artifacts.settledEventsFile,
+		interactive: resolved.request.behavior.interactive,
+		sessionBaseline,
+		runtimePlan: resolved.request.runtimePlan,
+		worktree: artifacts.worktree,
+
+		...(artifacts.worktree?.workspaceId
+			? { recoveryWorkspace: { id: artifacts.worktree.workspaceId, cwd: artifacts.worktree.path } }
+			: {}),
+		lifecycle: createLifecycle(resolved.startTime),
+	};
+}
+
+async function launchResumedPiSubagent(
+	request: ResumePiLaunchRequest,
+	operations: PiLaunchOperations,
+): Promise<PiRunningChild> {
+	let id = request.id ?? randomUUID();
+	const autoExit = request.behavior?.autoExit ?? true;
+	const artifactDir = join(request.parent.sessionDir, "artifacts", request.parent.sessionId);
+	const inherited = readSessionBinding(request.parent.sessionFile)?.child?.lineage ?? lineageFromEnvironment();
+	const priorBinding = readSessionBinding(request.sessionFile);
+	let prior: LineageRegistration | undefined = priorBinding?.child?.lineage;
+	try {
+		prior ??= JSON.parse(readFileSync(`${request.sessionFile}.lineage.json`, "utf8")) as LineageRegistration;
+		if (!prior.rootDir || !prior.rootId || !prior.nodeId) prior = undefined;
+	} catch {}
+	const reusable = prior && !isLineageNodeDrained(reduceLineage(prior.rootDir), prior.nodeId);
+
+	if (reusable && prior) id = prior.nodeId;
+	const lineage: LineageRegistration = (reusable ? prior : registerLineage({
+		artifactDir,
+		nodeId: id,
+		parentNodeId: inherited?.nodeId,
+		parentSessionId: request.parent.sessionId,
+		parentSessionFile: request.parent.sessionFile,
+		launchKind: "resume",
+		inheritedRootDir: inherited?.rootDir,
+		inheritedRootId: inherited?.rootId,
+	}))!;
+	const storeDir = sessionBindingStore(request.parent.sessionFile);
+	registerSessionLineage(storeDir, request.parent.sessionId, lineage.rootDir);
+	const interactive = request.behavior?.interactive ?? !autoExit;
+	const executionOwner = request.executionOwner;
+	const startTime = Date.now();
+	const surface = request.surface ?? operations.createPane(request.name, request.workspace);
+	const allocatedSurface = request.surface === undefined;
+	try {
+		const tabId = getPaneTabId(surface);
+		await operations.waitForShellReady(surface);
+		const activityFile = getSubagentActivityFile(artifactDir, id);
+		writeFileSync(`${request.sessionFile}.lineage.json`, JSON.stringify(lineage), "utf8");
+		const settledEventsFile = getSubagentSettledEventsFile(artifactDir, id);
+		mkdirSync(dirname(activityFile), { recursive: true });
+
+		if (lineage) {
+			appendLineageEvent(lineage.rootDir, `metadata:${lineage.nodeId}:${startTime}`, "launch_metadata", lineage.nodeId, {
+				name: request.name,
+				executionOwner,
+				task: request.message ?? "resumed session",
+				surface,
+				sessionFile: request.sessionFile,
+				tabId,
+				activityFile,
+				settledEventsFile,
+				startTime,
+				interactive,
+				autoExit,
+				...(request.workspace ? { workspaceId: request.workspace.id, cwd: request.workspace.cwd } : {}),
+			});
+		}
+		let messageFile: string | undefined;
+		if (request.message) {
+			messageFile = join(
+				artifactDir,
+				"subagent-resume",
+				`${safeName(request.name) || "resume"}-${timestampForFile(false)}.md`,
+			);
+			mkdirSync(dirname(messageFile), { recursive: true });
+			writeFileSync(messageFile, request.message, "utf8");
+		}
+
+		// Resume must use the existing session position from before the new Pi
+		// process starts, not a line count observed after launch.
+		const sessionBaseline = captureSessionBaseline(request.sessionFile);
+		seedSessionBinding(request.sessionFile, {
+			version: 1, storeDir,
+			child: {
+				lineage,
+				environment: {
+					...priorBinding?.child?.environment,
+					...lineageEnvironment(lineage),
+					PI_SUBAGENT_NAME: request.name,
+					PI_SUBAGENT_ID: id,
+					PI_SUBAGENT_ACTIVITY_FILE: activityFile,
+					PI_SUBAGENT_SETTLED_EVENTS_FILE: settledEventsFile,
+					PI_SUBAGENT_AUTO_EXIT: autoExit ? "1" : "0",
+					PI_SUBAGENT_RESUME_BASELINE_ASSISTANTS: JSON.stringify(sessionBaseline.assistantEntryIds),
+					PI_SUBAGENT_RESUME: "1",
+				},
+			},
+		});
+		const env = [
+			...(process.env.PI_CODING_AGENT_DIR
+				? [`PI_CODING_AGENT_DIR=${shellQuote(process.env.PI_CODING_AGENT_DIR)}`]
+				: []),
+			"PI_SUBAGENT_LAUNCHER_PID=$$",
+			...Object.entries(lineageEnvironment(lineage)).map(([key, value]) => `${key}=${shellQuote(value)}`),
+			`PI_SUBAGENT_NAME=${shellQuote(request.name)}`,
+			`PI_SUBAGENT_SESSION=${shellQuote(request.sessionFile)}`,
+			`PI_SUBAGENT_ID=${shellQuote(id)}`,
+			`PI_SUBAGENT_ACTIVITY_FILE=${shellQuote(activityFile)}`,
+			`PI_SUBAGENT_SETTLED_EVENTS_FILE=${shellQuote(settledEventsFile)}`,
+			`PI_SUBAGENT_AUTO_EXIT=${autoExit ? "1" : "0"}`,
+			`PI_SUBAGENT_RESUME_BASELINE_ASSISTANTS=${shellQuote(JSON.stringify(sessionBaseline.assistantEntryIds))}`,
+			"PI_SUBAGENT_RESUME=1",
+		];
+		const command = [
+			...env,
+			"pi",
+			"--session",
+			shellQuote(request.sessionFile),
+			...(JSON.parse(priorBinding?.child?.environment.PI_SUBAGENT_REPLICATION_EXTENSIONS ?? "[]") as string[]).map(shellQuote),
+			"-e",
+			shellQuote(join(SUBAGENTS_DIR, "subagent-done.ts")),
+			...(messageFile ? [shellQuote(`@${messageFile}`)] : []),
+		].join(" ");
+		const launchScriptFile = operations.runScript(
+			surface,
+			`${command}; echo '__SUBAGENT_DONE_'$?'__'`,
+			{
+				scriptPath: join(
+					artifactDir,
+					"subagent-scripts",
+					`${safeName(request.name) || "resume"}-resume-${Date.now()}.sh`,
+				),
+				scriptPreamble: [
+					`# Subagent resume script for ${request.name}`,
+					`# Generated: ${new Date().toISOString()}`,
+					`# Session: ${request.sessionFile}`,
+					`# Surface: ${surface}`,
+					...(messageFile ? [`# Resume message file: ${messageFile}`] : []),
+				].join("\n"),
+			},
+		);
+		return {
+			lineage,
+			executionOwner,
+			id,
+			name: request.name,
+			task: request.message ?? "resumed session",
+			surface,
+			startTime,
+			sessionFile: request.sessionFile,
+			...(tabId ? { tabId } : {}),
+			launchScriptFile,
+			activityFile,
+			settledEventsFile,
+			...(priorBinding?.child?.environment.PI_SUBAGENT_REPLICATION === "1" ? { replication: true } : {}),
+			interactive,
+			runtimePlan: undefined,
+			sessionBaseline,
+			...(request.workspace ? { recoveryWorkspace: request.workspace } : {}),
+			lifecycle: createLifecycle(startTime),
+		};
+	} catch (error) {
+		if (allocatedSurface) {
+			try {
+				operations.closePane?.(surface);
+			} catch {
+				// The original launch failure remains authoritative.
+			}
+		}
+		throw error;
+	}
+}
+
+export function buildSubagentToolAllowlist(
+	tools?: string,
+	_autoExit = false,
+	_includeControlTools = true,
+): string | null {
+	const requested = (tools ?? "")
+		.split(",")
+		.map((tool) => tool.trim())
+		.filter(Boolean);
+	if (requested.length === 0) return null;
+	const removed = new Set(["subagent", "subagent_resume", "subagent_interrupt", "subagent_cancel", "subagents_list", "caller_ping", "subagent_done"]);
+	return [...new Set(requested.filter((tool) => !removed.has(tool)))].join(",");
+}
+
+/** Normalize requested skill names for safe, deterministic child transport. */
+export function normalizeSkillNames(skills: string): string[] {
+	return [...new Set(
+		skills
+			.split(",")
+			.map((skill) => skill.trim())
+			.filter(Boolean),
+	)];
+}
+
+function getDefaultSessionDirFor(cwd: string, agentDir: string): string {
+	const safePath = `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+	const sessionDir = join(agentDir, "sessions", safePath);
+	mkdirSync(sessionDir, { recursive: true });
+	return sessionDir;
+}
+
+function timestampForFile(includeMilliseconds = true): string {
+	return (
+		new Date()
+			.toISOString()
+			.replace(/[:.]/g, "-")
+			.slice(0, includeMilliseconds ? 23 : 19) +
+		(includeMilliseconds ? "Z" : "")
+	);
+}
+
+function safeName(name: string): string {
+	return name
+		.toLowerCase()
+		.replace(/[^a-z0-9\s-]/g, "")
+		.replace(/\s+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-|-$/g, "");
+}
+
+function resolveGitCommit(cwd: string, ref: string): string {
+	return execFileSync("git", ["rev-parse", "--verify", `${ref}^{commit}`], {
+		cwd,
+		encoding: "utf8",
+	}).trim();
+}
+
+export function writeWorktreeManifest(
+	path: string,
+	value: Record<string, unknown>,
+): void {
+	mkdirSync(dirname(path), { recursive: true });
+	let existing: Record<string, unknown> = {};
+	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",
+	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 errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}