pi-agent-squad 0.8.0 → 0.8.3

package/pool.ts

@@ -59,18 +59,45 @@ export function finalOutput(messages: TaskResult["messages"]): string {
 
 const IDLE_RECYCLE_MS = 10 * 60 * 1000; // recycle idle processes after 10 min
 const FORCE_KILL_DELAY_MS = 5000;
+/** Max wait for one RPC command/response round trip on the control channel. */
+const RPC_TIMEOUT_MS = 30 * 1000;
+/** Max wait for a freshly spawned RPC child to answer its first command. */
+const STARTUP_TIMEOUT_MS = 30 * 1000;
 
 interface TurnWaiter {
+	/**
+	 * agent_settled generation this waiter is waiting to exceed; `null` while
+	 * the prompt that started the turn has not been accepted yet. A waiter is
+	 * only resolved by an agent_settled observed after its own prompt was
+	 * accepted, so a stale settled from an earlier turn can never complete it.
+	 */
+	waitGen: number | null;
 	resolve: () => void;
 	reject: (error: Error) => void;
 }
 
+/** One in-flight RPC request awaiting its id-correlated response. */
+interface PendingCall {
+	resolve: (data: unknown) => void;
+	reject: (error: Error) => void;
+}
+
 interface PooledProcess {
 	agent: AgentConfig;
+	runId: string;
+	childIndex: number;
 	proc: ChildProcess;
 	nextId: number;
-	pending: Map<string, (data: unknown) => void>;
-	events: Array<Record<string, unknown>>;
+	pending: Map<string, PendingCall>;
+	/** Count of observed agent_settled events; used to correlate task waiters. */
+	settledGeneration: number;
+	/** Events for the currently running task only; never a process-wide log. */
+	activeTaskEvents?: Array<Record<string, unknown>>;
+	/**
+	 * Temp file holding --append-system-prompt. Deleted once the child
+	 * confirmed startup (first RPC answer) or when the process is gone.
+	 */
+	promptPath?: string;
 	lastUsed: number;
 	spawnError?: string;
 	closed: boolean;
@@ -81,8 +108,13 @@ interface PooledProcess {
 
 export class SubagentPool {
 	private procs = new Map<string, PooledProcess>();
+	private starting = new Map<string, Promise<PooledProcess>>();
+	private startingProcesses = new Map<string, PooledProcess>();
+	/** Per-agent queue serializing check-then-act session ops (send/abort). */
+	private sessionOps = new Map<string, Promise<unknown>>();
 	private eventListeners = new Map<string, Set<(event: any) => void>>();
 	private taskTails = new Map<string, Promise<void>>();
+	private processExitHandler?: (agentName: string, runId: string) => void;
 	private recycleTimer: ReturnType<typeof setInterval>;
 	private messageRoot: string;
 	private workingDirectory = process.cwd();
@@ -108,6 +140,66 @@ export class SubagentPool {
 		}
 	}
 
+	setProcessExitHandler(handler: ((agentName: string, runId: string) => void) | undefined): void {
+		this.processExitHandler = handler;
+	}
+
+	private isUsable(pooled: PooledProcess | undefined): pooled is PooledProcess {
+		return (
+			!!pooled &&
+			!pooled.closed &&
+			pooled.proc.exitCode === null &&
+			pooled.proc.signalCode === null
+		);
+	}
+
+	private stderrTail(pooled: PooledProcess): string {
+		const text = (pooled.spawnError ?? "").trim();
+		if (!text) return "";
+		return text.length > 2000 ? `…${text.slice(-2000)}` : text;
+	}
+
+	/** Reject every in-flight RPC call; the process is going away. */
+	private failPending(pooled: PooledProcess, error: Error): void {
+		const calls = [...pooled.pending.values()];
+		pooled.pending.clear();
+		for (const call of calls) call.reject(error);
+	}
+
+	/** Delete the --append-system-prompt temp file (idempotent). */
+	private cleanupPromptFile(pooled: PooledProcess): void {
+		const filePath = pooled.promptPath;
+		if (!filePath) return;
+		pooled.promptPath = undefined;
+		try {
+			fs.unlinkSync(filePath);
+		} catch {
+			/* already gone */
+		}
+		try {
+			fs.rmdirSync(path.dirname(filePath));
+		} catch {
+			/* not empty or already gone */
+		}
+	}
+
+	/**
+	 * Serialize check-then-act session operations (send/abort) per agent. This
+	 * is separate from withAgentLock on purpose: tasks hold the agent lock for
+	 * their whole duration, while session ops must interleave with a running
+	 * task (e.g. steering or aborting it from the UI).
+	 */
+	private withSessionOp<T>(agentName: string, run: () => Promise<T>): Promise<T> {
+		const previous = this.sessionOps.get(agentName) ?? Promise.resolve();
+		const next: Promise<T> = previous.catch(() => {}).then(run);
+		const tail = next.catch(() => {});
+		this.sessionOps.set(agentName, tail);
+		void tail.finally(() => {
+			if (this.sessionOps.get(agentName) === tail) this.sessionOps.delete(agentName);
+		});
+		return next;
+	}
+
 	/** Serialize tasks per agent so one agent_end cannot complete multiple callers. */
 	private async withAgentLock<T>(agentName: string, run: () => Promise<T>): Promise<T> {
 		const previous = this.taskTails.get(agentName) ?? Promise.resolve();
@@ -129,10 +221,15 @@ export class SubagentPool {
 
 	private terminateProcess(agentName: string, pooled: PooledProcess, reason: Error): void {
 		if (this.procs.get(agentName) === pooled) this.procs.delete(agentName);
+		const wasClosed = pooled.closed;
 		pooled.closed = true;
-		this.emitAgentEvent(agentName, { type: "session_closed", error: reason.message });
-		const waiters = pooled.turnWaiters.splice(0);
-		for (const waiter of waiters) waiter.reject(reason);
+		this.failPending(pooled, reason);
+		if (!wasClosed) this.processExitHandler?.(agentName, pooled.runId);
+		if (!wasClosed) {
+			this.emitAgentEvent(agentName, { type: "session_closed", error: reason.message });
+			const waiters = pooled.turnWaiters.splice(0);
+			for (const waiter of waiters) waiter.reject(reason);
+		}
 		try {
 			pooled.proc.kill("SIGTERM");
 		} catch {
@@ -166,17 +263,43 @@ export class SubagentPool {
 		const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
 		const safeName = agentName.replace(/[^\w.-]+/g, "_");
 		const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
-		await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
-		return filePath;
+		try {
+			await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
+			return filePath;
+		} catch (error) {
+			await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+			throw error;
+		}
 	}
 
-	/** Ensure a resident process exists for the agent */
+	/** Ensure a resident process exists for the agent. Concurrent callers share one startup. */
 	async ensureProcess(agent: AgentConfig): Promise<PooledProcess> {
 		if (this.disposed) throw new Error("Subagent pool is disposed.");
 		const existing = this.procs.get(agent.name);
-		if (existing && !existing.closed && existing.proc.exitCode === null && existing.proc.signalCode === null) {
-			return existing;
+		if (this.isUsable(existing)) return existing;
+		const inFlight = this.starting.get(agent.name);
+		if (inFlight) {
+			// Another caller is already spawning this agent; share its startup
+			// instead of spawning an orphan. A rejected startup propagates to
+			// every waiter; if it resolved with a process that died right away,
+			// fall through to the normal path again.
+			const pooled = await inFlight;
+			if (this.isUsable(pooled) && this.procs.get(agent.name) === pooled) return pooled;
+			return this.ensureProcess(agent);
+		}
+		const startup = this.startProcess(agent);
+		this.starting.set(agent.name, startup);
+		try {
+			return await startup;
+		} finally {
+			if (this.starting.get(agent.name) === startup) this.starting.delete(agent.name);
 		}
+	}
+
+	private async startProcess(agent: AgentConfig): Promise<PooledProcess> {
+		if (this.disposed) throw new Error("Subagent pool is disposed.");
+		const existing = this.procs.get(agent.name);
+		if (this.isUsable(existing)) return existing;
 		// kill the old process, if any
 		if (existing) {
 			this.terminateProcess(agent.name, existing, new Error(`Replacing stale subagent process for ${agent.name}.`));
@@ -194,7 +317,7 @@ export class SubagentPool {
 		let tmpPromptPath: string | null = null;
 		if (agent.systemPrompt.trim()) {
 			tmpPromptPath = await this.writePromptToTempFile(agent.name, agent.systemPrompt);
-			args.push("--append-system-prompt", tmpPromptPath);
+			if (tmpPromptPath) args.push("--append-system-prompt", tmpPromptPath);
 		}
 
 		const runId = randomUUID();
@@ -210,10 +333,13 @@ export class SubagentPool {
 
 		const pooled: PooledProcess = {
 			agent,
+			runId,
+			childIndex,
 			proc: null as unknown as ChildProcess,
 			nextId: 1,
 			pending: new Map(),
-			events: [],
+			settledGeneration: 0,
+			promptPath: tmpPromptPath ?? undefined,
 			lastUsed: Date.now(),
 			closed: false,
 			turnWaiters: [],
@@ -227,86 +353,83 @@ export class SubagentPool {
 			env,
 		});
 		pooled.proc = proc;
+		this.startingProcesses.set(agent.name, pooled);
 
 		let buffer = "";
-		let readyResolve: (() => void) | undefined;
-		const ready = new Promise<void>((r) => (readyResolve = r));
-		let readyTimer: ReturnType<typeof setTimeout> | undefined;
 		proc.stdout.on("data", (data) => {
 			buffer += data.toString();
 			const lines = buffer.split("\n");
 			buffer = lines.pop() || "";
 			for (const line of lines) this.processLine(pooled, line);
-			// any event means the RPC loop is up
-			if (readyResolve && pooled.events.length > 0) {
-				readyResolve();
-				readyResolve = undefined;
-				if (readyTimer) clearTimeout(readyTimer);
-			}
 		});
 		proc.stderr.on("data", (data) => {
 			pooled.spawnError = (pooled.spawnError ?? "") + data.toString();
 		});
 		proc.on("close", (code) => {
+			const wasClosed = pooled.closed;
 			pooled.closed = true;
-			this.emitAgentEvent(agent.name, {
-				type: "session_closed",
-				error: `Subagent process exited (code ${code ?? "unknown"}).`,
-			});
-			if (readyResolve) {
-				readyResolve();
-				readyResolve = undefined;
-				if (readyTimer) clearTimeout(readyTimer);
-			}
-			for (const [, resolve] of pooled.pending) {
-				resolve({ type: "process_exit", code });
-			}
-			pooled.pending.clear();
-			pooled.events.push({ type: "process_exit", code });
-			const waiters = pooled.turnWaiters.splice(0);
-			const error = new Error(
-				`Subagent process exited before completing the task (code ${code ?? "unknown"}).${pooled.spawnError ? ` ${pooled.spawnError.trim()}` : ""}`,
+			if (this.procs.get(agent.name) === pooled) this.procs.delete(agent.name);
+			if (this.startingProcesses.get(agent.name) === pooled) this.startingProcesses.delete(agent.name);
+			this.failPending(
+				pooled,
+				new Error(`Subagent process exited before answering (code ${code ?? "unknown"}).`),
 			);
-			for (const waiter of waiters) waiter.reject(error);
+			const waiters = pooled.turnWaiters.splice(0);
+			if (!wasClosed) {
+				this.processExitHandler?.(agent.name, pooled.runId);
+				if (waiters.length > 0) {
+					const error = new Error(
+						`Subagent process exited before completing the task (code ${code ?? "unknown"}).${pooled.spawnError ? ` ${this.stderrTail(pooled)}` : ""}`,
+					);
+					for (const waiter of waiters) waiter.reject(error);
+				}
+				this.emitAgentEvent(agent.name, {
+					type: "session_closed",
+					error: `Subagent process exited (code ${code ?? "unknown"}).`,
+				});
+			}
+			// Safety net: a prompt file is still on disk if the child never
+			// confirmed startup; the process is gone now, so it can go too.
+			this.cleanupPromptFile(pooled);
 		});
 		proc.on("error", (err) => {
-			pooled.spawnError = err.message;
-			if (readyResolve) {
-				readyResolve();
-				readyResolve = undefined;
-				if (readyTimer) clearTimeout(readyTimer);
-			}
+			pooled.spawnError = (pooled.spawnError ?? "") + err.message;
+			this.failPending(pooled, new Error(`Failed to start subagent ${agent.name}: ${err.message}`));
 		});
 
-		// wait for RPC readiness: first event, or a 2s fallback timeout
-		readyTimer = setTimeout(() => {
-			if (readyResolve) {
-				readyResolve();
-				readyResolve = undefined;
-			}
-		}, 2000);
 		try {
-			await ready;
-			if (this.disposed) {
-				this.terminateProcess(agent.name, pooled, new Error("Subagent pool disposed during process startup."));
-				throw new Error("Subagent pool is disposed.");
-			}
-			if (pooled.closed || proc.exitCode !== null || proc.signalCode !== null) {
+			// Startup is confirmed only when the RPC loop answers a real command.
+			// The previous "first event or 2s" heuristic could resolve before the
+			// child had booted, deleting the system-prompt file while it was still
+			// needed.
+			const response = await this.sendCommandAndWait(pooled, { type: "get_state" }, STARTUP_TIMEOUT_MS);
+			this.responseData(response);
+			if (this.disposed) throw new Error("Subagent pool is disposed.");
+			if (!this.isUsable(pooled)) {
+				const stderr = this.stderrTail(pooled);
 				throw new Error(
-					`Failed to start subagent ${agent.name}.${pooled.spawnError ? ` ${pooled.spawnError.trim()}` : ""}`,
+					`Failed to start subagent ${agent.name}.${stderr ? ` ${stderr}` : ""}`,
 				);
 			}
+			// The child confirmed startup (RPC answered): the system prompt has
+			// been read from the temp file and it can be removed now. The close
+			// handler keeps a best-effort cleanup as a safety net.
+			this.cleanupPromptFile(pooled);
 			this.procs.set(agent.name, pooled);
+			this.startingProcesses.delete(agent.name);
+			this.emitAgentEvent(agent.name, {
+				type: "session_ready",
+				agent: agent.name,
+				runId,
+				childIndex,
+			});
 			return pooled;
-		} finally {
-			if (tmpPromptPath) {
-				try {
-					fs.unlinkSync(tmpPromptPath);
-					fs.rmdirSync(path.dirname(tmpPromptPath));
-				} catch {
-					/* ignore */
-				}
-			}
+		} catch (error) {
+			const failure = error instanceof Error ? error : new Error(String(error));
+			this.terminateProcess(agent.name, pooled, failure);
+			this.startingProcesses.delete(agent.name);
+			this.cleanupPromptFile(pooled);
+			throw failure;
 		}
 	}
 
@@ -318,22 +441,34 @@ export class SubagentPool {
 		} catch {
 			return;
 		}
-		if (event?.type === "response" && event?.id !== undefined) {
-			const resolve = pooled.pending.get(String(event.id));
-			if (resolve) {
+		if (event?.type === "response") {
+			// A response without an id cannot be correlated; drop it instead of
+			// treating it as an agent event.
+			if (event?.id === undefined) return;
+			const call = pooled.pending.get(String(event.id));
+			if (call) {
 				pooled.pending.delete(String(event.id));
-				resolve(event);
+				call.resolve(event);
 			}
 			return;
 		}
-		pooled.events.push(event);
+		pooled.activeTaskEvents?.push(event);
 		this.emitAgentEvent(pooled.agent.name, event);
 		// The whole session-level run is finished only at agent_settled. Waiting
 		// for agent_end would close the activity before queued interactive steer
-		// or follow-up messages have been processed.
-		if (event?.type === "agent_settled" && pooled.turnWaiters.length > 0) {
-			const waiters = pooled.turnWaiters.splice(0);
-			for (const waiter of waiters) waiter.resolve();
+		// or follow-up messages have been processed. A waiter only completes for
+		// a settled observed after its own prompt was accepted (waitGen), so a
+		// stale settled already in flight cannot complete a newer task.
+		if (event?.type === "agent_settled") {
+			pooled.settledGeneration++;
+			if (pooled.turnWaiters.length > 0) {
+				const remaining: TurnWaiter[] = [];
+				for (const waiter of pooled.turnWaiters) {
+					if (waiter.waitGen !== null && waiter.waitGen < pooled.settledGeneration) waiter.resolve();
+					else remaining.push(waiter);
+				}
+				pooled.turnWaiters = remaining;
+			}
 		}
 	}
 
@@ -356,17 +491,33 @@ export class SubagentPool {
 		return id;
 	}
 
-	private sendCommandAndWait(pooled: PooledProcess, cmd: Record<string, unknown>, timeoutMs: number): Promise<unknown> {
+	private sendCommandAndWait(
+		pooled: PooledProcess,
+		cmd: Record<string, unknown>,
+		timeoutMs: number,
+		onResponded?: () => void,
+	): Promise<unknown> {
 		const id = this.sendCommand(pooled, cmd);
 		return new Promise((resolve, reject) => {
-			const timer = setTimeout(() => {
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const call: PendingCall = {
+				resolve: (data) => {
+					if (timer) clearTimeout(timer);
+					// Runs synchronously inside processLine before any later stdout
+					// line is parsed; runTask relies on that for settled ordering.
+					onResponded?.();
+					resolve(data);
+				},
+				reject: (error) => {
+					if (timer) clearTimeout(timer);
+					reject(error);
+				},
+			};
+			timer = setTimeout(() => {
 				pooled.pending.delete(id);
-				reject(new Error("RPC command timed out"));
+				call.reject(new Error(`RPC command ${String(cmd.type ?? "unknown")} timed out.`));
 			}, timeoutMs);
-			pooled.pending.set(id, (data) => {
-				clearTimeout(timer);
-				resolve(data);
-			});
+			pooled.pending.set(id, call);
 		});
 	}
 
@@ -382,26 +533,39 @@ export class SubagentPool {
 			agent: agent.name,
 			getMessages: async () => {
 				const pooled = await this.ensureProcess(agent);
-				const response = await this.sendCommandAndWait(pooled, { type: "get_messages" }, 10000);
+				pooled.lastUsed = Date.now();
+				const response = await this.sendCommandAndWait(pooled, { type: "get_messages" }, RPC_TIMEOUT_MS);
 				return this.responseData(response)?.messages ?? [];
 			},
 			isStreaming: async () => {
 				const pooled = await this.ensureProcess(agent);
-				const response = await this.sendCommandAndWait(pooled, { type: "get_state" }, 10000);
+				pooled.lastUsed = Date.now();
+				const response = await this.sendCommandAndWait(pooled, { type: "get_state" }, RPC_TIMEOUT_MS);
 				return this.responseData(response)?.isStreaming === true;
 			},
 			send: async (message: string) => {
-				const pooled = await this.ensureProcess(agent);
-				const stateResponse = await this.sendCommandAndWait(pooled, { type: "get_state" }, 10000);
-				const streaming = this.responseData(stateResponse)?.isStreaming === true;
-				const command = streaming ? { type: "steer", message } : { type: "prompt", message };
-				const response = await this.sendCommandAndWait(pooled, command, 10000);
-				this.responseData(response);
+				// Session ops must interleave with a running task (steering or
+				// aborting it from the UI), so this uses withSessionOp and never
+				// the agent task lock, which a task holds for its whole duration.
+				await this.withSessionOp(agent.name, async () => {
+					const pooled = await this.ensureProcess(agent);
+					pooled.lastUsed = Date.now();
+					const stateResponse = await this.sendCommandAndWait(pooled, { type: "get_state" }, RPC_TIMEOUT_MS);
+					const streaming = this.responseData(stateResponse)?.isStreaming === true;
+					const command = streaming ? { type: "steer", message } : { type: "prompt", message };
+					// Check the RPC response: a rejected steer/prompt must surface
+					// to the caller instead of silently dropping the message.
+					const response = await this.sendCommandAndWait(pooled, command, RPC_TIMEOUT_MS);
+					this.responseData(response);
+				});
 			},
 			abort: async () => {
-				const pooled = await this.ensureProcess(agent);
-				const response = await this.sendCommandAndWait(pooled, { type: "abort" }, 10000);
-				this.responseData(response);
+				await this.withSessionOp(agent.name, async () => {
+					const pooled = await this.ensureProcess(agent);
+					pooled.lastUsed = Date.now();
+					const response = await this.sendCommandAndWait(pooled, { type: "abort" }, RPC_TIMEOUT_MS);
+					this.responseData(response);
+				});
 			},
 			subscribe: (listener) => {
 				let listeners = this.eventListeners.get(agent.name);
@@ -418,7 +582,26 @@ export class SubagentPool {
 		};
 	}
 
-	/** Send a prompt command (fire-and-forget; events land in events) */
+	/** Runtime identity of the resident process, for the main-side run registry. */
+	getProcessIdentity(agentName: string): { runId: string; childIndex: number } | undefined {
+		const pooled = this.procs.get(agentName);
+		if (!pooled || pooled.closed || pooled.proc.exitCode !== null || pooled.proc.signalCode !== null) {
+			return undefined;
+		}
+		return { runId: pooled.runId, childIndex: pooled.childIndex };
+	}
+
+	/** Drop a resident so a subsequent request loads updated agent configuration. */
+	restartAgent(agentName: string): void {
+		const pooled = this.procs.get(agentName);
+		if (pooled) this.terminateProcess(agentName, pooled, new Error(`Reloading configuration for ${agentName}.`));
+	}
+
+	/**
+	 * Send a prompt command fire-and-forget; events are delivered to listeners.
+	 * The RPC response is not awaited — prefer the session handle's `send`
+	 * (validates the response, avoids prompt/settled mismatches) or `runTask`.
+	 */
 	sendPrompt(agent: AgentConfig, message: string): string {
 		const pooled = this.procs.get(agent.name);
 		if (!pooled || pooled.closed) throw new Error(`No process for agent ${agent.name}`);
@@ -434,7 +617,9 @@ export class SubagentPool {
 		onUpdate?: (events: unknown[]) => void,
 		signal?: AbortSignal,
 	): Promise<TaskResult> {
+		if (signal?.aborted) throw new Error("Subagent task cancelled.");
 		return this.withAgentLock(agent.name, async () => {
+			if (signal?.aborted) throw new Error("Subagent task cancelled.");
 			const pooled = await this.ensureProcess(agent);
 			pooled.lastUsed = Date.now();
 
@@ -447,99 +632,126 @@ export class SubagentPool {
 				model: agent.model,
 			};
 
-			// event index at the start of this task
-			const startIndex = pooled.events.length;
-			// Register the waiter before sending the prompt so an extremely fast
-			// agent_end cannot arrive in the gap and leave us waiting until timeout.
-			const completion = new Promise<void>((resolve, reject) => {
-				let waiter: TurnWaiter;
+			// Collect only this task's events. A process-wide event history would
+			// grow without bound for long-lived resident processes.
+			const taskEvents: Array<Record<string, unknown>> = [];
+			pooled.activeTaskEvents = taskEvents;
+			try {
+				// One waiter per task, registered before the prompt is sent so no
+				// completion event can slip through a registration gap. It fires
+				// only for an agent_settled observed after this prompt was accepted
+				// (waitGen, see processLine): a stale settled that is still in
+				// flight cannot complete this task early, and a rejected prompt
+				// rejects the waiter instead of hanging until timeout.
+				let finish!: () => void;
+				let fail!: (error: Error) => void;
+				const completion = new Promise<void>((resolve, reject) => {
+					finish = resolve;
+					fail = reject;
+				});
+				// An early failure below throws without awaiting completion.
+				void completion.catch(() => {});
+				let timer: ReturnType<typeof setTimeout> | undefined;
 				let abortHandler: (() => void) | undefined;
-				const cleanup = () => {
-					clearTimeout(timer);
-					if (signal && abortHandler) signal.removeEventListener("abort", abortHandler);
-				};
-				const timer = setTimeout(() => {
+				const detach = () => {
 					const i = pooled.turnWaiters.indexOf(waiter);
 					if (i >= 0) pooled.turnWaiters.splice(i, 1);
-					const error = new Error(`Subagent task timed out after ${Math.round(timeoutMs / 1000)}s`);
-					this.terminateProcess(agent.name, pooled, error);
-					cleanup();
-					reject(error);
-				}, timeoutMs);
-				waiter = {
+					if (timer) clearTimeout(timer);
+					if (signal && abortHandler) signal.removeEventListener("abort", abortHandler);
+				};
+				const waiter: TurnWaiter = {
+					waitGen: null,
 					resolve: () => {
-						cleanup();
-						resolve();
+						detach();
+						finish();
 					},
 					reject: (error) => {
-						cleanup();
-						reject(error);
+						detach();
+						fail(error);
 					},
 				};
-				pooled.turnWaiters.push(waiter);
+				timer = setTimeout(() => {
+					const error = new Error(`Subagent task timed out after ${Math.round(timeoutMs / 1000)}s`);
+					detach();
+					this.terminateProcess(agent.name, pooled, error);
+					fail(error);
+				}, timeoutMs);
 				if (signal) {
 					abortHandler = () => {
-						const i = pooled.turnWaiters.indexOf(waiter);
-						if (i >= 0) pooled.turnWaiters.splice(i, 1);
 						const error = new Error("Subagent task cancelled.");
+						detach();
 						this.terminateProcess(agent.name, pooled, error);
-						cleanup();
-						reject(error);
+						fail(error);
 					};
 					if (signal.aborted) abortHandler();
 					else signal.addEventListener("abort", abortHandler, { once: true });
 				}
-			});
-			try {
-				this.sendCommand(pooled, { type: "prompt", message: task });
-			} catch (e) {
-				const waiter = pooled.turnWaiters.pop();
-				waiter?.reject(e instanceof Error ? e : new Error(String(e)));
-			}
+				pooled.turnWaiters.push(waiter);
+				try {
+					await this.withSessionOp(agent.name, async () => {
+						// Serialize the busy check with concurrent UI sends so the
+						// settled waiter can never bind to a foreign turn: a busy
+						// process is a hard error, not a silently queued prompt.
+						const stateResponse = await this.sendCommandAndWait(pooled, { type: "get_state" }, RPC_TIMEOUT_MS);
+						if (this.responseData(stateResponse)?.isStreaming === true) {
+							throw new Error(`Subagent ${agent.name} is busy; the current run must settle first.`);
+						}
+						const promptResponse = await this.sendCommandAndWait(
+							pooled,
+							{ type: "prompt", message: task },
+							RPC_TIMEOUT_MS,
+							// Captured synchronously when the prompt response line is
+							// parsed: every agent_settled parsed after this moment
+							// belongs to (or follows) this task's turn.
+							() => {
+								waiter.waitGen = pooled.settledGeneration;
+							},
+						);
+						// Check the RPC response; success:false (prompt rejected)
+						// must fail the task instead of waiting on an unrelated turn.
+						this.responseData(promptResponse);
+					});
+				} catch (e) {
+					const error = e instanceof Error ? e : new Error(String(e));
+					waiter.reject(error);
+					throw error;
+				}
 
-			// RPC returns the prompt response at preflight; wait for agent_settled
-			// so retries, compaction, and interactive queued messages are included.
-			await completion;
-
-			// collect the events for this task
-			const taskEvents = pooled.events.slice(startIndex);
-			for (const ev of taskEvents as any[]) {
-				if (ev.type === "message_end" && ev.message) {
-					result.messages.push(ev.message);
-					if (ev.message.role === "assistant") {
-						result.usage.turns++;
-						const u = ev.message.usage;
-						if (u) {
-							result.usage.input += u.input || 0;
-							result.usage.output += u.output || 0;
-							result.usage.cacheRead += u.cacheRead || 0;
-							result.usage.cacheWrite += u.cacheWrite || 0;
-							result.usage.cost += u.cost?.total || 0;
-							result.usage.contextTokens = u.totalTokens || 0;
+				// RPC returns the prompt response at preflight; wait for agent_settled
+				// so retries, compaction, and interactive queued messages are included.
+				await completion;
+
+				for (const ev of taskEvents as any[]) {
+					if (ev.type === "message_end" && ev.message) {
+						result.messages.push(ev.message);
+						if (ev.message.role === "assistant") {
+							result.usage.turns++;
+							const u = ev.message.usage;
+							if (u) {
+								result.usage.input += u.input || 0;
+								result.usage.output += u.output || 0;
+								result.usage.cacheRead += u.cacheRead || 0;
+								result.usage.cacheWrite += u.cacheWrite || 0;
+								result.usage.cost += u.cost?.total || 0;
+								result.usage.contextTokens = u.totalTokens || 0;
+							}
+							if (!result.model && ev.message.model) result.model = ev.message.model;
+							if (ev.message.stopReason) result.stopReason = ev.message.stopReason;
+							if (ev.message.errorMessage) result.errorMessage = ev.message.errorMessage;
 						}
-						if (!result.model && ev.message.model) result.model = ev.message.model;
-						if (ev.message.stopReason) result.stopReason = ev.message.stopReason;
-						if (ev.message.errorMessage) result.errorMessage = ev.message.errorMessage;
+					}
+					if (ev.type === "tool_result_end" && ev.message) {
+						result.messages.push(ev.message);
 					}
 				}
-				if (ev.type === "tool_result_end" && ev.message) {
-					result.messages.push(ev.message);
-				}
+				onUpdate?.(taskEvents);
+				return result;
+			} finally {
+				if (pooled.activeTaskEvents === taskEvents) pooled.activeTaskEvents = undefined;
 			}
-			onUpdate?.(taskEvents);
-			return result;
 		});
 	}
 
-	/** Get unconsumed events for an agent's process (for message-route scanning) */
-	drainEvents(agentName: string): Array<Record<string, unknown>> {
-		const pooled = this.procs.get(agentName);
-		if (!pooled) return [];
-		const out = pooled.events;
-		pooled.events = [];
-		return out;
-	}
-
 	/** Whether the process is alive */
 	isAlive(agentName: string): boolean {
 		const p = this.procs.get(agentName);
@@ -550,7 +762,7 @@ export class SubagentPool {
 	private recycleIdle() {
 		const now = Date.now();
 		for (const [name, pooled] of this.procs) {
-			if (pooled.closed || pooled.proc.exitCode !== null || pooled.proc.signalCode !== null) {
+			if (!this.isUsable(pooled)) {
 				this.procs.delete(name);
 				continue;
 			}
@@ -568,10 +780,18 @@ export class SubagentPool {
 		if (this.disposed) return;
 		this.disposed = true;
 		clearInterval(this.recycleTimer);
-		for (const [name, pooled] of this.procs) {
+		for (const [name, pooled] of [...this.procs]) {
 			this.terminateProcess(name, pooled, new Error("Subagent pool disposed."));
+			this.cleanupPromptFile(pooled);
 		}
 		this.procs.clear();
+		for (const [name, pooled] of [...this.startingProcesses]) {
+			this.terminateProcess(name, pooled, new Error("Subagent pool disposed during startup."));
+			this.cleanupPromptFile(pooled);
+		}
+		this.startingProcesses.clear();
+		this.starting.clear();
+		this.sessionOps.clear();
 		this.taskTails.clear();
 		this.eventListeners.clear();
 	}