@gajae-code/coding-agent 0.11.5 → 0.11.7

package/src/runtime-mcp/client.ts

@@ -15,15 +15,12 @@ import type {
 	MCPInitializeParams,
 	MCPInitializeResult,
 	MCPPrompt,
-	MCPPromptsListResult,
 	MCPRequestOptions,
 	MCPResource,
 	MCPResourceReadParams,
 	MCPResourceReadResult,
 	MCPResourceSubscribeParams,
-	MCPResourcesListResult,
 	MCPResourceTemplate,
-	MCPResourceTemplatesListResult,
 	MCPServerCapabilities,
 	MCPServerConfig,
 	MCPServerConnection,
@@ -43,6 +40,9 @@ const PROTOCOL_VERSION = "2025-03-26";
 /** Default connection timeout in ms */
 const CONNECTION_TIMEOUT_MS = 30_000;
 
+const MAX_PAGINATION_PAGES = 100,
+	MAX_PAGINATION_ITEMS = 10_000;
+
 /** Client info sent during initialization */
 const CLIENT_INFO = {
 	name: "gjc-coding-agent",
@@ -109,6 +109,40 @@ function decodeToolsListResult(value: unknown): MCPToolsListResult {
 	return value.nextCursor === undefined ? { tools } : { tools, nextCursor: value.nextCursor };
 }
 
+async function collectPaginated<T>(
+	connection: MCPServerConnection,
+	options: MCPRequestOptions | undefined,
+	method: string,
+	itemKey: string,
+	items: T[],
+	decode?: (value: unknown) => unknown,
+): Promise<void> {
+	const seenCursors = new Set<string>();
+	const failure = (detail: string) => new MCPExpectedFailure(new Error(`MCP ${method} pagination ${detail}`));
+	let cursor: string | undefined;
+	for (let page = 1; page <= MAX_PAGINATION_PAGES; page++) {
+		const value = await connection.transport.request<unknown>(method, cursor ? { cursor } : {}, options);
+		const result = decode ? decode(value) : value;
+		if (
+			!isRecord(result) ||
+			!Array.isArray(result[itemKey]) ||
+			(result.nextCursor !== undefined && typeof result.nextCursor !== "string")
+		)
+			throw new MCPExpectedFailure();
+		const nextCursor = result.nextCursor as string | undefined;
+		if (nextCursor && seenCursors.has(nextCursor)) throw failure("repeated a cursor");
+		const pageItems = result[itemKey] as T[];
+		const itemCount = items.length + pageItems.length;
+		if (itemCount > MAX_PAGINATION_ITEMS || (itemCount === MAX_PAGINATION_ITEMS && nextCursor))
+			throw failure("did not complete within the 10000-item budget");
+		items.push(...pageItems);
+		if (!nextCursor) return;
+		if (page === MAX_PAGINATION_PAGES) throw failure("did not complete within the 100-page budget");
+		seenCursors.add(nextCursor);
+		cursor = nextCursor;
+	}
+}
+
 /**
  * Default handler for standard MCP server-to-client requests.
  * Handles `ping` and `roots/list`; rejects unknown methods with -32601.
@@ -292,18 +326,7 @@ export async function listTools(
 	}
 
 	const allTools: MCPToolDefinition[] = [];
-	let cursor: string | undefined;
-
-	do {
-		const params: Record<string, unknown> = {};
-		if (cursor) {
-			params.cursor = cursor;
-		}
-
-		const result = decodeToolsListResult(await connection.transport.request<unknown>("tools/list", params, options));
-		allTools.push(...result.tools);
-		cursor = result.nextCursor;
-	} while (cursor);
+	await collectPaginated(connection, options, "tools/list", "tools", allTools, decodeToolsListResult);
 
 	// Cache tools
 	connection.tools = allTools;
@@ -362,18 +385,7 @@ export async function listResources(
 	}
 
 	const allResources: MCPResource[] = [];
-	let cursor: string | undefined;
-
-	do {
-		const params: Record<string, unknown> = {};
-		if (cursor) {
-			params.cursor = cursor;
-		}
-
-		const result = await connection.transport.request<MCPResourcesListResult>("resources/list", params, options);
-		allResources.push(...result.resources);
-		cursor = result.nextCursor;
-	} while (cursor);
+	await collectPaginated(connection, options, "resources/list", "resources", allResources);
 
 	connection.resources = allResources;
 	return allResources;
@@ -395,22 +407,7 @@ export async function listResourceTemplates(
 	}
 
 	const allTemplates: MCPResourceTemplate[] = [];
-	let cursor: string | undefined;
-
-	do {
-		const params: Record<string, unknown> = {};
-		if (cursor) {
-			params.cursor = cursor;
-		}
-
-		const result = await connection.transport.request<MCPResourceTemplatesListResult>(
-			"resources/templates/list",
-			params,
-			options,
-		);
-		allTemplates.push(...result.resourceTemplates);
-		cursor = result.nextCursor;
-	} while (cursor);
+	await collectPaginated(connection, options, "resources/templates/list", "resourceTemplates", allTemplates);
 
 	connection.resourceTemplates = allTemplates;
 	return allTemplates;
@@ -514,18 +511,7 @@ export async function listPrompts(
 	}
 
 	const allPrompts: MCPPrompt[] = [];
-	let cursor: string | undefined;
-
-	do {
-		const params: Record<string, unknown> = {};
-		if (cursor) {
-			params.cursor = cursor;
-		}
-
-		const result = await connection.transport.request<MCPPromptsListResult>("prompts/list", params, options);
-		allPrompts.push(...result.prompts);
-		cursor = result.nextCursor;
-	} while (cursor);
+	await collectPaginated(connection, options, "prompts/list", "prompts", allPrompts);
 
 	connection.prompts = allPrompts;
 	return allPrompts;

package/src/runtime-mcp/content-limits.ts

@@ -0,0 +1,71 @@
+export const MCP_MAX_CONTENT_BYTES = 16 * 1024 * 1024;
+export const MCP_MAX_ERROR_BYTES = 16 * 1024;
+export const MCP_MAX_SSE_REQUEST_MESSAGES = 1024;
+export const MCP_MAX_SSE_BATCH_MESSAGES = 1024;
+export const MCP_HTTP_TIMEOUT_MS = 30_000;
+
+function ignoreCancellation(cancel: () => Promise<unknown>): void {
+	try {
+		void cancel().catch(() => {});
+	} catch {}
+}
+
+export function cancelMCPStream(stream: ReadableStream<Uint8Array> | null): void {
+	if (stream) ignoreCancellation(() => stream.cancel());
+}
+
+type ByteReader = Pick<ReadableStreamDefaultReader<Uint8Array>, "read">;
+
+async function readChunk(reader: ByteReader, signal?: AbortSignal) {
+	if (!signal) return reader.read();
+	signal.throwIfAborted();
+	const aborted = Promise.withResolvers<never>();
+	const onAbort = () => aborted.reject(signal.reason);
+	signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		return await Promise.race([reader.read(), aborted.promise]);
+	} finally {
+		signal.removeEventListener("abort", onAbort);
+	}
+}
+
+export async function readMCPResponseText(response: Response, limit: number, truncate = false, signal?: AbortSignal) {
+	const declared = response.headers.get("Content-Length");
+	if (!truncate && declared && /^\d+$/.test(declared) && Number(declared) > limit) {
+		cancelMCPStream(response.body);
+		throw new Error("MCP response exceeds size limit");
+	}
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	let buffer = new Uint8Array(Math.min(limit, 64 * 1024));
+	let total = 0;
+	try {
+		while (true) {
+			const { value, done } = await readChunk(reader, signal);
+			if (done) break;
+			if (value.length === 0) continue;
+			const remaining = limit - total;
+			if (value.length > remaining) {
+				if (truncate && remaining > 0) buffer.set(value.subarray(0, remaining), total);
+				ignoreCancellation(() => reader.cancel());
+				if (!truncate) throw new Error("MCP response exceeds size limit");
+				return `${new TextDecoder().decode(buffer)}\u2026`;
+			}
+			if (total + value.length > buffer.length) {
+				const grown = new Uint8Array(Math.min(limit, Math.max(total + value.length, buffer.length * 2)));
+				grown.set(buffer);
+				buffer = grown;
+			}
+			buffer.set(value, total);
+			total += value.length;
+		}
+		return new TextDecoder().decode(buffer.subarray(0, total));
+	} catch (error) {
+		ignoreCancellation(() => reader.cancel());
+		throw error;
+	} finally {
+		try {
+			reader.releaseLock();
+		} catch {}
+	}
+}

package/src/runtime-mcp/json-rpc.ts

@@ -4,6 +4,8 @@
  * Lightweight utilities for calling MCP servers directly via HTTP
  * without maintaining persistent connections.
  */
+// biome-ignore assist/source/organizeImports: Keep independent MCP security imports on separate merge anchors.
+import { cancelMCPStream, MCP_HTTP_TIMEOUT_MS, MCP_MAX_CONTENT_BYTES, readMCPResponseText } from "./content-limits";
 import { logger } from "@gajae-code/utils";
 
 /** Parse SSE response format (lines starting with "data: ") */
@@ -25,6 +27,15 @@ export function parseSSE(text: string): unknown {
 	}
 }
 
+async function translateMCPTimeout<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
+	try {
+		return await operation;
+	} catch (error) {
+		if (signal.aborted && error === signal.reason) throw new Error("MCP request timed out");
+		throw error;
+	}
+}
+
 /** JSON-RPC 2.0 response structure */
 export interface JsonRpcResponse<T = unknown> {
 	jsonrpc: "2.0";
@@ -57,22 +68,25 @@ export async function callMCP<T = unknown>(
 		params: params ?? {},
 	};
 
-	const response = await fetch(url, {
-		method: "POST",
-		headers: {
-			"Content-Type": "application/json",
-			Accept: "application/json, text/event-stream",
-		},
-		body: JSON.stringify(body),
-	});
+	const signal = AbortSignal.timeout(MCP_HTTP_TIMEOUT_MS);
+	const response = await translateMCPTimeout(
+		fetch(url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+			body: JSON.stringify(body),
+			signal,
+		}),
+		signal,
+	);
 
 	if (!response.ok) {
+		cancelMCPStream(response.body);
 		const errorMsg = `MCP request failed: ${response.status} ${response.statusText}`;
 		logger.error(errorMsg, { url, method, params });
 		throw new Error(errorMsg);
 	}
 
-	const text = await response.text();
+	const text = await translateMCPTimeout(readMCPResponseText(response, MCP_MAX_CONTENT_BYTES, false, signal), signal);
 	const result = parseSSE(text) as JsonRpcResponse<T> | null;
 
 	if (!result) {

package/src/runtime-mcp/transports/http.ts

@@ -16,6 +16,14 @@ import type {
 	MCPTransport,
 } from "../../runtime-mcp/types";
 import { MCPExpectedFailure, toJsonRpcError } from "../../runtime-mcp/types";
+import {
+	cancelMCPStream,
+	MCP_MAX_CONTENT_BYTES,
+	MCP_MAX_ERROR_BYTES,
+	MCP_MAX_SSE_BATCH_MESSAGES,
+	MCP_MAX_SSE_REQUEST_MESSAGES,
+	readMCPResponseText,
+} from "../content-limits";
 
 /**
  * HTTP transport for MCP servers.
@@ -73,6 +81,9 @@ export class HttpTransport implements MCPTransport {
 		if (this.#sseConnection) return;
 
 		const sseConnection = new AbortController();
+		const headerController = new AbortController();
+		const headerTimeout = this.config.timeout ?? 30000;
+		const headerTimeoutId = setTimeout(() => headerController.abort(), headerTimeout);
 		this.#sseConnection = sseConnection;
 		const headers: Record<string, string> = {
 			Accept: "text/event-stream",
@@ -88,18 +99,22 @@ export class HttpTransport implements MCPTransport {
 			response = await fetch(this.config.url, {
 				method: "GET",
 				headers,
-				signal: sseConnection.signal,
+				signal: AbortSignal.any([sseConnection.signal, headerController.signal]),
 			});
 		} catch (error) {
 			this.#sseConnection = this.#sseConnection === sseConnection ? null : this.#sseConnection;
-			if (error instanceof Error && error.name !== "AbortError") {
+			if (headerController.signal.aborted && !sseConnection.signal.aborted) {
+				this.onError?.(new Error(`SSE connection timeout after ${headerTimeout}ms`));
+			} else if (error instanceof Error && error.name !== "AbortError") {
 				this.onError?.(error);
 			}
 			return;
+		} finally {
+			clearTimeout(headerTimeoutId);
 		}
 
 		if (response.status === 405 || !response.ok || !response.body) {
-			await response.body?.cancel().catch(() => {});
+			cancelMCPStream(response.body);
 			this.#sseConnection = this.#sseConnection === sseConnection ? null : this.#sseConnection;
 			return;
 		}
@@ -117,8 +132,13 @@ export class HttpTransport implements MCPTransport {
 	}
 	async #readSSEStream(body: ReadableStream<Uint8Array>, signal: AbortSignal): Promise<void> {
 		try {
-			for await (const message of readSseJson<JsonRpcMessage>(body, signal)) {
+			for await (const message of readSseJson<JsonRpcMessage>(body, signal, undefined, {
+				maxEventBytes: MCP_MAX_CONTENT_BYTES,
+			})) {
 				if (!this.#connected) break;
+				if (Array.isArray(message) && message.length > MCP_MAX_SSE_BATCH_MESSAGES) {
+					throw new Error("MCP SSE batch exceeds message limit");
+				}
 				this.#dispatchSSEMessage(message);
 			}
 		} catch (error) {
@@ -221,7 +241,7 @@ export class HttpTransport implements MCPTransport {
 			}
 
 			if (!response.ok) {
-				const text = await response.text();
+				const text = await readMCPResponseText(response, MCP_MAX_ERROR_BYTES, true, operationSignal);
 				const wwwAuthenticate = response.headers.get("WWW-Authenticate");
 				const mcpAuthServer = response.headers.get("Mcp-Auth-Server");
 				const authHints = [
@@ -245,7 +265,9 @@ export class HttpTransport implements MCPTransport {
 			if (!response.body) {
 				throw new MCPExpectedFailure();
 			}
-			const parsedResult = await response.json();
+			const parsedResult = JSON.parse(
+				await readMCPResponseText(response, MCP_MAX_CONTENT_BYTES, false, operationSignal),
+			) as unknown;
 
 			if (
 				typeof parsedResult !== "object" ||
@@ -293,6 +315,7 @@ export class HttpTransport implements MCPTransport {
 
 		const { promise, resolve, reject } = Promise.withResolvers<T>();
 		let captured = false;
+		let messageCount = 0;
 
 		// Drain this per-request SSE response from a single iterator. Once the
 		// matching response arrives, resolve/reject and abort the reader so the
@@ -304,8 +327,20 @@ export class HttpTransport implements MCPTransport {
 		this.#streamControllers.add(drainController);
 		const drain = async (): Promise<void> => {
 			try {
-				for await (const raw of readSseJson<JsonRpcMessage | JsonRpcMessage[]>(response.body!, operationSignal)) {
+				for await (const raw of readSseJson<JsonRpcMessage | JsonRpcMessage[]>(
+					response.body!,
+					operationSignal,
+					undefined,
+					{
+						maxEventBytes: MCP_MAX_CONTENT_BYTES,
+						maxTotalBytes: MCP_MAX_CONTENT_BYTES,
+					},
+				)) {
 					const messages = Array.isArray(raw) ? raw : [raw];
+					if (messages.length > MCP_MAX_SSE_BATCH_MESSAGES) throw new Error("MCP SSE batch exceeds message limit");
+					messageCount += messages.length;
+					if (messageCount > MCP_MAX_SSE_REQUEST_MESSAGES)
+						throw new Error("MCP SSE response exceeds message limit");
 					for (const message of messages) {
 						if (
 							!captured &&
@@ -352,7 +387,7 @@ export class HttpTransport implements MCPTransport {
 			} finally {
 				clearTimeout(timeoutId);
 				this.#streamControllers.delete(drainController);
-				await response.body?.cancel().catch(() => {});
+				cancelMCPStream(response.body);
 			}
 		};
 
@@ -396,7 +431,7 @@ export class HttpTransport implements MCPTransport {
 			});
 			// Retry once on auth failure if onAuthError is wired
 			if (this.onAuthError && (resp.status === 401 || resp.status === 403)) {
-				await resp.body?.cancel();
+				cancelMCPStream(resp.body);
 				const newHeaders = await this.onAuthError();
 				if (newHeaders) {
 					this.config.headers ??= {};
@@ -408,11 +443,11 @@ export class HttpTransport implements MCPTransport {
 						body: JSON.stringify(body),
 						signal: AbortSignal.timeout(this.config.timeout ?? 30000),
 					});
-					await retry.body?.cancel();
+					cancelMCPStream(retry.body);
 					return;
 				}
 			}
-			await resp.body?.cancel();
+			cancelMCPStream(resp.body);
 		} catch {
 			// Best-effort response delivery — server may have disconnected
 		}
@@ -452,11 +487,9 @@ export class HttpTransport implements MCPTransport {
 				signal: abortController.signal,
 			});
 
-			clearTimeout(timeoutId);
-
 			// 202 Accepted is success for notifications
 			if (!response.ok && response.status !== 202) {
-				const text = await response.text();
+				const text = await readMCPResponseText(response, MCP_MAX_ERROR_BYTES, true, abortController.signal);
 				throw new Error(`HTTP ${response.status}: ${text}`);
 			}
 
@@ -472,14 +505,15 @@ export class HttpTransport implements MCPTransport {
 				const reader = this.#readSSEStream(response.body, AbortSignal.any(signals));
 				this.#trackReader(reader, streamController);
 			} else {
-				await response.body?.cancel();
+				cancelMCPStream(response.body);
 			}
 		} catch (error) {
-			clearTimeout(timeoutId);
 			if (error instanceof Error && error.name === "AbortError") {
 				throw new MCPExpectedFailure(new Error(`Notify timeout after ${timeout}ms`));
 			}
 			throw error instanceof MCPExpectedFailure ? error : new MCPExpectedFailure(error);
+		} finally {
+			clearTimeout(timeoutId);
 		}
 	}
 

package/src/sdk/bus/chat-daemon-control.ts

@@ -25,10 +25,14 @@ export type ChatDaemonAction = "stop" | "reload";
  * Operational generations of the Discord/Slack daemon lifecycle contracts.
  * These are intentionally separate from per-session endpoint generations.
  * Generation 6 carries the retained managed filesystem authority boundary.
+ * Generation 7 restores macOS daemon signaling (kill(2) with a start-time
+ * incarnation recheck) so a live/hung owner can be replaced without an external
+ * `kill -9`. Generation 8 adopts Windows expected-identity ACL verification and
+ * repair for shared native authority.
  */
 export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
-	discord: 6,
-	slack: 6,
+	discord: 8,
+	slack: 8,
 };
 
 export function chatDaemonGeneration(kind: ChatDaemonKind): number {
@@ -166,18 +170,27 @@ export interface ChatDaemonProcessReference {
 }
 
 function defaultProcessReference(pid: number, platform = os.platform()): ChatDaemonProcessReference | undefined {
-	// Process.fromPid on Darwin still resolves identity and then signals a numeric
-	// PID. A process can exit and its PID be reused in that interval, so daemon
-	// control must not use it as privileged signaling authority.
-	if (platform === "darwin") return undefined;
 	try {
 		const processRef = Process.fromPid(pid);
 		if (!processRef || !hasProcessIncarnationAuthority(processRef.incarnation)) return undefined;
+		const incarnation = processRef.incarnation;
 		return {
-			incarnation: processRef.incarnation,
+			incarnation,
 			signalRoot: signal => {
 				const nativeSignal = os.constants.signals[signal];
 				if (nativeSignal === undefined) throw new Error(`Unsupported signal: ${signal}`);
+				// macOS exposes no pidfd and the native signal_root is a no-op there, so
+				// the daemon control plane previously had NO way to signal a live owner —
+				// every stop/reload of a live/hung daemon refused, and only an external
+				// `kill -9` could recover it. Signal by numeric PID via kill(2), but
+				// re-read the immutable start-time incarnation immediately beforehand so a
+				// PID that exited and was reused since capture is never signaled.
+				if (platform === "darwin") {
+					const current = Process.fromPid(pid) as { incarnation?: unknown } | null;
+					if (!current || current.incarnation !== incarnation) throw new Error("Pinned process is already gone");
+					process.kill(pid, signal);
+					return;
+				}
 				const rootProcess = processRef as typeof processRef & { signalRoot(signal: number): boolean };
 				if (!rootProcess.signalRoot(nativeSignal)) throw new Error("Pinned process is already gone");
 			},

package/src/sdk/bus/index.ts

@@ -30,7 +30,7 @@ import { promisify } from "node:util";
 import { ThinkingLevel } from "@gajae-code/agent-core";
 import type { ImageContent, TextContent, Tool } from "@gajae-code/ai";
 import { NotificationServer, nativeBuildInfo } from "@gajae-code/natives";
-import { logger, postmortem, prompt, VERSION } from "@gajae-code/utils";
+import { logger, postmortem, VERSION } from "@gajae-code/utils";
 import { Settings } from "../../config/settings";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "../../extensibility/extensions";
 import { toAgentWireEventPayload } from "../../modes/shared/agent-wire/event-envelope";
@@ -40,7 +40,6 @@ import {
 	type WorkflowGateTerminalController,
 	type WorkflowGateTerminalProof,
 } from "../../modes/shared/agent-wire/workflow-gate-broker";
-import btwUserPrompt from "../../prompts/system/btw-user.md" with { type: "text" };
 import type { AgentSessionEvent } from "../../session/agent-session";
 import { parseThinkingLevel } from "../../thinking";
 import type {
@@ -1926,8 +1925,10 @@ function sdkControlSurface(
 		}
 		return "unknown";
 	};
-	const sendSteer = (text: string) => {
-		api.sendUserMessage(text, { deliverAs: "steer" });
+	const sendSteer = async (text: string) => {
+		// Await admission so a rejection (e.g. handoff in progress) surfaces as a
+		// control error instead of a false `accepted: true`.
+		await api.sendUserMessage(text, { deliverAs: "steer" });
 		return { commandId: crypto.randomUUID(), accepted: true };
 	};
 	const resolveModel = (id: string) => {
@@ -2776,7 +2777,7 @@ export function createNotificationsExtension(
 		sdkHostModeSupported?: boolean;
 
 		onSdkRequest?: (kind: "control" | "query", connectionId: string, frame: Record<string, unknown>) => void;
-		runEphemeralTurn?: (promptText: string, signal: AbortSignal) => Promise<{ replyText: string }>;
+		runBtwTurn?: (question: string, signal: AbortSignal) => Promise<{ replyText: string }>;
 		/** Observes settlement of optional session-branch startup after reconciliation completes. */
 		onBranchStartupSettled?: (receipt: { sessionId: string; status: SessionStartResult["status"] }) => void;
 		readNotificationFile?: (path: string) => Promise<Buffer>;
@@ -3585,10 +3586,10 @@ export function createNotificationsExtension(
 		};
 
 		const ephemeralTurns = new EphemeralTurnHost(sendSdkFrame, async (question, signal) => {
-			if (!options.runEphemeralTurn) throw new Error("Ephemeral turns are unavailable.");
+			if (!options.runBtwTurn) throw new Error("Ephemeral turns are unavailable.");
 			const generation = initializedRuntime.policyGeneration;
 			if (initializedRuntime.policySuspended) throw new Error("Notification policy is provisional.");
-			const result = await options.runEphemeralTurn(prompt.render(btwUserPrompt, { question }), signal);
+			const result = await options.runBtwTurn(question, signal);
 			if (
 				initializedRuntime.policySuspended ||
 				initializedRuntime.policyGeneration !== generation ||

package/src/sdk/bus/lifecycle-commands.ts

@@ -238,11 +238,12 @@ function isSafeBranch(value: string): boolean {
 /**
  * Map a lifecycle response/error to a user-facing Telegram message (G010).
  *
- * Only derives text from sessionId, mode, reason, a safe message, and candidate
- * {sessionId,path} — never a token or prompt. Each error reason gets tailored,
- * actionable copy; an "in progress" pending response is surfaced distinctly.
+ * Only derives text from sessionId, mode, reason, a safe message, the originating
+ * lifecycle verb, and candidate {sessionId,path} — never a token or prompt. Each
+ * error reason gets tailored, actionable copy; an "in progress" pending response
+ * is surfaced distinctly.
  */
-export function formatLifecycleOutcome(r: SessionLifecycleResponse): string {
+export function formatLifecycleOutcome(r: SessionLifecycleResponse, verb?: LifecycleCommandVerb): string {
 	switch (r.type) {
 		case "session_create_response":
 			return `\u{1f680} Launching session ${r.sessionId} in tmux. It will appear once ready \u2014 check /session_recent.`;
@@ -282,9 +283,17 @@ export function formatLifecycleOutcome(r: SessionLifecycleResponse): string {
 		case "unsupported_platform":
 			return "Remote session lifecycle is unavailable on this psmux host because GJC cannot prove immutable session identity. No lifecycle action was performed. Use a local GJC terminal with a supported tmux provider.";
 		case "terminal_uncertain":
-			return /in progress/i.test(r.message)
-				? "\u23f3 That request is already in progress \u2014 hold on."
-				: "\u26a0\ufe0f Outcome uncertain. Check /session_recent before retrying so you don't double-spawn.";
+			if (/in progress/i.test(r.message)) return "\u23f3 That request is already in progress \u2014 hold on.";
+			switch (verb) {
+				case "session_create":
+					return "\u26a0\ufe0f Create outcome uncertain. The session may already be starting \u2014 check /session_recent before retrying to avoid starting it twice.";
+				case "session_close":
+					return "\u26a0\ufe0f Close outcome uncertain. The session may already be closed \u2014 check /session_recent before retrying.";
+				case "session_resume":
+					return "\u26a0\ufe0f Resume outcome uncertain. The session may already be reattached or restarting \u2014 check /session_recent before retrying.";
+				default:
+					return "\u26a0\ufe0f Outcome uncertain. Check /session_recent before retrying.";
+			}
 		default:
 			return `\u26a0\ufe0f ${r.reason}: ${r.message}`;
 	}