pi-subagents 0.34.0 → 0.35.0

package/src/runs/background/run-id-resolver.ts

@@ -29,7 +29,19 @@ function exactAsyncLocation(id: string, asyncDirRoot: string, resultsDir: string
 
 function foregroundIds(state: SubagentState | undefined): string[] {
 	if (!state) return [];
-	return [...new Set([...state.foregroundControls.keys(), ...(state.foregroundRuns?.keys() ?? [])])];
+	const remembered = state.currentSessionId
+		? [...(state.foregroundRuns?.values() ?? [])]
+			.filter((run) => run.sessionId === state.currentSessionId)
+			.map((run) => run.runId)
+		: [];
+	return [...new Set([...state.foregroundControls.keys(), ...remembered])];
+}
+
+function hasExactForegroundId(state: SubagentState | undefined, id: string): boolean {
+	if (!state) return false;
+	if (state.foregroundControls.has(id)) return true;
+	const remembered = state.foregroundRuns?.get(id);
+	return Boolean(remembered && state.currentSessionId && remembered.sessionId === state.currentSessionId);
 }
 
 function nestedScopeFromState(state: SubagentState | undefined): NestedRunResolutionScope | undefined {
@@ -58,7 +70,7 @@ export function resolveSubagentRunId(id: string, deps: ResolveSubagentRunIdDeps
 	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
 
 	const nestedScope = deps.nested ?? nestedScopeFromState(deps.state);
-	if (deps.state?.foregroundControls.has(id) || deps.state?.foregroundRuns?.has(id)) return { kind: "foreground", id };
+	if (hasExactForegroundId(deps.state, id)) return { kind: "foreground", id };
 	const exactAsync = exactAsyncLocation(id, asyncDirRoot, resultsDir);
 	if (exactAsync) return { kind: "async", id, location: exactAsync };
 	const exactNested = findNestedRunMatchesById(id, nestedScope ? { scope: nestedScope } : {});

package/src/runs/background/run-status.ts

@@ -6,7 +6,7 @@ import { formatAsyncResultTranscript, formatAsyncRunTranscript, formatNestedRunT
 import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
 import { formatModelThinking } from "../../shared/formatters.ts";
 import { formatActivityLabel } from "../../shared/status-format.ts";
-import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus, type Details, type ForegroundResumeRun, type NestedRunSummary, type SubagentState } from "../../shared/types.ts";
+import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus, type Details, type ForegroundResumeRun, type NestedRunSummary, type SteeringStatus, type SubagentState } from "../../shared/types.ts";
 import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts";
 import { resolveAsyncRunLocation } from "./async-resume.ts";
 import { resolveSubagentRunId } from "./run-id-resolver.ts";
@@ -38,7 +38,8 @@ function hasExistingSessionFile(value: unknown): value is string {
 	return typeof value === "string" && fs.existsSync(value);
 }
 
-function formatResumeGuidance(runId: string | undefined, children: Array<{ agent?: unknown; sessionFile?: unknown }>, fallbackSessionFile?: unknown): string {
+function formatResumeGuidance(runId: string | undefined, children: Array<{ agent?: unknown; sessionFile?: unknown }>, fallbackSessionFile?: unknown, options: { stopped?: boolean } = {}): string {
+	if (options.stopped) return "Resume: unavailable; stopped runs are not resumable. Start a new run instead.";
 	const knownChildren = children
 		.map((child, index) => ({ child, index }))
 		.filter(({ child }) => typeof child.agent === "string");
@@ -73,15 +74,15 @@ function nestedRunDisplayName(run: NestedRunSummary): string {
 	return run.id;
 }
 
-function formatSteeringSummary(input: { steerCount?: number; lastSteerAt?: number }): string | undefined {
-	const parts: string[] = [];
-	if (input.steerCount !== undefined) parts.push(`${input.steerCount} steer${input.steerCount === 1 ? "" : "s"}`);
-	if (typeof input.lastSteerAt === "number" && Number.isFinite(input.lastSteerAt)) parts.push(`last ${new Date(input.lastSteerAt).toISOString()}`);
-	return parts.length ? parts.join(", ") : undefined;
+function formatSteeringSummary(input: { steering?: SteeringStatus }): string | undefined {
+	const steering = input.steering;
+	if (!steering || steering.requested === 0) return undefined;
+	const lateAcknowledgments = steering.recent.reduce((count, request) => count + request.targets.filter((target) => target.lateDeliveredAt !== undefined).length, 0);
+	return `${steering.requested} requested, ${steering.scheduled} scheduled, ${steering.pending} pending, ${steering.delivered} delivered, ${steering.failed} failed, ${steering.recovered} recovered${lateAcknowledgments ? `, ${lateAcknowledgments} late acknowledged` : ""}`;
 }
 
 function rememberedForegroundChildOutput(child: ForegroundResumeRun["children"][number]): string {
-	const outputPath = child.artifactPaths?.outputPath;
+	const outputPath = child.artifactPaths?.outputPath ?? child.savedOutputPath;
 	if (outputPath && fs.existsSync(outputPath)) {
 		try {
 			const artifactOutput = fs.readFileSync(outputPath, "utf-8").trim();
@@ -107,24 +108,29 @@ function formatRememberedForegroundStatus(run: ForegroundResumeRun): string {
 			`${child.index + 1}. ${child.agent} ${child.status}`,
 			child.exitCode !== undefined ? `exit ${child.exitCode}` : undefined,
 			child.detachedReason ? `detached: ${child.detachedReason}` : undefined,
+			child.acceptance ? `acceptance: ${child.acceptance.status}` : undefined,
+			child.error ? `error: ${child.error}` : undefined,
 			output ? `output: ${output.slice(0, 160)}` : undefined,
 		].filter(Boolean);
 		lines.push(parts.join(", "));
 		if (child.sessionFile) lines.push(`  Session: ${child.sessionFile}`);
 		if (child.transcriptPath) lines.push(`  Transcript: ${child.transcriptPath}`);
 		if (child.artifactPaths?.outputPath) lines.push(`  Output: ${child.artifactPaths.outputPath}`);
+		if (child.savedOutputPath && child.savedOutputPath !== child.artifactPaths?.outputPath) lines.push(`  Saved output: ${child.savedOutputPath}`);
+		if (child.outputSaveError) lines.push(`  Output warning: ${child.outputSaveError}`);
 		if (child.transcriptError) lines.push(`  Transcript warning: ${child.transcriptError}`);
 	}
 	lines.push("", `Status: subagent({ action: "status", id: "${run.runId}" })`);
 	if (run.children.length === 1) lines.push(`Transcript: subagent({ action: "status", id: "${run.runId}", view: "transcript" })`);
 	else lines.push(`Transcript: subagent({ action: "status", id: "${run.runId}", index: 0, view: "transcript" })`);
-	const resumable = run.children.find((child) => child.status !== "detached" && hasExistingSessionFile(child.sessionFile));
-	if (resumable) {
+	const detached = run.children.some((child) => child.status === "detached");
+	const resumable = run.children.find((child) => hasExistingSessionFile(child.sessionFile));
+	if (detached) {
+		lines.push(`Recovery: reply to the supervisor request first, then wait with subagent_wait({ id: "${run.runId}" }); do not resume or launch a replacement while any child remains detached.`);
+	} else if (resumable) {
 		lines.push(run.children.length === 1
 			? `Revive: subagent({ action: "resume", id: "${run.runId}", message: "..." })`
 			: `Revive child: subagent({ action: "resume", id: "${run.runId}", index: ${resumable.index}, message: "..." })`);
-	} else if (run.children.some((child) => child.status === "detached")) {
-		lines.push("Recovery: child detached for intercom coordination; status will show recovered output after the child exits when Pi can observe it.");
 	} else {
 		lines.push("Resume: unavailable; no child session file was persisted.");
 	}
@@ -147,6 +153,8 @@ function formatRememberedForegroundTranscript(run: ForegroundResumeRun, options:
 		child.sessionFile ? `Session: ${child.sessionFile}` : undefined,
 		child.transcriptPath ? `Transcript: ${child.transcriptPath}` : undefined,
 		child.artifactPaths?.outputPath ? `Output: ${child.artifactPaths.outputPath}` : undefined,
+		child.savedOutputPath && child.savedOutputPath !== child.artifactPaths?.outputPath ? `Saved output: ${child.savedOutputPath}` : undefined,
+		child.outputSaveError ? `Output warning: ${child.outputSaveError}` : undefined,
 	].filter((line): line is string => Boolean(line));
 	lines.push("Result transcript tail:");
 	if (outputLines.length === 0) lines.push("  (no recovered final output available yet)");
@@ -388,7 +396,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			if (status.sessionFile) lines.push(`Session: ${status.sessionFile}`);
 			if (status.state === "running") lines.push(`Steer running child: subagent({ action: "steer", id: "${status.runId}", message: "..." })`);
 			if (status.state !== "running") {
-				lines.push(formatResumeGuidance(status.runId, status.steps ?? [], status.sessionFile));
+				lines.push(formatResumeGuidance(status.runId, status.steps ?? [], status.sessionFile, { stopped: status.state === "stopped" || status.stopped === true }));
 			}
 			if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);
 			if (fs.existsSync(eventsPath)) lines.push(`Events: ${eventsPath}`);
@@ -409,11 +417,11 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 					return { content: [{ type: "text", text: message }], isError: true, details: { mode: "single", results: [] } };
 				}
 			}
-			const status = data.success ? "complete" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
+			const status = data.state === "stopped" ? "stopped" : data.success ? "complete" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
 			const runId = data.runId ?? data.id ?? resolvedId;
 			const lines = [`Run: ${runId}`, `State: ${status}`, `Result: ${resultPath}`];
 			const children = Array.isArray(data.results) ? data.results : data.agent ? [{ agent: data.agent, sessionFile: data.sessionFile }] : [];
-			lines.push(formatResumeGuidance(runId, children, data.sessionFile));
+			lines.push(formatResumeGuidance(runId, children, data.sessionFile, { stopped: status === "stopped" }));
 			if (data.summary) lines.push("", data.summary);
 			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [] } };
 		} catch (error) {

package/src/runs/background/scheduled-runs.ts

@@ -12,6 +12,7 @@ import {
 	type ExtensionConfig,
 } from "../../shared/types.ts";
 import type { SubagentParamsLike } from "../foreground/subagent-executor.ts";
+import { validateExecutionAcceptance } from "../shared/acceptance.ts";
 
 export const SCHEDULED_RUNS_DIR = path.join(TEMP_ROOT_DIR, "scheduled-subagent-runs");
 export const SCHEDULED_RUN_ACTIONS = ["schedule", "schedule-list", "schedule-status", "schedule-cancel"] as const;
@@ -228,6 +229,8 @@ function sanitizeScheduledParams(params: SubagentParamsLike): { params?: Subagen
 	if (params.context === "fork") return { error: "Scheduled subagent runs require fresh context. Forked parent-session context is not safe at fire time." };
 	if (params.async === false) return { error: "Scheduled subagent runs are always async; omit async or set async: true." };
 	if (params.clarify === true) return { error: "Scheduled subagent runs cannot open clarify UI; omit clarify or set clarify: false." };
+	const acceptanceErrors = validateExecutionAcceptance(params);
+	if (acceptanceErrors.length > 0) return { error: acceptanceErrors.join(" ") };
 
 	const {
 		action: _action,

package/src/runs/background/stale-run-reconciler.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { RESULTS_DIR, type AsyncParallelGroupStatus, type AsyncStatus, type NestedRunSummary, type SubagentRunMode } from "../../shared/types.ts";
+import { resolveEffectiveThinking } from "../../shared/model-info.ts";
 import { normalizeParallelGroups } from "./parallel-groups.ts";
 import { nestedSummaryFromAsyncStatus, projectNestedEvents, resolveNestedAsyncDir, writeNestedEvent, type NestedRoute } from "../shared/nested-events.ts";
 
@@ -109,20 +110,30 @@ interface ResultChildOutcome {
 	error?: string;
 	sessionFile?: string;
 	model?: string;
+	thinking?: string;
 	attemptedModels?: string[];
 	modelAttempts?: NonNullable<AsyncStatus["steps"]>[number]["modelAttempts"];
 }
 
 interface ResultRepairData {
-	state: "complete" | "failed" | "paused";
+	state: "complete" | "failed" | "paused" | "stopped";
 	results?: ResultChildOutcome[];
 }
 
 function readResultRepairData(resultPath: string): ResultRepairData | undefined {
 	try {
-		const data = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as { success?: boolean; state?: string; exitCode?: number; results?: ResultChildOutcome[] };
-		const state = data.success ? "complete" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
-		return { state, ...(Array.isArray(data.results) ? { results: data.results } : {}) };
+		const data = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as { success?: boolean; state?: string; exitCode?: number; results?: unknown };
+		const state = data.success ? "complete" : data.state === "stopped" ? "stopped" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
+		const results = Array.isArray(data.results)
+			? data.results.map((entry, index) => {
+				if (!entry || typeof entry !== "object" || Array.isArray(entry)) return {};
+				const child = entry as ResultChildOutcome;
+				if (child.model !== undefined && typeof child.model !== "string") throw new Error(`Invalid async result file '${resultPath}': results[${index}].model must be a string.`);
+				if (child.thinking !== undefined && typeof child.thinking !== "string") throw new Error(`Invalid async result file '${resultPath}': results[${index}].thinking must be a string.`);
+				return child;
+			})
+			: undefined;
+		return { state, ...(results ? { results } : {}) };
 	} catch (error) {
 		if (isNotFoundError(error)) return undefined;
 		throw new Error(`Failed to read async result file '${resultPath}': ${getErrorMessage(error)}`, {
@@ -131,7 +142,7 @@ function readResultRepairData(resultPath: string): ResultRepairData | undefined
 	}
 }
 
-function childState(overallState: ResultRepairData["state"], child: ResultChildOutcome | undefined): "complete" | "failed" | "paused" {
+function childState(overallState: ResultRepairData["state"], child: ResultChildOutcome | undefined): "complete" | "failed" | "paused" | "stopped" {
 	if (child?.success === true) return "complete";
 	if (child?.success === false) return "failed";
 	return overallState;
@@ -144,22 +155,27 @@ function terminalStatusFromResult(status: AsyncStatus, resultPath: string, now:
 		if (step.status !== "running" && step.status !== "pending") return step;
 		const child = repair.results?.[index];
 		const state = childState(repair.state, child);
+		const model = child?.model ?? step.model;
+		const thinking = resolveEffectiveThinking(model, child?.thinking ?? step.thinking);
 		return {
 			...step,
 			status: state === "complete" ? "complete" as const : state,
 			endedAt: step.endedAt ?? now,
 			durationMs: step.startedAt !== undefined && step.durationMs === undefined ? Math.max(0, now - step.startedAt) : step.durationMs,
 			exitCode: step.exitCode ?? (state === "complete" || state === "paused" ? 0 : 1),
-			error: state === "failed" ? step.error ?? child?.error : step.error,
+			error: state === "failed" || state === "stopped" ? step.error ?? child?.error : step.error,
+			stopped: state === "stopped" ? true : step.stopped,
 			sessionFile: step.sessionFile ?? child?.sessionFile,
-			model: step.model ?? child?.model,
-			attemptedModels: step.attemptedModels ?? child?.attemptedModels,
-			modelAttempts: step.modelAttempts ?? child?.modelAttempts,
+			model,
+			thinking,
+			attemptedModels: child?.attemptedModels ?? step.attemptedModels,
+			modelAttempts: child?.modelAttempts ?? step.modelAttempts,
 		};
 	});
 	return {
 		...status,
 		state: repair.state,
+		...(repair.state === "stopped" ? { stopped: true } : {}),
 		activityState: undefined,
 		lastUpdate: now,
 		endedAt: status.endedAt ?? now,
@@ -267,7 +283,7 @@ function writeFailedRepair(asyncDir: string, status: AsyncStatus, resultPath: st
 }
 
 function terminal(state: AsyncStatus["state"]): boolean {
-	return state === "complete" || state === "failed" || state === "paused";
+	return state === "complete" || state === "failed" || state === "paused" || state === "stopped";
 }
 
 function* nestedRuns(children: NestedRunSummary[] | undefined): Generator<NestedRunSummary> {
@@ -330,6 +346,12 @@ export function reconcileAsyncRun(asyncDir: string, options: ReconcileAsyncRunOp
 	const startedStatus = !status && options.startedRun ? buildStartedStatus(asyncDir, options.startedRun, now) : undefined;
 	const effectiveStatus = status ?? startedStatus;
 	if (!effectiveStatus) return { status: null, repaired: false };
+	const statusPath = path.join(asyncDir, "status.json");
+	for (const [index, step] of (effectiveStatus.steps ?? []).entries()) {
+		const stepRecord = step as Record<string, unknown>;
+		if (stepRecord.model !== undefined && typeof stepRecord.model !== "string") throw new Error(`Invalid async status file '${statusPath}': steps[${index}].model must be a string.`);
+		if (stepRecord.thinking !== undefined && typeof stepRecord.thinking !== "string") throw new Error(`Invalid async status file '${statusPath}': steps[${index}].thinking must be a string.`);
+	}
 
 	const runId = effectiveStatus.runId || path.basename(asyncDir);
 	const resultPath = path.join(options.resultsDir ?? RESULTS_DIR, `${runId}.json`);

package/src/runs/background/steering.ts

@@ -0,0 +1,237 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writePrivateAtomicJson } from "../../shared/atomic-json.ts";
+import type {
+	AsyncStatus,
+	ResolvedToolBudget,
+	ResolvedTurnBudget,
+	SteerActionResult,
+	SteeringRecoveryDescriptor,
+	SteeringRequestStatus,
+	SteeringStatus,
+	SteeringTargetState,
+	SteeringTargetStatus,
+} from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
+
+export const MAX_STEERING_REQUESTS = 20;
+export const STEERING_MESSAGE_PREVIEW_LIMIT = 160;
+
+export function createSteeringStatus(): SteeringStatus {
+	return { requested: 0, scheduled: 0, pending: 0, delivered: 0, failed: 0, recovered: 0, recent: [] };
+}
+
+export function steeringStatus(status: Pick<AsyncStatus, "steering">): SteeringStatus {
+	return status.steering ?? createSteeringStatus();
+}
+
+export function recordSteeringRequest(
+	status: SteeringStatus,
+	input: { id: string; requestedAt: number; source?: string; message: string; targets: Array<{ index: number; state: SteeringTargetState; reason?: string }> },
+): SteeringRequestStatus {
+	const existing = status.recent.find((request) => request.id === input.id);
+	if (existing) return existing;
+	const request: SteeringRequestStatus = {
+		id: input.id,
+		requestedAt: input.requestedAt,
+		...(input.source ? { source: input.source } : {}),
+		messagePreview: input.message.slice(0, STEERING_MESSAGE_PREVIEW_LIMIT),
+		targets: input.targets.map((target) => ({ index: target.index, state: target.state, ...(target.reason ? { reason: target.reason } : {}) })),
+	};
+	status.requested++;
+	status.lastRequestedAt = input.requestedAt;
+	status.recent = [...status.recent, request].slice(-MAX_STEERING_REQUESTS);
+	for (const target of request.targets) incrementStateCount(status, target.state);
+	return request;
+}
+
+function incrementStateCount(status: SteeringStatus, state: SteeringTargetState): void {
+	if (state === "scheduled") status.scheduled++;
+	else if (state === "routed") status.pending++;
+	else if (state === "delivered" || state === "late") status.delivered++;
+	else if (state === "failed") status.failed++;
+	else if (state === "recovered") status.recovered++;
+}
+
+export function updateSteeringTarget(
+	status: SteeringStatus,
+	requestId: string,
+	index: number,
+	state: SteeringTargetState,
+	now: number,
+	fields: Pick<SteeringTargetStatus, "reason" | "replacementRunId"> = {},
+): SteeringTargetStatus | undefined {
+	const request = status.recent.find((candidate) => candidate.id === requestId);
+	const target = request?.targets.find((candidate) => candidate.index === index);
+	if (!target) return undefined;
+	if (state === "late" && target.state === "recovered") {
+		if (target.lateDeliveredAt === undefined) {
+			target.lateDeliveredAt = now;
+			status.delivered++;
+			status.lastDeliveredAt = now;
+		}
+		if (fields.reason) target.reason = fields.reason;
+		return target;
+	}
+	if (target.state === state) {
+		if (state === "routed" && target.routedAt === undefined) target.routedAt = now;
+		if (state === "delivered" && target.deliveredAt === undefined) target.deliveredAt = now;
+		if (state === "late" && target.lateDeliveredAt === undefined) target.lateDeliveredAt = now;
+		if (fields.reason) target.reason = fields.reason;
+		if (fields.replacementRunId) target.replacementRunId = fields.replacementRunId;
+		return target;
+	}
+	if (target.state === "routed" && state !== "routed") status.pending = Math.max(0, status.pending - 1);
+	target.state = state;
+	if (state === "routed") target.routedAt = now;
+	if (state === "delivered") {
+		target.deliveredAt = now;
+		status.lastDeliveredAt = now;
+	}
+	if (state === "late") {
+		target.lateDeliveredAt = now;
+		status.lastDeliveredAt = now;
+	}
+	if (state === "failed") target.failedAt = now;
+	if (state === "recovered") target.recoveredAt = now;
+	if (fields.reason) target.reason = fields.reason;
+	if (fields.replacementRunId) target.replacementRunId = fields.replacementRunId;
+	incrementStateCount(status, state);
+	return target;
+}
+
+export function findSteeringRequest(status: SteeringStatus, requestId: string): SteeringRequestStatus | undefined {
+	return status.recent.find((request) => request.id === requestId);
+}
+
+export function actionResultFromSteeringStatus(status: SteeringStatus, sourceRunId: string, requestId: string, replacementRunId?: string): SteerActionResult | undefined {
+	const request = findSteeringRequest(status, requestId);
+	if (!request) return undefined;
+	const targets = request.targets.map((target) => ({
+		index: target.index,
+		state: target.state,
+		...(target.deliveredAt !== undefined ? { deliveredAt: target.deliveredAt } : {}),
+		...(target.lateDeliveredAt !== undefined ? { lateDeliveredAt: target.lateDeliveredAt } : {}),
+		...(target.reason ? { reason: target.reason } : {}),
+		...(target.replacementRunId ? { replacementRunId: target.replacementRunId } : {}),
+	}));
+	const states = targets.map((target) => target.state);
+	let state: SteerActionResult["state"] = "pending";
+	if (states.length > 0 && states.every((candidate) => candidate === "delivered")) state = "delivered";
+	else if (states.length > 0 && states.every((candidate) => candidate === "scheduled")) state = "scheduled";
+	else if (states.length > 0 && states.every((candidate) => candidate === "recovered")) state = "recovered";
+	else if (states.length > 0 && states.every((candidate) => candidate === "failed" || candidate === "late")) state = "failed";
+	else if (states.some((candidate) => candidate === "failed" || candidate === "late") && states.some((candidate) => candidate !== "failed" && candidate !== "late")) state = "partial";
+	const effectiveReplacementRunId = replacementRunId ?? request.targets.find((target) => target.replacementRunId)?.replacementRunId;
+	return { requestId, state, sourceRunId, ...(effectiveReplacementRunId ? { replacementRunId: effectiveReplacementRunId } : {}), targets };
+}
+
+export function steeringActionIsTerminal(result: SteerActionResult | undefined): boolean {
+	return result?.state === "delivered" || result?.state === "scheduled" || result?.state === "partial" || result?.state === "recovered" || result?.state === "failed";
+}
+
+export function terminalSteeringNoticeState(status: SteeringStatus, requestId: string): "failed" | "partial" | undefined {
+	const request = status.recent.find((candidate) => candidate.id === requestId);
+	if (!request || request.targets.some((target) => target.state === "routed" || target.state === "scheduled")) return undefined;
+	const hasSuccess = request.targets.some((target) => target.state === "delivered" || target.state === "recovered");
+	const hasFailure = request.targets.some((target) => target.state === "failed" || target.state === "late");
+	if (hasSuccess && hasFailure) return "partial";
+	return hasFailure ? "failed" : undefined;
+}
+
+export function claimSteeringRecovery(
+	asyncDir: string,
+	input: { requestId: string; sourceRunId: string; committedAt: number },
+): { claimPath: string; markerPath: string } {
+	const recoveryDir = path.join(asyncDir, "control", "steer-recovery");
+	fs.mkdirSync(recoveryDir, { recursive: true, mode: 0o700 });
+	const claimPath = path.join(recoveryDir, "claim.json");
+	let fd: number;
+	try {
+		fd = fs.openSync(claimPath, "wx", 0o600);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+			throw new Error("Another steering recovery is already committed for this source run.");
+		}
+		throw error;
+	}
+	let writeError: unknown;
+	try {
+		fs.writeFileSync(fd, JSON.stringify({ version: 1, ...input }, null, 2), "utf-8");
+		fs.fsyncSync(fd);
+	} catch (error) {
+		writeError = error;
+	} finally {
+		fs.closeSync(fd);
+	}
+	if (writeError !== undefined) {
+		fs.rmSync(claimPath, { force: true });
+		throw writeError;
+	}
+	const markerPath = path.join(recoveryDir, `${Buffer.from(input.requestId).toString("base64url")}.json`);
+	try {
+		writePrivateAtomicJson(markerPath, { version: 1, ...input });
+	} catch (error) {
+		fs.rmSync(claimPath, { force: true });
+		throw error;
+	}
+	return { claimPath, markerPath };
+}
+
+export function readSteeringStatus(asyncDir: string): SteeringStatus | undefined {
+	return readStatus(asyncDir)?.steering;
+}
+
+export function remainingSteeringRecoveryLimits(
+	descriptor: Pick<SteeringRecoveryDescriptor, "absoluteDeadlineAt" | "initialTurnBudget" | "initialToolBudget">,
+	status: Pick<AsyncStatus, "turnBudget" | "turnCount" | "toolBudget" | "toolCount">,
+	now = Date.now(),
+): { timeoutMs?: number; absoluteDeadlineAt?: number; turnBudget?: ResolvedTurnBudget; toolBudget?: ResolvedToolBudget } {
+	const limits: { timeoutMs?: number; absoluteDeadlineAt?: number; turnBudget?: ResolvedTurnBudget; toolBudget?: ResolvedToolBudget } = {};
+	if (descriptor.absoluteDeadlineAt !== undefined) {
+		const timeoutMs = descriptor.absoluteDeadlineAt - now;
+		if (timeoutMs <= 0) throw new Error("Source run has no remaining deadline budget; it remains paused.");
+		limits.timeoutMs = timeoutMs;
+		limits.absoluteDeadlineAt = descriptor.absoluteDeadlineAt;
+	}
+	if (descriptor.initialTurnBudget) {
+		const consumed = status.turnBudget?.turnCount ?? status.turnCount ?? 0;
+		const totalRemaining = descriptor.initialTurnBudget.maxTurns + descriptor.initialTurnBudget.graceTurns - consumed;
+		if (totalRemaining <= 0) throw new Error("Source run has no remaining turn budget; it remains paused.");
+		const softRemaining = Math.max(0, descriptor.initialTurnBudget.maxTurns - consumed);
+		limits.turnBudget = softRemaining > 0
+			? { maxTurns: softRemaining, graceTurns: totalRemaining - softRemaining }
+			: { maxTurns: 1, graceTurns: totalRemaining - 1 };
+	}
+	if (descriptor.initialToolBudget) {
+		const consumed = status.toolBudget?.toolCount ?? status.toolCount ?? 0;
+		const hard = descriptor.initialToolBudget.hard - consumed;
+		if (hard <= 0) throw new Error("Source run has no remaining tool budget; it remains paused.");
+		const soft = descriptor.initialToolBudget.soft === undefined ? undefined : descriptor.initialToolBudget.soft - consumed;
+		limits.toolBudget = {
+			hard,
+			...(soft !== undefined && soft > 0 && soft < hard ? { soft } : {}),
+			block: descriptor.initialToolBudget.block,
+		};
+	}
+	return limits;
+}
+
+export async function waitForSteeringAction(input: {
+	asyncDir: string;
+	sourceRunId: string;
+	requestId: string;
+	timeoutMs: number;
+	signal?: AbortSignal;
+}): Promise<SteerActionResult | undefined> {
+	const deadline = Date.now() + input.timeoutMs;
+	while (Date.now() <= deadline) {
+		if (input.signal?.aborted) return undefined;
+		const status = readSteeringStatus(input.asyncDir);
+		const result = status ? actionResultFromSteeringStatus(status, input.sourceRunId, input.requestId) : undefined;
+		if (steeringActionIsTerminal(result)) return result;
+		await new Promise<void>((resolve) => setTimeout(resolve, Math.min(50, Math.max(1, deadline - Date.now()))));
+	}
+	const status = readSteeringStatus(input.asyncDir);
+	return status ? actionResultFromSteeringStatus(status, input.sourceRunId, input.requestId) : undefined;
+}