pi-agent-squad 0.8.0 → 0.8.3

package/index.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
@@ -16,7 +17,7 @@ import {
 	getCompactMarkdownTheme,
 	normalizeCompactCodeBlockLines,
 } from "pi-compact-ui";
-import { discoverAgents, type AgentConfig } from "./agents.ts";
+import { discoverAgents, isSafeAgentName, type AgentConfig, userAgentsDir } from "./agents.ts";
 import {
 	createMessageRouter,
 	ENV_ROLE,
@@ -25,6 +26,8 @@ import {
 	writeReply,
 	channelDir,
 	removeRequestFile,
+	ensureChannelRoot,
+	sweepMessageRoots,
 	type MessageRequest,
 } from "./message.ts";
 import { SubagentPool } from "./pool.ts";
@@ -32,8 +35,12 @@ import type { SubagentSessionHandle } from "./session.ts";
 import { openSubagentSessionOverlay } from "./session-ui.ts";
 import { getFinalOutput, spawnInteractiveSubagent } from "./spawn.ts";
 import { deadlockMessage, MessageWaitGraph } from "./wait-graph.ts";
+import { ActiveRunRegistry, type ActiveRun } from "./active-runs.ts";
 
-const MESSAGE_ROOT_BASE = "/tmp/pi-subagents-messages";
+const MESSAGE_ROOT_BASE = path.join(
+	os.tmpdir(),
+	`pi-subagents-${typeof process.getuid === "function" ? process.getuid() : "user"}-${randomUUID()}`,
+);
 const DEFAULT_SUBAGENT_TIMEOUT_SECONDS = 6 * 60 * 60;
 const MIN_SUBAGENT_TIMEOUT_SECONDS = 10;
 const MAX_SUBAGENT_TIMEOUT_SECONDS = 3 * 24 * 60 * 60;
@@ -56,6 +63,7 @@ interface IncomingMessageDetails {
 
 interface BackgroundEventDetails {
 	agent?: string;
+	address?: string;
 	status?: "done" | "error";
 	body?: string;
 	elapsedMs?: number;
@@ -222,8 +230,8 @@ function readOrchestratorPrompt(): string {
 
 /**
  * Read the current session's adaptive-orchestration flag (the last entry wins).
- * Adaptive orchestration is enabled by default; `/orchestrate off` is an
- * explicit per-session opt-out.
+ * Adaptive orchestration is disabled by default; `/orchestrate on` is an
+ * explicit per-session opt-in.
  */
 function isOrchestratorMode(ctx: { sessionManager?: { getEntries?: () => unknown[] } }): boolean {
 	try {
@@ -232,7 +240,7 @@ function isOrchestratorMode(ctx: { sessionManager?: { getEntries?: () => unknown
 			customType?: string;
 			data?: { enabled?: boolean };
 		}>;
-		let enabled = true;
+		let enabled = false;
 		for (const e of entries) {
 			if (e.type === "custom" && e.customType === ORCHESTRATOR_MODE_ENTRY && typeof e.data?.enabled === "boolean") {
 				enabled = e.data.enabled;
@@ -240,7 +248,7 @@ function isOrchestratorMode(ctx: { sessionManager?: { getEntries?: () => unknown
 		}
 		return enabled;
 	} catch {
-		return true;
+		return false;
 	}
 }
 
@@ -250,10 +258,15 @@ function agentFilePath(agentName: string): string {
 	return path.join(here, "agents", `${agentName}.md`);
 }
 
+function userAgentFilePath(agentName: string): string {
+	if (!isSafeAgentName(agentName)) throw new Error(`Invalid agent name "${agentName}".`);
+	return path.join(userAgentsDir(), `${agentName}.md`);
+}
+
 /** Available model ids (provider/model) for the current session */
 function availableModelIds(ctx: {
-	scopedModels?: Array<{ model?: { provider?: string; id?: string } }>;
-	modelRegistry?: { getAvailable?: () => Array<{ provider?: string; id?: string }> };
+	scopedModels?: ReadonlyArray<{ model?: { provider?: string; id?: string } }>;
+	modelRegistry?: { getAvailable?: () => ReadonlyArray<{ provider?: string; id?: string }> };
 }): string[] {
 	const scoped = ctx.scopedModels;
 	if (Array.isArray(scoped) && scoped.length > 0) {
@@ -269,18 +282,37 @@ function availableModelIds(ctx: {
 
 /** Update a `model` or `thinking` line in an agent's frontmatter */
 function updateAgentConfig(agentName: string, key: "model" | "thinking", value: string): boolean {
-	const file = agentFilePath(agentName);
-	if (!fs.existsSync(file)) return false;
+	const builtinFile = agentFilePath(agentName);
+	const userFile = userAgentFilePath(agentName);
+	const sourceFile = fs.existsSync(userFile) ? userFile : builtinFile;
+	if (!fs.existsSync(sourceFile)) return false;
 	try {
-		let content = fs.readFileSync(file, "utf-8");
+		let content = fs.readFileSync(sourceFile, "utf-8");
+		const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+		if (!frontmatter) return false;
+		const header = frontmatter[1] ?? "";
 		const lineRe = new RegExp(`^(${key}:).*$`, "m");
-		if (lineRe.test(content)) {
-			content = content.replace(lineRe, `${key}: ${value}`);
-		} else {
-			// insert after the opening frontmatter marker
-			content = content.replace(/^---\r?\n/, `---\n${key}: ${value}\n`);
+		const nextHeader = lineRe.test(header)
+			? header.replace(lineRe, `${key}: ${value}`)
+			: `${header}\n${key}: ${value}`;
+		content = `${content.slice(0, frontmatter.index!)}---\n${nextHeader.trim()}\n---${content.slice(frontmatter[0].length)}`;
+		const userDir = userAgentsDir();
+		fs.mkdirSync(userDir, { recursive: true, mode: 0o700 });
+		fs.chmodSync(userDir, 0o700);
+		const dirStat = fs.lstatSync(userDir);
+		if (typeof process.getuid === "function" && dirStat.uid !== process.getuid()) return false;
+		const tempFile = `${userFile}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+		try {
+			fs.writeFileSync(tempFile, content, { encoding: "utf-8", mode: 0o600 });
+			fs.renameSync(tempFile, userFile);
+		} catch (error) {
+			try {
+				fs.unlinkSync(tempFile);
+			} catch {
+				/* ignore cleanup failure */
+			}
+			throw error;
 		}
-		fs.writeFileSync(file, content, "utf-8");
 		return true;
 	} catch {
 		return false;
@@ -294,8 +326,9 @@ function updateAgentConfig(agentName: string, key: "model" | "thinking", value:
 interface AsyncTask {
 	runId: string;
 	agent: string;
-	status: "running" | "done" | "error";
+	address: string;
 	startedAt: number;
+	sessionGeneration: number;
 }
 
 export interface RunningSubagentActivity {
@@ -577,8 +610,12 @@ export default function (pi: ExtensionAPI) {
 
 	let cwd = process.cwd();
 	let messageRoot = sessionRoot("ephemeral");
+	let sessionGeneration = 0;
 	const tasks = new Map<string, AsyncTask>();
-	const pool = new SubagentPool(messageRoot);
+	const runControllers = new Map<string, AbortController>();
+	let pool = new SubagentPool(messageRoot);
+	let poolDisposed = false;
+	const activeRuns = new ActiveRunRegistry();
 	const runningWidget = new RunningSubagentWidgetController();
 	const sessionHandles = new Map<string, SubagentSessionHandle>();
 	const waitGraph = new MessageWaitGraph();
@@ -589,9 +626,18 @@ export default function (pi: ExtensionAPI) {
 	let sessionContext: any;
 	let terminalInputUnsubscribe: (() => void) | undefined;
 	let sessionOverlayOpen = false;
+	let closeSessionOverlay: (() => void) | undefined;
 	let pendingOpenActivityId: string | undefined;
 	let lastNavigation: { direction: -1 | 1; at: number } | undefined;
 
+	const bindPoolLifecycle = (): void => {
+		pool.setProcessExitHandler((agentName, runId) => {
+			const run = activeRuns.resolveExact(runId);
+			if (run?.agent === agentName) activeRuns.remove(run);
+		});
+	};
+	bindPoolLifecycle();
+
 	function moveWidgetSelection(direction: -1 | 1): void {
 		const now = Date.now();
 		if (
@@ -625,7 +671,9 @@ export default function (pi: ExtensionAPI) {
 		pendingOpenActivityId = undefined;
 		runningWidget.clearSelection();
 		sessionOverlayOpen = true;
-		void openSubagentSessionOverlay(sessionContext, session)
+		void openSubagentSessionOverlay(sessionContext, session, (close) => {
+			closeSessionOverlay = close;
+		})
 			.catch((error) => {
 				sessionContext?.ui?.notify?.(
 					`Failed to open ${selected.agent} session: ${error instanceof Error ? error.message : String(error)}`,
@@ -633,18 +681,27 @@ export default function (pi: ExtensionAPI) {
 				);
 			})
 			.finally(() => {
+				closeSessionOverlay = undefined;
 				sessionOverlayOpen = false;
 			});
 	}
 
 	pi.on("session_start", (event, ctx) => {
+		sessionGeneration++;
+		if (poolDisposed) {
+			pool = new SubagentPool(messageRoot);
+			bindPoolLifecycle();
+			poolDisposed = false;
+		}
 		cwd = ctx.cwd;
 		const sessionId =
 			ctx.sessionManager?.getSessionId?.() ??
 			(event as any).sessionId ??
 			"ephemeral";
 		messageRoot = sessionRoot(sessionId);
-		fs.mkdirSync(messageRoot, { recursive: true });
+		ensureChannelRoot(MESSAGE_ROOT_BASE);
+		sweepMessageRoots(MESSAGE_ROOT_BASE);
+		ensureChannelRoot(messageRoot);
 		pool.setIntercomRoot(messageRoot);
 		pool.setWorkingDirectory(cwd);
 		runningWidget.attach(ctx);
@@ -677,11 +734,18 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("session_shutdown", () => {
+		sessionGeneration++;
+		for (const controller of runControllers.values()) controller.abort();
+		runControllers.clear();
+		closeSessionOverlay?.();
+		closeSessionOverlay = undefined;
+		sessionOverlayOpen = false;
 		terminalInputUnsubscribe?.();
 		terminalInputUnsubscribe = undefined;
 		sessionContext = undefined;
 		pendingOpenActivityId = undefined;
 		sessionHandles.clear();
+		activeRuns.clear();
 		for (const pending of pendingMainReplyEdges.values()) {
 			if (pending.timer) clearTimeout(pending.timer);
 			pending.release();
@@ -690,6 +754,8 @@ export default function (pi: ExtensionAPI) {
 		waitGraph.clear();
 		runningWidget.shutdown();
 		pool.dispose();
+		poolDisposed = true;
+		sweepMessageRoots(MESSAGE_ROOT_BASE);
 	});
 
 	function releaseMainReplyEdge(messageId: string): void {
@@ -713,12 +779,76 @@ export default function (pi: ExtensionAPI) {
 		pendingMainReplyEdges.set(msg.id, { release, timer });
 	}
 
-	// ---- message router: subagent -> main injects into main session; subagent -> subagent forwards to a resident process ----
+	// ---- message router: subagent -> main injects into main session; child
+	// messages resolve through the active-run registry before being delivered
+	// to a direct/background session or the resident pool. ----
 	let router: ReturnType<typeof createMessageRouter> | undefined;
+	const routedTimeout = (msg: MessageRequest): number =>
+		Math.min(
+			MAX_SUBAGENT_TIMEOUT_SECONDS * 1000,
+			Math.max(
+				MIN_SUBAGENT_TIMEOUT_SECONDS * 1000,
+				msg.timeoutMs ?? DEFAULT_SUBAGENT_TIMEOUT_SECONDS * 1000,
+			),
+		);
+	const routedPrompt = (msg: MessageRequest): string =>
+		[
+			`You received a message from ${msg.from === MAIN_AGENT ? "the main agent" : `subagent ${msg.from}`} (message id ${msg.id}):`,
+			"",
+			msg.content,
+			"",
+			`Process this message and give your reply. Your reply will be sent back to ${msg.from === MAIN_AGENT ? "the main agent" : msg.from}.`,
+		].join("\n");
+	const normalizeCwd = (value: string): string => {
+		const resolved = path.resolve(value);
+		try {
+			return fs.realpathSync(resolved);
+		} catch {
+			return resolved;
+		}
+	};
+
+	/**
+	 * Keep the resident pool in the same address registry as direct/background
+	 * runs.  The logical name remains the resident address; direct runs get a
+	 * unique address such as actor#01ab23cd.
+	 */
+	function registerResidentRun(agent: AgentConfig): ActiveRun | undefined {
+		const residentPool = pool;
+		const identity = residentPool.getProcessIdentity(agent.name);
+		if (!identity) return undefined;
+		const address = agent.name;
+		const existing = activeRuns.resolveExact(address);
+		if (existing?.mode === "resident" && existing.runId === identity.runId) return existing;
+		if (existing?.mode === "resident") activeRuns.remove(existing);
+		const run: ActiveRun = {
+			runId: identity.runId,
+			agent: agent.name,
+			address,
+			mode: "resident",
+			readOnly: agent.readOnly === true,
+			cwd: normalizeCwd(cwd),
+			startedAt: Date.now(),
+			route: async (msg, signal) => {
+				const result = await residentPool.runTask(
+					agent,
+					routedPrompt(msg),
+					routedTimeout(msg),
+					undefined,
+					signal,
+				);
+				return getFinalOutput(result.messages) || `(subagent ${agent.name} gave no reply)`;
+			},
+		};
+		activeRuns.register(run);
+		return run;
+	}
+
 	pi.on("session_start", () => {
 		router?.dispose();
+		const routeRoot = messageRoot;
 		router = createMessageRouter(pi, {
-			root: messageRoot,
+			root: routeRoot,
 			matchesContext: () => true,
 			// to main: inject into the main session; the main model replies with reply_message
 			onMainMessage: (msg: MessageRequest) => {
@@ -726,7 +856,7 @@ export default function (pi: ExtensionAPI) {
 				if (msg.expectsReply) {
 					const acquired = waitGraph.acquire(msg.from, MAIN_AGENT);
 					if (acquired.cycle) {
-						if (!writeReplyTo(msg, deadlockMessage(acquired.cycle))) {
+						if (!writeReplyTo(msg, deadlockMessage(acquired.cycle), routeRoot)) {
 							throw new Error("Failed to write deadlock-prevention reply.");
 						}
 						return;
@@ -764,6 +894,7 @@ export default function (pi: ExtensionAPI) {
 						writeReplyTo(
 							msg,
 							`Failed to deliver message to main: ${error instanceof Error ? error.message : String(error)}`,
+							routeRoot,
 						);
 					}
 					throw error;
@@ -771,53 +902,71 @@ export default function (pi: ExtensionAPI) {
 			},
 			// to another subagent: route to its resident process, collect its reply, write it back
 			onChildMessage: async (msg: MessageRequest, signal?: AbortSignal) => {
+				const routePool = pool;
 				const agents = discoverAgents(cwd);
-				const target = agents.find((a) => a.name === msg.to);
-				if (!target) {
+				let targetRun = activeRuns.resolve(msg.to);
+				let target = targetRun
+					? agents.find((a) => a.name === targetRun?.agent)
+					: agents.find((a) => a.name === msg.to);
+				if (!target && targetRun) {
+					// The definition may have been reloaded while an existing
+					// run is still alive; its route is still unambiguous.
+					target = agents.find((a) => a.name === targetRun?.agent);
+				}
+				if (!target && !targetRun) {
 					const reply = `Unknown subagent "${msg.to}"`;
-					completeRoutedMessage(msg, reply);
+					completeRoutedMessage(msg, reply, routeRoot);
+					if (msg.from === MAIN_AGENT) throw new Error(reply);
+					return reply;
+				}
+				if (targetRun?.mode === "resident" && target) {
+					await pool.ensureProcess(target);
+					targetRun = registerResidentRun(target);
+				}
+				if (!targetRun && target) {
+					await pool.ensureProcess(target);
+					targetRun = registerResidentRun(target);
+				}
+				if (!targetRun) {
+					const reply = `Subagent "${msg.to}" has no active process.`;
+					completeRoutedMessage(msg, reply, routeRoot);
+					if (msg.from === MAIN_AGENT) throw new Error(reply);
+					return reply;
+				}
+				const resolvedTargetRun = targetRun;
+				const senderRun = activeRuns.findSender(msg);
+				if (senderRun?.runId === resolvedTargetRun.runId) {
+					const reply = `Cannot send a message to the same active run (${resolvedTargetRun.address}).`;
+					completeRoutedMessage(msg, reply, routeRoot);
 					if (msg.from === MAIN_AGENT) throw new Error(reply);
 					return reply;
 				}
 				let releaseWait: (() => void) | undefined;
 				if (msg.expectsReply) {
-					const acquired = waitGraph.acquire(msg.from, msg.to);
+					const acquired = waitGraph.acquire(msg.from, resolvedTargetRun.address);
 					if (acquired.cycle) {
 						const reply = deadlockMessage(acquired.cycle);
-						completeRoutedMessage(msg, reply);
+						completeRoutedMessage(msg, reply, routeRoot);
 						if (msg.from === MAIN_AGENT) throw new Error(reply);
 						return reply;
 					}
 					releaseWait = acquired.release;
 				}
 				const activityId = `message:${msg.id}`;
-				runningWidget.start(activityId, target.name, msg.content, "message");
+				runningWidget.start(activityId, resolvedTargetRun.address, msg.content, "message");
 				try {
-					await pool.ensureProcess(target);
-					registerSessionHandle(activityId, pool.getSessionHandle(target));
-					const timeoutMs = Math.min(
-						MAX_SUBAGENT_TIMEOUT_SECONDS * 1000,
-						Math.max(MIN_SUBAGENT_TIMEOUT_SECONDS * 1000, msg.timeoutMs ?? DEFAULT_SUBAGENT_TIMEOUT_SECONDS * 1000),
-					);
-					const result = await pool.runTask(
-						target,
-						[
-							`You received a message from ${msg.from === MAIN_AGENT ? "the main agent" : `subagent ${msg.from}`} (message id ${msg.id}):`,
-							``,
-							msg.content,
-							``,
-							`Process this message and give your reply. Your reply will be sent back to ${msg.from === MAIN_AGENT ? "the main agent" : msg.from}.`,
-						].join("\n"),
-						timeoutMs,
-						undefined,
-						signal,
-					);
-					const replyText = getFinalOutput(result.messages) || `(subagent ${msg.to} gave no reply)`;
-					completeRoutedMessage(msg, replyText);
+					if (resolvedTargetRun.session) {
+						const session = await resolvedTargetRun.session;
+						registerSessionHandle(activityId, session);
+					} else if (resolvedTargetRun.mode === "resident" && target) {
+						registerSessionHandle(activityId, routePool.getSessionHandle(target));
+					}
+					const replyText = await resolvedTargetRun.route(msg, signal);
+					completeRoutedMessage(msg, replyText, routeRoot);
 					return replyText;
 				} catch (e) {
-					const reply = `Target subagent failed to process the message: ${e instanceof Error ? e.message : String(e)}`;
-					completeRoutedMessage(msg, reply);
+					const reply = `Target subagent ${resolvedTargetRun.address} failed to process the message: ${e instanceof Error ? e.message : String(e)}`;
+					completeRoutedMessage(msg, reply, routeRoot);
 					if (msg.from === MAIN_AGENT) throw new Error(reply);
 					return reply;
 				} finally {
@@ -839,9 +988,9 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	/** Write a reply back to the message sender */
-	function writeReplyTo(msg: MessageRequest, content: string): boolean {
+	function writeReplyTo(msg: MessageRequest, content: string, root = messageRoot): boolean {
 		try {
-			const dir = channelDir(messageRoot, msg.fromRunId, msg.fromAgent, msg.fromChildIndex);
+			const dir = channelDir(root, msg.fromRunId, msg.fromAgent, msg.fromChildIndex);
 			writeReply(dir, msg.id, content);
 			removeRequestFile(msg);
 			releaseMainReplyEdge(msg.id);
@@ -851,52 +1000,149 @@ export default function (pi: ExtensionAPI) {
 		}
 	}
 
-	function completeRoutedMessage(msg: MessageRequest, content: string) {
+	function completeRoutedMessage(msg: MessageRequest, content: string, root = messageRoot) {
 		if (msg.from === MAIN_AGENT) return;
-		if (msg.expectsReply) writeReplyTo(msg, content);
-		else removeRequestFile(msg);
+		if (msg.expectsReply) {
+			if (!writeReplyTo(msg, content, root)) {
+				throw new Error(`Failed to write reply for message ${msg.id}.`);
+			}
+			return;
+		}
+		removeRequestFile(msg);
+		if (msg.requestFile && fs.existsSync(msg.requestFile)) {
+			throw new Error(`Failed to remove request file for message ${msg.id}.`);
+		}
 	}
 
-	// ---- background task persistence ----
-	function persistTasks() {
-		try {
-			pi.appendEntry(
-				"subagent-async-task",
-				[...tasks.values()].map((t) => ({
-					runId: t.runId,
-					agent: t.agent,
-					status: t.status,
-					startedAt: t.startedAt,
-				})),
+	function directRunAddress(agent: AgentConfig, runId: string): string {
+		return `${agent.name}#${runId.slice(0, 8)}`;
+	}
+
+	function createDirectRun(
+		agent: AgentConfig,
+		runId: string,
+		mode: "background" | "task",
+		requestedAddress?: string,
+		readOnly = agent.readOnly === true,
+		runCwd = cwd,
+	): {
+		address: string;
+		session: Promise<SubagentSessionHandle>;
+		resolveSession: (session: SubagentSessionHandle) => void;
+		rejectSession: (error: Error) => void;
+	} {
+		const address = requestedAddress?.trim() || directRunAddress(agent, runId);
+		if (
+			(requestedAddress &&
+				(!/^[A-Za-z0-9_.-]+$/.test(address) ||
+					address === "." ||
+					address === ".." ||
+					discoverAgents(cwd).some((candidate) => candidate.name === address) ||
+					address === MAIN_AGENT)) ||
+			address === MAIN_AGENT ||
+			activeRuns.hasAddress(address)
+		) {
+			throw new Error(
+				`Invalid or unavailable runtime address "${address}". Use a unique name matching [A-Za-z0-9_.-] that is not a logical agent name or "main".`,
 			);
-		} catch {
-			/* ignore */
 		}
+		let resolveSession!: (session: SubagentSessionHandle) => void;
+		let rejectSession!: (error: Error) => void;
+		const session = new Promise<SubagentSessionHandle>((resolve, reject) => {
+			resolveSession = resolve;
+			rejectSession = reject;
+		});
+		// A run can fail before any message is addressed to it. Keep the
+		// bookkeeping promise from becoming an unhandled rejection while still
+		// propagating the error to any router that is waiting on it.
+		void session.catch(() => {});
+		let routeTail = Promise.resolve();
+		const run: ActiveRun = {
+			runId,
+			agent: agent.name,
+			address,
+			mode,
+			readOnly,
+			cwd: normalizeCwd(runCwd),
+			startedAt: Date.now(),
+			session,
+			route: async (msg, signal) => {
+				let release!: () => void;
+				const current = new Promise<void>((resolve) => (release = resolve));
+				const previous = routeTail;
+				routeTail = previous.catch(() => {}).then(() => current);
+				await previous.catch(() => {});
+				try {
+					const handle = await session;
+					if (!handle.sendAndWait) {
+						throw new Error("The active run does not support routed messages.");
+					}
+					const reply = await handle.sendAndWait(routedPrompt(msg), routedTimeout(msg), signal);
+					return reply || `(subagent ${address} gave no reply)`;
+				} finally {
+					release();
+				}
+			},
+		};
+		activeRuns.register(run);
+		return { address, session, resolveSession, rejectSession };
 	}
 
-	function launchBackground(agent: AgentConfig, taskText: string, cwdOverride?: string, timeoutMs?: number): string {
+	function launchBackground(
+		agent: AgentConfig,
+		taskText: string,
+		cwdOverride?: string,
+		timeoutMs?: number,
+		requestedAddress?: string,
+		readOnly = agent.readOnly === true,
+	): { runId: string; address: string } {
 		const runId = randomUUID();
-		tasks.set(runId, { runId, agent: agent.name, status: "running", startedAt: Date.now() });
-		persistTasks();
-		runningWidget.start(runId, agent.name, taskText, "background");
-
-		spawnInteractiveSubagent({
+		const controller = new AbortController();
+		const direct = createDirectRun(
 			agent,
-			task: taskText,
-			cwd: cwdOverride,
-			messageRoot,
 			runId,
-			childIndex: 0,
-			timeoutMs,
-			onSession: (session) => registerSessionHandle(runId, session),
-		})
+			"background",
+			requestedAddress,
+			readOnly,
+			cwdOverride ?? cwd,
+		);
+		runControllers.set(runId, controller);
+		tasks.set(runId, {
+			runId,
+			agent: agent.name,
+			address: direct.address,
+			startedAt: Date.now(),
+			sessionGeneration,
+		});
+		runningWidget.start(runId, agent.name, taskText, "background");
+
+		const start = async () => {
+			return await spawnInteractiveSubagent({
+				agent,
+				task: taskText,
+				address: direct.address,
+				cwd: cwdOverride,
+				messageRoot,
+				runId,
+				childIndex: 0,
+				signal: controller.signal,
+				timeoutMs,
+				onSession: (session) => {
+					direct.resolveSession(session);
+					registerSessionHandle(runId, session);
+				},
+			});
+		};
+		start()
 			.then((result) => {
+				// spawnInteractiveSubagent stops its direct process before the
+				// promise resolves; remove the address before publishing the
+				// completion event so no new message can target a dead process.
+				activeRuns.remove(runId);
 				const task = tasks.get(runId);
-				if (!task) return;
+				if (!task || task.sessionGeneration !== sessionGeneration) return;
 				const finalStatus: "done" | "error" =
 					result.exitCode === 0 && result.stopReason !== "error" ? "done" : "error";
-				task.status = finalStatus;
-				persistTasks();
 				const output = getFinalOutput(result.messages) || "(no text output)";
 				const failureReason =
 					result.exitCode !== 0
@@ -925,6 +1171,7 @@ export default function (pi: ExtensionAPI) {
 							display: true,
 							details: {
 								agent: agent.name,
+								address: direct.address,
 								status: finalStatus,
 								body: displayBody,
 								elapsedMs: Date.now() - task.startedAt,
@@ -938,13 +1185,12 @@ export default function (pi: ExtensionAPI) {
 				}
 			})
 			.catch((err) => {
+				activeRuns.remove(runId);
+				direct.rejectSession(err instanceof Error ? err : new Error(String(err)));
 				const task = tasks.get(runId);
-				if (task) {
-					task.status = "error";
-					persistTasks();
-				}
 				const errorText = err instanceof Error ? err.message : String(err);
 				try {
+					if (task && task.sessionGeneration !== sessionGeneration) return;
 					pi.sendMessage(
 						{
 							customType: BACKGROUND_EVENT_TYPE,
@@ -952,6 +1198,7 @@ export default function (pi: ExtensionAPI) {
 							display: true,
 							details: {
 								agent: agent.name,
+								address: direct.address,
 								status: "error",
 								body: errorText,
 								elapsedMs: task ? Date.now() - task.startedAt : undefined,
@@ -965,15 +1212,18 @@ export default function (pi: ExtensionAPI) {
 				}
 			})
 			.finally(() => {
+				runControllers.delete(runId);
+				tasks.delete(runId);
+				activeRuns.remove(runId);
 				if (pendingOpenActivityId === runId) pendingOpenActivityId = undefined;
 				sessionHandles.delete(runId);
 				runningWidget.finish(runId);
 			});
 
-		return runId;
+		return { runId, address: direct.address };
 	}
 
-	// ---- adaptive orchestration prompt; `/orchestrate off` installs the explicit opt-out guard ----
+	// ---- adaptive orchestration prompt; `/orchestrate on` installs the opt-in prompt ----
 	pi.on("before_agent_start", (event, ctx) => {
 		// Treat an explicitly appended orchestrator prompt (CLI
 		// --append-system-prompt) as orchestrator mode too.
@@ -993,16 +1243,26 @@ export default function (pi: ExtensionAPI) {
 		label: "Subagent",
 		description: [
 			"Delegate a task to a subagent (isolated context, separate process).",
-			"agent: subagent name (defined in the agents directory, e.g. planner/reviewer/actor); task: task description; cwd: optional;",
+			"agent: logical subagent identity (defined in the agents directory, e.g. planner/reviewer/actor); task: task description; cwd: optional; as: optional unique runtime address for this process;",
 			"async=true: run in background, return a runId immediately, inject the result into the conversation when done (non-blocking);",
 			"async=false (default): wait synchronously for the result.",
 			`timeoutSeconds: optional; omit unless the user explicitly requested a time. Default ${DEFAULT_SUBAGENT_TIMEOUT_SECONDS}s (6 hours), range ${MIN_SUBAGENT_TIMEOUT_SECONDS}-${MAX_SUBAGENT_TIMEOUT_SECONDS};`,
-			"While running, a subagent may send_message (to=main) to reach you, or contact other subagents — reply promptly with reply_message.",
+			"While running, a subagent may send_message (to=main) to reach you, or contact other subagents — reply promptly with reply_message. Synchronous tasks must use wait=false when contacting main.",
 		].join(" "),
 		parameters: Type.Object({
 			agent: Type.String({ description: "Subagent name" }),
 			task: Type.String({ description: "Task description for the subagent" }),
 			cwd: Type.Optional(Type.String({ description: "Working directory for the subagent" })),
+			as: Type.Optional(
+				Type.String({
+					description: "Optional unique runtime address for this run (for example actor-a); identity still comes from agent",
+				}),
+			),
+			readonly: Type.Optional(
+				Type.Boolean({
+					description: "Declare whether this run is read-only; used as orchestration metadata, not as a write sandbox",
+				}),
+			),
 			async: Type.Optional(Type.Boolean({ description: "true=run in background without blocking (default false)" })),
 			timeoutSeconds: Type.Optional(
 				Type.Integer({
@@ -1020,6 +1280,7 @@ export default function (pi: ExtensionAPI) {
 				const available = agents.map((a) => a.name).join(", ") || "none";
 				return {
 					content: [{ type: "text", text: `Unknown subagent "${params.agent}". Available: ${available}` }],
+					details: undefined,
 				};
 			}
 			const timeoutSeconds = Math.min(
@@ -1030,48 +1291,88 @@ export default function (pi: ExtensionAPI) {
 
 			if (params.async) {
 				try {
-					const runId = launchBackground(agent, params.task, params.cwd, timeoutMs);
+					const readOnly = params.readonly ?? agent.readOnly === true;
+					const launched = launchBackground(agent, params.task, params.cwd, timeoutMs, params.as, readOnly);
+					const { runId, address } = launched;
 					return {
 						content: [
 							{
 								type: "text",
-								text: `Started background subagent ${params.agent} (run ${runId.slice(0, 8)}). The main session can keep doing other things; the result will be injected when done.`,
+								text: `Started background subagent ${params.agent} at address ${address} (run ${runId.slice(0, 8)}). Send messages to that address to reach this exact process; the logical name ${params.agent} resolves to the newest active run.`,
 							},
 						],
-						details: { mode: "async", runId },
+						details: { mode: "async", runId, address },
 					};
 				} catch (e) {
 					return {
 						content: [{ type: "text", text: `Failed to start background subagent: ${e instanceof Error ? e.message : String(e)}` }],
+						details: undefined,
 					};
 				}
 			}
 
-			onUpdate?.({ content: [{ type: "text", text: `Starting ${params.agent} subagent...` }] });
+			onUpdate?.({
+				content: [{ type: "text", text: `Starting ${params.agent} subagent...` }],
+				details: undefined,
+			});
 			const runId = randomUUID();
-			const acquired = waitGraph.acquire(MAIN_AGENT, agent.name);
+			const readOnly = params.readonly ?? agent.readOnly === true;
+			const runController = new AbortController();
+			const forwardAbort = () => runController.abort();
+			runControllers.set(runId, runController);
+			if (signal?.aborted) forwardAbort();
+			else signal?.addEventListener("abort", forwardAbort, { once: true });
+			let direct: ReturnType<typeof createDirectRun>;
+			try {
+				direct = createDirectRun(agent, runId, "task", params.as, readOnly, params.cwd ?? cwd);
+			} catch (error) {
+				signal?.removeEventListener("abort", forwardAbort);
+				runControllers.delete(runId);
+				return {
+					content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+					details: undefined,
+				};
+			}
+			const acquired = waitGraph.acquire(MAIN_AGENT, direct.address);
 			if (acquired.cycle) {
+				signal?.removeEventListener("abort", forwardAbort);
+				runControllers.delete(runId);
+				activeRuns.remove(runId);
 				return {
 					content: [{ type: "text", text: deadlockMessage(acquired.cycle) }],
+					details: undefined,
 				};
 			}
 			runningWidget.start(runId, agent.name, params.task, "task");
-			const result = await spawnInteractiveSubagent({
-				agent,
-				task: params.task,
-				cwd: params.cwd,
-				messageRoot,
-				runId,
-				childIndex: 0,
-				signal,
-				timeoutMs,
-				onSession: (session) => registerSessionHandle(runId, session),
-			}).finally(() => {
+			let result: Awaited<ReturnType<typeof spawnInteractiveSubagent>>;
+			try {
+				result = await spawnInteractiveSubagent({
+					agent,
+					task: params.task,
+					address: direct.address,
+					cwd: params.cwd,
+					messageRoot,
+					runId,
+					childIndex: 0,
+					signal: runController.signal,
+					timeoutMs,
+					onSession: (session) => {
+						direct.resolveSession(session);
+						registerSessionHandle(runId, session);
+					},
+				});
+			} catch (error) {
+				direct.rejectSession(error instanceof Error ? error : new Error(String(error)));
+				throw error;
+			} finally {
+				signal?.removeEventListener("abort", forwardAbort);
+				runControllers.delete(runId);
+				activeRuns.remove(runId);
 				acquired.release?.();
 				if (pendingOpenActivityId === runId) pendingOpenActivityId = undefined;
 				sessionHandles.delete(runId);
 				runningWidget.finish(runId);
-			});
+			}
 			const output = getFinalOutput(result.messages);
 
 			if (result.exitCode !== 0) {
@@ -1095,7 +1396,7 @@ export default function (pi: ExtensionAPI) {
 
 	// ---- commands ----
 	pi.registerCommand("orchestrate", {
-		description: "Enable/disable adaptive subagent delegation (on|off|status, default on)",
+		description: "Enable/disable adaptive subagent delegation (on|off|status, default off)",
 		handler: async (args, ctx) => {
 			const first = Array.isArray(args) ? (args[0] ?? "on") : String(args ?? "on").trim().split(/\s+/)[0] ?? "on";
 			const arg = String(first).toLowerCase();
@@ -1132,7 +1433,7 @@ export default function (pi: ExtensionAPI) {
 			const agents = discoverAgents(ctx.cwd);
 			const lines = agents.map(
 				(a) =>
-					`- ${a.name}: ${a.description}${a.model ? ` (${a.model})` : ""}${a.thinking ? ` [thinking: ${a.thinking}]` : ""}${a.tools ? ` [tools: ${a.tools.join(",")}]` : ""}`,
+					`- ${a.name}: ${a.description}${a.readOnly === true ? " [read-only]" : " [writer]"}${a.model ? ` (${a.model})` : ""}${a.thinking ? ` [thinking: ${a.thinking}]` : ""}${a.tools ? ` [tools: ${a.tools.join(",")}]` : ""}`,
 			);
 			ctx.ui.notify(lines.length ? `Available subagents:\n${lines.join("\n")}` : "No subagents found", "info");
 		},
@@ -1161,6 +1462,7 @@ export default function (pi: ExtensionAPI) {
 					ctx.ui.notify(`No built-in agent named "${agentName}"`, "warning");
 					return;
 				}
+				pool.restartAgent(agentName);
 				ctx.ui.notify(`Subagent ${agentName}: thinking -> ${level}`, "info");
 			} else {
 				const choices = availableModelIds(ctx);
@@ -1174,33 +1476,31 @@ export default function (pi: ExtensionAPI) {
 					ctx.ui.notify(`No built-in agent named "${agentName}"`, "warning");
 					return;
 				}
+				pool.restartAgent(agentName);
 				ctx.ui.notify(`Subagent ${agentName}: model -> ${model}`, "info");
 			}
 		},
 	});
 
 	pi.registerCommand("subagent-status", {
-		description: "Show background subagent tasks and resident processes",
+		description: "Show active subagent runs and runtime addresses",
 		handler: async (_args, ctx) => {
 			const list = [...tasks.values()];
 			const lines = list.map((t) => {
-				const age = Math.round((Date.now() - t.startedAt) / 1000);
-				return `- run ${t.runId.slice(0, 8)} ${t.agent} ${t.status} (${age}s ago)`;
+					const age = Math.round((Date.now() - t.startedAt) / 1000);
+					return `- ${t.address} run ${t.runId.slice(0, 8)} ${t.agent} running (${age}s ago)`;
 			});
-			const alive = [...poolAliveNames(pool)];
+			const active = activeRuns.list();
+			const activeLines = active.map(
+				(run) => `- ${run.address} -> ${run.agent} [${run.mode}] (run ${run.runId.slice(0, 8)})`,
+			);
 			ctx.ui.notify(
 				[
 					lines.length ? `Background tasks:\n${lines.join("\n")}` : "Background tasks: none",
-					`Resident processes: ${alive.length ? alive.join(", ") : "none"}`,
+					activeLines.length ? `Active run registry:\n${activeLines.join("\n")}` : "Active run registry: none",
 				].join("\n"),
 				"info",
 			);
 		},
 	});
 }
-
-function* poolAliveNames(pool: SubagentPool): Generator<string> {
-	for (const n of ["planner", "reviewer", "actor"]) {
-		if (pool.isAlive(n)) yield n;
-	}
-}