pi-subagents 0.64.0 → 0.65.1

package/src/intercom/supervisor-ui.ts

@@ -0,0 +1,244 @@
+import type { EntryRenderOptions, MessageRenderOptions, Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
+import { safeTerminalText } from "../shared/display-text.ts";
+
+export const SUPERVISOR_REQUEST_MESSAGE_TYPE = "subagent_supervisor_request";
+export const SUPERVISOR_REPLY_ENTRY_TYPE = "subagent_supervisor_reply";
+
+export type SupervisorReason = "need_decision" | "interview_request" | "progress_update";
+
+export interface SupervisorRequestMessageDetails {
+	id?: string;
+	requestId?: string;
+	reason?: SupervisorReason;
+	expectsReply?: boolean;
+	runId?: string;
+	agent?: string;
+	childIndex?: number;
+	childTarget?: string;
+	interview?: unknown;
+	requestBody?: string;
+	replyHint?: string;
+}
+
+export interface SupervisorReplyEntryData {
+	requestId: string;
+	reason?: SupervisorReason;
+	runId: string;
+	agent: string;
+	childIndex: number;
+	childTarget?: string;
+	message: string;
+	createdAt: number;
+}
+
+interface SupervisorMessageLike {
+	content: unknown;
+	details?: unknown;
+}
+
+interface SupervisorEntryLike {
+	data?: unknown;
+}
+
+const MAX_FIELD_CHARS = 512;
+const MAX_BODY_CHARS = 8_000;
+const MAX_INTERVIEW_CHARS = 4_000;
+const MAX_RENDER_LINES = 36;
+const TRUNCATION_MARKER = "[truncated]";
+
+export function supervisorReplyHint(requestId: string): string {
+	return `subagent_supervisor({ action: "reply", replyTo: "${requestId}", message: "..." })`;
+}
+
+function boundedText(value: string, maxChars: number): string {
+	const safe = safeTerminalText(value);
+	if (safe.length <= maxChars) return safe;
+	const prefixLength = Math.max(0, maxChars - TRUNCATION_MARKER.length - 1);
+	let prefix = "";
+	for (const character of safe) {
+		if (prefix.length + character.length > prefixLength) break;
+		prefix += character;
+	}
+	return `${prefix} ${TRUNCATION_MARKER}`;
+}
+
+function displayText(value: string, maxChars: number, expanded: boolean): string {
+	return expanded ? safeTerminalText(value) : boundedText(value, maxChars);
+}
+
+function boundedField(value: unknown, fallback = "unknown"): string {
+	return boundedText(typeof value === "string" ? value : value === undefined ? fallback : String(value), MAX_FIELD_CHARS);
+}
+
+function contentText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((part) => {
+			if (!part || typeof part !== "object") return "";
+			const text = (part as { text?: unknown }).text;
+			return typeof text === "string" ? text : "";
+		})
+		.filter(Boolean)
+		.join("\n");
+}
+
+function interviewText(interview: unknown, expanded: boolean): string {
+	let serialized: string;
+	try {
+		serialized = JSON.stringify(interview, null, 2) ?? String(interview);
+	} catch {
+		serialized = "[unavailable]";
+	}
+	return displayText(serialized, MAX_INTERVIEW_CHARS, expanded);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isSupervisorReason(value: unknown): value is SupervisorReason {
+	return value === "need_decision" || value === "interview_request" || value === "progress_update";
+}
+
+function optionalString(value: unknown): boolean {
+	return value === undefined || typeof value === "string";
+}
+
+function requestDetails(value: unknown): SupervisorRequestMessageDetails | undefined {
+	if (!isRecord(value)) return undefined;
+	if (!optionalString(value.id) || !optionalString(value.requestId) || !optionalString(value.replyHint) || !optionalString(value.requestBody) || !optionalString(value.runId) || !optionalString(value.agent) || !optionalString(value.childTarget)) return undefined;
+	if (value.reason !== undefined && !isSupervisorReason(value.reason)) return undefined;
+	if (value.expectsReply !== undefined && typeof value.expectsReply !== "boolean") return undefined;
+	if (value.childIndex !== undefined && (typeof value.childIndex !== "number" || !Number.isFinite(value.childIndex))) return undefined;
+	return value;
+}
+
+function replyData(value: unknown): SupervisorReplyEntryData | undefined {
+	if (!isRecord(value)) return undefined;
+	if (typeof value.requestId !== "string" || typeof value.runId !== "string" || typeof value.agent !== "string" || typeof value.message !== "string") return undefined;
+	if (value.reason !== undefined && !isSupervisorReason(value.reason)) return undefined;
+	if (value.childTarget !== undefined && typeof value.childTarget !== "string") return undefined;
+	if (typeof value.childIndex !== "number" || !Number.isFinite(value.childIndex) || typeof value.createdAt !== "number" || !Number.isFinite(value.createdAt)) return undefined;
+	return {
+		requestId: value.requestId,
+		...(value.reason === undefined ? {} : { reason: value.reason }),
+		runId: value.runId,
+		agent: value.agent,
+		childIndex: value.childIndex,
+		...(value.childTarget === undefined ? {} : { childTarget: value.childTarget }),
+		message: value.message,
+		createdAt: value.createdAt,
+	};
+}
+
+function withRequestId(details: SupervisorRequestMessageDetails): string {
+	return boundedField(details.requestId ?? details.id);
+}
+
+function requestHeading(reason: SupervisorReason | undefined): string {
+	if (reason === "interview_request") return "⚠ Supervisor interview request";
+	if (reason === "progress_update") return "ℹ Supervisor progress update";
+	return "⚠ Supervisor decision request";
+}
+
+function requestLines(message: SupervisorMessageLike, details: SupervisorRequestMessageDetails, expanded: boolean): string[] {
+	const requestId = withRequestId(details);
+	const lines = [
+		`Reason: ${boundedField(details.reason)}`,
+		`Run: ${boundedField(details.runId)}`,
+		`Agent: ${boundedField(details.agent)}`,
+		`Child index: ${boundedField(details.childIndex)}`,
+	];
+	if (details.childTarget) lines.push(`Child target: ${boundedField(details.childTarget)}`);
+	lines.push(`Request ID: ${requestId}`);
+	if (details.expectsReply) lines.push(`Reply with: ${displayText(details.replyHint ?? supervisorReplyHint(requestId), MAX_BODY_CHARS, expanded)}`);
+	lines.push("", "Request:", displayText((details.requestBody ?? contentText(message.content)) || "(no request body)", MAX_BODY_CHARS, expanded));
+	if (details.interview !== undefined) lines.push("", "Interview shape:", interviewText(details.interview, expanded));
+	return lines;
+}
+
+function replyLines(data: SupervisorReplyEntryData, expanded: boolean): string[] {
+	const requestId = boundedField(data.requestId);
+	const lines = [
+		...(data.reason ? [`Reason: ${boundedField(data.reason)}`] : []),
+		`Run: ${boundedField(data.runId)}`,
+		`Agent: ${boundedField(data.agent)}`,
+		`Child index: ${boundedField(data.childIndex)}`,
+	];
+	if (data.childTarget) lines.push(`Child target: ${boundedField(data.childTarget)}`);
+	lines.push(`Reply to: ${requestId}`, "", "Reply:", displayText(data.message || "(empty reply)", MAX_BODY_CHARS, expanded));
+	return lines;
+}
+
+function renderCard(lines: string[], heading: string, theme: Theme, width: number, expanded: boolean): string[] {
+	const safeWidth = Math.max(0, Math.floor(width));
+	if (safeWidth < 3) return [truncateToWidth(heading, safeWidth, "")];
+	const bodyWidth = safeWidth - 2;
+	const headerText = truncateToWidth(` ${heading} `, bodyWidth, "");
+	const headerPadding = Math.max(0, bodyWidth - visibleWidth(headerText));
+	const border = (text: string) => theme.fg("accent", text);
+	const rendered = [border(`╭${headerText}${"─".repeat(headerPadding)}╮`)];
+	let hidden = false;
+	let interiorLines = 0;
+	for (const line of lines) {
+		const wrapped = wrapTextWithAnsi(line, Math.max(1, bodyWidth));
+		for (const wrappedLine of wrapped.length > 0 ? wrapped : [""]) {
+			if (!expanded && interiorLines >= MAX_RENDER_LINES) {
+				hidden = true;
+				break;
+			}
+			const text = truncateToWidth(wrappedLine, bodyWidth, "");
+			rendered.push(border(`│${text}${" ".repeat(Math.max(0, bodyWidth - visibleWidth(text)))}│`));
+			interiorLines++;
+		}
+		if (hidden) break;
+	}
+	if (hidden) {
+		const text = truncateToWidth(TRUNCATION_MARKER, bodyWidth, "");
+		rendered.push(border(`│${text}${" ".repeat(Math.max(0, bodyWidth - visibleWidth(text)))}│`));
+	}
+	rendered.push(border(`╰${"─".repeat(bodyWidth)}╯`));
+	return rendered;
+}
+
+class SupervisorCardComponent implements Component {
+	private readonly expanded: boolean;
+	private readonly heading: string;
+	private readonly lines: string[];
+	private readonly theme: Theme;
+
+	constructor(heading: string, lines: string[], theme: Theme, expanded: boolean) {
+		this.expanded = expanded;
+		this.heading = heading;
+		this.lines = lines;
+		this.theme = theme;
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		return renderCard(this.lines, this.heading, this.theme, width, this.expanded);
+	}
+}
+
+export function renderSupervisorRequest(
+	message: SupervisorMessageLike,
+	options: MessageRenderOptions,
+	theme: Theme,
+): Component | undefined {
+	const details = requestDetails(message.details);
+	if (!details) return undefined;
+	return new SupervisorCardComponent(requestHeading(details.reason), requestLines(message, details, options.expanded), theme, options.expanded);
+}
+
+export function renderSupervisorReply(
+	entry: SupervisorEntryLike,
+	options: EntryRenderOptions,
+	theme: Theme,
+): Component | undefined {
+	const data = replyData(entry.data);
+	if (!data) return undefined;
+	return new SupervisorCardComponent("↩ Supervisor reply to child", replyLines(data, options.expanded), theme, options.expanded);
+}

package/src/missions/workflow-state.ts

@@ -18,6 +18,12 @@ export interface MissionWorkflowState {
 	set(key: string, value: unknown): void;
 }
 
+export interface MissionWorkflowStateOptions {
+	isProcessAlive?: (pid: number) => boolean;
+	getProcessStartKey?: (pid: number) => string | undefined;
+	retryDelaysMs?: readonly number[];
+}
+
 export function missionStatePath(location: MissionStoreLocation, missionId: string): string {
 	return path.join(location.missionDir, validateMissionId(missionId), "state.json");
 }
@@ -66,13 +72,22 @@ function windowsProcessStartKey(pid: number): string | undefined {
 	}
 }
 
+let currentProcessKey: string | undefined | null = null;
+
 function processStartKey(pid: number): string | undefined {
+	// Foreign PIDs can be reused while this process lives, so resolve them afresh.
+	if (pid !== process.pid) return computeProcessStartKey(pid);
+	if (currentProcessKey === null) currentProcessKey = computeProcessStartKey(pid);
+	return currentProcessKey;
+}
+
+function computeProcessStartKey(pid: number): string | undefined {
 	if (process.platform === "linux") return linuxProcessStartKey(pid) ?? psProcessStartKey(pid);
 	if (process.platform === "win32") return windowsProcessStartKey(pid);
 	return undefined;
 }
 
-const CURRENT_PROCESS_KEY = processStartKey(process.pid);
+type StateLockOptions = Required<MissionWorkflowStateOptions>;
 
 function readStateLockOwner(lockPath: string): StateLockOwner | undefined {
 	try {
@@ -91,13 +106,13 @@ function readStateLockOwner(lockPath: string): StateLockOwner | undefined {
 	return undefined;
 }
 
-function stateLockIsStale(lockPath: string, now = Date.now()): boolean {
+function stateLockIsStale(lockPath: string, options: StateLockOptions, now = Date.now()): boolean {
 	const owner = readStateLockOwner(lockPath);
 	if (owner) {
-		if (!isProcessAlive(owner.pid)) return true;
+		if (!options.isProcessAlive(owner.pid)) return true;
 		if (owner.processKey) {
-			const currentProcessKey = owner.pid === process.pid ? CURRENT_PROCESS_KEY : processStartKey(owner.pid);
-			if (currentProcessKey) return owner.processKey !== currentProcessKey;
+			const observedProcessKey = options.getProcessStartKey(owner.pid);
+			if (observedProcessKey) return owner.processKey !== observedProcessKey;
 			if (owner.pid === process.pid) return true;
 		}
 		return false;
@@ -140,11 +155,11 @@ function waitForStateLock(delayMs: number | undefined, lockPath: string): void {
 	waitForFileSystemRetry(delayMs);
 }
 
-function reclaimStaleStateLock(lockPath: string, reclaimPath: string): boolean {
-	if (!stateLockIsStale(lockPath)) return false;
+function reclaimStaleStateLock(lockPath: string, reclaimPath: string, options: StateLockOptions): boolean {
+	if (!stateLockIsStale(lockPath, options)) return false;
 	if (!tryMakeDirectory(reclaimPath, 0o700)) return false;
 	try {
-		if (!stateLockIsStale(lockPath)) return false;
+		if (!stateLockIsStale(lockPath, options)) return false;
 		fs.rmSync(lockPath, { recursive: true, force: true });
 		return true;
 	} finally {
@@ -152,7 +167,7 @@ function reclaimStaleStateLock(lockPath: string, reclaimPath: string): boolean {
 	}
 }
 
-function withStateFileLock<T>(filePath: string, operation: () => T): T {
+function withStateFileLock<T>(filePath: string, operation: () => T, options: StateLockOptions): T {
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	const lockPath = `${filePath}.lock`;
 	const reclaimPath = `${lockPath}.reclaim`;
@@ -163,7 +178,7 @@ function withStateFileLock<T>(filePath: string, operation: () => T): T {
 				fs.rmSync(reclaimPath, { recursive: true, force: true });
 				continue;
 			}
-			waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
+			waitForStateLock(options.retryDelaysMs[attempt], lockPath);
 			continue;
 		}
 		let acquired = false;
@@ -171,17 +186,18 @@ function withStateFileLock<T>(filePath: string, operation: () => T): T {
 			acquired = tryMakeDirectory(lockPath, 0o700);
 		} catch (error) {
 			if (isRetryableFileSystemError(error)) {
-				waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
+				waitForStateLock(options.retryDelaysMs[attempt], lockPath);
 				continue;
 			}
 			throw new Error(`Failed to acquire mission state lock '${lockPath}': ${error instanceof Error ? error.message : String(error)}`);
 		}
 		if (!acquired) {
-			if (reclaimStaleStateLock(lockPath, reclaimPath)) continue;
-			waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
+			if (reclaimStaleStateLock(lockPath, reclaimPath, options)) continue;
+			waitForStateLock(options.retryDelaysMs[attempt], lockPath);
 			continue;
 		}
-		owner = { pid: process.pid, token: randomUUID(), createdAt: Date.now(), ...(CURRENT_PROCESS_KEY ? { processKey: CURRENT_PROCESS_KEY } : {}) };
+		const key = options.getProcessStartKey(process.pid);
+		owner = { pid: process.pid, token: randomUUID(), createdAt: Date.now(), ...(key ? { processKey: key } : {}) };
 		try {
 			fs.writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify(owner), { encoding: "utf-8", mode: 0o600 });
 		} catch (error) {
@@ -205,8 +221,13 @@ function validateStateKey(value: unknown): string {
 	return value;
 }
 
-export function createMissionWorkflowState(location: MissionStoreLocation, missionId: string): MissionWorkflowState {
+export function createMissionWorkflowState(location: MissionStoreLocation, missionId: string, options: MissionWorkflowStateOptions = {}): MissionWorkflowState {
 	const filePath = missionStatePath(location, missionId);
+	const lockOptions: StateLockOptions = {
+		isProcessAlive: options.isProcessAlive ?? isProcessAlive,
+		getProcessStartKey: options.getProcessStartKey ?? processStartKey,
+		retryDelaysMs: options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS,
+	};
 	let loaded = false;
 	let values: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
 
@@ -254,7 +275,7 @@ export function createMissionWorkflowState(location: MissionStoreLocation, missi
 				writePrivateAtomicJson(filePath, next);
 				values = next;
 				loaded = true;
-			});
+			}, lockOptions);
 		},
 	};
 }

package/src/runs/background/async-execution.ts

@@ -14,13 +14,14 @@ import { appendAgentRefinementOverlay } from "../../agents/agent-refinements.ts"
 import { createAtomicJsonWriter, writePrivateAtomicJson } from "../../shared/atomic-json.ts";
 import { currentCompletionOwnerId } from "../../shared/completion-owner.ts";
 import { planChildLaunch, resolveStepBehavior, suppressProgressForReadOnlyTask, type ResolvedStepBehavior } from "../shared/child-launch-plan.ts";
-import { applyThinkingSuffix, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/pi-args.ts";
+import { applyThinkingSuffix, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/child-tool-plan.ts";
 import { injectOutputPathSystemPrompt, injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { applyWatchdogLaunchRules, sendRuleViolationWarning } from "../../watchdog/rules.ts";
 import { buildChainInstructions, isDynamicParallelStep, isParallelStep, resolveExistingReadInstructionPaths, resolveExistingReadPaths, writeInitialProgressFile, type ChainStep, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
 import type { RunnerStep } from "../shared/parallel-utils.ts";
 import type { ContextMode } from "../shared/context-mode.ts";
-import { resolveInstalledPiPackageRoot, resolvePiPackageRoot } from "../shared/pi-spawn.ts";
+import { PI_CODING_AGENT_PACKAGE, resolveInstalledPiPackageRoot, resolvePiPackageRoot } from "../shared/pi-spawn.ts";
+import { JITI_ALIAS_ENV, resolveHostPeerAliases } from "./runner-aliases.ts";
 import { preflightLaunchCwd } from "../shared/launch-cwd.ts";
 import { resolveNodeExecutable } from "../../shared/node-executable.ts";
 import { backgroundProcessOptions } from "../shared/background-process-options.ts";
@@ -31,7 +32,7 @@ import { buildModelCandidates, resolveEffectiveSubagentModel, resolveModelOrigin
 import { resolveToolTimeoutMs, toolTimeoutFromEnv } from "../shared/tool-timeout.ts";
 import { resolveModelScopesForAgent, type ModelScopeConfig } from "../shared/model-scope.ts";
 import { findModelInfo, resolveEffectiveThinking } from "../../shared/model-info.ts";
-import { assertThinkingWithinCeiling, decodeThinkingCeiling, intersectThinkingCeilings, SUBAGENT_THINKING_CEILING_ENV, type ThinkingLevel } from "../../shared/thinking-ceiling.ts";
+import { assertThinkingWithinCeiling, intersectThinkingCeilings, type ThinkingLevel } from "../../shared/thinking-ceiling.ts";
 import { resolveExpectedWorktreeAgentCwd, resolveWorktreeProvider, shouldDeferWorktreeCwd, WORKTREE_AGENT_CWD_PLACEHOLDER } from "../shared/worktree.ts";
 import { buildWorkflowGraphSnapshot } from "../shared/workflow-graph.ts";
 import { ChainOutputValidationError, validateChainOutputBindings } from "../shared/chain-outputs.ts";
@@ -65,7 +66,10 @@ import {
 	getAsyncConfigPath,
 	resolveChildMaxSubagentDepth,
 } from "../../shared/types.ts";
-import { nestedResultsPath, nestedSummaryFromAsyncStatus, resolveInheritedNestedRouteFromEnv, resolveNestedParentAddressFromEnv, writeNestedEvent } from "../shared/nested-events.ts";
+import { inheritedNestedParentAddressOf, inheritedNestedRouteOf, nestedResultsPath, nestedSummaryFromAsyncStatus, writeNestedEvent } from "../shared/nested-events.ts";
+import type { ChildRuntimeConfig } from "../shared/child-runtime-config.ts";
+import { childSessionFactoryModule } from "../shared/child-session.ts";
+import { inheritedChildRuntime } from "../shared/child-launch.ts";
 import { resultFilePath } from "./result-files.ts";
 import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
 import { usageBudgetState } from "../shared/usage-budget.ts";
@@ -75,7 +79,7 @@ import { finalizeProcessTerminal, initializeProcessTerminal, readProcessTerminal
 import type { ActiveAsyncCapacityHandle } from "./active-async-capacity.ts";
 import { statusStepDescription } from "./chain-append.ts";
 import { SUBAGENT_PROCESS_TERMINAL_EVENT } from "../../shared/types.ts";
-import { assertAgentAllowedByCapabilityCeiling, decodeSubagentCapabilityCeiling, intersectSubagentCapabilityCeilings, resolveCurrentSubagentCapabilityCeiling, SUBAGENT_CAPABILITY_CEILING_ENV, type ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
+import { assertAgentAllowedByCapabilityCeiling, intersectSubagentCapabilityCeilings, resolveCurrentSubagentCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
 import { agentDefinitionDigest, launchBindingDigest } from "../../shared/launch-contract.ts";
 import { resolvePermissionRules, type PermissionConfig } from "../shared/permissions.ts";
 import { normalizeExtensionBindings, omitExtensionBindingsEnv, type ExtensionBindings } from "../shared/extension-bindings.ts";
@@ -142,8 +146,11 @@ interface AsyncExecutionContext {
 	currentModel?: ParentModel;
 	/** Optional model-scope enforcement resolved from subagent settings. */
 	modelScope?: ModelScopeConfig;
+	modelResponseAliases?: Record<string, string[]>;
 	/** Whether the parent session has an interactive UI. */
 	interactive?: boolean;
+	/** The executor's own child runtime when the launch comes from an in-process child. */
+	childRuntime?: ChildRuntimeConfig;
 }
 
 export const DEFAULT_ASYNC_TIMEOUT_MS = 30 * 60 * 1000;
@@ -179,6 +186,7 @@ interface AsyncChainParams {
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
 	worktreeBaseDir?: string;
+	baseRef?: string;
 	worktreeProvider?: import("../../shared/types.ts").WorktreeProvider;
 	worktreeBranchPrefix?: string;
 	controlConfig?: ResolvedControlConfig;
@@ -248,6 +256,7 @@ interface AsyncSingleParams {
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
 	worktreeBaseDir?: string;
+	baseRef?: string;
 	worktreeProvider?: import("../../shared/types.ts").WorktreeProvider;
 	worktreeBranchPrefix?: string;
 	worktree?: boolean;
@@ -536,6 +545,13 @@ function spawnRunner(cfg: object, suffix: string, cwd: string, initialStatus: Om
 	if (!jitiCliPath) {
 		return { error: "upstream jiti for TypeScript execution could not be found; ensure package dependencies are installed" };
 	}
+	if (!piPackageRoot) {
+		return { error: `Background children require pi installed as the npm package (${PI_CODING_AGENT_PACKAGE}); a standalone pi binary has no package directory, so the async runner cannot create child sessions. Run this child in the foreground (async: false) or install pi from npm.` };
+	}
+	const hostPeerAliases = resolveHostPeerAliases(piPackageRoot);
+	if (hostPeerAliases.missing.length > 0) {
+		return { error: `Background children require pi installed as the npm package (${PI_CODING_AGENT_PACKAGE}) with its dependencies; ${piPackageRoot} does not provide ${hostPeerAliases.missing.join(", ")}, so the async runner cannot create child sessions. A standalone pi binary cannot run background children.` };
+	}
 
 	fs.mkdirSync(TEMP_ROOT_DIR, { recursive: true });
 	const cfgPath = getAsyncConfigPath(suffix);
@@ -571,13 +587,17 @@ function spawnRunner(cfg: object, suffix: string, cwd: string, initialStatus: Om
 			stdoutFd = fs.openSync(logPaths.stdoutPath, "a");
 			stderrFd = fs.openSync(logPaths.stderrPath, "a");
 		}
-		const proc = spawn(nodeCommand, [jitiCliPath, runner, cfgPath], {
+		const preload = hostPeerAliases.supplemental.length > 0
+			? ["--import", new URL("../../../runner-server-preload.mjs", import.meta.url).href]
+			: [];
+		const proc = spawn(nodeCommand, [...preload, jitiCliPath, runner, cfgPath], {
 			cwd,
 			...backgroundProcessOptions(),
 			stdio: ["ignore", stdoutFd ?? "ignore", stderrFd ?? "ignore"],
 			env: {
 				...omitExtensionBindingsEnv(process.env),
-				...(piPackageRoot ? { [PI_CODING_AGENT_PACKAGE_ROOT_ENV]: piPackageRoot } : {}),
+				[PI_CODING_AGENT_PACKAGE_ROOT_ENV]: piPackageRoot,
+				[JITI_ALIAS_ENV]: JSON.stringify(hostPeerAliases.aliases),
 			},
 		});
 		closeFd(stdoutFd);
@@ -833,7 +853,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 			if (unsupported.length > 0) throw new AsyncStartValidationError(`Agent '${a.name}' uses runner.type='${externalRunnerType}' and does not support: ${unsupported.join(", ")}.`);
 		}
 		try {
-			assertAgentAllowedByCapabilityCeiling(a.name, intersectSubagentCapabilityCeilings(params.capabilityCeiling, decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV])));
+			assertAgentAllowedByCapabilityCeiling(a.name, intersectSubagentCapabilityCeilings(params.capabilityCeiling, ctx.childRuntime?.capabilityCeiling));
 		} catch (error) {
 			throw new AsyncStartValidationError(error instanceof Error ? error.message : String(error));
 		}
@@ -913,7 +933,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		const thinkingCeiling = externalRunner ? undefined : intersectThinkingCeilings(
 			params.thinkingCeiling,
 			a.maxThinking,
-			decodeThinkingCeiling(process.env[SUBAGENT_THINKING_CEILING_ENV]),
+			ctx.childRuntime?.thinkingCeiling,
 		);
 		if (!externalRunner) {
 			try {
@@ -957,7 +977,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 			model,
 			modelCandidates,
 			capabilityCeiling: params.capabilityCeiling,
-			inheritedCapabilityCeiling: decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]),
+			inheritedCapabilityCeiling: ctx.childRuntime?.capabilityCeiling,
 			agentName: a.name,
 			permissionRules,
 			runtimeSnapshotHost: ctx.pi,
@@ -1002,11 +1022,10 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 			thinking: resolveEffectiveThinking(model, effectiveThinking),
 			...(thinkingCeiling ? { thinkingCeiling } : {}),
 			launchResolvedExtensions,
-			...(toolPlan.mcpConfig ? { mcpConfig: toolPlan.mcpConfig } : {}),
-			...(toolPlan.runtimeServerNames ? { runtimeServerNames: toolPlan.runtimeServerNames } : {}),
 			modelCandidates: externalRunner ? undefined : modelCandidates,
 			...(primaryModelFromParent ? { skipPrimaryModelVerification: true } : {}),
 			...(availableModels && availableModels.length > 0 ? { modelVerificationRegistry: availableModels } : {}),
+			...(ctx.modelResponseAliases ? { modelResponseAliases: ctx.modelResponseAliases } : {}),
 			tools: a.tools,
 			excludeTools: a.excludeTools,
 			allowNestedSubagents: a.allowNestedSubagents,
@@ -1207,6 +1226,7 @@ export function executeAsyncChain(
 		worktreeSetupHook,
 		worktreeSetupHookTimeoutMs,
 		worktreeBaseDir,
+		baseRef,
 		worktreeProvider,
 		worktreeBranchPrefix,
 		controlConfig,
@@ -1224,8 +1244,8 @@ export function executeAsyncChain(
 	});
 	if (acceptanceErrors.length > 0) return formatAsyncStartError(resultMode, acceptanceErrors.join(" "));
 	const capabilityCeiling = params.capabilityCeiling ?? resolveCurrentSubagentCapabilityCeiling(ctx.currentSessionId);
-	const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
-	const nestedAddress = inheritedNestedRoute ? resolveNestedParentAddressFromEnv() : undefined;
+	const inheritedNestedRoute = inheritedNestedRouteOf(ctx.childRuntime);
+	const nestedAddress = inheritedNestedRoute ? inheritedNestedParentAddressOf(ctx.childRuntime) : undefined;
 	const asyncDir = inheritedNestedRoute
 		? path.join(TEMP_ROOT_DIR, "nested-subagent-runs", inheritedNestedRoute.rootRunId, id)
 		: path.join(DIRS.async, id);
@@ -1338,10 +1358,12 @@ export function executeAsyncChain(
 				completionOwnerId: ctx.completionOwnerId ?? currentCompletionOwnerId(),
 				...(capabilityCeiling ? { capabilityCeiling } : {}),
 				piPackageRoot,
-				piArgv1: process.argv[1],
+				childSessionFactoryModule: childSessionFactoryModule(),
+				inheritedChildRuntime: inheritedChildRuntime(ctx.childRuntime),
 				worktreeSetupHook,
 				worktreeSetupHookTimeoutMs,
 				worktreeBaseDir,
+				baseRef,
 				worktreeProvider,
 				worktreeBranchPrefix,
 				controlConfig,
@@ -1454,7 +1476,7 @@ export function executeAsyncChain(
 						path: nestedAddress.path,
 						asyncDir,
 						pid: spawnResult.pid,
-						ownerIntercomTarget: process.env.PI_SUBAGENT_INTERCOM_SESSION_NAME,
+						ownerIntercomTarget: ctx.childRuntime?.intercomSessionName,
 						leafIntercomTarget: childIntercomTargets?.[0],
 						intercomTarget: childIntercomTargets?.[0],
 						ownerState: "live",
@@ -1541,6 +1563,7 @@ export function executeAsyncSingle(
 		worktreeSetupHook,
 		worktreeSetupHookTimeoutMs,
 		worktreeBaseDir,
+		baseRef,
 		worktreeProvider,
 		worktreeBranchPrefix,
 		controlConfig,
@@ -1581,7 +1604,7 @@ export function executeAsyncSingle(
 		if (extensionBindings !== undefined) unsupported.push("extension bindings");
 		if (unsupported.length > 0) return formatAsyncStartError("single", `Agent '${agentConfig.name}' uses runner.type='${externalRunnerType}' and does not support: ${unsupported.join(", ")}.`);
 	}
-	const capabilityCeiling = intersectSubagentCapabilityCeilings(params.capabilityCeiling ?? resolveCurrentSubagentCapabilityCeiling(ctx.currentSessionId), decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]));
+	const capabilityCeiling = intersectSubagentCapabilityCeilings(params.capabilityCeiling ?? resolveCurrentSubagentCapabilityCeiling(ctx.currentSessionId), ctx.childRuntime?.capabilityCeiling);
 	try {
 		assertAgentAllowedByCapabilityCeiling(agentConfig.name, capabilityCeiling);
 	} catch (error) {
@@ -1624,8 +1647,8 @@ export function executeAsyncSingle(
 	}
 	systemPrompt = appendAgentRefinementOverlay(systemPrompt, { cwd: runnerCwd, agentName: agentConfig.name });
 
-	const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
-	const nestedAddress = inheritedNestedRoute ? resolveNestedParentAddressFromEnv() : undefined;
+	const inheritedNestedRoute = inheritedNestedRouteOf(ctx.childRuntime);
+	const nestedAddress = inheritedNestedRoute ? inheritedNestedParentAddressOf(ctx.childRuntime) : undefined;
 	const asyncDir = inheritedNestedRoute
 		? path.join(TEMP_ROOT_DIR, "nested-subagent-runs", inheritedNestedRoute.rootRunId, id)
 		: path.join(DIRS.async, id);
@@ -1690,7 +1713,7 @@ export function executeAsyncSingle(
 	const thinkingCeiling = externalRunner ? undefined : intersectThinkingCeilings(
 		params.thinkingCeiling,
 		agentConfig.maxThinking,
-		decodeThinkingCeiling(process.env[SUBAGENT_THINKING_CEILING_ENV]),
+		ctx.childRuntime?.thinkingCeiling,
 	);
 	if (!externalRunner) {
 		try {
@@ -1750,7 +1773,7 @@ export function executeAsyncSingle(
 		model,
 		modelCandidates,
 		capabilityCeiling,
-		inheritedCapabilityCeiling: decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]),
+		inheritedCapabilityCeiling: ctx.childRuntime?.capabilityCeiling,
 		agentName: agentConfig.name,
 		permissionRules: resolvePermissionRules(ctx.permissions, agentConfig.permissions),
 		runtimeSnapshotHost: ctx.pi,
@@ -1804,6 +1827,7 @@ export function executeAsyncSingle(
 	});
 	const recoveryAgentConfig = params.recoveryAgentConfig ?? agentConfig;
 	const recoveryDescriptor: SteeringRecoveryDescriptor = {
+		...(ctx.modelResponseAliases ? { modelResponseAliases: ctx.modelResponseAliases } : {}),
 		version: 1,
 		...(lane ? { lane } : {}),
 		launchContractDigest,
@@ -1847,6 +1871,7 @@ export function executeAsyncSingle(
 		...(controlConfig ? { controlConfig } : {}),
 		...(params.context ? { context: params.context } : {}),
 		...(params.intercomBridge !== undefined ? { intercomBridge: params.intercomBridge } : {}),
+		...(params.baseRef !== undefined ? { baseRef: params.baseRef } : {}),
 		...(deadlineAt !== undefined ? { absoluteDeadlineAt: deadlineAt } : {}),
 		...(resolvedToolBudget.budget ? { initialToolBudget: resolvedToolBudget.budget } : {}),
 		maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, recoveryAgentConfig.maxSubagentDepth),
@@ -1891,14 +1916,13 @@ export function executeAsyncSingle(
 						modelCandidates,
 						...(modelOrigin === "inherited" ? { skipPrimaryModelVerification: true } : {}),
 						...(availableModels && availableModels.length > 0 ? { modelVerificationRegistry: availableModels } : {}),
+						...(ctx.modelResponseAliases ? { modelResponseAliases: ctx.modelResponseAliases } : {}),
 						tools: agentConfig.tools,
 						excludeTools: agentConfig.excludeTools,
 						allowNestedSubagents: agentConfig.allowNestedSubagents,
 						extensions: agentConfig.extensions,
 						subagentOnlyExtensions: agentConfig.subagentOnlyExtensions,
 						mcpDirectTools: agentConfig.mcpDirectTools,
-						...(toolPlan.mcpConfig ? { mcpConfig: toolPlan.mcpConfig } : {}),
-						...(toolPlan.runtimeServerNames ? { runtimeServerNames: toolPlan.runtimeServerNames } : {}),
 						mutationTools: agentConfig.mutationTools,
 						completionGuard: agentConfig.completionGuard,
 						systemPrompt,
@@ -1944,10 +1968,12 @@ export function executeAsyncSingle(
 				completionOwnerId: ctx.completionOwnerId ?? currentCompletionOwnerId(),
 				...(capabilityCeiling ? { capabilityCeiling } : {}),
 				piPackageRoot,
-				piArgv1: process.argv[1],
+				childSessionFactoryModule: childSessionFactoryModule(),
+				inheritedChildRuntime: inheritedChildRuntime(ctx.childRuntime),
 				worktreeSetupHook,
 				worktreeSetupHookTimeoutMs,
 				worktreeBaseDir,
+				baseRef,
 				worktreeProvider,
 				worktreeBranchPrefix,
 				controlConfig,
@@ -2030,7 +2056,7 @@ export function executeAsyncSingle(
 						path: nestedAddress.path,
 						asyncDir,
 						pid: spawnResult.pid,
-						ownerIntercomTarget: process.env.PI_SUBAGENT_INTERCOM_SESSION_NAME,
+						ownerIntercomTarget: ctx.childRuntime?.intercomSessionName,
 						leafIntercomTarget: childIntercomTarget?.(agent, 0),
 						intercomTarget: childIntercomTarget?.(agent, 0),
 						ownerState: "live",