pi-subagents 0.63.0 → 0.65.0

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

@@ -14,12 +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";
@@ -30,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";
@@ -64,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";
@@ -74,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";
@@ -143,6 +148,8 @@ interface AsyncExecutionContext {
 	modelScope?: ModelScopeConfig;
 	/** 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;
@@ -178,6 +185,7 @@ interface AsyncChainParams {
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
 	worktreeBaseDir?: string;
+	baseRef?: string;
 	worktreeProvider?: import("../../shared/types.ts").WorktreeProvider;
 	worktreeBranchPrefix?: string;
 	controlConfig?: ResolvedControlConfig;
@@ -247,6 +255,7 @@ interface AsyncSingleParams {
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
 	worktreeBaseDir?: string;
+	baseRef?: string;
 	worktreeProvider?: import("../../shared/types.ts").WorktreeProvider;
 	worktreeBranchPrefix?: string;
 	worktree?: boolean;
@@ -535,6 +544,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);
@@ -576,7 +592,8 @@ function spawnRunner(cfg: object, suffix: string, cwd: string, initialStatus: Om
 			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);
@@ -832,7 +849,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));
 		}
@@ -912,7 +929,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 {
@@ -939,6 +956,8 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 				throw new AsyncStartValidationError(error instanceof Error ? error.message : String(error));
 			}
 		}
+		const launchRuleError = applyWatchdogLaunchRules({ cwd: stepCwd, agent: a.name, model: modelCandidates[0] ?? model, warn: (violation) => sendRuleViolationWarning(ctx.pi, violation) });
+		if (launchRuleError) throw new AsyncStartValidationError(launchRuleError);
 		const fast = s.fast ?? params.fast ?? a.fast;
 		const toolPlan = resolvePiLaunchToolPlan({
 			tools: a.tools,
@@ -954,7 +973,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,
@@ -999,8 +1018,6 @@ 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 } : {}),
@@ -1204,6 +1221,7 @@ export function executeAsyncChain(
 		worktreeSetupHook,
 		worktreeSetupHookTimeoutMs,
 		worktreeBaseDir,
+		baseRef,
 		worktreeProvider,
 		worktreeBranchPrefix,
 		controlConfig,
@@ -1221,8 +1239,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);
@@ -1335,10 +1353,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,
@@ -1451,7 +1471,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",
@@ -1538,6 +1558,7 @@ export function executeAsyncSingle(
 		worktreeSetupHook,
 		worktreeSetupHookTimeoutMs,
 		worktreeBaseDir,
+		baseRef,
 		worktreeProvider,
 		worktreeBranchPrefix,
 		controlConfig,
@@ -1578,7 +1599,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) {
@@ -1621,8 +1642,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);
@@ -1687,7 +1708,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 {
@@ -1747,7 +1768,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,
@@ -1844,6 +1865,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),
@@ -1894,8 +1916,6 @@ export function executeAsyncSingle(
 						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,
@@ -1941,10 +1961,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,
@@ -2027,7 +2049,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",

package/src/runs/background/async-job-tracker.ts

@@ -39,6 +39,8 @@ interface AsyncJobTrackerOptions {
 	watch?: typeof fs.watch;
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	now?: () => number;
+	/** Resolve native supervisor requests without scanning supervisor mailboxes. */
+	supervisorRequestState?: (event: ControlEvent) => "pending" | "resolved" | "unknown";
 }
 
 const CONTROL_EVENT_READ_CHUNK_BYTES = 64 * 1024;
@@ -293,6 +295,15 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				if ((parsed as { type?: unknown }).type !== "subagent.control") return;
 				const record = parsed as { event?: ControlEvent; channels?: string[]; childIntercomTarget?: string; noticeText?: string; intercom?: { to?: string; message?: string } };
 				if (!record.event || !Array.isArray(record.channels)) return;
+				if (record.event.type === "needs_attention" && record.event.reason === "supervisor_request" && options.supervisorRequestState) {
+					let requestState: "pending" | "resolved" | "unknown" = "unknown";
+					try {
+						requestState = options.supervisorRequestState(record.event);
+					} catch (error) {
+						console.error(`Failed to resolve supervisor request state for async control event in '${job.asyncDir}':`, error);
+					}
+					if (requestState === "resolved") return;
+				}
 				const payload = {
 					event: record.event,
 					source: "async" as const,

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

@@ -12,6 +12,7 @@ import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
 import { resultFilePath, resultPayloadPathForIndexedRun } from "./result-files.ts";
 import { canScanAsyncRunPrefix, MIN_SAFE_ASYNC_RUN_PREFIX_LENGTH } from "./run-id-query.ts";
 import { parallelHandoffPath, resolveRetainedWorktreeCwd } from "../shared/parallel-handoff.ts";
+import { normalizeWorktreeBaseRef } from "../shared/worktree.ts";
 import { intersectThinkingCeilings, parseThinkingLevel, type ThinkingLevel } from "../../shared/thinking-ceiling.ts";
 import { assertWorkflowGraphHostSteps } from "../shared/host-step-status.ts";
 
@@ -320,7 +321,7 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 		"subagentOnlyExtensions", "mcpDirectTools", "excludeTools", "mutationTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills",
 		"skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "structuredOutputSchema", "acceptance", "sessionDir", "artifactConfig",
 		"artifactsDir", "maxOutput", "controlConfig", "context", "intercomBridge", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
-		"launchResolvedExtensions", "runFanoutBudget", "lane",
+		"launchResolvedExtensions", "runFanoutBudget", "lane", "baseRef",
 		"extensionBindings",
 	]);
 	for (const field of Object.keys(parsed)) {
@@ -366,6 +367,14 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 	for (const field of ["launchContractDigest", "sessionFile", "model", "modelProvider", "thinking", "agentFilePath", "outputPath", "sessionDir", "artifactsDir"] as const) {
 		if (parsed[field] !== undefined && (typeof parsed[field] !== "string" || !(parsed[field] as string).trim())) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a non-empty string.`);
 	}
+	if (parsed.baseRef !== undefined) {
+		if (typeof parsed.baseRef !== "string") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': baseRef must be a string.`);
+		try {
+			parsed.baseRef = normalizeWorktreeBaseRef(parsed.baseRef);
+		} catch (error) {
+			throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
 	if (parsed.completionGuard !== undefined && typeof parsed.completionGuard !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': completionGuard must be a boolean.`);
 	if (parsed.structuredOutputSchema !== undefined && (!parsed.structuredOutputSchema || typeof parsed.structuredOutputSchema !== "object" || Array.isArray(parsed.structuredOutputSchema))) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': structuredOutputSchema must be an object.`);
 	if (parsed.memory !== undefined) {
@@ -623,7 +632,7 @@ export function buildRevivedAsyncTask(target: AsyncResumeTarget, message: string
 		`Original agent: ${target.agent}`,
 		target.sessionFile ? `Original session file: ${target.sessionFile}` : undefined,
 		"",
-		"Use the stored session context as background. Answer the orchestrator's follow-up below. Do not assume the original child process is still alive.",
+		"Use the stored session context as background. Answer the orchestrator's follow-up below. Do not assume the original child session is still running.",
 		"",
 		"Follow-up:",
 		message,

package/src/runs/background/control-channel.ts

@@ -1,7 +1,7 @@
 /**
  * Cross-OS control channel for async subagent runs.
  *
- * Background runs use child processes. Unix detaches them from the parent process.
+ * Background runs use a detached runner process. Unix detaches it from the parent process.
  * The original control path delivered an interrupt with
  * `process.kill(pid, SIGUSR2|SIGBREAK)`, but Windows cannot
  * deliver those signals cross-process via `process.kill` and throws `ENOSYS`,
@@ -74,33 +74,10 @@ export interface SteerRequest {
 	source?: string;
 }
 
-export interface SteerCapability {
-	type: "steer-capability";
-	protocolVersion: 1;
-	index: number;
-	pid: number;
-	readyAt: number;
-	supported: boolean;
-}
-
-export interface SteerAck {
-	type: "steer-ack";
-	protocolVersion: 1;
-	requestId: string;
-	index: number;
-	ts: number;
-	state: "delivered" | "queued" | "failed";
-	deliveryStatus?: SteerDeliveryStatus;
-	message: string;
-}
-
 const STEER_REQUESTS_DIR = "steer-requests";
 const STOP_REQUESTS_DIR = "stop-requests";
 const REVIVAL_BRIEFS_DIR = "revival-briefs";
 export const MAX_STEER_QUEUE_SIZE = 20;
-const STEER_TARGETS_DIR = "steer-targets";
-const STEER_CAPABILITIES_DIR = "steer-capabilities";
-const STEER_ACKS_DIR = "steer-acks";
 const STEER_INBOX_CLOSED_FILE = "steer-inbox-closed.json";
 const MAX_STEER_MESSAGE_BYTES = 128 * 1024;
 const MAX_STEER_REQUEST_ID_LENGTH = 256;
@@ -143,35 +120,6 @@ export function closeSteerInbox(asyncDir: string, state: string, write: (filePat
 	write(steerInboxClosedPath(asyncDir), { version: 1, closedAt: Date.now(), state });
 }
 
-/** Per-child inbox consumed by the child prompt runtime inside the Pi process. */
-export function stepSteerInboxDir(asyncDir: string, index: number): string {
-	assertChildIndex(index);
-	return path.join(controlInboxDir(asyncDir), STEER_TARGETS_DIR, String(index));
-}
-
-export function steerCapabilitiesDir(asyncDir: string): string {
-	return path.join(controlInboxDir(asyncDir), STEER_CAPABILITIES_DIR);
-}
-
-export function steerCapabilityPath(asyncDir: string, index: number): string {
-	assertChildIndex(index);
-	return path.join(steerCapabilitiesDir(asyncDir), `${index}.json`);
-}
-
-export function steerAcksDir(asyncDir: string, index: number): string {
-	assertChildIndex(index);
-	return path.join(controlInboxDir(asyncDir), STEER_ACKS_DIR, String(index));
-}
-
-function steerAckFileName(requestId: string): string {
-	return `${Buffer.from(requestId).toString("base64url")}.json`;
-}
-
-export function steerAckPathFromDir(dir: string, requestId: string): string {
-	if (!/^[^\s]+$/.test(requestId) || requestId.length > 256) throw new Error("steer acknowledgment requestId is invalid.");
-	return path.join(dir, steerAckFileName(requestId));
-}
-
 function assertChildIndex(index: number): void {
 	if (!Number.isInteger(index) || index < 0 || index > 1_000_000) throw new Error("child index must be a non-negative integer.");
 }
@@ -229,45 +177,6 @@ export function writeSteerRequestToExistingDir(dir: string, request: SteerReques
 	return requestPath;
 }
 
-export function writeSteerCapabilityAt(filePath: string, capability: Omit<SteerCapability, "type" | "protocolVersion">): string {
-	assertChildIndex(capability.index);
-	if (!Number.isInteger(capability.pid) || capability.pid <= 0) throw new Error("steer capability pid must be a positive integer.");
-	if (!Number.isFinite(capability.readyAt) || capability.readyAt <= 0) throw new Error("steer capability readyAt must be a finite timestamp.");
-	const record: SteerCapability = { type: "steer-capability", protocolVersion: 1, ...capability };
-	writeAtomicJson(filePath, record);
-	return filePath;
-}
-
-export function writeSteerCapability(asyncDir: string, capability: Omit<SteerCapability, "type" | "protocolVersion">): string {
-	return writeSteerCapabilityAt(steerCapabilityPath(asyncDir, capability.index), capability);
-}
-
-function steerAckWritePath(filePath: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string {
-	const parsed = path.parse(filePath);
-	const stateOrder = ack.state === "queued" ? "0" : ack.state === "delivered" ? "1" : "2";
-	const timestamp = String(Math.trunc(ack.ts)).padStart(13, "0");
-	for (let suffix = 0; suffix < 1_000; suffix += 1) {
-		const candidate = path.join(parsed.dir, `${parsed.name}-${timestamp}-${stateOrder}-${ack.state}${suffix === 0 ? "" : `-${suffix}`}${parsed.ext}`);
-		if (!fs.existsSync(candidate)) return candidate;
-	}
-	throw new Error("steer acknowledgment queue is full.");
-}
-
-export function writeSteerAckAt(filePath: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string {
-	assertChildIndex(ack.index);
-	if (!/^[^\s]+$/.test(ack.requestId) || ack.requestId.length > 256) throw new Error("steer acknowledgment requestId is invalid.");
-	if (!Number.isFinite(ack.ts) || ack.ts <= 0) throw new Error("steer acknowledgment ts must be a finite timestamp.");
-	if (!ack.message.trim() || ack.message.length > 1000) throw new Error("steer acknowledgment message is invalid.");
-	const record: SteerAck = { type: "steer-ack", protocolVersion: 1, ...ack, message: ack.message.trim() };
-	const ackPath = steerAckWritePath(filePath, ack);
-	writeAtomicJson(ackPath, record);
-	return ackPath;
-}
-
-export function writeSteerAck(asyncDir: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string {
-	return writeSteerAckAt(path.join(steerAcksDir(asyncDir, ack.index), steerAckFileName(ack.requestId)), ack);
-}
-
 /**
  * Parent side: drop a portable interrupt request the runner's inbox watcher will
  * pick up regardless of OS. Written atomically (temp + rename), dir auto-created.
@@ -350,97 +259,6 @@ export function requestAsyncSteer(
 	return requestPath;
 }
 
-export function enqueueStepSteer(asyncDir: string, index: number, request: SteerRequest): string {
-	assertChildIndex(index);
-	const { targetIndexes: _targetIndexes, ...singleTargetRequest } = request;
-	return writeSteerRequestToDir(stepSteerInboxDir(asyncDir, index), { ...singleTargetRequest, targetIndex: index, type: "steer" });
-}
-
-function parseSteerCapability(raw: unknown): SteerCapability | undefined {
-	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
-	const input = raw as Partial<SteerCapability>;
-	if (input.type !== "steer-capability" || input.protocolVersion !== 1) return undefined;
-	const { index, pid, readyAt, supported } = input;
-	if (typeof index !== "number" || !Number.isInteger(index) || index < 0 || index > 1_000_000) return undefined;
-	if (typeof pid !== "number" || typeof readyAt !== "number" || !Number.isInteger(pid) || pid <= 0 || !Number.isFinite(readyAt) || readyAt <= 0 || typeof supported !== "boolean") return undefined;
-	return { type: "steer-capability", protocolVersion: 1, index, pid, readyAt, supported };
-}
-
-function parseSteerAck(raw: unknown): SteerAck | undefined {
-	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
-	const input = raw as Partial<SteerAck>;
-	if (input.type !== "steer-ack" || input.protocolVersion !== 1 || typeof input.requestId !== "string" || !/^[^\s]+$/.test(input.requestId) || input.requestId.length > 256) return undefined;
-	const { index, ts, state, message } = input;
-	if (typeof index !== "number" || typeof ts !== "number" || !Number.isInteger(index) || index < 0 || index > 1_000_000 || !Number.isFinite(ts) || ts <= 0) return undefined;
-	if (state !== "delivered" && state !== "queued" && state !== "failed") return undefined;
-	if (input.deliveryStatus !== undefined && input.deliveryStatus !== "delivered" && input.deliveryStatus !== "queued") return undefined;
-	if (typeof message !== "string" || !message.trim() || message.length > 1000) return undefined;
-	return { type: "steer-ack", protocolVersion: 1, requestId: input.requestId, index, ts, state, ...(input.deliveryStatus ? { deliveryStatus: input.deliveryStatus } : {}), message: message.trim() };
-}
-
-export function readSteerCapability(asyncDir: string, index: number): SteerCapability | undefined {
-	try {
-		return parseSteerCapability(JSON.parse(fs.readFileSync(steerCapabilityPath(asyncDir, index), "utf-8")));
-	} catch {
-		return undefined;
-	}
-}
-
-export function consumeSteerCapabilities(asyncDir: string, fsImpl: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync"> = fs): SteerCapability[] {
-	const dir = steerCapabilitiesDir(asyncDir);
-	if (!fsImpl.existsSync(dir)) return [];
-	const capabilities: SteerCapability[] = [];
-	for (const entry of fsImpl.readdirSync(dir).filter((name) => /^\d+\.json$/.test(name)).sort()) {
-		try {
-			const capability = parseSteerCapability(JSON.parse(fsImpl.readFileSync(path.join(dir, entry), "utf-8")));
-			if (capability) capabilities.push(capability);
-		} catch {
-			// A partially written or malformed capability is ignored until a valid one arrives.
-		}
-	}
-	return capabilities;
-}
-
-export function consumeSteerAckFromDir(
-	dir: string,
-	requestId: string,
-	fsImpl: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync" | "rmSync"> = fs,
-): SteerAck | undefined {
-	if (!fsImpl.existsSync(dir)) return undefined;
-	let entries: string[];
-	try { entries = fsImpl.readdirSync(dir).filter((name) => name.endsWith(".json")).sort(); } catch { return undefined; }
-	for (const entry of entries) {
-		const target = path.join(dir, entry);
-		let ack: SteerAck | undefined;
-		try { ack = parseSteerAck(JSON.parse(fsImpl.readFileSync(target, "utf-8"))); } catch { ack = undefined; }
-		if (ack?.requestId !== requestId) continue;
-		try { fsImpl.rmSync(target, { force: true }); } catch { return undefined; }
-		return ack;
-	}
-	return undefined;
-}
-
-export function consumeSteerAcks(asyncDir: string, fsImpl: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync" | "rmSync"> = fs): SteerAck[] {
-	const root = path.join(controlInboxDir(asyncDir), STEER_ACKS_DIR);
-	if (!fsImpl.existsSync(root)) return [];
-	const acks: SteerAck[] = [];
-	let indexNames: string[];
-	try { indexNames = fsImpl.readdirSync(root).filter((name) => /^\d+$/.test(name)); } catch { return []; }
-	for (const indexName of indexNames) {
-		const dir = path.join(root, indexName);
-		let entries: string[];
-		try { entries = fsImpl.readdirSync(dir).filter((name) => name.endsWith(".json")).sort(); } catch { continue; }
-		for (const entry of entries) {
-			const target = path.join(dir, entry);
-			let ack: SteerAck | undefined;
-			try { ack = parseSteerAck(JSON.parse(fsImpl.readFileSync(target, "utf-8"))); } catch { ack = undefined; }
-			try { fsImpl.rmSync(target, { force: true }); } catch { continue; }
-			if (ack) acks.push(ack);
-		}
-	}
-	return acks;
-}
-
 function parseSteerRequest(raw: unknown): SteerRequest | undefined {
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
 	const input = raw as Partial<SteerRequest>;
@@ -665,8 +483,6 @@ export function watchAsyncControlInbox(
 		onTimeout?: () => void;
 		onStop?: (request: StopRequest) => void;
 		onSteer?: (request: SteerRequest) => void;
-		onSteerCapability?: (capability: SteerCapability) => void;
-		onSteerAck?: (ack: SteerAck) => void;
 		pollIntervalMs?: number;
 		safetyPollIntervalMs?: number;
 		platform?: NodeJS.Platform;
@@ -691,8 +507,6 @@ export function watchAsyncControlInbox(
 			if (consumeTimeoutRequest(asyncDir, fsImpl)) opts.onTimeout?.();
 			if (consumeInterruptRequest(asyncDir, fsImpl)) opts.onInterrupt();
 			for (const request of consumeSteerRequests(asyncDir, fsImpl)) opts.onSteer?.(request);
-			for (const capability of consumeSteerCapabilities(asyncDir, fsImpl)) opts.onSteerCapability?.(capability);
-			for (const ack of consumeSteerAcks(asyncDir, fsImpl)) opts.onSteerAck?.(ack);
 		} catch {
 			// Never let inbox errors crash the runner.
 		}
@@ -718,32 +532,16 @@ export function watchAsyncControlInbox(
 	const watchDir = (target: string, create = false): void => {
 		if (disposed || watchedDirs.has(target)) return;
 		if (create) fsImpl.mkdirSync(target, { recursive: true });
-		const watcher = fsImpl.watch(resolveWatchPath(target, fsImpl.realpathSync.native), () => {
-			watchExistingSteerAckDirs();
-			check();
-		});
+		const watcher = fsImpl.watch(resolveWatchPath(target, fsImpl.realpathSync.native), () => check());
 		watcher.on?.("error", startPolling);
 		watchers.push(watcher);
 		watchedDirs.add(target);
 	};
-	const watchExistingSteerAckDirs = (): void => {
-		const ackRoot = path.join(dir, STEER_ACKS_DIR);
-		let entries: string[];
-		try {
-			entries = fsImpl.readdirSync(ackRoot).filter((name) => /^\d+$/.test(name));
-		} catch {
-			return;
-		}
-		for (const entry of entries) watchDir(path.join(ackRoot, entry));
-	};
 	try {
 		if (shouldUseNativeFsWatch("runner-control-inbox", opts.platform)) {
 			watchDir(dir);
 			watchDir(stopRequestsDir(asyncDir), true);
 			watchDir(steerRequestsDir(asyncDir), true);
-			watchDir(steerCapabilitiesDir(asyncDir), true);
-			watchDir(path.join(dir, STEER_ACKS_DIR), true);
-			watchExistingSteerAckDirs();
 			startSafetyPolling();
 		} else {
 			startPolling();