pi-subagents 0.42.1 → 0.44.0

package/src/missions/workflow-state.ts

@@ -0,0 +1,250 @@
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
+import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, waitForFileSystemRetry } from "../shared/file-system-retry.ts";
+import { assertWorkflowJsonValue } from "../workflows/scripted-workflow.ts";
+import type { MissionStoreLocation } from "./types.ts";
+import { validateMissionId } from "./store.ts";
+
+const STATE_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const STATE_LOCK_STALE_MS = 60_000;
+export const MISSION_STATE_MAX_BYTES = 256 * 1024;
+
+export interface MissionWorkflowState {
+	path: string;
+	get(key: string): unknown;
+	set(key: string, value: unknown): void;
+}
+
+export function missionStatePath(location: MissionStoreLocation, missionId: string): string {
+	return path.join(location.missionDir, validateMissionId(missionId), "state.json");
+}
+
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+interface StateLockOwner {
+	pid: number;
+	token: string;
+	createdAt: number;
+	processKey?: string;
+}
+
+function linuxProcessStartKey(pid: number): string | undefined {
+	try {
+		const raw = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
+		const tail = raw.slice(raw.lastIndexOf(")") + 2).trim().split(/\s+/);
+		return tail[19] ? `linux:${tail[19]}` : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function psProcessStartKey(pid: number): string | undefined {
+	try {
+		const raw = execFileSync("ps", ["-p", String(pid), "-o", "lstart="], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 1000 }).trim();
+		return raw ? `ps:${raw}` : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function windowsProcessStartKey(pid: number): string | undefined {
+	try {
+		const raw = execFileSync("powershell.exe", ["-NoProfile", "-Command", `(Get-CimInstance Win32_Process -Filter \"ProcessId=${pid}\").CreationDate`], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 1000 }).trim();
+		return raw ? `win:${raw}` : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function processStartKey(pid: number): string | undefined {
+	if (process.platform === "linux") return linuxProcessStartKey(pid) ?? psProcessStartKey(pid);
+	if (process.platform === "win32") return windowsProcessStartKey(pid);
+	return psProcessStartKey(pid);
+}
+
+const CURRENT_PROCESS_KEY = processStartKey(process.pid);
+
+function readStateLockOwner(lockPath: string): StateLockOwner | undefined {
+	try {
+		const owner = JSON.parse(fs.readFileSync(path.join(lockPath, "owner.json"), "utf-8")) as { pid?: unknown; token?: unknown; createdAt?: unknown; processKey?: unknown };
+		if (Number.isSafeInteger(owner.pid) && (owner.pid as number) > 0 && typeof owner.token === "string" && owner.token && Number.isSafeInteger(owner.createdAt)) {
+			return {
+				pid: owner.pid as number,
+				token: owner.token,
+				createdAt: owner.createdAt as number,
+				...(typeof owner.processKey === "string" && owner.processKey ? { processKey: owner.processKey } : {}),
+			};
+		}
+	} catch {
+		return undefined;
+	}
+	return undefined;
+}
+
+function stateLockIsStale(lockPath: string, now = Date.now()): boolean {
+	const owner = readStateLockOwner(lockPath);
+	if (owner) {
+		if (!isProcessAlive(owner.pid)) return true;
+		const currentProcessKey = processStartKey(owner.pid);
+		return Boolean(owner.processKey && currentProcessKey && owner.processKey !== currentProcessKey);
+	}
+	try {
+		return now - fs.statSync(lockPath).mtimeMs > STATE_LOCK_STALE_MS;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+function removeOwnedStateLock(lockPath: string, owner: StateLockOwner): void {
+	const current = readStateLockOwner(lockPath);
+	if (current?.token !== owner.token) return;
+	fs.rmSync(lockPath, { recursive: true, force: true });
+}
+
+function staleDirectoryExists(dirPath: string, now = Date.now()): boolean {
+	try {
+		return now - fs.statSync(dirPath).mtimeMs > STATE_LOCK_STALE_MS;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+function tryMakeDirectory(dirPath: string, mode: number): boolean {
+	try {
+		fs.mkdirSync(dirPath, { mode });
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+		throw error;
+	}
+}
+
+function waitForStateLock(delayMs: number | undefined, lockPath: string): void {
+	if (delayMs === undefined) throw new Error(`Timed out acquiring mission state lock '${lockPath}'.`);
+	waitForFileSystemRetry(delayMs);
+}
+
+function reclaimStaleStateLock(lockPath: string, reclaimPath: string): boolean {
+	if (!stateLockIsStale(lockPath)) return false;
+	if (!tryMakeDirectory(reclaimPath, 0o700)) return false;
+	try {
+		if (!stateLockIsStale(lockPath)) return false;
+		fs.rmSync(lockPath, { recursive: true, force: true });
+		return true;
+	} finally {
+		fs.rmSync(reclaimPath, { recursive: true, force: true });
+	}
+}
+
+function withStateFileLock<T>(filePath: string, operation: () => T): T {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	const lockPath = `${filePath}.lock`;
+	const reclaimPath = `${lockPath}.reclaim`;
+	let owner: StateLockOwner | undefined;
+	for (let attempt = 0; ; attempt++) {
+		if (fs.existsSync(reclaimPath)) {
+			if (staleDirectoryExists(reclaimPath)) {
+				fs.rmSync(reclaimPath, { recursive: true, force: true });
+				continue;
+			}
+			waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
+			continue;
+		}
+		try {
+			fs.mkdirSync(lockPath, { mode: 0o700 });
+			owner = { pid: process.pid, token: randomUUID(), createdAt: Date.now(), ...(CURRENT_PROCESS_KEY ? { processKey: CURRENT_PROCESS_KEY } : {}) };
+			try {
+				fs.writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify(owner), { encoding: "utf-8", mode: 0o600 });
+			} catch (error) {
+				removeOwnedStateLock(lockPath, owner);
+				owner = undefined;
+				throw error;
+			}
+			break;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+				throw new Error(`Failed to acquire mission state lock '${lockPath}': ${error instanceof Error ? error.message : String(error)}`);
+			}
+			if (reclaimStaleStateLock(lockPath, reclaimPath)) continue;
+			waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
+		}
+	}
+	try {
+		return operation();
+	} finally {
+		if (owner) removeOwnedStateLock(lockPath, owner);
+	}
+}
+
+function validateStateKey(value: unknown): string {
+	if (typeof value !== "string" || !STATE_KEY_PATTERN.test(value)) {
+		throw new Error("state key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.");
+	}
+	return value;
+}
+
+export function createMissionWorkflowState(location: MissionStoreLocation, missionId: string): MissionWorkflowState {
+	const filePath = missionStatePath(location, missionId);
+	let loaded = false;
+	let values: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+
+	const readStateFile = (): Record<string, unknown> => {
+		let raw: string;
+		try {
+			raw = fs.readFileSync(filePath, "utf-8");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return Object.create(null) as Record<string, unknown>;
+			throw new Error(`Failed to read mission state '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const bytes = Buffer.byteLength(raw);
+		if (bytes > MISSION_STATE_MAX_BYTES) throw new Error(`Mission state file '${filePath}' exceeds the 256 KiB limit (${bytes} bytes).`);
+		try {
+			const parsed: unknown = JSON.parse(raw);
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("root must be a JSON object");
+			assertWorkflowJsonValue(parsed, "mission state");
+			return Object.assign(Object.create(null) as Record<string, unknown>, parsed);
+		} catch (error) {
+			throw new Error(`Invalid mission state file '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+	};
+
+	const load = (): Record<string, unknown> => {
+		if (loaded) return values;
+		values = readStateFile();
+		loaded = true;
+		return values;
+	};
+
+	return {
+		path: filePath,
+		get(key) {
+			const validKey = validateStateKey(key);
+			const current = load();
+			return Object.hasOwn(current, validKey) ? current[validKey] : undefined;
+		},
+		set(key, value) {
+			const validKey = validateStateKey(key);
+			assertWorkflowJsonValue(value, `state.set('${validKey}') value`);
+			withStateFileLock(filePath, () => {
+				const next = Object.assign(Object.create(null) as Record<string, unknown>, readStateFile(), { [validKey]: value });
+				const bytes = Buffer.byteLength(JSON.stringify(next, null, 2));
+				if (bytes > MISSION_STATE_MAX_BYTES) throw new Error(`Mission state exceeds the 256 KiB limit (${bytes} bytes; maximum ${MISSION_STATE_MAX_BYTES} bytes).`);
+				writePrivateAtomicJson(filePath, next);
+				values = next;
+				loaded = true;
+			});
+		},
+	};
+}

package/src/profiles/profiles.ts

@@ -260,7 +260,7 @@ function qualityTierToRoleTier(quality: QualityTier, cost: CostTier): Recommende
 
 function agentsForRoleTier(roleTier: RecommendedRoleTier): BuiltinAgentName[] {
 	if (roleTier === "cheap") return ["scout", "delegate"];
-	if (roleTier === "medium") return ["planner", "context-builder", "researcher"];
+	if (roleTier === "medium") return ["researcher", "reviewer"];
 	return ["worker", "reviewer", "oracle"];
 }
 
@@ -405,8 +405,6 @@ function buildProfileFile(kind: ProfileKind, models: { cheap: string; medium: st
 			agentOverrides: {
 				scout: { model: models.cheap },
 				delegate: { model: models.cheap },
-				planner: { model: models.medium },
-				"context-builder": { model: models.medium },
 				researcher: { model: models.medium },
 				worker: { model: models.strong },
 				reviewer: { model: models.strong },

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

@@ -11,6 +11,7 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "../../agents/agents.ts";
+import { appendAgentRefinementOverlay } from "../../agents/agent-refinements.ts";
 import { writePrivateAtomicJson } from "../../shared/atomic-json.ts";
 import { applyThinkingSuffix, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/pi-args.ts";
 import { injectOutputPathSystemPrompt, injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
@@ -268,7 +269,8 @@ export function formatAsyncStartedMessage(headline: string, interactive: boolean
 		? [
 			"The async run is detached and running in the background.",
 			"You are in an interactive session. By default, return control to the user now; Pi will wake you on completion when the run finishes or needs attention. Do NOT call subagent_wait() merely to wait, and do not run sleep/polling loops to wait for it.",
-			"Override that default and call subagent_wait() before ending the turn only when the current request is run-to-completion — for example, the user asked you to report results back here before continuing, or a skill must finish in one turn. In that case, call subagent_wait() to block until the run completes so its results are delivered in this turn instead of deferred.",
+			"When you need an explicit wake for one known run but do not need same-turn results, call subagent_wait({ id: \"...\", nonBlocking: true }) to arm a subscription and return immediately.",
+			"Override the default and call blocking subagent_wait() before ending the turn only when the current request is run-to-completion — for example, the user asked you to report results back here before continuing, or a skill must finish in one turn. In that case, call subagent_wait() to block until the run completes so its results are delivered in this turn instead of deferred.",
 			"Otherwise, continue any independent work or return control to the user. Use subagent({ action: \"status\", id: \"...\" }) for a one-shot status/result or to inspect a blocked/stale run, never as a wait loop.",
 		]
 		: [
@@ -693,6 +695,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		if (memoryInjection) {
 			systemPrompt = systemPrompt ? `${systemPrompt}\n\n${memoryInjection}` : memoryInjection;
 		}
+		systemPrompt = appendAgentRefinementOverlay(systemPrompt, { cwd: stepCwd, agentName: a.name });
 
 		const readInstructions = buildChainInstructions({ ...behavior, output: false, progress: false }, instructionCwd, false);
 		const isFirstProgressAgent = behavior.progress && !progressPrecreated && !progressInstructionCreated;
@@ -1260,6 +1263,7 @@ export function executeAsyncSingle(
 	if (memoryInjection) {
 		systemPrompt = systemPrompt ? `${systemPrompt}\n\n${memoryInjection}` : memoryInjection;
 	}
+	systemPrompt = appendAgentRefinementOverlay(systemPrompt, { cwd: runnerCwd, agentName: agentConfig.name });
 
 	const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
 	const nestedAddress = inheritedNestedRoute ? resolveNestedParentAddressFromEnv() : undefined;

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

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { renderWidget, requestWidgetRender, widgetRenderKey } from "../../tui/render.ts";
+import { renderWidget, widgetRenderKey } from "../../tui/render.ts";
 import { formatControlNoticeMessage } from "../shared/subagent-control.ts";
 import {
 	type AsyncJobState,
@@ -34,7 +34,6 @@ 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;
-const WIDGET_ANIMATION_REFRESH_MS = 500;
 
 function rememberFleetJob(state: SubagentState, job: AsyncJobState): void {
 	state.fleetJobs ??= new Map();
@@ -57,14 +56,9 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 	const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
 	const resultsDir = options.resultsDir ?? DIRS.results;
 	const steeringNoticeSeen = new Map<string, number>();
-	let lastWidgetAnimationAt = 0;
-	const requestStatusRender = (ctx: ExtensionContext) => {
-		if (requestWidgetRender()) return;
-		(ctx.ui as { requestRender?: () => void }).requestRender?.();
-	};
 	const rerenderWidget = (ctx: ExtensionContext, jobs = Array.from(state.asyncJobs.values())) => {
 		renderWidget(ctx, options.widgetEnabled === false ? [] : jobs);
-		requestStatusRender(ctx);
+		(ctx.ui as { requestRender?: () => void }).requestRender?.();
 	};
 	const rerenderLastWidget = (jobs = Array.from(state.asyncJobs.values())) => {
 		const ctx = state.lastUiContext;
@@ -80,14 +74,6 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		}
 	};
 	const refreshWidget = (ctx: ExtensionContext) => rerenderWidget(ctx);
-	const hasRunningWidgetJobs = () => options.widgetEnabled !== false && [...state.asyncJobs.values()].some((job) => job.status === "running");
-	const refreshWidgetAnimation = () => {
-		if (!hasRunningWidgetJobs()) return;
-		const now = Date.now();
-		if (now - lastWidgetAnimationAt < WIDGET_ANIMATION_REFRESH_MS) return;
-		lastWidgetAnimationAt = now;
-		requestWidgetRender();
-	};
 	const restoredControlEventCursor = (asyncDir: string) => {
 		try {
 			return fs.statSync(path.join(asyncDir, "events.jsonl")).size;
@@ -414,7 +400,6 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			}
 
 			if (widgetChanged) rerenderLastWidget();
-			else refreshWidgetAnimation();
 		}, pollIntervalMs);
 		state.poller.unref?.();
 	};

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

@@ -65,6 +65,7 @@ interface AsyncRunStepSummary {
 export interface AsyncRunSummary {
 	id: string;
 	asyncDir: string;
+	toolCallId?: string;
 	sessionId?: string;
 	state: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
 	error?: string;
@@ -288,6 +289,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 	return {
 		id: status.runId || path.basename(asyncDir),
 		asyncDir,
+		...(status.toolCallId ? { toolCallId: status.toolCallId } : {}),
 		...(status.sessionId ? { sessionId: status.sessionId } : {}),
 		state: status.state,
 		...(status.error ? { error: status.error } : {}),

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

@@ -60,11 +60,15 @@ export interface CheckpointDecisionRequest {
 	reason?: string;
 }
 
+export type SteerDeliveryMode = "steer" | "follow_up" | "auto";
+export type SteerDeliveryStatus = "delivered" | "queued";
+
 export interface SteerRequest {
 	type: "steer";
 	id: string;
 	ts: number;
 	message: string;
+	mode?: SteerDeliveryMode;
 	targetIndex?: number;
 	targetIndexes?: number[];
 	source?: string;
@@ -85,11 +89,14 @@ export interface SteerAck {
 	requestId: string;
 	index: number;
 	ts: number;
-	state: "delivered" | "failed";
+	state: "delivered" | "queued" | "failed";
+	deliveryStatus?: SteerDeliveryStatus;
 	message: string;
 }
 
 const STEER_REQUESTS_DIR = "steer-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";
@@ -186,6 +193,7 @@ function validSteerRequest(request: Partial<SteerRequest>): request is SteerRequ
 		&& typeof request.message === "string"
 		&& Boolean(request.message.trim())
 		&& Buffer.byteLength(request.message, "utf8") <= MAX_STEER_MESSAGE_BYTES
+		&& (request.mode === undefined || request.mode === "steer" || request.mode === "follow_up" || request.mode === "auto")
 		&& (request.targetIndex === undefined || (Number.isInteger(request.targetIndex) && request.targetIndex >= 0 && request.targetIndex <= 1_000_000))
 		&& (request.targetIndexes === undefined || (
 			request.targetIndex === undefined
@@ -218,14 +226,26 @@ export function writeSteerCapability(asyncDir: string, capability: Omit<SteerCap
 	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() };
-	writeAtomicJson(filePath, record);
-	return filePath;
+	const ackPath = steerAckWritePath(filePath, ack);
+	writeAtomicJson(ackPath, record);
+	return ackPath;
 }
 
 export function writeSteerAck(asyncDir: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string {
@@ -283,7 +303,7 @@ export function requestAsyncCheckpointDecision(
 
 export function requestAsyncSteer(
 	asyncDir: string,
-	payload: { message: string; targetIndex?: number; targetIndexes?: number[]; source?: string; id?: string; ts?: number },
+	payload: { message: string; mode?: SteerDeliveryMode; targetIndex?: number; targetIndexes?: number[]; source?: string; id?: string; ts?: number },
 	deps: { now?: () => number; randomId?: () => string } = {},
 ): string {
 	const message = payload.message.trim();
@@ -309,6 +329,7 @@ export function requestAsyncSteer(
 		id: payload.id ?? deps.randomId?.() ?? randomUUID(),
 		ts: payload.ts ?? deps.now?.() ?? Date.now(),
 		message,
+		...(payload.mode && payload.mode !== "steer" ? { mode: payload.mode } : {}),
 		...(payload.targetIndex !== undefined ? { targetIndex: payload.targetIndex } : {}),
 		...(payload.targetIndexes !== undefined ? { targetIndexes: [...payload.targetIndexes] } : {}),
 		...(payload.source ? { source: payload.source } : {}),
@@ -343,9 +364,10 @@ function parseSteerAck(raw: unknown): SteerAck | undefined {
 	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 !== "failed") 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, message: message.trim() };
+	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 {
@@ -401,6 +423,7 @@ function parseSteerRequest(raw: unknown): SteerRequest | undefined {
 		id: input.id.trim(),
 		ts: input.ts,
 		message: input.message.trim(),
+		...(input.mode ? { mode: input.mode } : {}),
 		...(input.targetIndex !== undefined ? { targetIndex: input.targetIndex } : {}),
 		...(input.targetIndexes !== undefined ? { targetIndexes: [...input.targetIndexes] } : {}),
 		...(typeof input.source === "string" && input.source.trim() ? { source: input.source } : {}),
@@ -440,6 +463,27 @@ export function consumeSteerRequests(asyncDir: string, fsImpl: Pick<typeof fs, "
 	return consumeSteerRequestsFromDir(steerRequestsDir(asyncDir), fsImpl);
 }
 
+export function queueRevivalBrief(asyncDir: string, request: SteerRequest): string {
+	const dir = path.join(controlInboxDir(asyncDir), REVIVAL_BRIEFS_DIR);
+	const queued = fs.existsSync(dir) ? fs.readdirSync(dir).filter((entry) => entry.endsWith(".json")).length : 0;
+	if (queued >= MAX_STEER_QUEUE_SIZE) throw new Error(`Follow-up queue is full (${MAX_STEER_QUEUE_SIZE} messages).`);
+	return writeSteerRequestToDir(dir, { ...request, mode: "follow_up" });
+}
+
+export function readRevivalBriefs(asyncDir: string): Array<{ request: SteerRequest; path: string }> {
+	const dir = path.join(controlInboxDir(asyncDir), REVIVAL_BRIEFS_DIR);
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir).filter((entry) => entry.endsWith(".json")).sort().flatMap((entry) => {
+		const filePath = path.join(dir, entry);
+		try {
+			const request = parseSteerRequest(JSON.parse(fs.readFileSync(filePath, "utf-8")));
+			return request ? [{ request, path: filePath }] : [];
+		} catch {
+			return [];
+		}
+	});
+}
+
 /**
  * Runner side: consume a pending interrupt request. Idempotent — removes the file
  * so each distinct request fires exactly once. Returns whether one was pending.

package/src/runs/background/retained-children.ts

@@ -0,0 +1,68 @@
+import * as fs from "node:fs";
+import { listAsyncRuns } from "./async-status.ts";
+import type { TokenUsage } from "../../shared/types.ts";
+
+const MAX_RETAINED_CHILDREN = 10;
+const MAX_TASK_SUMMARY_LENGTH = 120;
+
+export interface RetainedChild {
+	runId: string;
+	parentRunId?: string;
+	agent: string;
+	taskSummary: string;
+	completedAt: number;
+	sessionPath: string;
+	tokenTotals?: TokenUsage;
+}
+
+function retainedSessionFile(sessionFile: string | undefined): sessionFile is string {
+	if (!sessionFile?.endsWith(".jsonl")) return false;
+	try {
+		const stat = fs.lstatSync(sessionFile);
+		return stat.isFile() && !stat.isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+
+function boundedTaskSummary(value: string | undefined): string {
+	const normalized = value?.replace(/\s+/g, " ").trim() ?? "";
+	return normalized.length > MAX_TASK_SUMMARY_LENGTH
+		? `${normalized.slice(0, MAX_TASK_SUMMARY_LENGTH - 1)}…`
+		: normalized;
+}
+
+export function listRetainedChildren(asyncDirRoot: string, sessionId: string): RetainedChild[] {
+	return listAsyncRuns(asyncDirRoot, { sessionId, states: ["complete"], reconcile: false })
+		.flatMap((run) => {
+			if (!run.parentWorkflowRunId || run.steps.length !== 1) return [];
+			const step = run.steps[0]!;
+			if ((step.status !== "complete" && step.status !== "completed") || !retainedSessionFile(step.sessionFile ?? run.sessionFile)) return [];
+			const completedAt = run.endedAt;
+			if (completedAt === undefined) return [];
+			return [{
+				runId: run.id,
+				...(run.parentWorkflowRunId ? { parentRunId: run.parentWorkflowRunId } : {}),
+				agent: step.agent,
+				taskSummary: boundedTaskSummary(step.description),
+				completedAt,
+				sessionPath: step.sessionFile ?? run.sessionFile!,
+				...(step.tokens ?? run.totalTokens ? { tokenTotals: step.tokens ?? run.totalTokens } : {}),
+			}];
+		})
+		.sort((left, right) => right.completedAt - left.completedAt)
+		.slice(0, MAX_RETAINED_CHILDREN);
+}
+
+export function formatRetainedChildren(children: RetainedChild[]): string {
+	if (children.length === 0) return "No completed retained children in the active parent session.";
+	return [
+		`Completed retained children (newest first, last ${MAX_RETAINED_CHILDREN}):`,
+		...children.flatMap((child) => [
+			`- ${child.runId} | ${child.agent} | ${new Date(child.completedAt).toISOString()}`,
+			`  task: ${child.taskSummary || "(no task summary)"}`,
+			`  session: ${child.sessionPath}`,
+			...(child.tokenTotals ? [`  tokens: input ${child.tokenTotals.input}, output ${child.tokenTotals.output}, total ${child.tokenTotals.total}`] : []),
+		]),
+	].join("\n");
+}

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

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { DIRS, type SubagentState } from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
 import { findAsyncRunPrefixMatches, type AsyncRunLocation } from "./async-resume.ts";
 import { assertSafeNestedId, findNestedRunMatchesById, type NestedRoute, type NestedRunMatch, type NestedRunResolutionScope } from "../shared/nested-events.ts";
 
@@ -27,6 +28,70 @@ function exactAsyncLocation(id: string, asyncDirRoot: string, resultsDir: string
 	};
 }
 
+type AsyncRunMatch = { id: string; location: AsyncRunLocation };
+
+type WorkflowResultIdentity = {
+	id?: string;
+	runId?: string;
+	toolCallId?: string;
+};
+
+function readWorkflowResultIdentity(resultPath: string): WorkflowResultIdentity | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as unknown;
+	} catch {
+		return undefined;
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+	const record = parsed as Record<string, unknown>;
+	return {
+		...(typeof record.id === "string" ? { id: record.id } : {}),
+		...(typeof record.runId === "string" ? { runId: record.runId } : {}),
+		...(typeof record.toolCallId === "string" ? { toolCallId: record.toolCallId } : {}),
+	};
+}
+
+function directoryEntries(root: string): string[] {
+	try {
+		return fs.readdirSync(root);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+function resultPathFor(resultsDir: string, runId: string): string | null {
+	const resultPath = path.join(resultsDir, `${runId}.json`);
+	return fs.existsSync(resultPath) ? resultPath : null;
+}
+
+function toolCallIdMatches(value: string | undefined, query: string, options: { prefix?: boolean }): boolean {
+	if (value === undefined) return false;
+	return options.prefix === true ? value.startsWith(query) : value === query;
+}
+
+function toolCallIdAsyncLocations(toolCallId: string, asyncDirRoot: string, resultsDir: string, options: { prefix?: boolean } = {}): AsyncRunMatch[] {
+	const byId = new Map<string, AsyncRunLocation>();
+	for (const entry of directoryEntries(asyncDirRoot)) {
+		const asyncDir = path.join(asyncDirRoot, entry);
+		const status = readStatus(asyncDir);
+		if (!status || !toolCallIdMatches(status.toolCallId, toolCallId, options)) continue;
+		const runId = status.runId || entry;
+		byId.set(runId, { asyncDir, resultPath: resultPathFor(resultsDir, runId), resolvedId: runId });
+	}
+	for (const entry of directoryEntries(resultsDir)) {
+		if (!entry.endsWith(".json")) continue;
+		const resultPath = path.join(resultsDir, entry);
+		const identity = readWorkflowResultIdentity(resultPath);
+		if (!identity || !toolCallIdMatches(identity.toolCallId, toolCallId, options)) continue;
+		const runId = identity.runId ?? identity.id ?? entry.slice(0, -".json".length);
+		const asyncDir = path.join(asyncDirRoot, runId);
+		byId.set(runId, { asyncDir: fs.existsSync(asyncDir) ? asyncDir : null, resultPath, resolvedId: runId });
+	}
+	return [...byId.entries()].map(([id, location]) => ({ id, location }));
+}
+
 function foregroundIds(state: SubagentState | undefined): string[] {
 	if (!state) return [];
 	const remembered = state.currentSessionId
@@ -73,6 +138,9 @@ export function resolveSubagentRunId(id: string, deps: ResolveSubagentRunIdDeps
 	if (hasExactForegroundId(deps.state, id)) return { kind: "foreground", id };
 	const exactAsync = exactAsyncLocation(id, asyncDirRoot, resultsDir);
 	if (exactAsync) return { kind: "async", id, location: exactAsync };
+	const exactToolCallIdMatches = toolCallIdAsyncLocations(id, asyncDirRoot, resultsDir);
+	if (exactToolCallIdMatches.length > 1) throw new Error(`Subagent tool-call id '${id}' is ambiguous across async runs. Use the returned asyncId instead.`);
+	if (exactToolCallIdMatches[0]) return { kind: "async", id: exactToolCallIdMatches[0].id, location: exactToolCallIdMatches[0].location };
 	const exactNested = findNestedRunMatchesById(id, nestedScope ? { scope: nestedScope } : {});
 	if (exactNested.length > 1) throw new Error(`Nested run id '${id}' is ambiguous across authorized registries. Provide the full id after stale registries are cleaned up.`);
 	if (exactNested[0]) return { kind: "nested", id, match: exactNested[0] };
@@ -84,6 +152,9 @@ export function resolveSubagentRunId(id: string, deps: ResolveSubagentRunIdDeps
 	for (const match of asyncPrefixMatches(id, asyncDirRoot, resultsDir)) {
 		matches.push({ kind: "async", id: match.id, location: match.location });
 	}
+	for (const match of toolCallIdAsyncLocations(id, asyncDirRoot, resultsDir, { prefix: true })) {
+		matches.push({ kind: "async", id: match.id, location: match.location });
+	}
 	for (const match of findNestedRunMatchesById(id, nestedScope ? { prefix: true, scope: nestedScope } : { prefix: true })) {
 		matches.push({ kind: "nested", id: match.run.id, match });
 	}