pi-agent-squad 0.7.0 → 0.8.1

package/message.ts

@@ -9,10 +9,15 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 //
 // Two parties communicate: `main` (the main agent) and any subagent. Identity
 // is defined entirely by each agent's prompt.
-// Messages = file channel + polling:
-//   send_message -> write <root>/<runId>/<agent>/<idx>/requests/<msgId>.json (to=target)
-//   reply_message -> write <root>/<runId>/<fromAgent>/<idx>/replies/<msgId>.json
-//   the waiting party polls replies/<msgId>.json
+// Messages = file channel + polling. Every file lives in the SENDER's channel
+// directory; the main-side router scans the tree and delivers:
+//   send_message  -> <root>/<runId>/<sender>/<idx>/requests/<msgId>.json
+//   reply_message -> <root>/<runId>/<sender>/<idx>/replies/<msgId>.json
+//                    (written back into the ORIGINAL sender's channel)
+// Channel semantics that follow from this:
+//   requests/ = this channel's OUTBOX (messages it sent)
+//   replies/  = this channel's INBOX (answers addressed to it)
+//   a request file whose `to` is this channel is also inbox content
 // Main-side routing: to === "main" -> inject into main session; otherwise
 // forward to the target subagent's resident process.
 // ============================================================================
@@ -43,12 +48,33 @@ const MAX_ROUTE_TIMEOUT_SECONDS = 3 * 24 * 60 * 60;
 const CHANNEL_POLL_MS = 500;
 const REPLY_POLL_MS = 250;
 
+// Delivery retry: a failing delivery must never be treated as success, but it
+// also must not spin on every 500ms poll forever. Retries back off, and a
+// permanently undeliverable message is dropped (file removed, waiter released).
+const MAX_DELIVERY_ATTEMPTS = 5;
+const RETRY_BACKOFF_BASE_MS = 1000;
+const RETRY_BACKOFF_MAX_MS = 60 * 1000;
+
+// Bookkeeping for already-delivered message ids is bounded and expires, so a
+// long-lived main process cannot accumulate state forever.
+const SEEN_TTL_MS = 60 * 60 * 1000;
+const SEEN_MAX_ENTRIES = 4096;
+const SEEN_SWEEP_INTERVAL_MS = 60 * 1000;
+
+// Channel-tree janitor (main side). It only removes content nobody can still
+// be waiting for, and only prunes directories that are completely empty.
+const SWEEP_INTERVAL_MS = 60 * 1000;
+/** After the longest possible wait window plus margin, no reply waiter exists. */
+const REPLY_ORPHAN_TTL_MS = (MAX_ROUTE_TIMEOUT_SECONDS + 24 * 60 * 60) * 1000;
+/** Unparseable files and leftover atomic-write temp files get a grace window. */
+const JUNK_FILE_TTL_MS = 60 * 60 * 1000;
+
 export interface MessageRequest {
 	type: "pi.message.request";
 	id: string;
 	createdAt: number;
-	from: string; // sender: main or a subagent name
-	to: string; // target: main or a subagent name
+	from: string; // sender: main or a runtime subagent address
+	to: string; // target: main, logical name, or runtime address
 	content: string;
 	expectsReply: boolean;
 	expiresAt?: number;
@@ -65,14 +91,21 @@ export interface MessageReply {
 	messageId: string;
 	content: string;
 	timestamp: number;
+	/** who wrote the reply (the original request's `to`), when known */
+	from?: string;
 }
 
 function safeSegment(value: string): string {
-	return value.replace(/[^\w.-]+/g, "_");
+	const safe = value.replace(/[^\w.-]+/g, "_");
+	if (safe === "." || safe === "..") return `_${safe.replace(/\./g, "")}`;
+	return safe || "_";
 }
 
 /** Channel directory of one agent instance */
 export function channelDir(root: string, runId: string, agent: string, childIndex: number): string {
+	if (!Number.isInteger(childIndex) || childIndex < 0 || childIndex > 1_000_000) {
+		throw new Error(`Invalid child index: ${childIndex}`);
+	}
 	return path.join(root, safeSegment(runId), safeSegment(agent), String(childIndex));
 }
 
@@ -84,11 +117,202 @@ function replyPath(dir: string, id: string): string {
 }
 
 export function ensureDir(dir: string): void {
-	fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+	const absolute = path.resolve(dir);
+	const parsed = path.parse(absolute);
+	let current = parsed.root;
+	for (const segment of absolute.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+		current = path.join(current, segment);
+		try {
+			const st = fs.lstatSync(current);
+			if (st.isSymbolicLink() || !st.isDirectory()) {
+				throw new Error(`Message channel path is not a real directory: ${current}`);
+			}
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			fs.mkdirSync(current, { mode: 0o700 });
+			const created = fs.lstatSync(current);
+			if (created.isSymbolicLink() || !created.isDirectory()) {
+				throw new Error(`Message channel path is not a real directory: ${current}`);
+			}
+		}
+	}
+}
+
+// ============================================================================
+// Channel-root hardening
+//
+// The root may live under a predictable /tmp path. A predictable, world
+// readable/writable directory lets another user pre-plant a symlink and
+// capture or tamper with messages. Creation is therefore always private
+// (0700), symlinked or foreign-owned roots are refused, and an existing root
+// owned by us is tightened.
+// ============================================================================
+
+function statRootSafe(root: string): fs.Stats | undefined {
+	try {
+		// lstat: never follow a symlink planted at the root path
+		return fs.lstatSync(root);
+	} catch {
+		return undefined;
+	}
+}
+
+function rootOwnershipError(root: string): Error | undefined {
+	if (typeof process.getuid !== "function") return undefined;
+	const st = statRootSafe(root);
+	if (st && st.uid !== process.getuid()) {
+		return new Error(`Message channel root "${root}" is owned by another user; refusing to use it.`);
+	}
+	return undefined;
+}
+
+/**
+ * Create/verify the channel root for the main side. Prefer this over a raw
+ * `fs.mkdirSync(root, { recursive: true })`: it is private from the start,
+ * refuses symlinked or foreign-owned roots, and tightens a pre-existing root.
+ */
+export function ensureChannelRoot(root: string): void {
+	const st = statRootSafe(root);
+	if (!st) {
+		// Fresh creation: mode is capped by the umask, never widened.
+		fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+		const created = statRootSafe(root);
+		if (!created || created.isSymbolicLink() || !created.isDirectory()) {
+			throw new Error(`Channel root "${root}" could not be created as a real directory.`);
+		}
+		const ownership = rootOwnershipError(root);
+		if (ownership) throw ownership;
+		try {
+			fs.chmodSync(root, 0o700);
+		} catch {
+			throw new Error(`Channel root "${root}" could not be locked down.`);
+		}
+		return;
+	}
+	if (st.isSymbolicLink() || !st.isDirectory()) {
+		throw new Error(`Channel root "${root}" exists but is not a real directory.`);
+	}
+	const ownership = rootOwnershipError(root);
+	if (ownership) throw ownership;
+	if ((st.mode & 0o077) !== 0) {
+		try {
+			fs.chmodSync(root, 0o700);
+		} catch {
+			throw new Error(`Channel root "${root}" is group/world accessible and could not be locked down.`);
+		}
+	}
+}
+
+/** Best-effort root hardening for child processes (the main side owns the root). */
+const hardenedRoots = new Set<string>();
+function hardenChannelRoot(root: string): void {
+	if (hardenedRoots.has(root)) return;
+	const st = statRootSafe(root);
+	if (!st) return; // not created yet; ensureDir creates it privately on first write
+	if (st.isSymbolicLink()) {
+		throw new Error(`Message channel root "${root}" is a symlink; refusing to use it.`);
+	}
+	const ownership = rootOwnershipError(root);
+	if (ownership) throw ownership;
+	if ((st.mode & 0o077) !== 0) {
+		try {
+			fs.chmodSync(root, 0o700);
+		} catch {
+			/* best effort: the main side enforces this on its own root */
+		}
+	}
+	hardenedRoots.add(root);
 }
 
 function writeAtomic(filePath: string, data: string): void {
-	fs.writeFileSync(filePath, data, { encoding: "utf-8", mode: 0o600 });
+	// Write to a temp file in the same directory and rename, so concurrent
+	// readers never observe a partially written JSON file.
+	const tmp = `${filePath}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+	try {
+		fs.writeFileSync(tmp, data, { encoding: "utf-8", mode: 0o600 });
+		fs.renameSync(tmp, filePath);
+	} catch (e) {
+		try {
+			fs.unlinkSync(tmp);
+		} catch {
+			/* ignore */
+		}
+		throw e;
+	}
+}
+
+// ============================================================================
+// Tolerant filesystem helpers (concurrent cleanup must not break scans)
+// ============================================================================
+
+function listDirSafe(dir: string): string[] {
+	try {
+		return fs.readdirSync(dir);
+	} catch {
+		return []; // vanished or unreadable between listing levels
+	}
+}
+
+function isDirectorySafe(p: string): boolean {
+	try {
+		return fs.lstatSync(p).isDirectory();
+	} catch {
+		return false; // removed concurrently or unreadable
+	}
+}
+
+function fileAgeMs(file: string, now: number): number {
+	try {
+		return now - fs.statSync(file).mtimeMs;
+	} catch {
+		return Number.POSITIVE_INFINITY; // already gone: nothing to clean
+	}
+}
+
+function unlinkQuiet(file: string): void {
+	try {
+		fs.unlinkSync(file);
+	} catch {
+		/* already removed */
+	}
+}
+
+function pruneEmptyDir(dir: string): void {
+	try {
+		// rmdirSync only removes empty directories, so this cannot race away
+		// files that a live process created in the meantime.
+		fs.rmdirSync(dir);
+	} catch {
+		/* not empty, gone, or not ours */
+	}
+}
+
+function isValidRequest(value: unknown): value is MessageRequest {
+	if (!value || typeof value !== "object") return false;
+	const req = value as MessageRequest;
+	return (
+		req.type === "pi.message.request" &&
+		typeof req.id === "string" &&
+		req.id.length > 0 &&
+		typeof req.createdAt === "number" &&
+		Number.isFinite(req.createdAt) &&
+		typeof req.from === "string" &&
+		typeof req.to === "string" &&
+		typeof req.content === "string" &&
+		typeof req.expectsReply === "boolean" &&
+		(req.expiresAt === undefined || (typeof req.expiresAt === "number" && Number.isFinite(req.expiresAt))) &&
+		(req.timeoutMs === undefined || (typeof req.timeoutMs === "number" && Number.isFinite(req.timeoutMs) && req.timeoutMs >= 0)) &&
+		typeof req.fromRunId === "string" &&
+		typeof req.fromAgent === "string" &&
+		Number.isInteger(req.fromChildIndex) &&
+		req.fromChildIndex >= 0 &&
+		req.fromChildIndex <= 1_000_000
+	);
+}
+
+/** Tool results in this file carry no structured details. */
+function textResult(text: string): { content: [{ type: "text"; text: string }]; details: undefined } {
+	return { content: [{ type: "text", text }], details: undefined };
 }
 
 // ============================================================================
@@ -111,15 +335,27 @@ function readClientMeta(): ClientMeta | undefined {
 	return { root, runId, agent, childIndex: Number(rawIndex) };
 }
 
+// Message ids with a live local reply waiter. `read_inbox` must not consume
+// reply files out from under a concurrent send_message(wait=true) call.
+const activeReplyWaits = new Set<string>();
+
 function waitForReply(dir: string, messageId: string, deadline: number, signal?: AbortSignal): Promise<string> {
 	return new Promise((resolve, reject) => {
+		activeReplyWaits.add(messageId);
 		const file = replyPath(dir, messageId);
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const cleanup = () => {
+			activeReplyWaits.delete(messageId);
+			if (timer) clearTimeout(timer);
+		};
 		const tick = () => {
 			if (signal?.aborted) {
+				cleanup();
 				reject(new Error("Message wait cancelled."));
 				return;
 			}
 			if (Date.now() > deadline) {
+				cleanup();
 				reject(new Error("Timed out waiting for reply."));
 				return;
 			}
@@ -130,16 +366,17 @@ function waitForReply(dir: string, messageId: string, deadline: number, signal?:
 						try {
 							fs.unlinkSync(file);
 						} catch {
-							/* ignore cleanup failure */
+							/* concurrent consumer or already removed */
 						}
+						cleanup();
 						resolve(parsed.content);
 						return;
 					}
 				}
 			} catch {
-				/* ignore */
+				/* transient read/parse issue; keep polling */
 			}
-			setTimeout(tick, REPLY_POLL_MS);
+			timer = setTimeout(tick, REPLY_POLL_MS);
 		};
 		tick();
 	});
@@ -155,6 +392,7 @@ async function sendMessageInternal(
 ): Promise<{ messageId: string; reply?: string }> {
 	const meta = readClientMeta();
 	if (!meta) throw new Error("Message channel is not available.");
+	hardenChannelRoot(meta.root);
 	const dir = channelDir(meta.root, meta.runId, meta.agent, meta.childIndex);
 	ensureDir(path.join(dir, REQUESTS_DIR));
 	ensureDir(path.join(dir, REPLIES_DIR));
@@ -186,6 +424,9 @@ async function sendMessageInternal(
 		const reply = await waitForReply(dir, messageId, deadline, signal);
 		return { messageId, reply };
 	} catch (e) {
+		// The wait failed (timeout/cancel): withdraw the request so the router
+		// stops trying to deliver it. A reply written right after this race is
+		// cleaned up by the inbox TTL sweep.
 		try {
 			fs.unlinkSync(requestPath(dir, messageId));
 		} catch {
@@ -197,11 +438,18 @@ async function sendMessageInternal(
 
 /** Reply to a message (locate the sender from the message, write the reply back) */
 function replyToMessage(root: string, messageId: string, content: string): boolean {
+	hardenChannelRoot(root);
 	const request = findRequestInTree(root, messageId);
 	if (!request) return false;
 	const senderDir = channelDir(root, request.fromRunId, request.fromAgent, request.fromChildIndex);
 	ensureDir(path.join(senderDir, REPLIES_DIR));
-	const reply: MessageReply = { type: "pi.message.reply", messageId, content, timestamp: Date.now() };
+	const reply: MessageReply = {
+		type: "pi.message.reply",
+		messageId,
+		content,
+		timestamp: Date.now(),
+		from: request.to,
+	};
 	writeAtomic(replyPath(senderDir, messageId), JSON.stringify(reply, null, 2));
 	// clean up the replied request
 	if (request.requestFile) {
@@ -215,42 +463,135 @@ function replyToMessage(root: string, messageId: string, content: string): boole
 }
 
 function findRequestInTree(root: string, messageId: string): MessageRequest | undefined {
-	try {
-		if (!fs.existsSync(root)) return undefined;
-		for (const run of fs.readdirSync(root)) {
-			const runDir = path.join(root, run);
-			if (!fs.statSync(runDir).isDirectory()) continue;
-			for (const agent of fs.readdirSync(runDir)) {
-				const agentDir = path.join(runDir, agent);
-				if (!fs.statSync(agentDir).isDirectory()) continue;
-				for (const idx of fs.readdirSync(agentDir)) {
-					const reqDir = path.join(agentDir, idx, REQUESTS_DIR);
-					if (!fs.existsSync(reqDir)) continue;
-					for (const f of fs.readdirSync(reqDir)) {
-						if (f !== `${safeSegment(messageId)}.json`) continue;
-						try {
-							return JSON.parse(fs.readFileSync(path.join(reqDir, f), "utf-8")) as MessageRequest;
-						} catch {
-							/* ignore */
+	if (!isDirectorySafe(root)) return undefined;
+	for (const run of listDirSafe(root)) {
+		const runDir = path.join(root, run);
+		if (!isDirectorySafe(runDir)) continue;
+		for (const agent of listDirSafe(runDir)) {
+			const agentDir = path.join(runDir, agent);
+			if (!isDirectorySafe(agentDir)) continue;
+			for (const idx of listDirSafe(agentDir)) {
+				const reqDir = path.join(agentDir, idx, REQUESTS_DIR);
+				if (!isDirectorySafe(reqDir)) continue;
+				for (const f of listDirSafe(reqDir)) {
+					if (f !== `${safeSegment(messageId)}.json`) continue;
+					try {
+						const requestFile = path.join(reqDir, f);
+						const req = JSON.parse(fs.readFileSync(requestFile, "utf-8")) as MessageRequest;
+						if (isValidRequest(req)) {
+							req.requestFile = requestFile;
+							return req;
 						}
+					} catch {
+						/* torn or concurrently removed file */
 					}
 				}
 			}
 		}
-	} catch {
-		/* ignore */
 	}
 	return undefined;
 }
 
+// ============================================================================
+// Channel tree janitor (main side)
+// ============================================================================
+
+function isDeliverableRequestFile(file: string): boolean {
+	try {
+		return isValidRequest(JSON.parse(fs.readFileSync(file, "utf-8")));
+	} catch {
+		return false;
+	}
+}
+
+function sweepChannelDir(idxDir: string, now: number): void {
+	const reqDir = path.join(idxDir, REQUESTS_DIR);
+	for (const f of listDirSafe(reqDir)) {
+		const file = path.join(reqDir, f);
+		if (f.endsWith(".tmp")) {
+			// leftover from a crashed atomic write
+			if (fileAgeMs(file, now) > JUNK_FILE_TTL_MS) unlinkQuiet(file);
+			continue;
+		}
+		if (!f.endsWith(".json")) continue;
+		// Keep live requests, but clean expired or abandoned requests even when
+		// their session is no longer active and no router will see them.
+		if (isDeliverableRequestFile(file)) {
+			try {
+				const req = JSON.parse(fs.readFileSync(file, "utf-8")) as MessageRequest;
+				const abandoned = req.expiresAt !== undefined
+					? req.expiresAt < now
+					: now - req.createdAt > REPLY_ORPHAN_TTL_MS;
+				if (!abandoned) continue;
+				unlinkQuiet(file);
+				continue;
+			} catch {
+				/* fall through to stale-file cleanup */
+			}
+		}
+		if (fileAgeMs(file, now) > JUNK_FILE_TTL_MS) unlinkQuiet(file);
+	}
+	const repliesDir = path.join(idxDir, REPLIES_DIR);
+	for (const f of listDirSafe(repliesDir)) {
+		const file = path.join(repliesDir, f);
+		if (f.endsWith(".tmp")) {
+			if (fileAgeMs(file, now) > JUNK_FILE_TTL_MS) unlinkQuiet(file);
+			continue;
+		}
+		if (!f.endsWith(".json")) continue;
+		// Unconsumed replies: once the longest possible wait window plus margin
+		// has passed, no waiter can still be polling for them.
+		if (fileAgeMs(file, now) > REPLY_ORPHAN_TTL_MS) unlinkQuiet(file);
+	}
+	for (const f of listDirSafe(idxDir)) {
+		if (f === REQUESTS_DIR || f === REPLIES_DIR) continue;
+		const file = path.join(idxDir, f);
+		if (!isDirectorySafe(file) && fileAgeMs(file, now) > JUNK_FILE_TTL_MS) unlinkQuiet(file);
+	}
+}
+
+function sweepChannelTree(root: string, now: number): void {
+	if (!isDirectorySafe(root)) return;
+	for (const run of listDirSafe(root)) {
+		const runDir = path.join(root, run);
+		if (!isDirectorySafe(runDir)) continue;
+		for (const agent of listDirSafe(runDir)) {
+			const agentDir = path.join(runDir, agent);
+			if (!isDirectorySafe(agentDir)) continue;
+			for (const idx of listDirSafe(agentDir)) {
+				const idxDir = path.join(agentDir, idx);
+				if (!isDirectorySafe(idxDir)) continue;
+				sweepChannelDir(idxDir, now);
+				pruneEmptyDir(path.join(idxDir, REQUESTS_DIR));
+				pruneEmptyDir(path.join(idxDir, REPLIES_DIR));
+				pruneEmptyDir(idxDir);
+				pruneEmptyDir(agentDir);
+			}
+			pruneEmptyDir(runDir);
+		}
+	}
+}
+
+/** Sweep all session roots below a private base directory. */
+export function sweepMessageRoots(base: string, now = Date.now()): void {
+	if (!isDirectorySafe(base)) return;
+	for (const session of listDirSafe(base)) {
+		const root = path.join(base, session);
+		if (!isDirectorySafe(root)) continue;
+		sweepChannelTree(root, now);
+		pruneEmptyDir(root);
+	}
+}
+
 /** Register the generic messaging tools for a child (subagent) */
 export function registerChildMessaging(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: TOOL_SEND,
 		label: "Send Message",
 		description: [
-			"Send a message to any target: to='main' reaches the main agent, to=<agent name> reaches that subagent.",
+			"Send a message to any target: to='main' reaches the main agent; use a logical agent name or an exact runtime address such as actor#01ab23cd for a subagent.",
 			"wait=true (ask): block until the other party replies before continuing; wait=false (send): fire and forget.",
+			"When running as a synchronous task, contact main with wait=false because main is waiting for the task to finish.",
 			"Use it to ask/confirm with the main agent or another subagent instead of leaving notes in normal output.",
 		].join(" "),
 		parameters: Type.Object({
@@ -282,15 +623,11 @@ export function registerChildMessaging(pi: ExtensionAPI): void {
 					signal,
 				);
 				if (reply !== undefined) {
-					return {
-						content: [{ type: "text", text: `Reply from ${params.to}:\n${reply}` }],
-					};
+					return textResult(`Reply from ${params.to}:\n${reply}`);
 				}
-				return { content: [{ type: "text", text: `Sent message to ${params.to} (id ${messageId.slice(0, 8)})` }] };
+				return textResult(`Sent message to ${params.to} (id ${messageId.slice(0, 8)})`);
 			} catch (e) {
-				return {
-					content: [{ type: "text", text: `Failed to send message: ${e instanceof Error ? e.message : String(e)}` }],
-				};
+				return textResult(`Failed to send message: ${e instanceof Error ? e.message : String(e)}`);
 			}
 		},
 	});
@@ -302,21 +639,12 @@ export function registerChildMessaging(pi: ExtensionAPI): void {
 		parameters: Type.Object({}),
 		execute: async (_id) => {
 			const meta = readClientMeta();
-			if (!meta) return { content: [{ type: "text", text: "Message channel is not available." }] };
-			const dir = channelDir(meta.root, meta.runId, meta.agent, meta.childIndex);
-			const reqDir = path.join(dir, REQUESTS_DIR);
-			if (!fs.existsSync(reqDir)) return { content: [{ type: "text", text: "Inbox is empty." }] };
-			const files = fs.readdirSync(reqDir).filter((f) => f.endsWith(".json"));
-			if (files.length === 0) return { content: [{ type: "text", text: "Inbox is empty." }] };
-			const lines = files.map((f) => {
-				try {
-					const r = JSON.parse(fs.readFileSync(path.join(reqDir, f), "utf-8")) as MessageRequest;
-					return `- [${r.id.slice(0, 8)}] from ${r.from}: ${r.content.slice(0, 150)}`;
-				} catch {
-					return "";
-				}
-			});
-			return { content: [{ type: "text", text: `Inbox (requests from other agents):\n${lines.join("\n")}` }] };
+			if (!meta) return textResult("Message channel is not available.");
+			try {
+				return textResult(readInbox(meta));
+			} catch (e) {
+				return textResult(`Failed to read inbox: ${e instanceof Error ? e.message : String(e)}`);
+			}
 		},
 	});
 
@@ -330,15 +658,71 @@ export function registerChildMessaging(pi: ExtensionAPI): void {
 		}),
 		execute: async (_id, params) => {
 			const meta = readClientMeta();
-			if (!meta) return { content: [{ type: "text", text: "Message channel is not available." }] };
+			if (!meta) return textResult("Message channel is not available.");
+			try {
+				hardenChannelRoot(meta.root);
+			} catch (e) {
+				return textResult(`Message channel is not available: ${e instanceof Error ? e.message : String(e)}`);
+			}
 			if (!replyToMessage(meta.root, params.message_id, params.content)) {
-				return { content: [{ type: "text", text: `Message not found: ${params.message_id.slice(0, 8)}` }] };
+				return textResult(`Message not found: ${params.message_id.slice(0, 8)}`);
 			}
-			return { content: [{ type: "text", text: `Replied to ${params.message_id.slice(0, 8)}` }] };
+			return textResult(`Replied to ${params.message_id.slice(0, 8)}`);
 		},
 	});
 }
 
+interface InboxEntry {
+	sortKey: number;
+	text: string;
+	file?: string; // consumed (removed) after being reported
+}
+
+/**
+ * A channel's inbound mail is the replies written back into this channel.
+ * Request files are the sender's outbox and are consumed by the main router;
+ * they are intentionally not exposed here. Reply files are consumed after
+ * reporting so reads do not repeat; files that a concurrent send_message
+ * (wait=true) is polling are left untouched.
+ */
+function readInbox(meta: ClientMeta): string {
+	hardenChannelRoot(meta.root);
+	const dir = channelDir(meta.root, meta.runId, meta.agent, meta.childIndex);
+	const entries: InboxEntry[] = [];
+
+	// 1) replies addressed to this channel
+	const repliesDir = path.join(dir, REPLIES_DIR);
+	for (const f of listDirSafe(repliesDir)) {
+		if (!f.endsWith(".json")) continue;
+		const id = f.slice(0, -".json".length);
+		// A live wait owns this reply; let waitForReply consume it.
+		if (activeReplyWaits.has(id)) continue;
+		const file = path.join(repliesDir, f);
+		try {
+			const reply = JSON.parse(fs.readFileSync(file, "utf-8")) as MessageReply;
+			if (reply.type !== "pi.message.reply" || typeof reply.content !== "string") throw new Error("malformed reply");
+			entries.push({
+				sortKey: typeof reply.timestamp === "number" ? reply.timestamp : 0,
+				text: `- [${id.slice(0, 8)}] reply from ${reply.from ?? "unknown"} at ${new Date(
+					typeof reply.timestamp === "number" ? reply.timestamp : Date.now(),
+				).toISOString()}:\n${reply.content}`,
+				file,
+			});
+		} catch {
+			// torn/corrupt file: drop it so it cannot poison every future read
+			unlinkQuiet(file);
+		}
+	}
+
+	if (entries.length === 0) return "Inbox is empty.";
+	entries.sort((a, b) => a.sortKey - b.sortKey);
+	// Consume reported replies only after they were read successfully.
+	for (const entry of entries) {
+		if (entry.file) unlinkQuiet(entry.file);
+	}
+	return `Inbox (${entries.length} message${entries.length === 1 ? "" : "s"}):\n${entries.map((e) => e.text).join("\n")}`;
+}
+
 // ============================================================================
 // Main-agent side: message router (poller)
 // ============================================================================
@@ -353,6 +737,8 @@ export interface MessageRouterState {
 	/** notification hooks used by the main-side wait graph */
 	onMessageReplied?: (msg: MessageRequest) => void;
 	onMessageExpired?: (msg: MessageRequest) => void;
+	/** a message was permanently dropped (expired or exhausted delivery retries) */
+	onMessageDropped?: (msg: MessageRequest) => void;
 }
 
 export interface MessageRouter {
@@ -363,41 +749,37 @@ export interface MessageRouter {
 /** Scan the channel tree for all pending message requests */
 export function scanMessages(root: string): MessageRequest[] {
 	const out: MessageRequest[] = [];
-	try {
-		if (!fs.existsSync(root)) return out;
-		for (const run of fs.readdirSync(root)) {
-			const runDir = path.join(root, run);
-			if (!fs.statSync(runDir).isDirectory()) continue;
-			for (const agent of fs.readdirSync(runDir)) {
-				const agentDir = path.join(runDir, agent);
-				if (!fs.statSync(agentDir).isDirectory()) continue;
-				for (const idx of fs.readdirSync(agentDir)) {
-					const reqDir = path.join(agentDir, idx, REQUESTS_DIR);
-					if (!fs.existsSync(reqDir)) continue;
-					for (const f of fs.readdirSync(reqDir)) {
-						if (!f.endsWith(".json")) continue;
-						try {
-							const req = JSON.parse(fs.readFileSync(path.join(reqDir, f), "utf-8")) as MessageRequest;
-							if (req.type === "pi.message.request" && req.id) {
-								req.requestFile = path.join(reqDir, f);
-								out.push(req);
-							}
-						} catch {
-							/* ignore */
+	if (!isDirectorySafe(root)) return out;
+	for (const run of listDirSafe(root)) {
+		const runDir = path.join(root, run);
+		if (!isDirectorySafe(runDir)) continue;
+		for (const agent of listDirSafe(runDir)) {
+			const agentDir = path.join(runDir, agent);
+			if (!isDirectorySafe(agentDir)) continue;
+			for (const idx of listDirSafe(agentDir)) {
+				const reqDir = path.join(agentDir, idx, REQUESTS_DIR);
+				if (!isDirectorySafe(reqDir)) continue;
+				for (const f of listDirSafe(reqDir)) {
+					if (!f.endsWith(".json")) continue;
+					try {
+						const req = JSON.parse(fs.readFileSync(path.join(reqDir, f), "utf-8")) as MessageRequest;
+						if (isValidRequest(req)) {
+							req.requestFile = path.join(reqDir, f);
+							out.push(req);
 						}
+					} catch {
+						/* torn or concurrently removed file: skip only this file */
 					}
 				}
 			}
 		}
-	} catch {
-		/* ignore */
 	}
 	return out;
 }
 
-export function writeReply(dir: string, messageId: string, content: string): void {
+export function writeReply(dir: string, messageId: string, content: string, from?: string): void {
 	ensureDir(path.join(dir, REPLIES_DIR));
-	const reply: MessageReply = { type: "pi.message.reply", messageId, content, timestamp: Date.now() };
+	const reply: MessageReply = { type: "pi.message.reply", messageId, content, timestamp: Date.now(), ...(from ? { from } : {}) };
 	writeAtomic(replyPath(dir, messageId), JSON.stringify(reply, null, 2));
 }
 
@@ -409,45 +791,158 @@ export function removeRequestFile(msg: MessageRequest): void {
 	}
 }
 
+/** Per-message router bookkeeping (replaces unbounded seen/inFlight sets) */
+interface RouteState {
+	attempts: number;
+	/** earliest wall-clock time the next delivery attempt may start */
+	nextAttemptAt: number;
+	inFlight: boolean;
+	/** set once delivery succeeded; kept for TTL/bounded dedup */
+	deliveredAt?: number;
+	/** Path is retained so delivered requests waiting for a reply stay deduped. */
+	requestFile?: string;
+	/** expiry handled; suppresses further delivery, seen marking, double notifies */
+	expired?: boolean;
+}
+
+/** Retry-state entries are garbage once their backoff window is long past. */
+const RETRY_ENTRY_TTL_MS = 10 * 60 * 1000;
+
+function sweepRouteStates(routes: Map<string, RouteState>, now: number): void {
+	// TTL: delivered ids only need to be remembered until their request file is
+	// gone (handlers remove it); while the file lingers the entry keeps deduping
+	// it. Entries waiting for a retry expire too: an entry whose backoff window
+	// passed long ago without an attempt means its request file has left the
+	// scan (replied, removed, filtered), so the state is garbage.
+	for (const [id, st] of routes) {
+		if (st.deliveredAt !== undefined) {
+			if (
+				(!st.requestFile || !fs.existsSync(st.requestFile)) &&
+				now - st.deliveredAt > SEEN_TTL_MS
+			) {
+				routes.delete(id);
+			}
+		} else if (!st.inFlight && now - st.nextAttemptAt > RETRY_ENTRY_TTL_MS) {
+			routes.delete(id);
+		}
+	}
+	// Bound: evict oldest entries (Map preserves insertion order), never ones
+	// whose delivery is still running.
+	let overflow = routes.size - SEEN_MAX_ENTRIES;
+	if (overflow > 0) {
+		for (const [id, st] of routes) {
+			if (st.inFlight) continue;
+			if (st.deliveredAt !== undefined && st.requestFile && fs.existsSync(st.requestFile)) continue;
+			routes.delete(id);
+			if (--overflow <= 0) break;
+		}
+	}
+}
+
 /** Main agent creates a message router: poller scans, then splits main vs subagent */
 export function createMessageRouter(pi: ExtensionAPI, state: MessageRouterState): MessageRouter {
-	const seen = new Set<string>();
-	const inFlight = new Set<string>();
+	const routes = new Map<string, RouteState>();
 	let poller: ReturnType<typeof setInterval> | undefined;
+	let lastSweepAt = 0;
+
+	const notifyDropped = (msg: MessageRequest): void => {
+		(state.onMessageDropped ?? state.onMessageExpired)?.(msg);
+	};
+
+	/** Record a failed delivery attempt; drop the message after too many tries. */
+	const failDelivery = (msg: MessageRequest, entry: RouteState, now: number): void => {
+		entry.attempts += 1;
+		if (entry.attempts >= MAX_DELIVERY_ATTEMPTS) {
+			entry.expired = true;
+			routes.delete(msg.id);
+			notifyDropped(msg);
+			if (msg.expectsReply) {
+				try {
+					const senderDir = channelDir(state.root, msg.fromRunId, msg.fromAgent, msg.fromChildIndex);
+					writeReply(senderDir, msg.id, `[delivery error] Message could not be delivered after ${entry.attempts} attempts.`);
+				} catch {
+					/* best effort; the sender will eventually time out */
+				}
+			}
+			removeRequestFile(msg);
+			return;
+		}
+		const backoff = Math.min(RETRY_BACKOFF_MAX_MS, RETRY_BACKOFF_BASE_MS * 2 ** (entry.attempts - 1));
+		entry.nextAttemptAt = now + backoff;
+	};
+
+	const expireMessage = (msg: MessageRequest, st: RouteState | undefined): void => {
+		if (!st) {
+			state.onMessageExpired?.(msg);
+			removeRequestFile(msg);
+			return;
+		}
+		// Notify at most once, even if a delivery is still in flight; the
+		// running delivery keeps owning the entry until it settles.
+		if (!st.expired) {
+			st.expired = true;
+			state.onMessageExpired?.(msg);
+			removeRequestFile(msg);
+		}
+		if (!st.inFlight) routes.delete(msg.id);
+	};
 
 	const poll = () => {
+		const now = Date.now();
+		if (now - lastSweepAt >= SWEEP_INTERVAL_MS) {
+			lastSweepAt = now;
+			sweepRouteStates(routes, now);
+			try {
+				sweepChannelTree(state.root, now);
+			} catch {
+				/* janitor failures must never break routing */
+			}
+		}
 		for (const msg of scanMessages(state.root)) {
-			if (msg.expiresAt !== undefined && msg.expiresAt < Date.now()) {
-				seen.delete(msg.id);
-				inFlight.delete(msg.id);
-				state.onMessageExpired?.(msg);
-				removeRequestFile(msg);
+			if (msg.expiresAt !== undefined && msg.expiresAt < now) {
+				expireMessage(msg, routes.get(msg.id));
 				continue;
 			}
-			if (seen.has(msg.id) || inFlight.has(msg.id)) continue;
+			const st = routes.get(msg.id);
+			if (st?.inFlight) continue;
+			if (st?.deliveredAt !== undefined) continue;
+			if (st && now < st.nextAttemptAt) continue;
 			if (!state.matchesContext(msg)) continue;
+			const entry: RouteState = st ?? { attempts: 0, nextAttemptAt: 0, inFlight: false };
+			entry.requestFile = msg.requestFile;
+			routes.set(msg.id, entry);
 			if (msg.to === MAIN_AGENT) {
 				try {
 					state.onMainMessage(msg);
 					// A request to main remains on disk until reply_message is
 					// called, so remember successful delivery to avoid injecting
-					// it on every poll. Failed delivery is deliberately retried.
-					seen.add(msg.id);
+					// it on every poll. Failed delivery is never marked seen; it
+					// retries with backoff and is dropped after too many tries.
+					entry.deliveredAt = now;
 				} catch {
-					/* retry on the next poll */
+					failDelivery(msg, entry, now);
 				}
 			} else {
-				inFlight.add(msg.id);
+				entry.inFlight = true;
 				void Promise.resolve()
 					.then(() => state.onChildMessage(msg))
 					.then(() => {
-						seen.add(msg.id);
+						// Do not mark delivered when the message expired while the
+						// delivery was running: its request file is already gone.
+						if (!entry.expired) entry.deliveredAt = Date.now();
 					})
 					.catch(() => {
-						/* retry unexpected routing failures on the next poll */
+						// Delivery failed: never mark seen. Retry with backoff, or
+						// drop (and release waiters) once attempts are exhausted.
+						if (!entry.expired) failDelivery(msg, entry, Date.now());
 					})
 					.finally(() => {
-						inFlight.delete(msg.id);
+						entry.inFlight = false;
+						// Delivered entries stay for TTL/bounded dedup and retrying
+						// entries keep their attempts/backoff state (deleting them
+						// would reset the backoff into a tight retry storm). Only
+						// expiry leaves no residue: its request file is already gone.
+						if (entry.expired && entry.deliveredAt === undefined) routes.delete(msg.id);
 					});
 			}
 		}
@@ -475,8 +970,8 @@ function registerMainReplyTool(pi: ExtensionAPI, state: MessageRouterState): voi
 		name: TOOL_SEND,
 		label: "Send Message",
 		description: [
-			"Send a message to a subagent: to=<agent name>. wait=true waits for its reply.",
-			"The subagent processes the message and replies via reply_message.",
+			"Send a message to a subagent: to=<logical name> or an exact runtime address such as actor#01ab23cd. wait=true waits for its reply.",
+			"The subagent processes the message and replies via reply_message. During a synchronous task, use wait=false when contacting main.",
 		].join(" "),
 		parameters: Type.Object({
 			to: Type.String({ description: "Subagent name" }),
@@ -500,22 +995,20 @@ function registerMainReplyTool(pi: ExtensionAPI, state: MessageRouterState): voi
 				) * 1000;
 			const msg = findOrCreateProxyRequest(state.root, params.content, wait, timeoutMs);
 			if (!msg) {
-				return { content: [{ type: "text", text: "Message channel is not ready." }] };
+				return textResult("Message channel is not ready.");
 			}
 			const routed = { ...msg, to: params.to };
 			if (!wait) {
 				void Promise.resolve(state.onChildMessage(routed)).catch(() => {
 					/* fire-and-forget failures cannot be returned to this completed tool call */
 				});
-				return { content: [{ type: "text", text: `Sent message to ${params.to}` }] };
+				return textResult(`Sent message to ${params.to}`);
 			}
 			try {
 				const reply = await state.onChildMessage(routed, signal);
-				return { content: [{ type: "text", text: `Reply from ${params.to}:\n${reply}` }] };
+				return textResult(`Reply from ${params.to}:\n${reply}`);
 			} catch (e) {
-				return {
-					content: [{ type: "text", text: `Failed to message ${params.to}: ${e instanceof Error ? e.message : String(e)}` }],
-				};
+				return textResult(`Failed to message ${params.to}: ${e instanceof Error ? e.message : String(e)}`);
 			}
 		},
 	});
@@ -534,15 +1027,13 @@ function registerMainReplyTool(pi: ExtensionAPI, state: MessageRouterState): voi
 		execute: async (_id, params) => {
 			const msg = findRequestInTree(state.root, params.message_id);
 			if (!msg) {
-				return {
-					content: [{ type: "text", text: `Message not found: ${params.message_id.slice(0, 8)} (may already be handled)` }],
-				};
+				return textResult(`Message not found: ${params.message_id.slice(0, 8)} (may already be handled)`);
 			}
 			const dir = channelDir(state.root, msg.fromRunId, msg.fromAgent, msg.fromChildIndex);
-			writeReply(dir, msg.id, params.content);
+			writeReply(dir, msg.id, params.content, msg.to);
 			removeRequestFile(msg);
 			state.onMessageReplied?.(msg);
-			return { content: [{ type: "text", text: `Replied to ${msg.from}` }] };
+			return textResult(`Replied to ${msg.from}`);
 		},
 	});
 }
@@ -555,14 +1046,16 @@ function findOrCreateProxyRequest(
 	timeoutMs: number,
 ): MessageRequest | undefined {
 	if (!root) return undefined;
+	const now = Date.now();
 	return {
 		type: "pi.message.request",
 		id: randomUUID(),
-		createdAt: Date.now(),
+		createdAt: now,
 		from: MAIN_AGENT,
 		to: "",
 		content,
 		expectsReply,
+		...(expectsReply ? { expiresAt: now + timeoutMs } : {}),
 		timeoutMs,
 		requestFile: "",
 		fromRunId: "main",