jeo-code 0.12.13 → 0.12.16

package/src/messenger/gateway.ts

@@ -1,4 +1,5 @@
 import { MessengerHttpError } from "./http";
+import { DiscordModelSelectionError } from "./model-selection";
 import type {
 	MessengerActivityReporter,
 	MessengerAdapter,
@@ -173,7 +174,7 @@ export type MessengerSessionIdentity = readonly [
 	channel: string,
 	thread: OptionalIdentity,
 	conversation: OptionalIdentity,
-	user: string,
+	user: OptionalIdentity,
 ];
 
 function optionalIdentity(name: string, value: string | undefined): OptionalIdentity {
@@ -201,7 +202,7 @@ export function messengerSessionIdentity(message: MessengerMessage): MessengerSe
 		message.parentChannelId ?? message.channelId,
 		optionalIdentity("thread", message.threadId),
 		optionalIdentity("conversation", message.conversationId),
-		message.senderId,
+		message.platform === "discord" && message.threadId !== undefined ? ["absent"] : ["present", message.senderId],
 	];
 }
 
@@ -215,9 +216,14 @@ export function messengerSessionRoute(cwd: string, message: MessengerMessage): s
 	return new Bun.CryptoHasher("sha256").update(JSON.stringify([cwd, messengerConversationKey(message)])).digest("hex");
 }
 
-function schedulingKey(message: MessengerMessage, adapter: MessengerAdapter): string {
+/**
+ * Admission lane. A top-level message has no thread yet, so only its raw channel can order it against its
+ * neighbours; anything already resolved is ordered by its own conversation. A lane is held only until the request
+ * is queued, never while it runs, so it cannot serialize requests that end up in different threads.
+ */
+function admissionKey(message: MessengerMessage, adapter: MessengerAdapter): string {
 	if (adapter.prepare && !message.direct && !message.threadId && !message.parentChannelId) {
-		return JSON.stringify([message.platform, message.accountId, message.channelId, message.messageId]);
+		return JSON.stringify([message.platform, message.accountId, message.guildId, message.channelId, message.platform === "discord" ? null : message.senderId]);
 	}
 	return messengerConversationKey(message);
 }
@@ -242,12 +248,15 @@ export function isMessengerMessageAllowed(message: MessengerMessage, config: Mes
 }
 
 interface PendingMessage {
+	/** Prepared destination: replies, deliveries and activity target it. */
 	message: MessengerMessage;
 	adapter: MessengerAdapter;
 	signal: AbortSignal;
 	resolve: () => void;
-	/** Requests sharing a key never run at the same time. */
+	/** Destination conversation key; requests sharing it never run at the same time. */
 	key: string;
+	/** Status reactions on the user's original message. */
+	status: (state: "processing" | "success" | "failure") => void;
 }
 
 export interface MessengerGateway {
@@ -259,10 +268,13 @@ export interface MessengerGatewayOptions {
 	/** Minimum spacing between in-place activity edits for one request. */
 	activityIntervalMs?: number;
 	/**
-	 * Requests processed at once (default 1). Requests of one prepared conversation still answer and deliver in
-	 * order; above 1 the reply implementation must accept concurrent turns for different conversations.
+	 * Requests processed at once (default 1). Requests of one conversation answer and deliver in arrival order and
+	 * wait in the queue, not in a slot, behind their predecessor; above 1 the reply implementation must accept
+	 * concurrent turns for different conversations.
 	 */
 	concurrency?: number;
+	/** Authenticated human controls bypass model queues, including busy sessions. */
+	sandboxControl?: (message: MessengerMessage, signal: AbortSignal) => Promise<{ handled: boolean; output: string }>;
 }
 
 export function createMessengerGateway(
@@ -283,22 +295,22 @@ export function createMessengerGateway(
 	const queue: PendingMessage[] = [];
 	const activeKeys = new Set<string>();
 	const turns = new Set<Promise<void>>();
-	/** Settles when the latest request of a prepared conversation has delivered its reply. */
-	const conversationTails = new Map<string, Promise<void>>();
+	/** Orders admission (sandbox control, capacity check, destination preparation) per raw lane. */
+	const admissionTails = new Map<string, Promise<void>>();
+	/** Requests holding a queue slot while the adapter prepares their destination; counted against the queue cap. */
+	let preparing = 0;
 	const lifetime = new AbortController();
 	let running = false;
 	let fatalError: MessengerFatalError | undefined;
 	let statusInFlight = 0;
 
-	async function processRequest(pending: PendingMessage): Promise<void> {
-		const { message, adapter, signal, resolve } = pending;
-		let failed = false;
-		let activity = NO_ACTIVITY;
-		let release = (): void => {};
-		let tail: Promise<void> | undefined;
-		let conversation = "";
+	function createStatusReporter(
+		adapter: MessengerAdapter,
+		message: MessengerMessage,
+		signal: AbortSignal,
+	): (state: "processing" | "success" | "failure") => void {
 		let statusChain = Promise.resolve();
-		const status = (state: "processing" | "success" | "failure"): void => {
+		return state => {
 			if (!adapter.status) return;
 			statusChain = statusChain.then(async () => {
 				if (signal.aborted || statusInFlight >= MAX_STATUS_IN_FLIGHT) return;
@@ -328,22 +340,20 @@ export function createMessengerGateway(
 				}
 			});
 		};
+	}
+
+	async function processRequest(pending: PendingMessage): Promise<void> {
+		const { message, adapter, signal, resolve, status } = pending;
+		let failed = false;
+		let activity = NO_ACTIVITY;
 		try {
 			if (signal.aborted) return;
 			status("processing");
-			const destination = (await adapter.prepare?.(message, signal)) ?? message;
-			conversation = messengerConversationKey(destination);
-			const previous = conversationTails.get(conversation);
-			const done = Promise.withResolvers<void>();
-			release = done.resolve;
-			tail = done.promise;
-			conversationTails.set(conversation, tail);
-			await previous;
-			activity = createActivityReporter(adapter, destination, signal, activityIntervalMs);
+			activity = createActivityReporter(adapter, message, signal, activityIntervalMs);
 			activity.report("Starting request");
 			let text: string;
 			try {
-				text = await reply(destination, signal, activity.report);
+				text = await reply(message, signal, activity.report);
 			} catch (error) {
 				failed = true;
 				if (error instanceof MessengerFatalError) {
@@ -353,11 +363,13 @@ export function createMessengerGateway(
 					return;
 				}
 				if (signal.aborted) return;
-				text = "The request could not be completed. Please try again.";
+				text = error instanceof DiscordModelSelectionError
+					? "Discord could not verify a model. Ask the operator to configure an explicit Discord model, check provider credentials and live model discovery, then restart the messenger service."
+					: "The request could not be completed. Please try again.";
 			}
 			if (!signal.aborted && text.trim()) {
 				// A failed send may already have delivered a chunk: never retry the entire reply.
-				await adapter.send(destination, text, signal);
+				await adapter.send(message, text, signal);
 			}
 			if (!signal.aborted) status(failed ? "failure" : "success");
 		} catch {
@@ -365,8 +377,6 @@ export function createMessengerGateway(
 			if (!signal.aborted) status("failure");
 		} finally {
 			await activity.close(failed ? "failure" : signal.aborted ? "cancelled" : "success");
-			release();
-			if (tail && conversationTails.get(conversation) === tail) conversationTails.delete(conversation);
 			resolve();
 		}
 	}
@@ -390,21 +400,59 @@ export function createMessengerGateway(
 		}
 	}
 
-	function handle(message: MessengerMessage, signal?: AbortSignal): Promise<void> {
+	async function handle(message: MessengerMessage, signal?: AbortSignal): Promise<void> {
 		const adapter = byPlatform.get(message.platform);
 		const effectiveSignal = signal ? AbortSignal.any([lifetime.signal, signal]) : lifetime.signal;
 		if (effectiveSignal.aborted || !adapter || !isMessengerMessageAllowed(message, config)) return Promise.resolve();
 		const id = JSON.stringify([message.platform, message.accountId, message.channelId, message.messageId]);
-		if (seen.has(id) || queue.length >= MAX_QUEUED_MESSAGES) return Promise.resolve();
+		if (seen.has(id)) return;
 		seen.add(id);
 		if (seen.size > MAX_SEEN_MESSAGES) {
 			const oldest = seen.values().next().value;
 			if (oldest !== undefined) seen.delete(oldest);
 		}
-		const { promise, resolve } = Promise.withResolvers<void>();
-		queue.push({ message, adapter, signal: effectiveSignal, resolve, key: schedulingKey(message, adapter) });
-		schedule();
-		return promise;
+		const lane = admissionKey(message, adapter);
+		const previous = admissionTails.get(lane) ?? Promise.resolve();
+		const ready = Promise.withResolvers<void>();
+		const tail = previous.then(() => ready.promise);
+		admissionTails.set(lane, tail);
+		void tail.then(() => { if (admissionTails.get(lane) === tail) admissionTails.delete(lane); });
+		try {
+			if (options.sandboxControl) {
+				const control = await options.sandboxControl(message, effectiveSignal);
+				if (control.handled) {
+					if (!effectiveSignal.aborted && control.output.trim()) await adapter.send(message, control.output, effectiveSignal);
+					return;
+				}
+			}
+			await previous;
+			if (effectiveSignal.aborted) return;
+			const status = createStatusReporter(adapter, message, effectiveSignal);
+			// Capacity is claimed before preparing: a request that cannot be queued must never create a thread.
+			if (queue.length + preparing >= MAX_QUEUED_MESSAGES) {
+				// Never executed, so forget the id: a redelivery is accepted once capacity returns, replaying nothing.
+				seen.delete(id);
+				status("failure");
+				return;
+			}
+			let destination: MessengerMessage;
+			let key: string;
+			preparing++;
+			try {
+				destination = (await adapter.prepare?.(message, effectiveSignal)) ?? message;
+				key = messengerConversationKey(destination);
+			} catch {
+				if (!effectiveSignal.aborted) status("failure");
+				return;
+			} finally {
+				preparing--;
+			}
+			if (effectiveSignal.aborted) return;
+			const { promise, resolve } = Promise.withResolvers<void>();
+			queue.push({ message: destination, adapter, signal: effectiveSignal, resolve, key, status });
+			schedule();
+			return promise;
+		} finally { ready.resolve(); }
 	}
 
 	return {

package/src/messenger/model-selection.ts

@@ -0,0 +1,101 @@
+import { readGlobalConfig, type Config } from "../agent/state";
+import { listProviderModels } from "../ai/model-discovery";
+import { credentialForCall, effectiveCredentialForProvider, qualifyModelId, resolveProvider } from "../ai/model-manager";
+import { resolveModelId } from "../ai/model-registry";
+import { resolveCredential, type AuthProvider, type Credential } from "../auth";
+
+export class DiscordModelSelectionError extends Error {
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : "Discord model selection failed", { cause });
+    this.name = "DiscordModelSelectionError";
+  }
+}
+
+/** Select only from the account's live catalog; never substitute a static model. */
+export async function selectDiscordModel(
+  explicit: string | undefined,
+  opts: { config?: Config; signal?: AbortSignal; list?: typeof listProviderModels; credential?: typeof resolveCredential } = {},
+): Promise<string> {
+  try {
+    return await selectDiscordModelFromCatalog(explicit, opts);
+  } catch (error) {
+    if (opts.signal?.aborted) throw error;
+    throw new DiscordModelSelectionError(error);
+  }
+}
+
+async function selectDiscordModelFromCatalog(
+  explicit: string | undefined,
+  opts: { config?: Config; signal?: AbortSignal; list?: typeof listProviderModels; credential?: typeof resolveCredential },
+): Promise<string> {
+  const config = opts.config ?? await readGlobalConfig();
+  const requested = explicit?.trim() ? await resolveModelId(explicit.trim(), config) : undefined;
+  const provider = resolveProvider(requested || await resolveModelId(config.defaultModel, config));
+  if (!requested && provider !== "anthropic" && provider !== "openai" && provider !== "antigravity") {
+    throw new Error(`Discord automatic model selection does not support provider ${provider}; configure an explicit model`);
+  }
+  const result = await (opts.list ?? listProviderModels)(provider, { config, signal: opts.signal, limit: Number.POSITIVE_INFINITY, preferOAuth: true });
+  if (opts.signal?.aborted) throw new Error("Messenger request aborted");
+  if (!result.ok || result.fallback || result.source === "none" || (result.source === "keyless" && (!requested || (provider !== "ollama" && provider !== "lmstudio"))) || !result.models.length) {
+    throw new Error(`Discord cannot verify available models for ${provider}; check login and live model discovery`);
+  }
+  const canonical = (model: string) => qualifyModelId(model, provider);
+  const verified = async (model: string): Promise<string> => {
+    const authProvider: AuthProvider | undefined = provider === "anthropic" ? "anthropic" : provider === "openai" ? "openai" : undefined;
+    if (authProvider && config.providers[authProvider]) {
+      const credential: Credential = await (opts.credential ?? resolveCredential)(authProvider);
+      const effective = effectiveCredentialForProvider(authProvider, credential, config, model);
+      const actual = credentialForCall(provider, effective, config, provider === "openai" ? config.openaiBaseUrl : undefined);
+      if (actual.kind !== result.source) {
+        throw new Error(`Discord cannot verify ${provider} model access for the credential used at runtime`);
+      }
+    }
+    return canonical(model);
+  };
+  if (requested) {
+    const prefix = `${provider}/`;
+    const requestedId = requested.startsWith(prefix) ? requested.slice(prefix.length) : requested;
+    const match = result.models.find(model => (model.startsWith(prefix) ? model.slice(prefix.length) : model) === requestedId);
+    if (!match) throw new Error(`Discord configured model is not available for ${provider}: ${requested}`);
+    return verified(match);
+  }
+  const family = provider === "anthropic" ? /sonnet/i : provider === "openai" ? /terra/i : /gemini.*flash/i;
+  const variant = /(?:^|[^a-z0-9])(?:mini|lite|codex|thinking|image)(?=$|[^a-z0-9])/i;
+  const models = [...new Set(result.models.filter(model => {
+    const name = provider === "antigravity" ? (result.displayNames?.[model] ?? model) : model;
+    return family.test(name) && !variant.test(model) && !variant.test(name);
+  }))];
+  if (!models.length) throw new Error(`Discord found no available ${provider} model in the required family`);
+  if (models.length === 1) return verified(models[0]!);
+  // Antigravity wire aliases can advertise a different version than their IDs.
+  // Only the display name from the same live response establishes recency.
+  if (provider === "antigravity" && models.some(model => !result.displayNames?.[model])) {
+    throw new Error("Discord cannot determine the newest Antigravity Flash model: live catalog is missing display names; configure an explicit model from the live catalog");
+  }
+  const ranked = models.map(model => {
+    const name = provider === "antigravity" ? result.displayNames![model]! : model;
+    const snapshot = name.match(/[-_ ](\d{4}-\d{2}-\d{2}|\d{8})$/);
+    const versionName = snapshot ? name.slice(0, -snapshot[0].length) : name;
+    const tierName = provider === "antigravity" ? name.match(/\((high|medium|low)\)\s*$/i)?.[1]?.toLowerCase() : undefined;
+    const tier = tierName === "high" ? 3 : tierName === "medium" ? 2 : tierName === "low" ? 1 : 0;
+    return { model, version: (versionName.match(/\d+/g) ?? []).map(Number), snapshot: Number(snapshot?.[1]?.replaceAll("-", "") ?? 0), tier, ambiguousVersion: provider === "openai" && /terra.*\d/i.test(versionName) };
+  });
+  if (ranked.some(item => !item.version.length || item.ambiguousVersion)) {
+    throw new Error(`Discord cannot determine the newest ${provider} model; configure an explicit model`);
+  }
+  const compare = (a: number[], b: number[]) => {
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+      const difference = (b[i] ?? 0) - (a[i] ?? 0);
+      if (difference) return difference;
+    }
+    return 0;
+  };
+  ranked.sort((a, b) => compare(a.version, b.version) || b.snapshot - a.snapshot || b.tier - a.tier);
+  if (provider === "antigravity" && ranked.some((item, index) => index > 0 && compare(ranked[0]!.version, item.version) === 0 && ranked[0]!.snapshot === item.snapshot && (!ranked[0]!.tier || !item.tier))) {
+    throw new Error("Discord cannot distinguish the newest antigravity models; configure an explicit model");
+  }
+  if (compare(ranked[0]!.version, ranked[1]!.version) === 0 && ranked[0]!.snapshot === ranked[1]!.snapshot && ranked[0]!.tier === ranked[1]!.tier) {
+    throw new Error(`Discord cannot distinguish the newest ${provider} models; configure an explicit model`);
+  }
+  return verified(ranked[0]!.model);
+}

package/src/messenger/session-pool.ts

@@ -6,6 +6,8 @@ interface WorkerProcess {
 	stderr: ReadableStream<Uint8Array>;
 	exited: Promise<number>;
 	kill(signal?: number | NodeJS.Signals): void;
+	/** Private IPC channel; present only on workers spawned with `ipc`. */
+	send?(message: unknown): unknown;
 }
 
 interface Pending {
@@ -18,35 +20,80 @@ interface Pending {
 
 interface Worker {
 	child: WorkerProcess;
+	exit: Promise<number>;
+	policyKey?: string;
 	pending?: Pending;
 	lastUsed: number;
 	dead: boolean;
+	forceSent?: boolean;
 	exited?: boolean;
+	cleanupNonce?: string;
+	cleanupGone?: boolean;
+	cleanupError?: Error;
 	idleTimer?: ReturnType<typeof setTimeout>;
 	exitTimer?: ReturnType<typeof setTimeout>;
 }
 
-export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn, limit = 16, idleTimeoutMs = 5 * 60_000, shutdownTimeoutMs = 5_000) {
+/** Resident sessions the pool keeps, and the number of turns it runs at once. */
+export const MESSENGER_SESSION_LIMIT = 16;
+
+export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn, limit = MESSENGER_SESSION_LIMIT, idleTimeoutMs = 5 * 60_000, shutdownTimeoutMs = 5_000, options: { requireSandboxCleanup?: boolean } = {}) {
 	const workers = new Map<string, Worker>();
 	const allWorkers = new Map<Worker, string>();
-	const exits = new Map<Promise<number>, WorkerProcess>();
+	const exits = new Map<Promise<number>, Worker>();
 	const retiring = new Map<string, Promise<number>>();
+	const keyTails = new Map<string, Promise<void>>();
+	const requireSandboxCleanup = options.requireSandboxCleanup === true;
+	const incomplete = (detail: string) => new Error(`REVOKE_INCOMPLETE: ${detail}`);
 
 	let closed = false;
 	const closedSignal = new AbortController();
 
 	let tick = 0;
 
+	// Admission: at most `limit` turns hold a worker at once. Later turns wait here in arrival order until a
+	// running turn settles, so a busy pool is backpressure on the waiting request, never a failure of it.
+	let admitted = 0;
+	const waiting: Array<() => void> = [];
+
+	function admit(signal: AbortSignal): Promise<void> {
+		return new Promise<void>((resolve, reject) => {
+			const grant = () => { cleanup(); resolve(); };
+			const abort = () => {
+				const index = waiting.indexOf(grant);
+				if (index >= 0) waiting.splice(index, 1);
+				cleanup();
+				reject(new Error("Messenger request aborted"));
+			};
+			const cleanup = () => { signal.removeEventListener("abort", abort); closedSignal.signal.removeEventListener("abort", abort); };
+			signal.addEventListener("abort", abort, { once: true });
+			closedSignal.signal.addEventListener("abort", abort, { once: true });
+			waiting.push(grant);
+		});
+	}
+
+	/** Hand the finished turn's slot straight to the oldest waiter, or free it. */
+	function release() {
+		const next = waiting.shift();
+		if (next) next(); else admitted--;
+	}
+
+	function forceKill(worker: Worker) {
+		if (worker.cleanupNonce) return;
+		if (worker.forceSent) return;
+		try { worker.child.kill("SIGKILL"); worker.forceSent = true; } catch { /* Retry on shutdown if termination failed. */ }
+	}
+
 	function retire(key: string, worker: Worker) {
 		if (worker.dead) return;
 		worker.dead = true;
 		if (workers.get(key) === worker) workers.delete(key);
-		allWorkers.delete(worker);
-		if (!worker.exited) {
-			retiring.set(key, worker.child.exited);
-			void worker.child.exited.then(
-				() => { if (retiring.get(key) === worker.child.exited) retiring.delete(key); },
-				() => { if (retiring.get(key) === worker.child.exited) retiring.delete(key); },
+		if (!worker.cleanupNonce) allWorkers.delete(worker);
+		if (!worker.exited || worker.cleanupNonce) {
+			retiring.set(key, worker.exit);
+			void worker.exit.then(
+				() => { if (retiring.get(key) === worker.exit) retiring.delete(key); },
+				() => { /* Keep the key blocked when process exit cannot be confirmed. */ },
 			);
 		}
 		if (worker.idleTimer) clearTimeout(worker.idleTimer);
@@ -55,7 +102,29 @@ export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn,
 		worker.pending?.reject(new Error("Messenger worker stopped"));
 		worker.pending = undefined;
 		if (!worker.exited) {
-			try { worker.child.kill(); } catch { /* Shutdown will attempt forced termination. */ }
+			if (worker.cleanupNonce) {
+				// Protected workers never receive a kill signal: Windows cannot deliver a catchable SIGTERM.
+				// Shutdown is a private IPC message; a missing or failing channel is visible, never success.
+				const channel = worker.child.send;
+				if (typeof channel !== "function") {
+					worker.cleanupError = incomplete("worker shutdown channel unavailable");
+				} else {
+					try {
+						const sent = channel.call(worker.child, { type: "jeo_messenger_shutdown", nonce: worker.cleanupNonce });
+						if (sent && typeof (sent as PromiseLike<unknown>).then === "function") {
+							void (sent as PromiseLike<unknown>).then(undefined, error => { worker.cleanupError = incomplete(`worker shutdown request failed: ${String(error)}`); });
+						}
+					} catch (error) { worker.cleanupError = incomplete(`worker shutdown request failed: ${String(error)}`); }
+				}
+			} else {
+				try { worker.child.kill(); }
+				catch (error) { worker.cleanupError = incomplete(`worker termination failed: ${String(error)}`); }
+			}
+			if (!worker.cleanupNonce) {
+				const force = setTimeout(() => forceKill(worker), shutdownTimeoutMs);
+				force.unref();
+				void worker.exit.then(() => clearTimeout(force), () => clearTimeout(force));
+			}
 		}
 	}
 
@@ -89,16 +158,45 @@ export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn,
 		} finally { reader.releaseLock(); }
 	}
 
-	function start(key: string, command: string[], cwd: string, env: Record<string, string>): Worker {
-		if (workers.size >= limit) {
+	function waitForExit(exit: Promise<number>, signal: AbortSignal, capacity = false): Promise<void> {
+		return new Promise<void>((resolve, reject) => {
+			const abort = () => { cleanup(); reject(new Error("Messenger request aborted")); };
+			const unavailable = () => new Error("Messenger worker capacity unavailable while another session is being cleaned up");
+			const timer = setTimeout(() => { cleanup(); reject(capacity ? unavailable() : requireSandboxCleanup ? incomplete("previous worker cleanup is still pending") : new Error("Messenger worker did not exit")); }, shutdownTimeoutMs * 2);
+			const cleanup = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); closedSignal.signal.removeEventListener("abort", abort); };
+			signal.addEventListener("abort", abort, { once: true });
+			closedSignal.signal.addEventListener("abort", abort, { once: true });
+			if (signal.aborted || closed) { abort(); return; }
+			void exit.then(() => { cleanup(); resolve(); }, error => { cleanup(); reject(capacity ? unavailable() : requireSandboxCleanup ? incomplete(`previous worker cleanup failed: ${String(error)}`) : new Error("Messenger worker exit could not be confirmed")); });
+		});
+	}
+
+	async function start(key: string, command: string[], cwd: string, env: Record<string, string>, signal: AbortSignal, policyKey?: string): Promise<Worker> {
+		while ((requireSandboxCleanup ? allWorkers.size : workers.size) >= limit) {
 			const idle = [...workers.entries()].filter(([, worker]) => !worker.pending).sort((a, b) => a[1].lastUsed - b[1].lastUsed)[0];
-			if (!idle) throw new Error("Messenger worker capacity reached");
+			if (!idle) {
+				const retiringWorker = requireSandboxCleanup ? [...allWorkers.keys()].find(worker => worker.dead) : undefined;
+				if (!retiringWorker) throw new Error("Messenger worker capacity reached");
+				await waitForExit(retiringWorker.exit, signal, true);
+				continue;
+			}
 			retire(idle[0], idle[1]);
+			if (requireSandboxCleanup) await waitForExit(idle[1].exit, signal, true);
 		}
-		const child = spawn(command, { cwd, env, stdin: "pipe", stdout: "pipe", stderr: "pipe" }) as unknown as WorkerProcess;
-		const worker: Worker = { child, lastUsed: ++tick, dead: false };
-		exits.set(child.exited, child);
-		void child.exited.then(() => exits.delete(child.exited), () => exits.delete(child.exited));
+		if (closed || signal.aborted) throw new Error("Messenger request aborted");
+		const cleanupNonce = requireSandboxCleanup ? crypto.randomUUID() : undefined;
+		const workerEnv = { ...env };
+		delete workerEnv.JEO_MESSENGER_SHUTDOWN_NONCE;
+		if (cleanupNonce) workerEnv.JEO_MESSENGER_SHUTDOWN_NONCE = cleanupNonce;
+		const spawnOptions = { cwd, env: workerEnv, stdin: "pipe", stdout: "pipe", stderr: "pipe", ...(cleanupNonce ? { ipc() {}, serialization: "json" } : {}) };
+		const child = spawn(command, spawnOptions as never) as unknown as WorkerProcess;
+		const cleanup = Promise.withResolvers<number>();
+		const worker: Worker = { child, exit: cleanupNonce ? cleanup.promise : child.exited, cleanupNonce, policyKey, lastUsed: ++tick, dead: false };
+		exits.set(worker.exit, worker);
+		void worker.exit.then(() => {
+			exits.delete(worker.exit);
+			if (cleanupNonce) allWorkers.delete(worker);
+		}, () => { if (!cleanupNonce) exits.delete(worker.exit); });
 		workers.set(key, worker);
 		allWorkers.set(worker, key);
 		const stdoutDone = readLines(child.stdout, line => {
@@ -113,7 +211,17 @@ export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn,
 				finishTurn(key, worker, pending);
 			} catch { retire(key, worker); }
 		}).catch(() => retire(key, worker));
-		void readLines(child.stderr, line => {
+		const stderrDone = readLines(child.stderr, line => {
+			if (cleanupNonce && line.startsWith("JEO_MESSENGER_SHUTDOWN_ACK ")) {
+				try {
+					const ack: unknown = JSON.parse(line.slice("JEO_MESSENGER_SHUTDOWN_ACK ".length));
+					if (typeof ack === "object" && ack !== null && "nonce" in ack && ack.nonce === cleanupNonce && "gone" in ack) {
+						worker.cleanupGone = ack.gone === true;
+						worker.cleanupError = worker.cleanupGone ? undefined : incomplete("worker supervisor cleanup failed");
+					}
+				} catch { /* Unauthenticated or malformed output is never cleanup proof. */ }
+				return;
+			}
 			if (line.startsWith("JEO_MESSENGER_ACTIVITY ")) {
 				const activityText = line.slice("JEO_MESSENGER_ACTIVITY ".length).trim();
 				if (activityText) worker.pending?.report?.(activityText);
@@ -121,9 +229,15 @@ export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn,
 				worker.pending?.report?.("Working on your request");
 			}
 		}).catch(() => retire(key, worker));
-		void child.exited.then(() => {
-			if (worker.dead) return;
+		if (cleanupNonce) {
+			void Promise.all([child.exited, stderrDone, stdoutDone]).then(([code]) => {
+				if (worker.cleanupGone) cleanup.resolve(code);
+				else cleanup.reject(worker.cleanupError ?? incomplete("worker exited without supervisor cleanup acknowledgement"));
+			}, error => cleanup.reject(incomplete(`worker exit could not be verified: ${String(error)}`)));
+		}
+		void worker.exit.then(() => {
 			worker.exited = true;
+			if (worker.dead) return;
 			if (workers.get(key) === worker) workers.delete(key);
 			worker.exitTimer = setTimeout(() => retire(key, worker), shutdownTimeoutMs);
 			worker.exitTimer.unref();
@@ -134,24 +248,61 @@ export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn,
 		return worker;
 	}
 
-	async function turn(key: string, command: string[], cwd: string, env: Record<string, string>, text: string, signal: AbortSignal, report?: MessengerActivityReporter): Promise<string> {
+	function turn(key: string, command: string[], cwd: string, env: Record<string, string>, text: string, signal: AbortSignal, report?: MessengerActivityReporter, policyKey?: string): Promise<string> {
+		if (closed || signal.aborted) return Promise.reject(new Error("Messenger request aborted"));
+		const run = () => runTurn(key, command, cwd, env, text, signal, report, policyKey).finally(release);
+		const admitRun = () => {
+			if (closed || signal.aborted) return Promise.reject(new Error("Messenger request aborted"));
+			if (admitted < limit && waiting.length === 0) {
+				admitted++;
+				return run();
+			}
+			return admit(signal).then(run);
+		};
+		// Same-key turns run strictly in arrival order. Queued turns hold no admission slot while they wait,
+		// so they never block other sessions; different keys are fully independent.
+		const previous = keyTails.get(key);
+		const result = previous ? waitForTurn(previous, signal).then(admitRun) : admitRun();
+		const settled = result.then(() => undefined, () => undefined);
+		// The tail also covers the predecessor, so an aborted queued turn never lets its successor overtake it.
+		const tail: Promise<void> = previous ? Promise.all([previous, settled]).then(() => undefined) : settled;
+		keyTails.set(key, tail);
+		void tail.then(() => { if (keyTails.get(key) === tail) keyTails.delete(key); });
+		return result;
+	}
+
+	function waitForTurn(previous: Promise<void>, signal: AbortSignal): Promise<void> {
+		return new Promise<void>((resolve, reject) => {
+			const abort = () => { cleanup(); reject(new Error("Messenger request aborted")); };
+			const cleanup = () => { signal.removeEventListener("abort", abort); closedSignal.signal.removeEventListener("abort", abort); };
+			signal.addEventListener("abort", abort, { once: true });
+			closedSignal.signal.addEventListener("abort", abort, { once: true });
+			if (signal.aborted || closed) { abort(); return; }
+			void previous.then(() => { cleanup(); resolve(); });
+		});
+	}
+
+	async function runTurn(key: string, command: string[], cwd: string, env: Record<string, string>, text: string, signal: AbortSignal, report?: MessengerActivityReporter, policyKey?: string): Promise<string> {
 		if (closed || signal.aborted) throw new Error("Messenger request aborted");
-		const previousExit = retiring.get(key);
-		if (previousExit) {
-			await new Promise<void>((resolve, reject) => {
-				const abort = () => { cleanup(); reject(new Error("Messenger request aborted")); };
-				const cleanup = () => { signal.removeEventListener("abort", abort); closedSignal.signal.removeEventListener("abort", abort); };
-				signal.addEventListener("abort", abort, { once: true });
-				closedSignal.signal.addEventListener("abort", abort, { once: true });
-				if (signal.aborted || closed) { abort(); return; }
-				void previousExit.then(() => { cleanup(); resolve(); }, () => { cleanup(); resolve(); });
-			});
+		for (;;) {
+			const existing = workers.get(key);
+			if (existing && existing.policyKey !== policyKey) {
+				if (existing.pending) throw new Error("Messenger conversation is already active");
+				retire(key, existing);
+			}
+			const previousExit = retiring.get(key);
+			if (!previousExit) break;
+			await waitForExit(previousExit, signal);
 		}
 		if (closed || signal.aborted) throw new Error("Messenger request aborted");
 		if ([...allWorkers].some(([worker, workerKey]) => workerKey === key && worker.pending)) {
 			throw new Error("Messenger conversation is already active");
 		}
-		const worker = workers.get(key) ?? start(key, command, cwd, env);
+		const worker = workers.get(key) ?? await start(key, command, cwd, env, signal, policyKey);
+		if (closed || signal.aborted || worker.dead) {
+			retire(key, worker);
+			throw new Error("Messenger worker stopped");
+		}
 		if (worker.pending) throw new Error("Messenger conversation is already active");
 		if (worker.idleTimer) clearTimeout(worker.idleTimer);
 		worker.idleTimer = undefined;
@@ -179,15 +330,18 @@ export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn,
 			let timer: ReturnType<typeof setTimeout> | undefined;
 			try {
 				return await Promise.race([
-					Promise.allSettled([...exits.keys()]).then(() => true),
+					Promise.allSettled([...exits.keys()]).then(results => {
+						const failure = results.find(result => result.status === "rejected");
+						if (failure?.status === "rejected" && requireSandboxCleanup) throw incomplete(`worker cleanup failed: ${String(failure.reason)}`);
+						return true;
+					}),
 					new Promise<false>(resolve => { timer = setTimeout(() => resolve(false), shutdownTimeoutMs); }),
 				]);
 			} finally { if (timer) clearTimeout(timer); }
 		};
 		if (await waitForExits()) return;
-		for (const child of exits.values()) {
-			try { child.kill("SIGKILL"); } catch { /* The process may have exited concurrently. */ }
-		}
+		if (requireSandboxCleanup) throw incomplete("worker cleanup is still pending; cleanup owner retained");
+		for (const worker of exits.values()) forceKill(worker);
 		if (!(await waitForExits())) throw new Error("Messenger workers did not exit after forced termination");
 	}