@selesai/code 0.8.3 → 0.8.4

package/dist/extensions/pi-subagents/src/runs/background/control-channel.ts

@@ -9,9 +9,8 @@
  * This module adds a portable, file-based control inbox inside the run directory.
  * The parent drops an interrupt request file; the runner watches the inbox and
  * routes the request into its existing graceful `interruptRunner()` (pause +
- * resumable), identically on every platform. The OS signal is kept only as an
- * opportunistic fast-path; its failure is non-fatal because the file inbox is
- * authoritative.
+ * resumable), identically on every platform. The file inbox is authoritative and
+ * avoids signaling a PID that the extension cannot prove belongs to the runner.
  */
 
 import { randomUUID } from "node:crypto";
@@ -21,15 +20,19 @@ import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { POLL_INTERVAL_MS } from "../../shared/types.ts";
 import { resolveWatchPath } from "../../shared/utils.ts";
 
-/**
- * Opportunistic fast-path interrupt signal. On Unix `SIGUSR2` is trapped by the
- * runner; on Windows `process.kill(pid, "SIGBREAK")` is not deliverable
- * cross-process and throws `ENOSYS`, so the file inbox below is the real channel.
- */
-export const INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
-
 export type ControlChannelFs = Pick<typeof fs, "mkdirSync" | "existsSync" | "rmSync" | "watch" | "readdirSync" | "readFileSync" | "realpathSync">;
+
+function writeJsonToExistingDir(filePath: string, payload: object): void {
+	const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`);
+	try {
+		fs.writeFileSync(tempPath, JSON.stringify(payload, null, 2), { encoding: "utf-8", flag: "wx" });
+		fs.renameSync(tempPath, filePath);
+	} finally {
+		fs.rmSync(tempPath, { force: true });
+	}
+}
 export type ControlChannelTimers = { setInterval: typeof setInterval; clearInterval: typeof clearInterval };
+const CONTROL_SAFETY_POLL_INTERVAL_MS = 5000;
 type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => unknown;
 
 export interface InterruptRequest {
@@ -60,11 +63,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 +92,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 +196,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
@@ -205,6 +216,13 @@ export function writeSteerRequestToDir(dir: string, request: SteerRequest): stri
 	return requestPath;
 }
 
+export function writeSteerRequestToExistingDir(dir: string, request: SteerRequest): string {
+	if (!validSteerRequest(request)) throw new Error("steer request is malformed or exceeds transport limits.");
+	const requestPath = path.join(dir, steerRequestFileName(request));
+	writeJsonToExistingDir(requestPath, request);
+	return requestPath;
+}
+
 export function writeSteerCapabilityAt(filePath: string, capability: Omit<SteerCapability, "type" | "protocolVersion">): string {
 	assertChildIndex(capability.index);
 	if (!Number.isInteger(capability.pid) || capability.pid <= 0) throw new Error("steer capability pid must be a positive integer.");
@@ -218,14 +236,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 +313,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 +339,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 +374,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 {
@@ -371,6 +403,25 @@ export function consumeSteerCapabilities(asyncDir: string, fsImpl: Pick<typeof f
 	return capabilities;
 }
 
+export function consumeSteerAckFromDir(
+	dir: string,
+	requestId: string,
+	fsImpl: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync" | "rmSync"> = fs,
+): SteerAck | undefined {
+	if (!fsImpl.existsSync(dir)) return undefined;
+	let entries: string[];
+	try { entries = fsImpl.readdirSync(dir).filter((name) => name.endsWith(".json")).sort(); } catch { return undefined; }
+	for (const entry of entries) {
+		const target = path.join(dir, entry);
+		let ack: SteerAck | undefined;
+		try { ack = parseSteerAck(JSON.parse(fsImpl.readFileSync(target, "utf-8"))); } catch { ack = undefined; }
+		if (ack?.requestId !== requestId) continue;
+		try { fsImpl.rmSync(target, { force: true }); } catch { return undefined; }
+		return ack;
+	}
+	return undefined;
+}
+
 export function consumeSteerAcks(asyncDir: string, fsImpl: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync" | "rmSync"> = fs): SteerAck[] {
 	const root = path.join(controlInboxDir(asyncDir), STEER_ACKS_DIR);
 	if (!fsImpl.existsSync(root)) return [];
@@ -401,6 +452,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 +492,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.
@@ -501,38 +574,13 @@ export function consumeCheckpointDecisionRequest(
 	return undefined;
 }
 
-/**
- * Parent side: portable interrupt = authoritative file request + best-effort OS
- * signal. The signal is only a latency optimization on Unix; ENOSYS on Windows
- * is swallowed because the file inbox is authoritative there. Other signal
- * failures are surfaced because they usually mean the runner is not alive to
- * consume the request.
- */
+/** Parent side: write the authoritative portable interrupt request. */
 export function deliverInterruptRequest(input: {
 	asyncDir: string;
-	pid?: number;
-	kill?: KillFn;
-	signal?: NodeJS.Signals;
 	now?: () => number;
 	source?: string;
 }): void {
-	const requestPath = requestAsyncInterrupt(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });
-	if (typeof input.pid === "number" && input.pid > 0) {
-		try {
-			(input.kill ?? process.kill)(input.pid, input.signal ?? INTERRUPT_SIGNAL);
-		} catch (error) {
-			if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOSYS") {
-				// File inbox is authoritative when custom cross-process signals are unavailable.
-				return;
-			}
-			try {
-				fs.rmSync(requestPath, { force: true });
-			} catch {
-				// Best effort cleanup; the caller still gets the signal failure.
-			}
-			throw error;
-		}
-	}
+	requestAsyncInterrupt(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });
 }
 
 export function deliverTimeoutRequest(input: {
@@ -574,9 +622,9 @@ export function deliverCheckpointDecisionRequest(input: {
 
 /**
  * Runner side: watch the control inbox and route interrupt requests into
- * `onInterrupt`. Uses `fs.watch` when available plus an interval poll as a
- * portable safety net (covers filesystems/platforms where `fs.watch` is
- * unreliable). Fires once per distinct request. Returns a disposer.
+ * `onInterrupt`. Uses `fs.watch` when available and starts interval polling
+ * only when native watching is unavailable or fails. Fires once per distinct
+ * request. Returns a disposer.
  */
 export function watchAsyncControlInbox(
 	asyncDir: string,
@@ -589,6 +637,7 @@ export function watchAsyncControlInbox(
 		onSteerCapability?: (capability: SteerCapability) => void;
 		onSteerAck?: (ack: SteerAck) => void;
 		pollIntervalMs?: number;
+		safetyPollIntervalMs?: number;
 		fs?: ControlChannelFs;
 		timers?: ControlChannelTimers;
 	},
@@ -622,27 +671,63 @@ export function watchAsyncControlInbox(
 	// Handle a request that may have arrived before the watcher started.
 	check();
 
-	let watcher: fs.FSWatcher | undefined;
-	try {
-		watcher = fsImpl.watch(resolveWatchPath(dir, fsImpl.realpathSync.native), () => check());
-		watcher.on?.("error", () => {
-			// fs.watch can emit on transient FS errors; the interval poll keeps us live.
+	const watchers: fs.FSWatcher[] = [];
+	const watchedDirs = new Set<string>();
+	let interval: ReturnType<typeof setInterval> | undefined;
+	let safetyInterval: ReturnType<typeof setInterval> | undefined;
+	const startPolling = (): void => {
+		if (interval || disposed) return;
+		interval = timers.setInterval(check, opts.pollIntervalMs ?? POLL_INTERVAL_MS);
+		interval.unref?.();
+	};
+	const startSafetyPolling = (): void => {
+		if (safetyInterval || disposed) return;
+		safetyInterval = timers.setInterval(check, opts.safetyPollIntervalMs ?? CONTROL_SAFETY_POLL_INTERVAL_MS);
+		safetyInterval.unref?.();
+	};
+	const watchDir = (target: string, create = false): void => {
+		if (disposed || watchedDirs.has(target)) return;
+		if (create) fsImpl.mkdirSync(target, { recursive: true });
+		const watcher = fsImpl.watch(resolveWatchPath(target, fsImpl.realpathSync.native), () => {
+			watchExistingSteerAckDirs();
+			check();
 		});
+		watcher.on?.("error", startPolling);
+		watchers.push(watcher);
+		watchedDirs.add(target);
+	};
+	const watchExistingSteerAckDirs = (): void => {
+		const ackRoot = path.join(dir, STEER_ACKS_DIR);
+		let entries: string[];
+		try {
+			entries = fsImpl.readdirSync(ackRoot).filter((name) => /^\d+$/.test(name));
+		} catch {
+			return;
+		}
+		for (const entry of entries) watchDir(path.join(ackRoot, entry));
+	};
+	try {
+		watchDir(dir);
+		watchDir(steerRequestsDir(asyncDir), true);
+		watchDir(steerCapabilitiesDir(asyncDir), true);
+		watchDir(path.join(dir, STEER_ACKS_DIR), true);
+		watchExistingSteerAckDirs();
+		startSafetyPolling();
 	} catch {
-		watcher = undefined;
+		startPolling();
 	}
 
-	const interval = timers.setInterval(check, opts.pollIntervalMs ?? POLL_INTERVAL_MS);
-	interval.unref?.();
-
 	return () => {
 		if (disposed) return;
 		disposed = true;
-		try {
-			watcher?.close();
-		} catch {
-			// ignore
+		for (const watcher of watchers) {
+			try {
+				watcher.close();
+			} catch {
+				// ignore
+			}
 		}
-		timers.clearInterval(interval);
+		if (interval) timers.clearInterval(interval);
+		if (safetyInterval) timers.clearInterval(safetyInterval);
 	};
 }

package/dist/extensions/pi-subagents/src/runs/background/result-watcher.ts

@@ -20,13 +20,16 @@ import {
 } from "../../intercom/result-intercom.ts";
 import { projectNestedRegistryForRoot, sanitizeSummary } from "../shared/nested-events.ts";
 import { resolveWatchPath } from "../../shared/utils.ts";
+import { recordWaitCompletion } from "./wait-completions.ts";
+import { MISSION_BINDING_FILE, syncMissionFromAsyncCompletion } from "../../missions/lifecycle.ts";
 import type { CompletionNotifier, CompletionNotification } from "./notify.ts";
 
 const WATCHER_RESTART_DELAY_MS = 3000;
 const POLL_INTERVAL_MS = 3000;
+const HEALTHY_SCAN_INTERVAL_MS = 60_000;
 const RETRY_DELAY_MS = 100;
 
-type ResultWatcherFs = Pick<typeof fs, "existsSync" | "readFileSync" | "unlinkSync" | "readdirSync" | "mkdirSync" | "realpathSync" | "watch">;
+type ResultWatcherFs = Pick<typeof fs, "existsSync" | "readFileSync" | "unlinkSync" | "readdirSync" | "mkdirSync" | "realpathSync" | "statSync" | "watch">;
 
 type ResultWatcherTimers = {
 	setTimeout: typeof setTimeout;
@@ -41,6 +44,10 @@ type ResultWatcherDeps = {
 	notifier?: Pick<CompletionNotifier, "deliver">;
 	/** Receives persisted completions before active-session delivery filtering. */
 	observeCompletion?: (result: CompletionNotification & { runId: string }) => void;
+	/** Returns cross-session run ids that the completion observer currently owns. */
+	observedCompletionRunIds?: () => Iterable<string>;
+	/** Parses a relevant result payload after its lightweight identity check. */
+	parseResult?: (raw: string) => ResultFileData;
 	/** External grouped-result transport. Disable when native completion notifications own delivery. */
 	deliverIntercomResults?: boolean;
 };
@@ -74,6 +81,33 @@ type ResultFileData = CompletionNotification & {
 	parallelHandoff?: ParallelHandoffReference;
 };
 
+type ResultFileIdentity = {
+	sessionId?: string;
+	runId?: string;
+	asyncDir?: string;
+};
+
+function jsonStringProperty(raw: string, property: string): string | undefined {
+	const matches = raw.matchAll(new RegExp(`"${property}"\\s*:\\s*("(?:\\\\.|[^"\\\\])*")`, "g"));
+	let encoded: string | undefined;
+	for (const match of matches) encoded = match[1];
+	if (!encoded) return undefined;
+	try {
+		const value = JSON.parse(encoded) as unknown;
+		return typeof value === "string" && value ? value : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function resultFileIdentity(raw: string, file: string): ResultFileIdentity {
+	return {
+		sessionId: jsonStringProperty(raw, "sessionId"),
+		runId: file.replace(/\.json$/i, ""),
+		asyncDir: jsonStringProperty(raw, "asyncDir"),
+	};
+}
+
 function sanitizeNestedResultChildren(value: unknown, resultPath: string, label: string): NestedRunSummary[] | undefined {
 	if (value === undefined) return undefined;
 	if (!Array.isArray(value)) {
@@ -119,11 +153,14 @@ export function createResultWatcher(
 	const fsApi = deps.fs ?? fs;
 	const timers = deps.timers ?? { setTimeout, clearTimeout, setInterval, clearInterval };
 	const notifier = deps.notifier ?? { deliver: async () => true };
+	const parseResult = deps.parseResult ?? ((raw: string) => JSON.parse(raw) as ResultFileData);
 	const deliverIntercomResults = deps.deliverIntercomResults !== false;
 	const pendingTriggerTurn = new Map<string, boolean>();
 	const processing = new Set<string>();
+	const identityCache = new Map<string, { signature: string; identity: ResultFileIdentity }>();
 	let deliveryActive = true;
 	let deliveryEpoch = 0;
+	let resultScanTimer: ReturnType<typeof setInterval> | null = null;
 	// The sole in-memory ownership lease. It is acquired for one active session
 	// and revoked before the watcher, queues, or callbacks are torn down.
 	let activeSessionId: string | null = null;
@@ -140,14 +177,58 @@ export function createResultWatcher(
 		state.resultFileCoalescer.schedule(file, delayMs);
 	};
 
+	const inspectResult = (file: string): ResultFileIdentity | undefined => {
+		const resultPath = path.join(resultsDir, file);
+		try {
+			const stat = fsApi.statSync(resultPath);
+			const signature = `${stat.size}:${stat.mtimeMs}`;
+			const cached = identityCache.get(file);
+			if (cached?.signature === signature) return cached.identity;
+			const identity = resultFileIdentity(fsApi.readFileSync(resultPath, "utf-8"), file);
+			identityCache.set(file, { signature, identity });
+			return identity;
+		} catch (error) {
+			identityCache.delete(file);
+			if (!isNotFound(error)) console.error(`Failed to inspect subagent result file '${resultPath}':`, error);
+			return undefined;
+		}
+	};
+
+	const observedRunIds = (): ReadonlySet<string> => {
+		try {
+			return new Set(deps.observedCompletionRunIds?.() ?? []);
+		} catch (error) {
+			console.error("Failed to inspect observed subagent completion ids:", error);
+			return new Set();
+		}
+	};
+
+	const shouldProcessResult = (file: string, observed?: ReadonlySet<string>): boolean => {
+		const identity = inspectResult(file);
+		if (!identity) return false;
+		// Missing identity stays on the normal parser path so malformed or legacy
+		// files keep their existing diagnostics and compatibility behavior.
+		if (!identity.sessionId) return true;
+		if (identity.sessionId === state.currentSessionId) return true;
+		if (identity.asyncDir && fsApi.existsSync(path.join(identity.asyncDir, MISSION_BINDING_FILE))) return true;
+		if (identity.runId && (observed ?? observedRunIds()).has(identity.runId)) return true;
+		return Boolean(deps.observeCompletion && !deps.observedCompletionRunIds);
+	};
+
 	const handleResult = async (file: string, triggerTurn: boolean) => {
 		const resultPath = path.join(resultsDir, file);
 		if (processing.has(file) || !fsApi.existsSync(resultPath)) return;
+		if (!shouldProcessResult(file)) return;
 		processing.add(file);
 		try {
-			const data = JSON.parse(fsApi.readFileSync(resultPath, "utf-8")) as ResultFileData;
+			const data = parseResult(fsApi.readFileSync(resultPath, "utf-8"));
 			if (typeof data.sessionId !== "string" || !data.sessionId) return;
 			const runId = data.runId ?? data.id ?? file.replace(/\.json$/i, "");
+			try {
+				syncMissionFromAsyncCompletion({ ...data, runId });
+			} catch (error) {
+				console.error(`Mission completion sync failed for '${resultPath}':`, error);
+			}
 			try {
 				deps.observeCompletion?.({ ...data, runId });
 			} catch (error) {
@@ -155,6 +236,12 @@ export function createResultWatcher(
 			}
 			const epoch = deliveryEpoch;
 			if (!ownsSession(data.sessionId, epoch)) return;
+			// Recorded before dedupe and before the unlink below so subagent_wait can
+			// use the in-memory record or its bounded durable replay after cleanup.
+			recordWaitCompletion(state, runId, data, Date.now(), completionTtlMs, {
+				resultsDir,
+				sessionId: data.sessionId,
+			});
 			const hasExplicitNestedChildren = data.nestedChildren !== undefined;
 			let nestedChildren = compactNestedResultChildren(sanitizeNestedResultChildren(data.nestedChildren, resultPath, "nestedChildren"));
 			if (!nestedChildren?.length && !hasExplicitNestedChildren) {
@@ -175,6 +262,7 @@ export function createResultWatcher(
 				if (!ownsSession(data.sessionId, epoch) || !fsApi.existsSync(resultPath)) return;
 				try {
 					fsApi.unlinkSync(resultPath);
+					identityCache.delete(file);
 				} catch (error) {
 					if (!isNotFound(error)) {
 						console.error(`Failed to remove delivered subagent result '${resultPath}'; will retry:`, error);
@@ -300,6 +388,7 @@ export function createResultWatcher(
 			if (!ownsSession(data.sessionId, epoch) || !fsApi.existsSync(resultPath)) return;
 			try {
 				fsApi.unlinkSync(resultPath);
+				identityCache.delete(file);
 			} catch (error) {
 				if (!isNotFound(error)) {
 					console.error(`Failed to remove delivered subagent result '${resultPath}'; will retry:`, error);
@@ -324,15 +413,23 @@ export function createResultWatcher(
 			const triggerTurn = options.triggerTurn !== false;
 			fsApi.readdirSync(resultsDir)
 				.filter((f) => f.endsWith(".json"))
-				.forEach((file) => scheduleResult(file, triggerTurn));
+				.forEach((file) => {
+					if (shouldProcessResult(file)) scheduleResult(file, triggerTurn);
+				});
 		} catch (error) {
 			if (!isNotFound(error)) console.error(`Failed to scan subagent result directory '${resultsDir}':`, error);
 		}
 	};
 
+	const clearResultScan = () => {
+		if (resultScanTimer) timers.clearInterval(resultScanTimer);
+		resultScanTimer = null;
+	};
+
 	const startPolling = (reason: unknown) => {
 		state.watcher?.close();
 		state.watcher = null;
+		clearResultScan();
 		if (state.watcherRestartTimer) return;
 		console.error(`Subagent result watcher for '${resultsDir}' fell back to polling because native fs.watch is unavailable (${errorCode(reason) ?? "unknown error"}).`);
 		primeExistingResults();
@@ -341,6 +438,7 @@ export function createResultWatcher(
 	};
 
 	const scheduleRestart = () => {
+		clearResultScan();
 		if (state.watcherRestartTimer) return;
 		state.watcherRestartTimer = timers.setTimeout(() => {
 			state.watcherRestartTimer = null;
@@ -368,10 +466,16 @@ export function createResultWatcher(
 		}
 		try {
 			const watchDir = resolveWatchPath(resultsDir, fsApi.realpathSync.native);
-			state.watcher = fsApi.watch(watchDir, (event, file) => {
-				if (event !== "rename" || !file) return;
+			state.watcher = fsApi.watch(watchDir, (_event, file) => {
+				if (!file) {
+					primeExistingResults();
+					return;
+				}
 				const fileName = file.toString();
-				if (fileName.endsWith(".json")) scheduleResult(fileName, true);
+				if (fileName.endsWith(".json")) {
+					identityCache.delete(fileName);
+					scheduleResult(fileName, true);
+				}
 			});
 			state.watcher.on("error", (error) => {
 				if (shouldPoll(error)) return startPolling(error);
@@ -381,6 +485,8 @@ export function createResultWatcher(
 				scheduleRestart();
 			});
 			state.watcher.unref?.();
+			resultScanTimer = timers.setInterval(primeExistingResults, HEALTHY_SCAN_INTERVAL_MS);
+			resultScanTimer.unref?.();
 		} catch (error) {
 			if (shouldPoll(error)) return startPolling(error);
 			console.error(`Failed to start subagent result watcher for '${resultsDir}':`, error);
@@ -400,9 +506,11 @@ export function createResultWatcher(
 			timers.clearInterval(state.watcherRestartTimer);
 		}
 		state.watcherRestartTimer = null;
+		clearResultScan();
 		state.resultFileCoalescer.clear();
 		pendingTriggerTurn.clear();
 		processing.clear();
+		identityCache.clear();
 	};
 
 	return { startResultWatcher, primeExistingResults, stopResultWatcher };

package/dist/extensions/pi-subagents/src/runs/background/resume-guidance.ts

@@ -0,0 +1,33 @@
+import * as fs from "node:fs";
+import type { AsyncRunSummary } from "./async-status.ts";
+
+export function formatAsyncReviveCommand(run: AsyncRunSummary): string | undefined {
+	const step = run.steps.find((candidate) => candidate.status === "failed" && candidate.sessionFile && fs.existsSync(candidate.sessionFile));
+	if (!step) {
+		if (run.steps.length === 1 && run.sessionFile && fs.existsSync(run.sessionFile)) {
+			return `subagent({ action: "resume", id: "${run.id}", message: "Continue from the persisted child session and report the result." })`;
+		}
+		return undefined;
+	}
+	const index = run.steps.length === 1 ? "" : `, index: ${step.index}`;
+	return `subagent({ action: "resume", id: "${run.id}"${index}, message: "Continue from the persisted child session and report the result." })`;
+}
+
+export function formatResumeFirstFailedRunDetail(run: AsyncRunSummary): string | undefined {
+	if (run.state !== "failed") return undefined;
+	const command = formatAsyncReviveCommand(run);
+	if (!command) return undefined;
+	return `Resume-first: failed run "${run.id}" has a persisted child session. Revive the original run with ${command} before reporting failure or launching a replacement. Launch a replacement only if revive fails or the user explicitly asks for one.`;
+}
+
+export function formatResumeFirstFailedRunsNote(runs: AsyncRunSummary[]): string {
+	const resumable = runs
+		.filter((run) => run.state === "failed")
+		.map((run) => ({ run, command: formatAsyncReviveCommand(run) }))
+		.filter((entry): entry is { run: AsyncRunSummary; command: string } => Boolean(entry.command));
+	if (resumable.length === 0) return "";
+	const guidance = resumable.length === 1
+		? `failed run "${resumable[0]!.run.id}" has a persisted child session. Revive the original run with ${resumable[0]!.command}`
+		: `${resumable.length} failed runs have persisted child sessions. Inspect status and revive each original run before retrying`;
+	return ` Resume-first: ${guidance} before reporting failure or launching a replacement. Launch a replacement only if revive fails or the user explicitly asks for one.`;
+}