@gajae-code/coding-agent 0.5.4 → 0.6.1

package/src/modes/rpc/rpc-client.ts

@@ -35,6 +35,14 @@ type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : n
 type RpcCommandBody = DistributiveOmit<RpcCommand, "id">;
 
 export interface RpcClientOptions {
+	/** Dial an existing Unix-domain socket instead of spawning a stdio child. */
+	socketPath?: string;
+	/** Explicit transport selector; defaults to uds when socketPath is set, otherwise stdio. */
+	transport?: "stdio" | "uds";
+	/** Observe transport close/error state. */
+	onTransportClose?: (error?: Error) => void;
+	/** Alias for transport close/error observation. */
+	onTransportError?: (error: Error) => void;
 	/** Path to the CLI entry point (default: searches for dist/cli.js) */
 	cliPath?: string;
 	/** Working directory for the agent */
@@ -176,62 +184,43 @@ function normalizeToolResult<TDetails>(result: RpcClientToolResult<TDetails>): A
 // RPC Client
 // ============================================================================
 
-export class RpcClient {
+export interface RpcTransport {
+	readonly kind: "stdio" | "uds";
+	start(onFrame: (frame: unknown) => void, onClose: (error?: Error) => void): Promise<void>;
+	write(frame: unknown): void;
+	stop(): void;
+	getStderr(): string;
+}
+
+class StdioRpcTransport implements RpcTransport {
+	readonly kind = "stdio" as const;
 	#process: ptree.ChildProcess | null = null;
-	#eventListeners: RpcEventListener[] = [];
-	#pendingRequests: Map<string, { resolve: (response: RpcResponse) => void; reject: (error: Error) => void }> =
-		new Map();
-	#customTools: RpcClientCustomTool[] = [];
-	#pendingHostToolCalls = new Map<string, { controller: AbortController }>();
-	#requestId = 0;
-	#extensionUiListeners: Set<(req: RpcExtensionUIRequest) => void> = new Set();
-	#workflowGateListeners: Set<(gate: RpcWorkflowGate) => void> = new Set();
 	#abortController = new AbortController();
+	#startupStderrPromise: Promise<string> = Promise.resolve("");
 
-	constructor(private options: RpcClientOptions = {}) {
-		this.#customTools = [...(options.customTools ?? [])];
-	}
-
-	/**
-	 * Start the RPC agent process.
-	 */
-	async start(): Promise<void> {
-		if (this.#process) {
-			throw new Error("Client already started");
-		}
+	constructor(private readonly options: RpcClientOptions) {}
 
+	async start(onFrame: (frame: unknown) => void, onClose: (error?: Error) => void): Promise<void> {
+		if (this.#process) throw new Error("Transport already started");
+		this.#abortController = new AbortController();
 		const cliPath = this.options.cliPath ?? "dist/cli.js";
 		const args = ["--mode", "rpc"];
-
-		if (this.options.provider) {
-			args.push("--provider", this.options.provider);
-		}
-		if (this.options.model) {
-			args.push("--model", this.options.model);
-		}
-		if (this.options.sessionDir) {
-			args.push("--session-dir", this.options.sessionDir);
-		}
-		if (this.options.args) {
-			args.push(...this.options.args);
-		}
-
+		if (this.options.provider) args.push("--provider", this.options.provider);
+		if (this.options.model) args.push("--model", this.options.model);
+		if (this.options.sessionDir) args.push("--session-dir", this.options.sessionDir);
+		if (this.options.args) args.push(...this.options.args);
 		this.#process = ptree.spawn(["bun", cliPath, ...args], {
 			cwd: this.options.cwd,
 			env: { ...Bun.env, ...this.options.env },
 			stdin: "pipe",
 			stderr: "full",
 		});
-		const startupStderrPromise = this.#process.stderr
+		this.#startupStderrPromise = this.#process.stderr
 			? new Response(this.#process.stderr).text().catch(() => "")
 			: Promise.resolve("");
-		const getStartupStderr = async () => this.#process?.peekStderr() || (await startupStderrPromise);
-
-		// Wait for the "ready" signal or process exit
+		const getStartupStderr = async () => this.#process?.peekStderr() || (await this.#startupStderrPromise);
 		const { promise: readyPromise, resolve: readyResolve, reject: readyReject } = Promise.withResolvers<void>();
 		let readySettled = false;
-
-		// Process lines in background, intercepting the ready signal
 		const lines = readJsonl(this.#process.stdout, this.#abortController.signal);
 		void (async () => {
 			for await (const line of lines) {
@@ -240,10 +229,8 @@ export class RpcClient {
 					readyResolve();
 					continue;
 				}
-				this.#handleLine(line);
+				onFrame(line);
 			}
-			// Stream ended without ready signal — process exited. Wait for the
-			// managed process wrapper so stderr is fully drained before reporting.
 			if (!readySettled) {
 				const proc = this.#process;
 				const exitCode = proc ? await proc.exited.catch(() => proc.exitCode ?? -1) : undefined;
@@ -256,40 +243,179 @@ export class RpcClient {
 						),
 					);
 				}
+			} else {
+				onClose(new Error("RPC stdio transport closed"));
 			}
 		})().catch((err: Error) => {
 			if (!readySettled) {
 				readySettled = true;
 				readyReject(err);
-			}
+			} else onClose(err);
 		});
-
-		// Also race against process exit (in case stdout closes before we read it)
 		void this.#process.exited.then(async (exitCode: number) => {
 			if (!readySettled) {
 				const stderr = await getStartupStderr();
 				if (readySettled) return;
 				readySettled = true;
 				readyReject(new Error(`Agent process exited with code ${exitCode}. Stderr: ${stderr}`));
-			}
+			} else onClose(new Error(`RPC stdio transport exited with code ${exitCode}`));
 		});
-
-		// Timeout to prevent hanging forever
-		const readyTimeout = this.#startTimeout(30000, () => {
+		const readyTimeout = setTimeout(() => {
 			if (readySettled) return;
 			readySettled = true;
-			void getStartupStderr().then(stderr => {
-				readyReject(new Error(`Timeout waiting for agent to become ready. Stderr: ${stderr}`));
-			});
-		});
+			void getStartupStderr().then(stderr =>
+				readyReject(new Error(`Timeout waiting for agent to become ready. Stderr: ${stderr}`)),
+			);
+		}, 30_000);
+		readyTimeout.unref();
+		try {
+			await readyPromise;
+		} finally {
+			clearTimeout(readyTimeout);
+		}
+	}
+
+	write(frame: unknown): void {
+		if (!this.#process?.stdin) throw new Error("Client not started");
+		const stdin = this.#process.stdin as import("bun").FileSink;
+		stdin.write(`${JSON.stringify(frame)}\n`);
+		const flushResult = stdin.flush();
+		if (flushResult instanceof Promise) void flushResult;
+	}
+
+	stop(): void {
+		if (!this.#process) return;
+		this.#process.kill();
+		this.#abortController.abort();
+		this.#process = null;
+	}
 
+	getStderr(): string {
+		return this.#process?.peekStderr() ?? "";
+	}
+}
+
+class UdsRpcTransport implements RpcTransport {
+	readonly kind = "uds" as const;
+	#socket: import("bun").Socket | null = null;
+	#buf = "";
+	#decoder = new TextDecoder("utf-8", { fatal: false });
+	constructor(private readonly socketPath: string) {}
+
+	async start(onFrame: (frame: unknown) => void, onClose: (error?: Error) => void): Promise<void> {
+		const { promise: readyPromise, resolve: readyResolve, reject: readyReject } = Promise.withResolvers<void>();
+		let readySettled = false;
+		this.#socket = await Bun.connect({
+			unix: this.socketPath,
+			socket: {
+				data: (_socket, data) => {
+					this.#buf += this.#decoder.decode(data);
+					while (true) {
+						const nl = this.#buf.indexOf("\n");
+						if (nl < 0) break;
+						const text = this.#buf.slice(0, nl).trim();
+						this.#buf = this.#buf.slice(nl + 1);
+						if (!text) continue;
+						let frame: unknown;
+						try {
+							frame = JSON.parse(text);
+						} catch (err) {
+							onClose(err instanceof Error ? err : new Error(String(err)));
+							continue;
+						}
+						if (!readySettled && isRecord(frame) && frame.type === "ready") {
+							readySettled = true;
+							readyResolve();
+							continue;
+						}
+						onFrame(frame);
+					}
+				},
+				close: () => {
+					if (!readySettled) {
+						readySettled = true;
+						readyReject(new Error(`RPC UDS transport closed before ready: ${this.socketPath}`));
+					} else onClose(new Error(`RPC UDS transport closed: ${this.socketPath}`));
+				},
+				error: (_socket, error) => {
+					const err = error instanceof Error ? error : new Error(String(error));
+					if (!readySettled) {
+						readySettled = true;
+						readyReject(err);
+					} else onClose(err);
+				},
+			},
+		});
+		const readyTimeout = setTimeout(() => {
+			if (readySettled) return;
+			readySettled = true;
+			readyReject(new Error(`Timeout waiting for RPC UDS ready frame: ${this.socketPath}`));
+		}, 30_000);
+		readyTimeout.unref();
 		try {
 			await readyPromise;
+		} finally {
+			clearTimeout(readyTimeout);
+		}
+	}
+
+	write(frame: unknown): void {
+		if (!this.#socket) throw new Error("Client not started");
+		this.#socket.write(`${JSON.stringify(frame)}\n`);
+	}
+
+	stop(): void {
+		this.#socket?.end();
+		this.#socket = null;
+	}
+
+	getStderr(): string {
+		return "";
+	}
+}
+
+export class RpcClient {
+	#transport: RpcTransport | null = null;
+	#transportClosed = false;
+	#eventListeners: RpcEventListener[] = [];
+	#pendingRequests: Map<string, { resolve: (response: RpcResponse) => void; reject: (error: Error) => void }> =
+		new Map();
+	#customTools: RpcClientCustomTool[] = [];
+	#pendingHostToolCalls = new Map<string, { controller: AbortController }>();
+	#requestId = 0;
+	#extensionUiListeners: Set<(req: RpcExtensionUIRequest) => void> = new Set();
+	#workflowGateListeners: Set<(gate: RpcWorkflowGate) => void> = new Set();
+
+	constructor(private options: RpcClientOptions = {}) {
+		this.#customTools = [...(options.customTools ?? [])];
+	}
+
+	/**
+	 * Start the RPC agent process.
+	 */
+	async start(): Promise<void> {
+		if (this.#transport) {
+			throw new Error("Client already started");
+		}
+		this.#transportClosed = false;
+		const transportKind = this.options.transport ?? (this.options.socketPath ? "uds" : "stdio");
+		if (transportKind === "uds") {
+			if (!this.options.socketPath) throw new Error("socketPath is required for uds transport");
+			this.#transport = new UdsRpcTransport(this.options.socketPath);
+		} else {
+			this.#transport = new StdioRpcTransport(this.options);
+		}
+		try {
+			await this.#transport.start(
+				line => this.#handleLine(line),
+				error => this.#handleTransportClose(error),
+			);
 			if (this.#customTools.length > 0) {
 				await this.setCustomTools(this.#customTools);
 			}
-		} finally {
-			clearTimeout(readyTimeout);
+		} catch (error) {
+			this.#transport = null;
+			throw error;
 		}
 	}
 
@@ -297,16 +423,11 @@ export class RpcClient {
 	 * Stop the RPC agent process.
 	 */
 	stop() {
-		if (!this.#process) return;
+		if (!this.#transport) return;
 
-		this.#process.kill();
-		this.#abortController.abort();
-		this.#process = null;
-		this.#pendingRequests.clear();
-		for (const pendingCall of this.#pendingHostToolCalls.values()) {
-			pendingCall.controller.abort();
-		}
-		this.#pendingHostToolCalls.clear();
+		this.#transport.stop();
+		this.#transport = null;
+		this.#rejectAllPending(new Error("RPC client stopped"));
 	}
 
 	/**
@@ -367,6 +488,29 @@ export class RpcClient {
 		};
 	}
 
+	/** Respond to an extension UI request over the live transport. */
+	respondExtensionUi(response: import("./rpc-types").RpcExtensionUIResponse): void {
+		this.#writeFrame(response);
+	}
+
+	/** Observe transport close/error notifications. */
+	onTransportError(listener: (error: Error) => void): () => void {
+		const previousClose = this.options.onTransportClose;
+		const previousError = this.options.onTransportError;
+		this.options.onTransportClose = error => {
+			previousClose?.(error);
+			listener(error ?? new Error("RPC transport closed"));
+		};
+		this.options.onTransportError = error => {
+			previousError?.(error);
+			listener(error);
+		};
+		return () => {
+			this.options.onTransportClose = previousClose;
+			this.options.onTransportError = previousError;
+		};
+	}
+
 	/**
 	 * Enter unattended mode by declaring budget + scopes + action allowlist.
 	 * Returns the accepted declaration, or rejects (fail-closed) on refusal.
@@ -380,7 +524,7 @@ export class RpcClient {
 	 * Get collected stderr output (useful for debugging).
 	 */
 	getStderr(): string {
-		return this.#process?.peekStderr() ?? "";
+		return this.#transport?.getStderr() ?? "";
 	}
 
 	#startTimeout(timeoutMs: number, onTimeout: () => void): NodeJS.Timeout {
@@ -448,6 +592,12 @@ export class RpcClient {
 		return this.#getData(response);
 	}
 
+	/** Return unresolved workflow gates persisted by the RPC session. */
+	async getPendingWorkflowGates(): Promise<RpcWorkflowGate[]> {
+		const response = await this.#send({ type: "get_pending_workflow_gates" });
+		return this.#getData<{ gates: RpcWorkflowGate[] }>(response).gates;
+	}
+
 	/**
 	 * Set model by provider and ID.
 	 */
@@ -658,7 +808,7 @@ export class RpcClient {
 	 */
 	async setCustomTools(tools: RpcClientCustomTool[]): Promise<string[]> {
 		this.#customTools = [...tools];
-		if (!this.#process) {
+		if (!this.#transport) {
 			return this.#customTools.map(tool => tool.name);
 		}
 		const definitions: RpcHostToolDefinition[] = this.#customTools.map(tool => ({
@@ -696,7 +846,7 @@ export class RpcClient {
 			if (settled) return;
 			settled = true;
 			unsubscribe();
-			reject(new Error(`Timeout waiting for agent to become idle. Stderr: ${this.#process?.peekStderr() ?? ""}`));
+			reject(new Error(`Timeout waiting for agent to become idle. Stderr: ${this.#transport?.getStderr() ?? ""}`));
 		});
 		return promise;
 	}
@@ -722,7 +872,7 @@ export class RpcClient {
 			if (settled) return;
 			settled = true;
 			unsubscribe();
-			reject(new Error(`Timeout collecting events. Stderr: ${this.#process?.peekStderr() ?? ""}`));
+			reject(new Error(`Timeout collecting events. Stderr: ${this.#transport?.getStderr() ?? ""}`));
 		});
 		return promise;
 	}
@@ -786,7 +936,7 @@ export class RpcClient {
 	}
 
 	#send(command: RpcCommandBody, timeoutMs = 30_000): Promise<RpcResponse> {
-		if (!this.#process?.stdin) {
+		if (!this.#transport || this.#transportClosed) {
 			throw new Error("Client not started");
 		}
 
@@ -799,7 +949,7 @@ export class RpcClient {
 			this.#pendingRequests.delete(id);
 			settled = true;
 			reject(
-				new Error(`Timeout waiting for response to ${command.type}. Stderr: ${this.#process?.peekStderr() ?? ""}`),
+				new Error(`Timeout waiting for response to ${command.type}. Stderr: ${this.#transport?.getStderr() ?? ""}`),
 			);
 		});
 
@@ -884,22 +1034,42 @@ export class RpcClient {
 	}
 
 	#writeFrame(
-		frame: RpcCommand | RpcWorkflowGateResponse | RpcHostToolResult | RpcHostToolUpdate,
+		frame:
+			| RpcCommand
+			| RpcWorkflowGateResponse
+			| RpcHostToolResult
+			| RpcHostToolUpdate
+			| import("./rpc-types").RpcExtensionUIResponse,
 		onError?: (error: Error) => void,
 	): void {
-		if (!this.#process?.stdin) {
+		if (!this.#transport || this.#transportClosed) {
 			throw new Error("Client not started");
 		}
-		const stdin = this.#process.stdin as import("bun").FileSink;
-		stdin.write(`${JSON.stringify(frame)}\n`);
-		const flushResult = stdin.flush();
-		if (flushResult instanceof Promise) {
-			flushResult.catch((err: Error) => {
-				onError?.(err);
-			});
+		try {
+			this.#transport.write(frame);
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			onError?.(error);
+			this.#handleTransportClose(error);
 		}
 	}
 
+	#handleTransportClose(error?: Error): void {
+		if (this.#transportClosed) return;
+		this.#transportClosed = true;
+		const closeError = error ?? new Error("RPC transport closed");
+		this.options.onTransportClose?.(closeError);
+		this.options.onTransportError?.(closeError);
+		this.#rejectAllPending(closeError);
+	}
+
+	#rejectAllPending(error: Error): void {
+		for (const pending of this.#pendingRequests.values()) pending.reject(error);
+		this.#pendingRequests.clear();
+		for (const pendingCall of this.#pendingHostToolCalls.values()) pendingCall.controller.abort();
+		this.#pendingHostToolCalls.clear();
+	}
+
 	#getData<T>(response: RpcResponse): T {
 		if (!response.success) {
 			const errorResponse = response as Extract<RpcResponse, { success: false }>;

package/src/modes/rpc/rpc-mode.ts

@@ -11,7 +11,6 @@
  * - Extension UI: Extension UI requests are emitted, client responds with extension_ui_response
  */
 
-import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { $pickenv, logger, readLines, Snowflake } from "@gajae-code/utils";
 import type {
@@ -31,6 +30,7 @@ import { modelSupportsTokenCostMetrics, UnattendedSessionControlPlane } from "..
 import { FileGateStore } from "../shared/agent-wire/workflow-gate-broker";
 import { isRpcHostToolResult, isRpcHostToolUpdate, RpcHostToolBridge } from "./host-tools";
 import { isRpcHostUriResult, RpcHostUriBridge } from "./host-uris";
+import { prepareRpcSocketPath, verifyRpcSocketAfterListen } from "./rpc-socket-security";
 import type {
 	RpcCommand,
 	RpcExtensionUIRequest,
@@ -128,6 +128,7 @@ export const RPC_SAFE_READ_CONTROL_COMMANDS: ReadonlySet<RpcCommand["type"]> = n
 	"get_last_assistant_text",
 	"get_messages",
 	"get_login_providers",
+	"get_pending_workflow_gates",
 ]);
 
 /** True when a command may bypass the ordered serial chain and run immediately. */
@@ -725,16 +726,7 @@ export async function runRpcMode(
 	// get_state/get_messages on reconnect).
 	if (options?.listen) {
 		const socketPath = options.listen;
-		await fs.mkdir(path.dirname(socketPath), { recursive: true }).catch(() => {});
-		// Refuse to clobber a live previous owner: probe the path first and only
-		// unlink a stale endpoint. A second `--listen` on the same path must not
-		// remove the socket another running server is still serving (#606).
-		// Unexpected probe failures are treated as alive, so this also refuses
-		// rather than unlinking a socket path we could not safely classify.
-		if (await isUnixSocketAlive(socketPath)) {
-			throw new RpcListenRefusedError(socketPath);
-		}
-		await fs.rm(socketPath, { force: true }).catch(() => {});
+		await prepareRpcSocketPath(socketPath);
 		await registerRpcSession({
 			sessionId: session.sessionId,
 			pid: process.pid,
@@ -748,7 +740,7 @@ export async function runRpcMode(
 		const noopSink = (_line: string): void => {};
 		let currentSocket: object | undefined;
 		let buf = "";
-		Bun.listen({
+		const server = Bun.listen({
 			unix: socketPath,
 			socket: {
 				open(socket) {
@@ -779,6 +771,8 @@ export async function runRpcMode(
 				error() {},
 			},
 		});
+		await verifyRpcSocketAfterListen(socketPath);
+		void server;
 
 		const onSignal = (): void => {
 			void shutdown(0, "RPC socket server signal");

package/src/modes/rpc/rpc-socket-security.ts

@@ -0,0 +1,103 @@
+import * as fs from "node:fs/promises";
+import * as net from "node:net";
+import * as path from "node:path";
+
+export class RpcSocketSecurityError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "RpcSocketSecurityError";
+	}
+}
+
+const unsafeBits = 0o077;
+
+function currentUid(): number | undefined {
+	return typeof process.getuid === "function" ? process.getuid() : undefined;
+}
+
+function assertOwned(stat: { uid: number }, target: string): void {
+	const uid = currentUid();
+	if (uid !== undefined && stat.uid !== uid) {
+		throw new RpcSocketSecurityError(`${target} is owned by uid ${stat.uid}, expected ${uid}`);
+	}
+}
+
+function assertPrivateMode(mode: number, target: string): void {
+	if ((mode & unsafeBits) !== 0) throw new RpcSocketSecurityError(`${target} has group/other permissions`);
+}
+
+export async function prepareRpcSocketPath(socketPath: string): Promise<void> {
+	const parent = path.dirname(socketPath);
+	let parentStat: import("node:fs").Stats;
+	try {
+		parentStat = await fs.lstat(parent);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+		await fs.mkdir(parent, { recursive: true, mode: 0o700 });
+		parentStat = await fs.lstat(parent);
+	}
+	if (parentStat.isSymbolicLink()) throw new RpcSocketSecurityError(`RPC socket parent is a symlink: ${parent}`);
+	if (!parentStat.isDirectory()) throw new RpcSocketSecurityError(`RPC socket parent is not a directory: ${parent}`);
+	assertOwned(parentStat, parent);
+	assertPrivateMode(parentStat.mode, parent);
+
+	let existing: import("node:fs").Stats;
+	try {
+		existing = await fs.lstat(socketPath);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
+		throw err;
+	}
+	if (existing.isSymbolicLink()) throw new RpcSocketSecurityError(`RPC socket path is a symlink: ${socketPath}`);
+	assertOwned(existing, socketPath);
+	if (!existing.isSocket()) throw new RpcSocketSecurityError(`RPC socket path is not a socket: ${socketPath}`);
+	assertPrivateMode(existing.mode, socketPath);
+	if (await probeUnixSocketAlive(socketPath)) {
+		throw new RpcSocketSecurityError(`RPC socket path is live: ${socketPath}`);
+	}
+	await fs.unlink(socketPath);
+}
+
+export async function assertSafeClientSocket(socketPath: string): Promise<void> {
+	const parent = path.dirname(socketPath);
+	const parentStat = await fs.lstat(parent);
+	if (parentStat.isSymbolicLink()) throw new RpcSocketSecurityError(`RPC socket parent is a symlink: ${parent}`);
+	if (!parentStat.isDirectory()) throw new RpcSocketSecurityError(`RPC socket parent is not a directory: ${parent}`);
+	assertOwned(parentStat, parent);
+	assertPrivateMode(parentStat.mode, parent);
+
+	const socketStat = await fs.lstat(socketPath);
+	if (socketStat.isSymbolicLink()) throw new RpcSocketSecurityError(`RPC socket path is a symlink: ${socketPath}`);
+	assertOwned(socketStat, socketPath);
+	if (!socketStat.isSocket()) throw new RpcSocketSecurityError(`RPC socket path is not a socket: ${socketPath}`);
+	assertPrivateMode(socketStat.mode, socketPath);
+}
+
+export async function verifyRpcSocketAfterListen(socketPath: string): Promise<void> {
+	await fs.chmod(socketPath, 0o600);
+	const st = await fs.lstat(socketPath);
+	if (st.isSymbolicLink()) throw new RpcSocketSecurityError(`RPC socket path became a symlink: ${socketPath}`);
+	if (!st.isSocket()) throw new RpcSocketSecurityError(`RPC socket path is not a socket after listen: ${socketPath}`);
+	assertOwned(st, socketPath);
+	assertPrivateMode(st.mode, socketPath);
+}
+
+export function probeUnixSocketAlive(socketPath: string): Promise<boolean> {
+	return new Promise((resolve, reject) => {
+		const socket = net.createConnection({ path: socketPath });
+		let settled = false;
+		const settle = (value: boolean) => {
+			if (settled) return;
+			settled = true;
+			socket.destroy();
+			resolve(value);
+		};
+		socket.once("connect", () => settle(true));
+		socket.once("error", err => {
+			const code = (err as NodeJS.ErrnoException).code;
+			if (code === "ENOENT" || code === "ECONNREFUSED") settle(false);
+			else reject(err);
+		});
+		socket.setTimeout(1000, () => reject(new RpcSocketSecurityError(`timed out probing ${socketPath}`)));
+	});
+}

package/src/modes/rpc/rpc-types.ts

@@ -32,6 +32,7 @@ export type RpcCommand =
 	| { id?: string; type: "set_todos"; phases: TodoPhase[] }
 	| { id?: string; type: "set_host_tools"; tools: RpcHostToolDefinition[] }
 	| { id?: string; type: "set_host_uri_schemes"; schemes: RpcHostUriSchemeDefinition[] }
+	| { id?: string; type: "get_pending_workflow_gates" }
 
 	// Model
 	| { id?: string; type: "set_model"; provider: string; modelId: string }
@@ -132,6 +133,13 @@ export type RpcResponse =
 	| { id?: string; type: "response"; command: "set_todos"; success: true; data: { todoPhases: TodoPhase[] } }
 	| { id?: string; type: "response"; command: "set_host_tools"; success: true; data: { toolNames: string[] } }
 	| { id?: string; type: "response"; command: "set_host_uri_schemes"; success: true; data: { schemes: string[] } }
+	| {
+			id?: string;
+			type: "response";
+			command: "get_pending_workflow_gates";
+			success: true;
+			data: { gates: RpcWorkflowGate[] };
+	  }
 
 	// Model
 	| {
@@ -446,6 +454,8 @@ export interface RpcWorkflowGateOption {
 
 export interface RpcWorkflowGateContext {
 	title?: string;
+	plan?: string;
+	source?: string;
 	prompt?: string;
 	summary?: string;
 	stage_state?: Record<string, unknown>;

package/src/modes/shared/agent-wire/command-dispatch.ts

@@ -45,6 +45,8 @@ export interface RpcUnattendedControlPlane {
 	negotiate(declaration: RpcUnattendedDeclaration): RpcUnattendedAccepted;
 	/** Resolve a pending workflow gate with the agent's answer. */
 	resolveGate(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution>;
+	/** List unresolved durable workflow gates for reconnect replay. */
+	listPendingGates?(): import("../../rpc/rpc-types").RpcWorkflowGate[];
 	isUnattended?(): boolean;
 	preflightCommand?(command: RpcCommand): void;
 	reconcileUsage?(phase?: string): void;
@@ -213,6 +215,11 @@ export async function dispatchRpcCommand(
 				return rpcSuccess(id, "set_host_tools", { toolNames: tools.map(tool => tool.name) });
 			}
 
+			case "get_pending_workflow_gates": {
+				const gates = unattendedControlPlane?.listPendingGates?.() ?? [];
+				return rpcSuccess(id, "get_pending_workflow_gates", { gates });
+			}
+
 			case "set_host_uri_schemes": {
 				try {
 					const schemes = hostUriRegistry.setSchemes(command.schemes);

package/src/modes/shared/agent-wire/command-validation.ts

@@ -118,6 +118,7 @@ export function isRpcCommand(value: unknown): value is RpcCommand {
 		case "get_last_assistant_text":
 		case "get_messages":
 		case "get_login_providers":
+		case "get_pending_workflow_gates":
 			return true;
 		case "abort_and_prompt":
 			return stringField(value, "message") && optionalArray(value.images);