pi-subagents 0.34.0 → 0.35.0

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

@@ -7,11 +7,13 @@ import {
 	type AsyncJobState,
 	type AsyncStartedEvent,
 	type ControlEvent,
+	type SteeringNotice,
 	type SubagentState,
 	POLL_INTERVAL_MS,
 	RESULTS_DIR,
 	SUBAGENT_CONTROL_EVENT,
 	SUBAGENT_CONTROL_INTERCOM_EVENT,
+	SUBAGENT_STEERING_NOTICE_EVENT,
 } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
 import { normalizeParallelGroups } from "./parallel-groups.ts";
@@ -23,6 +25,7 @@ interface AsyncJobTrackerOptions {
 	completionRetentionMs?: number;
 	pollIntervalMs?: number;
 	resultsDir?: string;
+	widgetEnabled?: boolean;
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	now?: () => number;
 }
@@ -30,9 +33,20 @@ interface AsyncJobTrackerOptions {
 const CONTROL_EVENT_READ_CHUNK_BYTES = 64 * 1024;
 const MAX_CONTROL_EVENT_LINE_BYTES = 1024 * 1024;
 const CONTROL_EVENT_SCAN_WINDOW_BYTES = 2 * 1024 * 1024;
+const MAX_RECENT_FLEET_JOBS = 20;
+
+function rememberFleetJob(state: SubagentState, job: AsyncJobState): void {
+	state.fleetJobs ??= new Map();
+	state.fleetJobs.set(job.asyncId, job);
+	const terminal = [...state.fleetJobs.values()]
+		.filter((candidate) => candidate.status === "complete" || candidate.status === "failed" || candidate.status === "paused" || candidate.status === "stopped")
+		.sort((left, right) => (right.updatedAt ?? right.startedAt ?? 0) - (left.updatedAt ?? left.startedAt ?? 0));
+	for (const stale of terminal.slice(MAX_RECENT_FLEET_JOBS)) state.fleetJobs.delete(stale.asyncId);
+}
 
 export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: SubagentState, asyncDirRoot: string, options: AsyncJobTrackerOptions = {}): {
 	ensurePoller: () => void;
+	refreshWidget: (ctx: ExtensionContext) => void;
 	handleStarted: (data: unknown) => void;
 	handleComplete: (data: unknown) => void;
 	resetJobs: (ctx?: ExtensionContext) => void;
@@ -41,10 +55,12 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 	const completionRetentionMs = options.completionRetentionMs ?? 10000;
 	const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
 	const resultsDir = options.resultsDir ?? RESULTS_DIR;
+	const steeringNoticeSeen = new Map<string, number>();
 	const rerenderWidget = (ctx: ExtensionContext, jobs = Array.from(state.asyncJobs.values())) => {
-		renderWidget(ctx, jobs);
+		renderWidget(ctx, options.widgetEnabled === false ? [] : jobs);
 		ctx.ui.requestRender?.();
 	};
+	const refreshWidget = (ctx: ExtensionContext) => rerenderWidget(ctx);
 	const restoredControlEventCursor = (asyncDir: string) => {
 		try {
 			return fs.statSync(path.join(asyncDir, "events.jsonl")).size;
@@ -73,6 +89,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			currentPath: run.currentPath,
 			turnCount: run.turnCount,
 			toolCount: run.toolCount,
+			steering: run.steering,
 			mode: run.mode,
 			agents: visibleSteps.map((step) => step.agent),
 			currentStep: run.currentStep,
@@ -89,6 +106,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			timeoutMs: run.timeoutMs,
 			deadlineAt: run.deadlineAt,
 			timedOut: run.timedOut,
+			stopped: run.stopped,
 			turnBudget: run.turnBudget,
 			turnBudgetExceeded: run.turnBudgetExceeded,
 			wrapUpRequested: run.wrapUpRequested,
@@ -144,7 +162,24 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 					console.error(`Ignoring malformed async control event in '${eventsPath}':`, error);
 					return;
 				}
-				if (!parsed || typeof parsed !== "object" || (parsed as { type?: unknown }).type !== "subagent.control") return;
+				if (!parsed || typeof parsed !== "object") return;
+				if ((parsed as { type?: unknown }).type === "subagent.steering.notice") {
+					const notice = parsed as Partial<SteeringNotice>;
+					if (typeof notice.requestId !== "string" || typeof notice.runId !== "string" || (notice.state !== "failed" && notice.state !== "partial" && notice.state !== "recovered") || typeof notice.message !== "string") return;
+					if (typeof state.currentSessionId === "string" && notice.currentSessionId !== state.currentSessionId) return;
+					const key = `${notice.runId}:${notice.requestId}:${notice.state}`;
+					if (steeringNoticeSeen.has(key)) return;
+					const now = Date.now();
+					steeringNoticeSeen.set(key, now);
+					if (steeringNoticeSeen.size > 200) {
+						for (const [seenKey, seenAt] of steeringNoticeSeen) {
+							if (now - seenAt > 10 * 60 * 1000 || steeringNoticeSeen.size > 200) steeringNoticeSeen.delete(seenKey);
+						}
+					}
+					pi.events.emit(SUBAGENT_STEERING_NOTICE_EVENT, { ...notice, source: "async", asyncDir: job.asyncDir, noticeText: notice.message });
+					return;
+				}
+				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;
 				const payload = {
@@ -269,7 +304,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 					if (status) {
 						const previousStatus = job.status;
 						job.status = status.state;
-						if (job.status !== "complete" && job.status !== "failed" && job.status !== "paused") cancelCleanup(job.asyncId);
+						if (job.status !== "complete" && job.status !== "failed" && job.status !== "paused" && job.status !== "stopped") cancelCleanup(job.asyncId);
 						job.sessionId = status.sessionId ?? job.sessionId;
 						job.activityState = status.activityState;
 						job.lastActivityAt = status.lastActivityAt ?? job.lastActivityAt;
@@ -278,6 +313,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 						job.currentPath = status.currentPath;
 						job.turnCount = status.turnCount ?? job.turnCount;
 						job.toolCount = status.toolCount ?? job.toolCount;
+						job.steering = status.steering ?? job.steering;
 						job.mode = status.mode;
 						job.currentStep = status.currentStep ?? job.currentStep;
 						job.chainStepCount = status.chainStepCount ?? job.chainStepCount;
@@ -308,12 +344,16 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 						job.timeoutMs = status.timeoutMs ?? job.timeoutMs;
 						job.deadlineAt = status.deadlineAt ?? job.deadlineAt;
 						job.timedOut = status.timedOut ?? job.timedOut;
+						job.stopped = status.stopped ?? job.stopped;
 						job.turnBudget = status.turnBudget ?? job.turnBudget;
 						job.turnBudgetExceeded = status.turnBudgetExceeded ?? job.turnBudgetExceeded;
 						job.wrapUpRequested = status.wrapUpRequested ?? job.wrapUpRequested;
 						job.sessionFile = status.sessionFile ?? job.sessionFile;
-						if ((job.status === "complete" || job.status === "failed" || job.status === "paused") && !nestedRefreshFailed && !hasLiveNestedDescendants(job.nestedChildren) && (previousStatus !== job.status || !state.cleanupTimers.has(job.asyncId))) {
-							scheduleCleanup(job.asyncId);
+						if (job.status === "complete" || job.status === "failed" || job.status === "paused" || job.status === "stopped") {
+							rememberFleetJob(state, job);
+							if (!nestedRefreshFailed && !hasLiveNestedDescendants(job.nestedChildren) && (previousStatus !== job.status || !state.cleanupTimers.has(job.asyncId))) {
+								scheduleCleanup(job.asyncId);
+							}
 						}
 						if (widgetRenderKey(job) !== widgetStateBefore) widgetChanged = true;
 						continue;
@@ -328,6 +368,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 						job.status = "failed";
 						job.updatedAt = Date.now();
 					}
+					rememberFleetJob(state, job);
 					if (!hasLiveNestedDescendants(job.nestedChildren) && !state.cleanupTimers.has(job.asyncId)) {
 						scheduleCleanup(job.asyncId);
 					}
@@ -374,6 +415,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			turnBudget: info.turnBudget,
 			controlEventCursor: 0,
 		});
+		rememberFleetJob(state, state.asyncJobs.get(info.id)!);
 		ensurePoller();
 		if (state.lastUiContext) {
 			rerenderWidget(state.lastUiContext);
@@ -381,14 +423,15 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 	};
 
 	const handleComplete = (data: unknown) => {
-		const result = data as { id?: string; success?: boolean; asyncDir?: string; sessionId?: string };
+		const result = data as { id?: string; success?: boolean; state?: AsyncJobState["status"]; asyncDir?: string; sessionId?: string; stopped?: boolean };
 		if (typeof state.currentSessionId === "string" && result.sessionId !== state.currentSessionId) return;
 		const asyncId = result.id;
 		if (!asyncId) return;
 		const job = state.asyncJobs.get(asyncId);
 		let nestedRefreshFailed = false;
 		if (job) {
-			job.status = result.success ? "complete" : "failed";
+			job.status = result.state ?? (result.success ? "complete" : "failed");
+			job.stopped = result.stopped ?? job.stopped;
 			job.updatedAt = Date.now();
 			if (result.asyncDir) job.asyncDir = result.asyncDir;
 			try {
@@ -398,6 +441,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				console.error(`Failed to refresh nested async descendants for '${job.asyncDir}':`, error);
 			}
 		}
+		if (job) rememberFleetJob(state, job);
 		if (state.lastUiContext) {
 			rerenderWidget(state.lastUiContext);
 		}
@@ -410,6 +454,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		}
 		state.cleanupTimers.clear();
 		state.asyncJobs.clear();
+		state.fleetJobs?.clear();
 		state.foregroundControls?.clear();
 		state.lastForegroundControlId = null;
 		state.resultFileCoalescer.clear();
@@ -430,12 +475,14 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			return;
 		}
 		for (const run of runs) {
-			state.asyncJobs.set(run.id, summaryToJob(run));
+			const job = summaryToJob(run);
+			state.asyncJobs.set(run.id, job);
+			rememberFleetJob(state, job);
 		}
 		if (runs.length === 0) return;
 		ensurePoller();
 		if (state.lastUiContext?.hasUI) rerenderWidget(state.lastUiContext);
 	};
 
-	return { ensurePoller, handleStarted, handleComplete, resetJobs, restoreActiveJobs };
+	return { ensurePoller, refreshWidget, handleStarted, handleComplete, resetJobs, restoreActiveJobs };
 }

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

@@ -1,12 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus, type SubagentState } from "../../shared/types.ts";
-import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts";
-import { deliverInterruptRequest } from "./control-channel.ts";
+import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus, type SteeringRecoveryDescriptor } from "../../shared/types.ts";
+import type { AgentConfig } from "../../agents/agents.ts";
+import { validateAcceptanceInput } from "../shared/acceptance.ts";
+import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
+import { resolveTurnBudgetConfig } from "../shared/turn-budget.ts";
 import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
 
-export const ASYNC_RESUME_INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
-
 export interface AsyncResumeParams {
 	id?: string;
 	runId?: string;
@@ -23,6 +23,7 @@ export interface AsyncResumeDeps {
 
 export interface AsyncResumeOptions {
 	requireSessionFile?: boolean;
+	sessionId?: string;
 }
 
 export type AsyncResumeTarget = {
@@ -32,49 +33,13 @@ export type AsyncResumeTarget = {
 	state: AsyncStatus["state"];
 	agent: string;
 	index: number;
-	intercomTarget: string;
 	cwd?: string;
 	sessionFile?: string;
+	model?: string;
+	thinking?: string;
+	recoveryDescriptor?: SteeringRecoveryDescriptor;
 };
 
-type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => boolean;
-
-export function interruptLiveAsyncResumeTarget(input: {
-	target: AsyncResumeTarget & { kind: "live" };
-	state?: Pick<SubagentState, "asyncJobs">;
-	kill?: KillFn;
-	now?: () => number;
-	resultsDir?: string;
-}): { ok: true; asyncId: string } | { ok: false; message: string } {
-	const asyncId = input.target.runId;
-	if (!input.target.asyncDir) {
-		return { ok: false, message: `Async run ${asyncId} is live but does not have an async directory to interrupt.` };
-	}
-	const status = reconcileAsyncRun(input.target.asyncDir, { resultsDir: input.resultsDir, kill: input.kill, now: input.now }).status;
-	if (!status || status.state !== "running" || typeof status.pid !== "number") {
-		return { ok: false, message: `Async run ${asyncId} is live but no interrupt-capable runner pid was found.` };
-	}
-	try {
-		deliverInterruptRequest({
-			asyncDir: input.target.asyncDir,
-			pid: status.pid,
-			kill: input.kill,
-			signal: ASYNC_RESUME_INTERRUPT_SIGNAL,
-			now: input.now,
-			source: "async-resume",
-		});
-		const tracked = input.state?.asyncJobs.get(asyncId);
-		if (tracked) {
-			tracked.activityState = undefined;
-			tracked.updatedAt = input.now?.() ?? Date.now();
-		}
-		return { ok: true, asyncId };
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		return { ok: false, message: `Failed to interrupt async run ${asyncId}: ${message}` };
-	}
-}
-
 interface AsyncResultFile {
 	id?: string;
 	runId?: string;
@@ -83,8 +48,11 @@ interface AsyncResultFile {
 	state?: string;
 	success?: boolean;
 	cwd?: string;
+	sessionId?: string;
 	sessionFile?: string;
-	results?: Array<{ agent?: string; success?: boolean; sessionFile?: string; intercomTarget?: string }>;
+	model?: string;
+	thinking?: string;
+	results?: Array<{ agent?: string; success?: boolean; sessionFile?: string; intercomTarget?: string; model?: string; thinking?: string }>;
 }
 
 export interface AsyncRunLocation {
@@ -122,9 +90,11 @@ function validateResultFile(value: unknown, resultPath: string): AsyncResultFile
 			const agent = validateOptionalString(child, "agent", resultPath, `results[${index}].agent`);
 			const sessionFile = validateOptionalString(child, "sessionFile", resultPath, `results[${index}].sessionFile`);
 			const intercomTarget = validateOptionalString(child, "intercomTarget", resultPath, `results[${index}].intercomTarget`);
+			const model = validateOptionalString(child, "model", resultPath, `results[${index}].model`);
+			const thinking = validateOptionalString(child, "thinking", resultPath, `results[${index}].thinking`);
 			const success = child.success;
 			if (success !== undefined && typeof success !== "boolean") throw new Error(`Invalid async result file '${resultPath}': results[${index}].success must be a boolean.`);
-			return { agent, sessionFile, intercomTarget, ...(typeof success === "boolean" ? { success } : {}) };
+			return { agent, sessionFile, intercomTarget, model, thinking, ...(typeof success === "boolean" ? { success } : {}) };
 		});
 	}
 	const success = data.success;
@@ -136,7 +106,10 @@ function validateResultFile(value: unknown, resultPath: string): AsyncResultFile
 		mode: validateOptionalString(data, "mode", resultPath),
 		state: validateOptionalString(data, "state", resultPath),
 		cwd: validateOptionalString(data, "cwd", resultPath),
+		sessionId: validateOptionalString(data, "sessionId", resultPath),
 		sessionFile: validateOptionalString(data, "sessionFile", resultPath),
+		model: validateOptionalString(data, "model", resultPath),
+		thinking: validateOptionalString(data, "thinking", resultPath),
 		...(typeof success === "boolean" ? { success } : {}),
 		...(results ? { results } : {}),
 	};
@@ -252,7 +225,7 @@ export function resolveAsyncRunLocation(params: AsyncResumeParams, asyncDirRoot:
 }
 
 function resultState(result: AsyncResultFile): AsyncStatus["state"] {
-	if (result.state === "complete" || result.state === "failed" || result.state === "paused" || result.state === "running" || result.state === "queued") {
+	if (result.state === "complete" || result.state === "failed" || result.state === "paused" || result.state === "stopped" || result.state === "running" || result.state === "queued") {
 		return result.state;
 	}
 	return result.success ? "complete" : "failed";
@@ -268,12 +241,106 @@ function validateStatusForResume(status: AsyncStatus | null, source: string): vo
 		if (!Array.isArray(status.steps)) throw new Error(`Invalid async status '${source}': steps must be an array.`);
 		status.steps.forEach((step, index) => {
 			if (!step || typeof step !== "object" || Array.isArray(step)) throw new Error(`Invalid async status '${source}': steps[${index}] must be an object.`);
-			if (typeof step.agent !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].agent must be a string.`);
-			if (step.sessionFile !== undefined && typeof step.sessionFile !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].sessionFile must be a string.`);
+			const stepRecord = step as Record<string, unknown>;
+			if (typeof stepRecord.agent !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].agent must be a string.`);
+			if (stepRecord.sessionFile !== undefined && typeof stepRecord.sessionFile !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].sessionFile must be a string.`);
+			if (stepRecord.model !== undefined && typeof stepRecord.model !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].model must be a string.`);
+			if (stepRecord.thinking !== undefined && typeof stepRecord.thinking !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].thinking must be a string.`);
 		});
 	}
 }
 
+export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): SteeringRecoveryDescriptor | undefined {
+	if (!asyncDir) return undefined;
+	const descriptorPath = path.join(asyncDir, "recovery-descriptor.json");
+	if (!fs.existsSync(descriptorPath)) return undefined;
+	let value: unknown;
+	try {
+		value = JSON.parse(fs.readFileSync(descriptorPath, "utf-8"));
+	} catch (error) {
+		throw new Error(`Failed to parse async recovery descriptor '${descriptorPath}': ${getErrorMessage(error)}`, { cause: error instanceof Error ? error : undefined });
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': expected an object.`);
+	const parsed = value as Record<string, unknown>;
+	const allowedFields = new Set([
+		"version", "sourceRunId", "agent", "sessionFile", "cwd", "model", "fallbackModels", "thinking", "tools", "extensions",
+		"subagentOnlyExtensions", "mcpDirectTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritSkills", "skills",
+		"skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "acceptance", "sessionDir", "artifactConfig",
+		"artifactsDir", "maxOutput", "controlConfig", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share",
+	]);
+	for (const field of Object.keys(parsed)) {
+		if (!allowedFields.has(field)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': unknown field '${field}'.`);
+	}
+	const requiredStrings = ["sourceRunId", "agent", "cwd", "systemPromptMode", "outputMode"] as const;
+	for (const field of requiredStrings) {
+		if (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.version !== 1) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': version must be 1.`);
+	if (parsed.systemPromptMode !== "append" && parsed.systemPromptMode !== "replace") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': systemPromptMode is invalid.`);
+	if (parsed.outputMode !== "inline" && parsed.outputMode !== "file-only") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': outputMode is invalid.`);
+	for (const field of ["inheritProjectContext", "inheritSkills", "share"] as const) {
+		if (typeof parsed[field] !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a boolean.`);
+	}
+	if (!Number.isInteger(parsed.maxSubagentDepth) || (parsed.maxSubagentDepth as number) < 0) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': maxSubagentDepth must be a non-negative integer.`);
+	for (const field of ["fallbackModels", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "skills", "skillPath"] as const) {
+		const item = parsed[field];
+		if (item !== undefined && (!Array.isArray(item) || item.some((entry) => typeof entry !== "string" || !entry.trim()))) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must contain non-empty strings.`);
+	}
+	if (parsed.systemPrompt !== undefined && typeof parsed.systemPrompt !== "string") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': systemPrompt must be a string.`);
+	for (const field of ["sessionFile", "model", "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.completionGuard !== undefined && typeof parsed.completionGuard !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': completionGuard must be a boolean.`);
+	if (parsed.memory !== undefined) {
+		if (!parsed.memory || typeof parsed.memory !== "object" || Array.isArray(parsed.memory)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': memory must be an object.`);
+		const memory = parsed.memory as Record<string, unknown>;
+		if ((memory.scope !== "project" && memory.scope !== "user") || typeof memory.path !== "string" || !memory.path.trim()) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': memory is invalid.`);
+	}
+	if (parsed.absoluteDeadlineAt !== undefined && (!Number.isFinite(parsed.absoluteDeadlineAt) || (parsed.absoluteDeadlineAt as number) <= 0)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': absoluteDeadlineAt must be a positive timestamp.`);
+	if (parsed.initialTurnBudget !== undefined) {
+		const result = resolveTurnBudgetConfig(parsed.initialTurnBudget, "recoveryDescriptor.initialTurnBudget");
+		if (result.error) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${result.error}`);
+	}
+	if (parsed.initialToolBudget !== undefined) {
+		const result = validateToolBudgetConfig(parsed.initialToolBudget, "recoveryDescriptor.initialToolBudget");
+		if (result.error) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${result.error}`);
+	}
+	if (parsed.maxOutput !== undefined) {
+		if (!parsed.maxOutput || typeof parsed.maxOutput !== "object" || Array.isArray(parsed.maxOutput)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': maxOutput must be an object.`);
+		for (const field of ["bytes", "lines"] as const) {
+			const item = (parsed.maxOutput as Record<string, unknown>)[field];
+			if (item !== undefined && (!Number.isInteger(item) || (item as number) < 1)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': maxOutput.${field} must be a positive integer.`);
+		}
+	}
+	if (parsed.artifactConfig !== undefined) {
+		if (!parsed.artifactConfig || typeof parsed.artifactConfig !== "object" || Array.isArray(parsed.artifactConfig)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig must be an object.`);
+		const artifact = parsed.artifactConfig as Record<string, unknown>;
+		for (const field of ["enabled", "includeInput", "includeOutput", "includeJsonl", "includeMetadata"] as const) {
+			if (typeof artifact[field] !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.${field} must be a boolean.`);
+		}
+		if (artifact.includeTranscript !== undefined && typeof artifact.includeTranscript !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.includeTranscript must be a boolean.`);
+		if (!Number.isInteger(artifact.cleanupDays) || (artifact.cleanupDays as number) < 0) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.cleanupDays must be a non-negative integer.`);
+	}
+	if (parsed.controlConfig !== undefined) {
+		if (!parsed.controlConfig || typeof parsed.controlConfig !== "object" || Array.isArray(parsed.controlConfig)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig must be an object.`);
+		const control = parsed.controlConfig as Record<string, unknown>;
+		if (typeof control.enabled !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.enabled must be a boolean.`);
+		for (const field of ["needsAttentionAfterMs", "activeNoticeAfterMs", "failedToolAttemptsBeforeAttention"] as const) {
+			if (!Number.isInteger(control[field]) || (control[field] as number) < 1) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.${field} must be a positive integer.`);
+		}
+		for (const field of ["activeNoticeAfterTurns", "activeNoticeAfterTokens"] as const) {
+			if (control[field] !== undefined && (!Number.isInteger(control[field]) || (control[field] as number) < 1)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.${field} must be a positive integer.`);
+		}
+		if (!Array.isArray(control.notifyOn) || control.notifyOn.some((item) => item !== "active_long_running" && item !== "needs_attention")) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.notifyOn is invalid.`);
+		if (!Array.isArray(control.notifyChannels) || control.notifyChannels.some((item) => item !== "event" && item !== "async" && item !== "intercom")) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.notifyChannels is invalid.`);
+	}
+	if (parsed.acceptance !== undefined) {
+		const errors = validateAcceptanceInput(parsed.acceptance, "recoveryDescriptor.acceptance");
+		if (errors.length) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${errors.join(" ")}`);
+	}
+	return parsed as unknown as SteeringRecoveryDescriptor;
+}
+
 function validateResumeSessionFile(runId: string, sessionFile: string): string {
 	if (path.extname(sessionFile) !== ".jsonl") throw new Error(`Async run '${runId}' session file must be a .jsonl file: ${sessionFile}`);
 	const resolved = path.resolve(sessionFile);
@@ -295,10 +362,16 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 		: undefined;
 	const status = reconciliation?.status ?? null;
 	validateStatusForResume(status, location.asyncDir ? path.join(location.asyncDir, "status.json") : "status.json");
+	const recoveryDescriptor = readAsyncRecoveryDescriptor(location.asyncDir);
 	const result = location.resultPath ? readResultFile(location.resultPath) : undefined;
 	const runId = status?.runId ?? result?.runId ?? result?.id ?? location.resolvedId ?? (location.asyncDir ? path.basename(location.asyncDir) : "unknown");
+	if (options.sessionId && ((status && status.sessionId !== options.sessionId) || (result && result.sessionId !== options.sessionId))) {
+		throw new Error(`Async run '${runId}' was not found in the active session.`);
+	}
+	if (recoveryDescriptor && recoveryDescriptor.sourceRunId !== runId) throw new Error(`Async run '${runId}' has a recovery descriptor for a different source run.`);
 	const state = status?.state ?? (result ? resultState(result) : undefined);
 	if (!state) throw new Error(`Status file not found for async run '${runId}'.`);
+	if (state === "stopped") throw new Error(`Async run '${runId}' was stopped and cannot be resumed. Start a new run instead.`);
 
 	const statusSteps = status?.steps ?? [];
 	const resultSteps = result?.results ?? [];
@@ -319,9 +392,11 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 					state,
 					agent: selectedStep.agent,
 					index: requestedIndex,
-					intercomTarget: resolveSubagentIntercomTarget(runId, selectedStep.agent, requestedIndex),
 					cwd: status?.cwd ?? result?.cwd,
 					sessionFile: selectedStep.sessionFile ?? status?.sessionFile ?? result?.sessionFile,
+					model: selectedStep.model,
+					thinking: selectedStep.thinking,
+					...(recoveryDescriptor ? { recoveryDescriptor } : {}),
 				};
 			}
 			if (selectedStep?.status === "pending") throw new Error(`Async run '${runId}' child ${requestedIndex} is pending and has not started yet. Wait for it to run or complete before resuming.`);
@@ -341,9 +416,11 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 				state,
 				agent: selected.step.agent,
 				index: selected.index,
-				intercomTarget: resolveSubagentIntercomTarget(runId, selected.step.agent, selected.index),
 				cwd: status?.cwd ?? result?.cwd,
 				sessionFile: selected.step.sessionFile ?? status?.sessionFile ?? result?.sessionFile,
+				model: selected.step.model,
+				thinking: selected.step.thinking,
+				...(recoveryDescriptor ? { recoveryDescriptor } : {}),
 			};
 		}
 	}
@@ -356,11 +433,14 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 	if (index < 0 || index >= stepCount) throw new Error(`Async run '${runId}' has ${stepCount} children. Index ${index} is out of range.`);
 	const agent = statusSteps[index]?.agent ?? resultSteps[index]?.agent ?? result?.agent;
 	if (!agent) throw new Error(`Could not determine child agent for async run '${runId}'.`);
+	if (recoveryDescriptor && recoveryDescriptor.agent !== agent) throw new Error(`Async run '${runId}' has a recovery descriptor for '${recoveryDescriptor.agent}', not '${agent}'.`);
 	const sessionFile = statusSteps[index]?.sessionFile
 		?? resultSteps[index]?.sessionFile
 		?? (stepCount === 1 ? status?.sessionFile ?? result?.sessionFile : undefined);
 	if (!sessionFile && requireSessionFile) throw new Error(`Async run '${runId}' child ${index} does not have a persisted session file to resume from.`);
 	const resolvedSessionFile = sessionFile ? validateResumeSessionFile(runId, sessionFile) : undefined;
+	const stepModel = statusSteps[index]?.model ?? resultSteps[index]?.model ?? (stepCount === 1 ? result?.model : undefined);
+	const stepThinking = statusSteps[index]?.thinking ?? resultSteps[index]?.thinking ?? (stepCount === 1 ? result?.thinking : undefined);
 
 	return {
 		kind: "revive",
@@ -369,9 +449,36 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 		state,
 		agent,
 		index,
-		intercomTarget: resolveSubagentIntercomTarget(runId, agent, index),
 		cwd: status?.cwd ?? result?.cwd,
 		...(resolvedSessionFile ? { sessionFile: resolvedSessionFile } : {}),
+		...(stepModel ? { model: stepModel } : {}),
+		...(stepThinking ? { thinking: stepThinking } : {}),
+		...(recoveryDescriptor ? { recoveryDescriptor } : {}),
+	};
+}
+
+export function applySteeringRecoveryAgentConfig(agentConfig: AgentConfig, descriptor: SteeringRecoveryDescriptor): AgentConfig {
+	return {
+		...agentConfig,
+		model: descriptor.model,
+		fallbackModels: descriptor.fallbackModels ? [...descriptor.fallbackModels] : undefined,
+		thinking: descriptor.thinking,
+		tools: descriptor.tools ? [...descriptor.tools] : undefined,
+		extensions: descriptor.extensions ? [...descriptor.extensions] : undefined,
+		subagentOnlyExtensions: descriptor.subagentOnlyExtensions ? [...descriptor.subagentOnlyExtensions] : undefined,
+		mcpDirectTools: descriptor.mcpDirectTools ? [...descriptor.mcpDirectTools] : undefined,
+		systemPrompt: descriptor.systemPrompt,
+		systemPromptMode: descriptor.systemPromptMode,
+		inheritProjectContext: descriptor.inheritProjectContext,
+		inheritSkills: descriptor.inheritSkills,
+		skills: descriptor.skills ? [...descriptor.skills] : undefined,
+		skillPath: descriptor.skillPath ? [...descriptor.skillPath] : undefined,
+		filePath: descriptor.agentFilePath,
+		completionGuard: descriptor.completionGuard,
+		memory: descriptor.memory ? { ...descriptor.memory } : undefined,
+		output: descriptor.outputPath,
+		toolBudget: descriptor.initialToolBudget,
+		maxSubagentDepth: descriptor.maxSubagentDepth,
 	};
 }