codex-relay 1.4.2 → 1.4.3

package/README.md

@@ -30,14 +30,18 @@ After approval, the phone can list Codex threads, start new work, stream message
 
 ## Shared Terminal and Mobile Sessions
 
-By default, Codex Relay starts a private app-server process. A terminal TUI that was started separately can resume the same saved thread, but it does not receive the relay process's live events.
+On macOS, Codex Relay prefers Codex's shared Unix socket so terminal and mobile clients can follow the same live sessions. If the shared app-server cannot start or initialize, the relay prints a warning and continues with a private app-server.
 
-Opt in to Codex's shared app-server:
+Linux, WSL, and native Windows keep using a private app-server by default. A terminal TUI that was started separately can resume the same saved thread, but it does not receive the relay process's live events.
+
+Require the shared app-server on any platform:
 
 ```sh
 npx codex-relay@latest --shared-app-server
 ```
 
+This explicit mode does not fall back to a private app-server when shared startup fails.
+
 When a shared app-server is already running, the relay attaches to it instead of starting another one. If the relay's own socket connection resets, it reconnects without deliberately stopping the shared app-server.
 
 Then connect a new terminal TUI to the shared app-server. On macOS, Linux, or WSL:
@@ -56,7 +60,7 @@ Pass a thread ID after the remote endpoint to open a specific thread. The relay
 
 Shared mode uses Codex's experimental app-server transport. A directly connected terminal TUI has its own WebSocket connection, which the relay cannot observe or reconnect. If that terminal reports a socket reset while the thread continues on mobile, reconnect it with the matching remote endpoint above and append the thread ID if needed.
 
-Shared mode requires a recent Codex CLI with app-server and `resume --remote` support. It uses a Unix socket on macOS, Linux, and WSL, or a loopback-only WebSocket on Windows. If those features are unavailable, update Codex or omit `--shared-app-server` to keep the existing private mode.
+Shared mode requires a recent Codex CLI with app-server and `resume --remote` support. It uses a Unix socket on macOS, Linux, and WSL, or a loopback-only WebSocket on Windows. If explicit shared mode is unavailable, update Codex or omit `--shared-app-server`. On macOS, set `CODEX_RELAY_APP_SERVER_MODE=stdio` to force private mode instead of using the shared-first default.
 
 ## Background Mode
 
@@ -79,10 +83,10 @@ Print the current pairing QR again:
 npx codex-relay@latest qr
 ```
 
-Stop a background server with the printed process id:
+Stop a background server:
 
 ```sh
-kill -TERM <pid>
+npx codex-relay@latest stop
 ```
 
 ## Commands
@@ -99,11 +103,17 @@ npx codex-relay@latest --bg
 
 Start the relay in the background.
 
+```sh
+npx codex-relay@latest stop
+```
+
+Stop the background relay. Repeating this command is safe when no background server is running.
+
 ```sh
 npx codex-relay@latest --shared-app-server
 ```
 
-Start the relay through Codex's shared app-server socket.
+Require the relay to start through Codex's shared app-server socket.
 
 ```sh
 npx codex-relay@latest qr
@@ -127,17 +137,17 @@ Start the relay and automatically approve mobile pairing requests. Use this only
 
 The relay listens on `0.0.0.0:8787` by default. Configure it with environment variables:
 
-| Variable                               | Purpose                                                                                            |
-| -------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `PORT`                                 | Server port. Defaults to `8787`.                                                                   |
-| `HOST`                                 | Listen host. Defaults to `0.0.0.0`.                                                                |
-| `CODEX_RELAY_WORKSPACE_PATH`           | Workspace path Codex should use. Defaults to the directory where you run `npx codex-relay@latest`. |
-| `CODEX_RELAY_AUTH_DB_PATH`             | Pairing and session database path. Defaults to `.codex-relay/auth.db`.                             |
-| `CODEX_RELAY_APPROVAL_SECRET`          | Secret used by the local approve command. Usually generated automatically.                         |
-| `CODEX_RELAY_DANGEROUSLY_AUTO_APPROVE` | Set to `1` to auto-approve mobile pairing requests. Prefer the CLI flag for local use.             |
-| `CODEX_RELAY_APP_SERVER_MODE`          | Set to `socket` for shared terminal/mobile sessions. Defaults to `stdio`.                          |
-| `CODEX_HOME`                           | Codex home directory, used when reading Codex session metadata.                                    |
-| `CODEX_BIN`                            | Codex CLI executable path.                                                                         |
+| Variable                               | Purpose                                                                                                                                                         |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                                 | Server port. Defaults to `8787`.                                                                                                                                |
+| `HOST`                                 | Listen host. Defaults to `0.0.0.0`.                                                                                                                             |
+| `CODEX_RELAY_WORKSPACE_PATH`           | Workspace path Codex should use. Defaults to the directory where you run `npx codex-relay@latest`.                                                              |
+| `CODEX_RELAY_AUTH_DB_PATH`             | Pairing and session database path. Defaults to `.codex-relay/auth.db`.                                                                                          |
+| `CODEX_RELAY_APPROVAL_SECRET`          | Secret used by the local approve command. Usually generated automatically.                                                                                      |
+| `CODEX_RELAY_DANGEROUSLY_AUTO_APPROVE` | Set to `1` to auto-approve mobile pairing requests. Prefer the CLI flag for local use.                                                                          |
+| `CODEX_RELAY_APP_SERVER_MODE`          | Set to `socket` to require shared mode or `stdio` to require private mode. Unset prefers shared mode with startup fallback on macOS and private mode elsewhere. |
+| `CODEX_HOME`                           | Codex home directory, used when reading Codex session metadata.                                                                                                 |
+| `CODEX_BIN`                            | Codex CLI executable path.                                                                                                                                      |
 
 Examples:
 
@@ -174,7 +184,7 @@ npx codex-relay@latest qr
 Or stop the background process shown by the CLI:
 
 ```sh
-kill -TERM <pid>
+npx codex-relay@latest stop
 ```
 
 If the mobile app cannot connect, confirm that the phone can reach the printed `Mobile:` URL and that the chosen port is not blocked by a firewall.

package/dist/cli.js

@@ -20,6 +20,23 @@ async function readRunningRelayPid(pidPath, options = {}) {
 	const command = await (options.commandReader ?? readProcessCommand)(pid);
 	return command && isRelayProcessCommand(command) ? pid : void 0;
 }
+async function stopRunningRelay(pidPath, options = {}) {
+	const pid = await readRunningRelayPid(pidPath, options);
+	if (!pid) {
+		await rm(pidPath, { force: true });
+		return { kind: "not-running" };
+	}
+	(options.signalProcess ?? signalRelayProcess)(pid);
+	if (!await (options.waitForProcessExit ?? waitForRelayProcessExit)(pid)) return {
+		kind: "timed-out",
+		pid
+	};
+	await rm(pidPath, { force: true });
+	return {
+		kind: "stopped",
+		pid
+	};
+}
 function defaultIsProcessAlive(pid) {
 	try {
 		process.kill(pid, 0);
@@ -28,6 +45,21 @@ function defaultIsProcessAlive(pid) {
 		return false;
 	}
 }
+function signalRelayProcess(pid) {
+	try {
+		process.kill(pid, "SIGTERM");
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ESRCH") return;
+		throw error;
+	}
+}
+async function waitForRelayProcessExit(pid) {
+	for (let attempt = 0; attempt < 100; attempt += 1) {
+		if (!defaultIsProcessAlive(pid)) return true;
+		await setTimeout(50);
+	}
+	return false;
+}
 async function readProcessCommand(pid) {
 	try {
 		const { stdout } = await execFileAsync("ps", [
@@ -48,12 +80,13 @@ function isRelayProcessCommand(command) {
 //#endregion
 //#region src/cli.ts
 const npxCommand = "npx codex-relay@latest";
-const program = new Command().name("codex-relay").description("Run and approve the codex-relay local CLI bridge.").option("--bg", "run the Codex Relay server in the background").option("--debug", "write verbose relay diagnostics to debug.log").option("--shared-app-server", "use a shared Codex app-server socket so terminal and mobile can share live sessions").option("--dangerously-auto-approve", "automatically approve mobile pairing requests without a local approval command").addHelpText("after", `
+const program = new Command().name("codex-relay").description("Run and approve the codex-relay local CLI bridge.").option("--bg", "run the Codex Relay server in the background").option("--debug", "write verbose relay diagnostics to debug.log").option("--shared-app-server", "require a shared Codex app-server so terminal and mobile can share live sessions").option("--dangerously-auto-approve", "automatically approve mobile pairing requests without a local approval command").addHelpText("after", `
 
 Examples:
   ${npxCommand}              Start the relay and print a pairing QR
   ${npxCommand} --shared-app-server Share live sessions with a connected terminal
   ${npxCommand} --bg         Start the relay in the background
+  ${npxCommand} stop         Stop the background relay
   ${npxCommand} qr           Print the current pairing QR
   ${npxCommand} clear        Sign out every paired mobile app
   ${npxCommand} approve CODE Approve a pending mobile pairing request`).action(async (options) => {
@@ -66,6 +99,9 @@ Examples:
 	}
 	await import("./src.js").catch(handleServerStartError);
 });
+program.command("stop").description("Stop the background Codex Relay server.").action(async () => {
+	await stopBackgroundServer();
+});
 program.command("qr").description("Print the current pairing QR for an already running server.").action(async () => {
 	await printPairingQr();
 });
@@ -124,6 +160,7 @@ async function startBackgroundServer() {
 	console.log(`Logs: ${logPath}`);
 	if (process.env.CODEX_RELAY_DEBUG === "1") console.log(`Debug logs: ${debugLogPath}`);
 	console.log(`Print the pairing QR later with: ${npxCommand} qr`);
+	console.log(`Stop the background relay with: ${npxCommand} stop`);
 }
 function backgroundArgs() {
 	return process.argv.slice(2).filter((arg) => arg !== "--bg");
@@ -140,6 +177,27 @@ async function waitForBackgroundPid(child, pidPath) {
 		await setTimeout(100);
 	}
 }
+async function stopBackgroundServer() {
+	printStopResult(await stopRunningRelay(codexRelayDataPath("server.pid")));
+}
+function printStopResult(result) {
+	switch (result.kind) {
+		case "not-running":
+			console.log("No background Codex Relay server is running.");
+			return;
+		case "stopped":
+			console.log(`Stopped codex-relay background server (pid ${result.pid}).`);
+			return;
+		case "timed-out":
+			console.error(`Timed out stopping codex-relay background server (pid ${result.pid}).`);
+			process.exitCode = 1;
+			return;
+		default: return assertNever(result);
+	}
+}
+function assertNever(value) {
+	throw new TypeError(`Unexpected background stop result: ${JSON.stringify(value)}`);
+}
 async function approvePairing(rawCode) {
 	const approvalCode = normalizeApprovalCode(rawCode ?? "");
 	if (!approvalCode) {
@@ -277,7 +335,7 @@ async function handleServerStartError(error) {
 		console.error(`  ${npxCommand} qr`);
 		console.error("");
 		console.error("To stop the background server:");
-		console.error(`  kill -TERM ${existingPid}`);
+		console.error(`  ${npxCommand} stop`);
 		console.error("");
 		console.error(`Logs: ${logPath}`);
 	} else {

package/dist/src.js

@@ -36,16 +36,31 @@ const stdioAppServerArgs = [
 ];
 const sharedWindowsServerUrl = "ws://127.0.0.1:8788";
 const windowsShellExtensions = new Set([".bat", ".cmd"]);
-function resolveCodexAppServerMode(env = process.env) {
+function resolveCodexAppServerMode(input = {}) {
+	const env = input.env ?? process.env;
+	const platform$2 = input.platform ?? platform();
 	const configuredMode = env.CODEX_RELAY_APP_SERVER_MODE?.trim().toLowerCase();
-	if (!configuredMode || configuredMode === "stdio") return "stdio";
-	if (configuredMode === "socket") return "socket";
+	if (!configuredMode) return platform$2 === "darwin" ? {
+		fallbackToStdio: true,
+		mode: "socket"
+	} : {
+		fallbackToStdio: false,
+		mode: "stdio"
+	};
+	if (configuredMode === "stdio") return {
+		fallbackToStdio: false,
+		mode: "stdio"
+	};
+	if (configuredMode === "socket") return {
+		fallbackToStdio: false,
+		mode: "socket"
+	};
 	throw new Error(`Unsupported CODEX_RELAY_APP_SERVER_MODE ${JSON.stringify(configuredMode)}. Expected "stdio" or "socket".`);
 }
 function resolveCodexAppServerSpawn(input = {}) {
-	const platform$2 = input.platform ?? platform();
+	const platform$3 = input.platform ?? platform();
 	const command = resolveCodexBinary(input.env ?? process.env);
-	const isWindows = platform$2 === "win32";
+	const isWindows = platform$3 === "win32";
 	return {
 		command,
 		args: [...stdioAppServerArgs],
@@ -54,15 +69,15 @@ function resolveCodexAppServerSpawn(input = {}) {
 	};
 }
 function resolveCodexSharedAppServerSpawn(input = {}) {
-	const platform$3 = input.platform ?? platform();
+	const platform$4 = input.platform ?? platform();
 	const command = resolveCodexBinary(input.env ?? process.env);
-	const isWindows = platform$3 === "win32";
+	const isWindows = platform$4 === "win32";
 	return {
 		command,
 		args: [
 			"app-server",
 			"--listen",
-			resolveCodexSharedAppServerRemoteAddress(platform$3)
+			resolveCodexSharedAppServerRemoteAddress(platform$4)
 		],
 		shell: isWindows && shouldUseWindowsShell(command),
 		windowsHide: isWindows
@@ -126,8 +141,10 @@ const sharedSocketReconnectDelaysMs = [
 	2e3
 ];
 var CodexAppServerClient = class {
+	activeMode;
 	child;
 	closed = false;
+	fallbackToStdio;
 	initialized;
 	notificationHandlers = /* @__PURE__ */ new Set();
 	nextId = 1;
@@ -135,12 +152,21 @@ var CodexAppServerClient = class {
 	reconnecting;
 	requestHandlers = /* @__PURE__ */ new Set();
 	readline;
+	sharedReconnectEnabled = false;
 	sharedServer;
 	socket;
+	onStartupFallback;
 	startSharedServer;
 	constructor(options = {}) {
+		const mode = options.mode ?? resolveCodexAppServerMode();
+		this.activeMode = mode.mode;
+		this.fallbackToStdio = mode.fallbackToStdio;
+		this.onStartupFallback = options.onStartupFallback;
 		this.startSharedServer = options.startSharedServer ?? startSharedCodexAppServer;
 	}
+	get appServerMode() {
+		return this.activeMode;
+	}
 	initialize() {
 		return this.ensureInitialized();
 	}
@@ -220,15 +246,8 @@ var CodexAppServerClient = class {
 		this.closed = true;
 		for (const pending of this.pending.values()) pending.reject(/* @__PURE__ */ new Error("Codex app-server was closed."));
 		this.pending.clear();
-		this.readline?.close();
-		this.child?.kill();
-		const socket = this.socket;
-		this.socket = void 0;
-		socket?.close();
-		this.sharedServer?.kill();
-		this.readline = void 0;
-		this.child = void 0;
-		this.sharedServer = void 0;
+		this.stopStdioCodexAppServer();
+		this.stopSharedCodexAppServer();
 		this.initialized = void 0;
 	}
 	async request(method, params) {
@@ -262,13 +281,31 @@ var CodexAppServerClient = class {
 		return this.initialized;
 	}
 	async start() {
-		const mode = resolveCodexAppServerMode();
+		if (this.activeMode === "stdio") {
+			await this.startAndInitializeStdioCodexAppServer();
+			return;
+		}
+		try {
+			await this.startOrAttachSharedCodexAppServer();
+			await this.initializeAppServer();
+			this.fallbackToStdio = false;
+			this.sharedReconnectEnabled = true;
+		} catch (error) {
+			const sharedError = error instanceof Error ? error : new Error(String(error));
+			this.stopSharedCodexAppServer();
+			if (!this.fallbackToStdio) throw sharedError;
+			this.activeMode = "stdio";
+			relayDebugLog("app_server.shared_socket.startup_fallback", { message: sharedError.message });
+			this.onStartupFallback?.(sharedError);
+			await this.startAndInitializeStdioCodexAppServer();
+		}
+	}
+	async startAndInitializeStdioCodexAppServer() {
 		try {
-			if (mode === "socket") await this.startOrAttachSharedCodexAppServer();
-			else this.startStdioCodexAppServer();
+			this.startStdioCodexAppServer();
 			await this.initializeAppServer();
 		} catch (error) {
-			if (mode === "stdio") this.stopStdioCodexAppServer();
+			this.stopStdioCodexAppServer();
 			throw error;
 		}
 	}
@@ -310,6 +347,14 @@ var CodexAppServerClient = class {
 		this.child?.kill();
 		this.child = void 0;
 	}
+	stopSharedCodexAppServer() {
+		this.sharedReconnectEnabled = false;
+		const socket = this.socket;
+		this.socket = void 0;
+		socket?.close();
+		this.sharedServer?.kill();
+		this.sharedServer = void 0;
+	}
 	async startOrAttachSharedCodexAppServer() {
 		try {
 			await this.connectSharedCodexAppServer();
@@ -319,7 +364,7 @@ var CodexAppServerClient = class {
 			});
 			return;
 		} catch (error) {
-			const attachError = asError(error);
+			const attachError = error instanceof Error ? error : new Error(String(error));
 			relayDebugLog("app_server.shared_socket.attach_failed", {
 				message: attachError.message,
 				socketPath: sharedCodexAppServerSocketPath()
@@ -409,7 +454,7 @@ var CodexAppServerClient = class {
 		return this.sharedServer ? "relay-owned" : "attached";
 	}
 	scheduleSharedSocketReconnect() {
-		if (this.closed || this.reconnecting) return;
+		if (this.closed || !this.sharedReconnectEnabled || this.reconnecting) return;
 		const reconnecting = this.reconnectSharedCodexAppServer();
 		this.reconnecting = reconnecting;
 		this.initialized = reconnecting;
@@ -428,7 +473,7 @@ var CodexAppServerClient = class {
 		let lastError;
 		for (const delayMs of sharedSocketReconnectDelaysMs) {
 			await setTimeout$1(delayMs);
-			if (this.closed) return;
+			if (this.closed || !this.sharedReconnectEnabled) return;
 			try {
 				await this.connectSharedCodexAppServer();
 				await this.initializeAppServer();
@@ -438,7 +483,7 @@ var CodexAppServerClient = class {
 				});
 				return;
 			} catch (error) {
-				lastError = asError(error);
+				lastError = error instanceof Error ? error : new Error(String(error));
 				const socket = this.socket;
 				this.socket = void 0;
 				socket?.close();
@@ -572,16 +617,8 @@ async function startSharedCodexAppServer() {
 	throw new Error(`Timed out waiting for the shared Codex app-server at ${remoteAddress}.`);
 }
 async function waitForSharedCodexAppServer(remoteAddress) {
-	if (remoteAddress === "unix://") {
-		await access(sharedCodexAppServerSocketPath());
-		return;
-	}
-	const url = new URL(remoteAddress);
 	await new Promise((resolve, reject) => {
-		const socket = connect({
-			host: url.hostname,
-			port: Number(url.port)
-		});
+		const socket = remoteAddress === "unix://" ? connect({ path: sharedCodexAppServerSocketPath() }) : connectRemoteAddress(remoteAddress);
 		const onError = (error) => reject(error);
 		socket.once("error", onError);
 		socket.once("connect", () => {
@@ -591,6 +628,13 @@ async function waitForSharedCodexAppServer(remoteAddress) {
 		});
 	});
 }
+function connectRemoteAddress(remoteAddress) {
+	const url = new URL(remoteAddress);
+	return connect({
+		host: url.hostname,
+		port: Number(url.port)
+	});
+}
 function sharedCodexAppServerSocketPath() {
 	return join(process.env.CODEX_HOME?.trim() || join(homedir(), ".codex"), "app-server-control", "app-server-control.sock");
 }
@@ -1424,7 +1468,7 @@ function createApp(options = {}) {
 	const appServerHistoryLoadsByThreadId = /* @__PURE__ */ new Map();
 	const steeringThreads = /* @__PURE__ */ new Set();
 	const secureSessionsByTokenHash = /* @__PURE__ */ new Map();
-	const activeStreamControllers = /* @__PURE__ */ new Set();
+	const activeStreamControllers = /* @__PURE__ */ new Map();
 	const threadOptions = { workingDirectory: workspacePath };
 	function runThreadOperation(threadId, operation) {
 		const result = (threadOperationTails.get(threadId) ?? Promise.resolve()).then(operation, operation);
@@ -1871,7 +1915,7 @@ function createApp(options = {}) {
 		const stream = new ReadableStream({
 			start(controller) {
 				streamController = controller;
-				activeStreamControllers.add(controller);
+				activeStreamControllers.set(controller, closeStream);
 				send(workspaceTerminalOutputResponse(session, since));
 				if (session.exitedAt) return;
 				unsubscribe = subscribeWorkspaceTerminalOutput(session, send);
@@ -2593,20 +2637,30 @@ function createApp(options = {}) {
 		});
 		const encoder = new TextEncoder();
 		const secureSession = getSecureSessionForRequest(c, options.pairing, secureSessionsByTokenHash);
-		let streamController;
 		let streamSettled = false;
+		let closeStream = () => {};
 		const stream = new ReadableStream({
 			start(controller) {
-				streamController = controller;
-				activeStreamControllers.add(controller);
+				const attachmentAbortController = new AbortController();
+				let closed = false;
+				let stopPreviewMonitor = () => {};
+				closeStream = () => {
+					if (closed) return;
+					closed = true;
+					stopPreviewMonitor();
+					attachmentAbortController.abort();
+					activeStreamControllers.delete(controller);
+					closeSseController(controller);
+				};
+				activeStreamControllers.set(controller, closeStream);
 				relayDebugLog("thread.stream.started", {
 					mode: !runOptions.prompt && appServer ? "attach" : "run",
 					threadId
 				});
-				const stopPreviewMonitor = startWebPreviewTargetMonitor({
+				stopPreviewMonitor = startWebPreviewTargetMonitor({
 					bridgeUrl: c.req.url,
 					send(target) {
-						sendSse(controller, encoder, secureSession, {
+						return sendSse(controller, encoder, secureSession, {
 							type: "thread.preview_target.detected",
 							threadId,
 							target
@@ -2621,6 +2675,7 @@ function createApp(options = {}) {
 						messagesByThreadId,
 						pendingApprovals,
 						secureSession,
+						signal: attachmentAbortController.signal,
 						threadId,
 						threads
 					}).finally(() => {
@@ -2629,8 +2684,7 @@ function createApp(options = {}) {
 							mode: "attach",
 							threadId
 						});
-						activeStreamControllers.delete(controller);
-						stopPreviewMonitor();
+						closeStream();
 					});
 					return;
 				}
@@ -2641,14 +2695,12 @@ function createApp(options = {}) {
 						thread: knownThread,
 						error: apiError("unsupported", "Running-thread stream attachment requires the Codex app-server.").error
 					});
-					closeSseController(controller);
 					streamSettled = true;
 					relayDebugLog("thread.stream.finished", {
 						mode: "unsupported",
 						threadId
 					});
-					activeStreamControllers.delete(controller);
-					stopPreviewMonitor();
+					closeStream();
 					return;
 				}
 				const skills = runOptions.skills ?? [];
@@ -2681,12 +2733,11 @@ function createApp(options = {}) {
 						mode: "run",
 						threadId
 					});
-					activeStreamControllers.delete(controller);
-					stopPreviewMonitor();
+					closeStream();
 				});
 			},
 			cancel(reason) {
-				if (streamController) activeStreamControllers.delete(streamController);
+				closeStream();
 				relayDebugLog("thread.stream.cancelled_by_client", {
 					reason: debugReason(reason),
 					settled: streamSettled,
@@ -3030,8 +3081,6 @@ async function runPromptStreamed(input) {
 			thread: threadSummary,
 			error: errorBody.error
 		});
-	} finally {
-		closeSseController(input.controller);
 	}
 }
 async function startAppServerTurn(appServer, threadId, input) {
@@ -3122,7 +3171,16 @@ async function streamRunningAppServerThread(input) {
 	let observedTurnActivity = false;
 	let producedTurnOutput = false;
 	let threadSummary = input.threads.get(input.threadId);
-	const cleanupRequestHandler = input.appServer.onRequest((request) => {
+	let cleanupNotificationHandler = () => void 0;
+	let cleanupRequestHandler = () => void 0;
+	let handlersCleaned = false;
+	const cleanupHandlers = () => {
+		if (handlersCleaned) return;
+		handlersCleaned = true;
+		cleanupRequestHandler();
+		cleanupNotificationHandler();
+	};
+	cleanupRequestHandler = input.appServer.onRequest((request) => {
 		if (!isApprovalServerRequest(request.method)) {
 			input.appServer.rejectRequest(request.id, -32601, `${request.method} is not supported by Codex Relay mobile yet.`);
 			return;
@@ -3175,8 +3233,15 @@ async function streamRunningAppServerThread(input) {
 			message
 		});
 	});
-	let cleanupNotificationHandler = () => void 0;
 	const completed = new Promise((resolve, reject) => {
+		let settled = false;
+		const finish = (error) => {
+			if (settled) return;
+			settled = true;
+			cleanupHandlers();
+			if (error === void 0) resolve();
+			else reject(error);
+		};
 		cleanupNotificationHandler = input.appServer.onNotification((notification) => {
 			const params = recordParams(notification);
 			const notificationThreadId = firstString(params, ["threadId"]);
@@ -3191,10 +3256,7 @@ async function streamRunningAppServerThread(input) {
 							type: "thread.state.changed",
 							thread: threadSummary
 						});
-						if (state !== "running") {
-							cleanupNotificationHandler();
-							resolve();
-						}
+						if (state !== "running") finish();
 						return;
 					}
 					case "thread/goal/updated":
@@ -3303,8 +3365,7 @@ async function streamRunningAppServerThread(input) {
 								threadId: input.threadId,
 								threads: input.threads
 							});
-							cleanupNotificationHandler();
-							resolve();
+							finish();
 							return;
 						}
 						if (assistantMessageId) {
@@ -3342,27 +3403,40 @@ async function streamRunningAppServerThread(input) {
 								error: errorBody.error
 							});
 						}
-						cleanupNotificationHandler();
-						resolve();
+						finish();
 						return;
 					}
 				}
 			} catch (error) {
-				cleanupNotificationHandler();
-				reject(error);
+				finish(error);
 			}
 		});
 	});
+	let removeAbortListener = () => {};
+	const aborted = new Promise((resolve) => {
+		const onAbort = () => {
+			cleanupHandlers();
+			resolve();
+		};
+		if (input.signal.aborted) {
+			onAbort();
+			return;
+		}
+		input.signal.addEventListener("abort", onAbort, { once: true });
+		removeAbortListener = () => input.signal.removeEventListener("abort", onAbort);
+	});
 	try {
-		const appServerThread = await input.appServer.readThread(input.threadId, { includeTurns: false });
+		const appServerThread = await Promise.race([input.appServer.readThread(input.threadId, { includeTurns: false }), aborted.then(() => void 0)]);
+		if (!appServerThread || input.signal.aborted) return;
 		threadSummary = rememberAppServerThread(input.threads, appServerThread);
 		sendSse(input.controller, input.encoder, input.secureSession, {
 			type: "thread.state.changed",
 			thread: threadSummary
 		});
 		if (threadSummary.state !== "running") return;
-		await completed;
+		await Promise.race([completed, aborted]);
 	} catch (error) {
+		if (input.signal.aborted) return;
 		threadSummary = updateThread(input.threads, input.messagesByThreadId, input.threadId, {
 			state: "failed",
 			lastError: errorMessage(error)
@@ -3373,9 +3447,8 @@ async function streamRunningAppServerThread(input) {
 			error: apiError("codex_run_failed", threadSummary.lastError ?? "Codex run failed.").error
 		});
 	} finally {
-		cleanupRequestHandler();
-		cleanupNotificationHandler();
-		closeSseController(input.controller);
+		removeAbortListener();
+		cleanupHandlers();
 	}
 }
 async function runAppServerPromptStreamed(input) {
@@ -3843,7 +3916,6 @@ async function runAppServerPromptStreamed(input) {
 			input.activeAppServerTurnIdsByThreadId.delete(activeThreadId);
 			input.steeringThreads.delete(activeThreadId);
 		}
-		closeSseController(input.controller);
 	}
 }
 function sendEmptyAppServerTurnError(input) {
@@ -4464,13 +4536,17 @@ function sendSse(controller, encoder, secureSession, event) {
 			stage: "event",
 			threadId
 		});
-		return;
+		return false;
 	}
-	if (!enqueueSseChunk(controller, encoder.encode(`data: ${JSON.stringify(data)}\n\n`))) relayDebugLog("thread.stream.sse.enqueue_failed", {
-		eventType: parsed.type,
-		stage: "data",
-		threadId
-	});
+	if (!enqueueSseChunk(controller, encoder.encode(`data: ${JSON.stringify(data)}\n\n`))) {
+		relayDebugLog("thread.stream.sse.enqueue_failed", {
+			eventType: parsed.type,
+			stage: "data",
+			threadId
+		});
+		return false;
+	}
+	return true;
 }
 function sendTerminalOutputSse(controller, encoder, secureSession, response) {
 	const parsed = WorkspaceTerminalOutputResponseSchema.parse(response);
@@ -4502,7 +4578,7 @@ function closeSseController(controller) {
 	}
 }
 function closeActiveStreamControllers(controllers) {
-	for (const controller of controllers) closeSseController(controller);
+	for (const closeStream of controllers.values()) closeStream();
 	controllers.clear();
 }
 function isClosedStreamControllerError(error) {
@@ -4510,28 +4586,36 @@ function isClosedStreamControllerError(error) {
 }
 function startWebPreviewTargetMonitor({ bridgeUrl, send }) {
 	const urls = webPreviewCandidateUrls(bridgeUrl);
-	const seenUrls = /* @__PURE__ */ new Set();
+	const abortController = new AbortController();
 	let stopped = false;
+	let nextScan;
+	const stop = () => {
+		if (stopped) return;
+		stopped = true;
+		abortController.abort();
+		if (nextScan) {
+			clearTimeout(nextScan);
+			nextScan = void 0;
+		}
+	};
 	async function scan() {
 		if (stopped) return;
-		const targets = await detectWebPreviewTargets(urls);
-		for (const target of targets) {
-			if (stopped || seenUrls.has(target.url)) continue;
-			seenUrls.add(target.url);
+		const target = await detectWebPreviewTarget(urls, abortController.signal);
+		if (stopped) return;
+		if (target) {
+			stop();
 			try {
 				send(target);
-			} catch {
-				stopped = true;
-				return;
-			}
+			} catch {}
+			return;
 		}
+		nextScan = setTimeout(() => {
+			nextScan = void 0;
+			scan();
+		}, 1500);
 	}
 	scan();
-	const interval = setInterval(() => void scan(), 1500);
-	return () => {
-		stopped = true;
-		clearInterval(interval);
-	};
+	return stop;
 }
 function webPreviewCandidateUrls(bridgeUrl) {
 	const bridge = new URL(bridgeUrl);
@@ -4554,11 +4638,14 @@ function webPreviewCandidatePorts() {
 function readCollaborationModeTemplate(name) {
 	return readFileSync(new URL(`./collaboration-mode-templates/${name}.md`, import.meta.url), "utf8").replaceAll("{{KNOWN_MODE_NAMES}}", knownCollaborationModeNames).trim();
 }
-async function detectWebPreviewTargets(urls) {
-	return (await Promise.all(urls.map((url) => probeWebPreviewTarget(url)))).filter((target) => Boolean(target));
+async function detectWebPreviewTarget(urls, signal) {
+	return (await Promise.all(urls.map((url) => probeWebPreviewTarget(url, signal)))).find((target) => Boolean(target));
 }
-async function probeWebPreviewTarget(url) {
+async function probeWebPreviewTarget(url, signal) {
 	const controller = new AbortController();
+	const abort = () => controller.abort();
+	if (signal.aborted) abort();
+	else signal.addEventListener("abort", abort, { once: true });
 	const timeout = setTimeout(() => controller.abort(), 700);
 	try {
 		const response = await fetch(url, { signal: controller.signal });
@@ -4579,6 +4666,7 @@ async function probeWebPreviewTarget(url) {
 		return;
 	} finally {
 		clearTimeout(timeout);
+		signal.removeEventListener("abort", abort);
 	}
 }
 function looksLikeHtml(value) {
@@ -6784,16 +6872,21 @@ const npxCommand = "npx codex-relay@latest";
 const sessionStore = await createTursoPairingSessionStore(process.env.CODEX_RELAY_AUTH_DB_PATH ?? await prepareCodexRelayDataPath("auth.db", ["auth.db-shm", "auth.db-wal"]));
 const preferencesStore = createFileRuntimePreferencesStore(process.env.CODEX_RELAY_PREFERENCES_PATH ?? await prepareCodexRelayDataPath("preferences.json"));
 const appServerMode = resolveCodexAppServerMode();
-const sharedAppServer = appServerMode === "socket" ? new CodexAppServerClient() : void 0;
-if (sharedAppServer) {
-	await sharedAppServer.initialize();
-	process.once("SIGINT", () => stopSharedAppServer(130));
-	process.once("SIGTERM", () => stopSharedAppServer(143));
-	process.once("exit", () => sharedAppServer.close());
+const relayAppServer = appServerMode.mode === "socket" ? new CodexAppServerClient({
+	mode: appServerMode,
+	onStartupFallback: (error) => {
+		logRuntimeEvent("Fallback", `Shared app-server unavailable; continuing with a private app-server (${error.message}).`);
+	}
+}) : void 0;
+if (relayAppServer) {
+	await relayAppServer.initialize();
+	process.once("SIGINT", () => stopRelayAppServer(130));
+	process.once("SIGTERM", () => stopRelayAppServer(143));
+	process.once("exit", () => relayAppServer.close());
 }
 serve({
 	fetch: createApp({
-		appServer: sharedAppServer,
+		appServer: relayAppServer,
 		pairing: {
 			approvalSecret,
 			dangerouslyAutoApprove,
@@ -6865,11 +6958,11 @@ serve({
 		listenUrl,
 		pairingPayload,
 		port: info.port,
-		sharedAppServerRemoteAddress: appServerMode === "socket" ? resolveCodexSharedAppServerRemoteAddress() : void 0
+		sharedAppServerRemoteAddress: relayAppServer?.appServerMode === "socket" ? resolveCodexSharedAppServerRemoteAddress() : void 0
 	}));
 });
-function stopSharedAppServer(exitCode) {
-	sharedAppServer?.close();
+function stopRelayAppServer(exitCode) {
+	relayAppServer?.close();
 	process.exit(exitCode);
 }
 function formatStartupInstructions(details) {
@@ -6893,6 +6986,7 @@ function formatStartupInstructions(details) {
 			`${color.prompt("›")} Commands`,
 			`  ${color.command(npxCommand)}              Start and print a pairing QR`,
 			`  ${color.command(`${npxCommand} --bg`)}         Start in the background`,
+			`  ${color.command(`${npxCommand} stop`)}         Stop the background relay`,
 			`  ${color.command(`${npxCommand} qr`)}           Print this QR again`,
 			`  ${color.command(`${npxCommand} approve <code>`)} Approve a device`,
 			"",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-relay",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "Local Codex Relay CLI bridge for the Codex Relay mobile app.",
   "license": "Apache-2.0",
   "repository": {
@@ -41,7 +41,7 @@
     "@noble/ciphers": "2.2.0",
     "@noble/curves": "2.2.0",
     "@noble/hashes": "2.2.0",
-    "@openai/codex-sdk": "0.144.5",
+    "@openai/codex-sdk": "0.145.0",
     "base64-js": "1.5.1",
     "commander": "^14.0.3",
     "es-git": "^0.6.0",