codex-relay 1.3.2 → 1.4.1

package/dist/src.js

@@ -1,4 +1,4 @@
-import { $ as RuntimePreferencesSchema, A as PairRequestSchema, B as QueuedThreadInputActionResponseSchema, Bt as apiPaths, C as ListModelsResponseSchema, Ct as WorkspaceChangesResponseSchema, D as ListWorkspaceDirectoriesResponseSchema, Dt as WorkspaceGitActionResponseSchema, E as ListThreadsResponseSchema, G as ReasoningEffortSchema, Gt as promptMarkdownWithSkills, Ht as createOpenApiDocument, It as WorkspaceTerminalOutputResponseSchema, J as RunThreadRequestSchema, K as ResolveApprovalRequestSchema, Lt as WorkspaceTerminalResizeRequestSchema, Mt as WorkspaceTailscaleServeRequestSchema, Nt as WorkspaceTailscaleServeResponseSchema, O as ListWorkspaceFilesResponseSchema, Pt as WorkspaceTerminalInputRequestSchema, Q as RuntimePreferencesResponseSchema, Rt as WorkspaceTerminalSessionResponseSchema, S as KnownReasoningEffortSchema, T as ListSkillsResponseSchema, Tt as WorkspaceFileContentResponseSchema, Vt as chatMessageDetailsFromPromptContext, W as RateLimitsResponseSchema, Wt as normalizePromptContext, Xt as stripPromptSkillMentions, _ as EncryptedPayloadSchema, _t as UpdateThreadGoalRequestSchema, a as ArchiveThreadResponseSchema, b as InterruptThreadRunResponseSchema, ct as ThreadGoalResponseSchema, d as CheckoutWorkspaceBranchRequestSchema, dt as ThreadMessageDetailFieldSchema, ft as ThreadMessageDetailResponseSchema, gt as UpdateRuntimePreferencesRequestSchema, h as CreateThreadRequestSchema, ht as ThreadSummarySchema, it as SubmitThreadInputResponseSchema, j as PairResponseSchema, l as ChatMessageSchema, lt as ThreadGoalSchema, m as ContextWindowUsageSchema, nt as StreamThreadRunEventSchema, ot as ThreadContextWindowResponseSchema, p as CommitPushWorkspaceRequestSchema, q as ResolveApprovalResponseSchema, rt as StreamThreadRunRequestSchema, st as ThreadDetailResponseSchema, tt as StatusResponseSchema, ut as ThreadGoalStatusSchema, vt as UpdateWorkspaceFileContentRequestSchema, w as ListQueuedThreadInputsResponseSchema, y as ImageAttachmentUploadResponseSchema, yt as VersionResponseSchema, zt as WorkspaceTerminalStartRequestSchema } from "./api-schema2.js";
+import { A as PairRequestSchema, Bt as WorkspaceTerminalOutputResponseSchema, C as ListModelsResponseSchema, Ct as VersionResponseSchema, D as ListWorkspaceDirectoriesResponseSchema, Dt as WorkspaceChangesResponseSchema, E as ListThreadsResponseSchema, Gt as chatMessageDetailsFromPromptContext, H as PushNotificationSettingsResponseSchema, Ht as WorkspaceTerminalSessionResponseSchema, It as WorkspaceTailscaleServeRequestSchema, J as ReasoningEffortSchema, Jt as normalizePromptContext, Kt as createOpenApiDocument, Lt as WorkspaceTailscaleServeResponseSchema, O as ListWorkspaceFilesResponseSchema, Q as RunThreadRequestSchema, Rt as WorkspaceTerminalInputRequestSchema, S as KnownReasoningEffortSchema, St as UpdateWorkspaceFileContentRequestSchema, T as ListSkillsResponseSchema, U as QueuedThreadInputActionResponseSchema, Ut as WorkspaceTerminalStartRequestSchema, Vt as WorkspaceTerminalResizeRequestSchema, Wt as apiPaths, X as ResolveApprovalRequestSchema, Y as RegisterPushNotificationRequestSchema, Yt as promptMarkdownWithSkills, Z as ResolveApprovalResponseSchema, _ as EncryptedPayloadSchema, a as ArchiveThreadResponseSchema, at as StatusResponseSchema, b as InterruptThreadRunResponseSchema, bt as UpdateRuntimePreferencesRequestSchema, ct as SubmitThreadInputResponseSchema, d as CheckoutWorkspaceBranchRequestSchema, dt as ThreadDetailResponseSchema, en as stripPromptSkillMentions, ft as ThreadGoalResponseSchema, gt as ThreadMessageDetailResponseSchema, h as CreateThreadRequestSchema, ht as ThreadMessageDetailFieldSchema, j as PairResponseSchema, jt as WorkspaceGitActionResponseSchema, kt as WorkspaceFileContentResponseSchema, l as ChatMessageSchema, m as ContextWindowUsageSchema, mt as ThreadGoalStatusSchema, nt as RuntimePreferencesResponseSchema, ot as StreamThreadRunEventSchema, p as CommitPushWorkspaceRequestSchema, pt as ThreadGoalSchema, q as RateLimitsResponseSchema, rt as RuntimePreferencesSchema, st as StreamThreadRunRequestSchema, ut as ThreadContextWindowResponseSchema, w as ListQueuedThreadInputsResponseSchema, xt as UpdateThreadGoalRequestSchema, y as ImageAttachmentUploadResponseSchema, yt as ThreadSummarySchema } from "./api-schema2.js";
 import { a as getConnectUrlCandidates, i as createPairingQrPayload, o as getConnectUrlGuidance, r as legacyCodexRelayDataPath, s as createTursoPairingSessionStore, t as codexRelayDataPath } from "./paths.js";
 import { createRequire } from "node:module";
 import qrcode from "qrcode-terminal";
@@ -19,6 +19,7 @@ import { openRepository } from "es-git";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import * as pty from "@lydell/node-pty";
+import { connect } from "node:net";
 import { createInterface } from "node:readline";
 import WebSocket from "ws";
 import { Codex } from "@openai/codex-sdk";
@@ -33,11 +34,7 @@ const stdioAppServerArgs = [
 	"--listen",
 	"stdio://"
 ];
-const sharedServerArgs = [
-	"app-server",
-	"--listen",
-	"unix://"
-];
+const sharedWindowsServerUrl = "ws://127.0.0.1:8788";
 const windowsShellExtensions = new Set([".bat", ".cmd"]);
 function resolveCodexAppServerMode(env = process.env) {
 	const configuredMode = env.CODEX_RELAY_APP_SERVER_MODE?.trim().toLowerCase();
@@ -46,9 +43,9 @@ function resolveCodexAppServerMode(env = process.env) {
 	throw new Error(`Unsupported CODEX_RELAY_APP_SERVER_MODE ${JSON.stringify(configuredMode)}. Expected "stdio" or "socket".`);
 }
 function resolveCodexAppServerSpawn(input = {}) {
-	const platform$1 = input.platform ?? platform();
+	const platform$2 = input.platform ?? platform();
 	const command = resolveCodexBinary(input.env ?? process.env);
-	const isWindows = platform$1 === "win32";
+	const isWindows = platform$2 === "win32";
 	return {
 		command,
 		args: [...stdioAppServerArgs],
@@ -57,19 +54,22 @@ function resolveCodexAppServerSpawn(input = {}) {
 	};
 }
 function resolveCodexSharedAppServerSpawn(input = {}) {
-	const platform$2 = input.platform ?? platform();
-	assertAppServerModeSupported("socket", platform$2);
+	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: [...sharedServerArgs],
+		args: [
+			"app-server",
+			"--listen",
+			resolveCodexSharedAppServerRemoteAddress(platform$3)
+		],
 		shell: isWindows && shouldUseWindowsShell(command),
 		windowsHide: isWindows
 	};
 }
-function assertAppServerModeSupported(mode, platform) {
-	if (mode === "socket" && platform === "win32") throw new Error("Shared Codex app-server mode requires macOS, Linux, or WSL.");
+function resolveCodexSharedAppServerRemoteAddress(platform$1 = platform()) {
+	return platform$1 === "win32" ? sharedWindowsServerUrl : "unix://";
 }
 function resolveCodexBinary(env) {
 	return env.CODEX_BIN?.trim() || "codex";
@@ -79,17 +79,68 @@ function shouldUseWindowsShell(command) {
 	return extension === "" || windowsShellExtensions.has(extension);
 }
 //#endregion
+//#region src/debug-log.ts
+function isRelayDebugEnabled() {
+	return process.env.CODEX_RELAY_DEBUG === "1" || process.env.CODEX_RELAY_DEBUG_STREAM === "1";
+}
+function relayDebugLog(event, fields = {}) {
+	if (!isRelayDebugEnabled()) return;
+	const entry = sanitizeDebugValue({
+		ts: (/* @__PURE__ */ new Date()).toISOString(),
+		event,
+		...fields
+	});
+	const line = `${JSON.stringify(entry)}\n`;
+	const path = process.env.CODEX_RELAY_DEBUG_LOG_PATH?.trim();
+	if (path) mkdir(dirname(path), { recursive: true }).then(() => appendFile(path, line, { mode: 384 })).catch(() => void 0);
+	console.log(`[debug] ${event} ${formatDebugFields(fields)}`.trimEnd());
+}
+function sanitizeDebugValue(value) {
+	if (value instanceof Error) return {
+		message: value.message,
+		name: value.name,
+		stack: value.stack
+	};
+	if (Array.isArray(value)) return value.map(sanitizeDebugValue);
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitizeDebugValue(item)]));
+	return value;
+}
+function formatDebugFields(fields) {
+	return Object.entries(fields).map(([key, value]) => `${key}=${formatDebugValue(value)}`).join(" ");
+}
+function formatDebugValue(value) {
+	if (value === void 0) return "undefined";
+	if (value === null) return "null";
+	if (typeof value === "string") return value.includes(" ") ? JSON.stringify(value) : value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	return JSON.stringify(sanitizeDebugValue(value));
+}
+//#endregion
 //#region src/app-server.ts
+const sharedSocketReconnectDelaysMs = [
+	50,
+	100,
+	250,
+	500,
+	1e3,
+	2e3
+];
 var CodexAppServerClient = class {
 	child;
+	closed = false;
 	initialized;
 	notificationHandlers = /* @__PURE__ */ new Set();
 	nextId = 1;
 	pending = /* @__PURE__ */ new Map();
+	reconnecting;
 	requestHandlers = /* @__PURE__ */ new Set();
 	readline;
 	sharedServer;
 	socket;
+	startSharedServer;
+	constructor(options = {}) {
+		this.startSharedServer = options.startSharedServer ?? startSharedCodexAppServer;
+	}
 	initialize() {
 		return this.ensureInitialized();
 	}
@@ -165,15 +216,18 @@ var CodexAppServerClient = class {
 		});
 	}
 	close() {
+		if (this.closed) return;
+		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();
-		this.socket?.close();
+		const socket = this.socket;
+		this.socket = void 0;
+		socket?.close();
 		this.sharedServer?.kill();
 		this.readline = void 0;
 		this.child = void 0;
-		this.socket = void 0;
 		this.sharedServer = void 0;
 		this.initialized = void 0;
 	}
@@ -197,35 +251,37 @@ var CodexAppServerClient = class {
 		});
 	}
 	ensureInitialized() {
-		if (!this.initialized) this.initialized = this.start();
+		if (this.closed) return Promise.reject(/* @__PURE__ */ new Error("Codex app-server was closed."));
+		if (!this.initialized) {
+			const initialized = this.start();
+			this.initialized = initialized;
+			initialized.catch(() => {
+				if (this.initialized === initialized) this.initialized = void 0;
+			});
+		}
 		return this.initialized;
 	}
 	async start() {
+		const mode = resolveCodexAppServerMode();
 		try {
-			if (resolveCodexAppServerMode() === "socket") {
-				this.sharedServer = await startSharedCodexAppServer();
-				await this.connectSharedCodexAppServer();
-			} else this.startStdioCodexAppServer();
-			await this.requestRaw("initialize", {
-				clientInfo: {
-					name: "codex-relay",
-					title: "Codex Relay Mobile Server",
-					version: "1.2.0"
-				},
-				capabilities: { experimentalApi: true }
-			});
+			if (mode === "socket") await this.startOrAttachSharedCodexAppServer();
+			else this.startStdioCodexAppServer();
+			await this.initializeAppServer();
 		} catch (error) {
-			this.readline?.close();
-			this.readline = void 0;
-			this.child?.kill();
-			this.child = void 0;
-			this.socket?.close();
-			this.socket = void 0;
-			this.sharedServer?.kill();
-			this.sharedServer = void 0;
+			if (mode === "stdio") this.stopStdioCodexAppServer();
 			throw error;
 		}
 	}
+	async initializeAppServer() {
+		await this.requestRaw("initialize", {
+			clientInfo: {
+				name: "codex-relay",
+				title: "Codex Relay Mobile Server",
+				version: "1.2.0"
+			},
+			capabilities: { experimentalApi: true }
+		});
+	}
 	startStdioCodexAppServer() {
 		const spawnConfig = resolveCodexAppServerSpawn();
 		this.child = spawn(spawnConfig.command, spawnConfig.args, {
@@ -248,31 +304,153 @@ var CodexAppServerClient = class {
 			this.initialized = void 0;
 		});
 	}
+	stopStdioCodexAppServer() {
+		this.readline?.close();
+		this.readline = void 0;
+		this.child?.kill();
+		this.child = void 0;
+	}
+	async startOrAttachSharedCodexAppServer() {
+		try {
+			await this.connectSharedCodexAppServer();
+			relayDebugLog("app_server.shared_socket.attached", {
+				ownership: "attached",
+				socketPath: sharedCodexAppServerSocketPath()
+			});
+			return;
+		} catch (error) {
+			const attachError = asError(error);
+			relayDebugLog("app_server.shared_socket.attach_failed", {
+				message: attachError.message,
+				socketPath: sharedCodexAppServerSocketPath()
+			});
+			if (this.sharedServer) throw attachError;
+		}
+		const sharedServer = await this.startSharedServer();
+		this.sharedServer = sharedServer;
+		this.observeSharedCodexAppServer(sharedServer);
+		relayDebugLog("app_server.shared_process.started", {
+			ownership: "relay-owned",
+			socketPath: sharedCodexAppServerSocketPath()
+		});
+		try {
+			await this.connectSharedCodexAppServer();
+		} catch (error) {
+			if (this.sharedServer === sharedServer) {
+				sharedServer.kill();
+				this.sharedServer = void 0;
+			}
+			throw error;
+		}
+	}
+	observeSharedCodexAppServer(sharedServer) {
+		sharedServer.on("error", (error) => {
+			relayDebugLog("app_server.shared_process.error", {
+				message: error.message,
+				ownership: "relay-owned"
+			});
+			if (this.sharedServer === sharedServer) this.sharedServer = void 0;
+		});
+		sharedServer.once("exit", (code, signal) => {
+			if (this.sharedServer !== sharedServer) return;
+			this.sharedServer = void 0;
+			const error = /* @__PURE__ */ new Error(`Codex shared app-server exited with ${signal ?? code ?? 1}.`);
+			relayDebugLog("app_server.shared_process.exited", {
+				message: error.message,
+				ownership: "relay-owned"
+			});
+			if (this.socket) this.handleSharedSocketFailure(this.socket, error);
+		});
+	}
 	async connectSharedCodexAppServer() {
-		const socket = new WebSocket(`ws+unix://${sharedCodexAppServerSocketPath()}:/`, { perMessageDeflate: false });
+		const remoteAddress = resolveCodexSharedAppServerRemoteAddress();
+		const socket = new WebSocket(remoteAddress === "unix://" ? `ws+unix://${sharedCodexAppServerSocketPath()}:/` : remoteAddress, { perMessageDeflate: false });
 		this.socket = socket;
-		await new Promise((resolve, reject) => {
-			const handleOpen = () => {
-				socket.off("error", handleInitialError);
-				resolve();
-			};
-			const handleInitialError = (error) => {
-				socket.off("open", handleOpen);
-				reject(error);
-			};
-			socket.once("open", handleOpen);
-			socket.once("error", handleInitialError);
-		});
+		try {
+			await new Promise((resolve, reject) => {
+				const handleOpen = () => {
+					socket.off("error", handleInitialError);
+					resolve();
+				};
+				const handleInitialError = (error) => {
+					socket.off("open", handleOpen);
+					reject(error);
+				};
+				socket.once("open", handleOpen);
+				socket.once("error", handleInitialError);
+			});
+		} catch (error) {
+			if (this.socket === socket) this.socket = void 0;
+			socket.close();
+			throw error;
+		}
 		socket.on("message", (data) => this.handleLine(String(data)));
-		socket.on("error", (error) => this.rejectAll(error));
+		socket.on("error", (error) => this.handleSharedSocketFailure(socket, error));
 		socket.once("close", (code, reason) => {
-			this.rejectAll(/* @__PURE__ */ new Error(`Codex app-server socket closed with ${code}${reason.length > 0 ? `: ${String(reason)}` : "."}`));
-			this.socket = void 0;
-			this.sharedServer?.kill();
-			this.sharedServer = void 0;
-			this.initialized = void 0;
+			this.handleSharedSocketFailure(socket, /* @__PURE__ */ new Error(`Codex app-server socket closed with ${code}${reason.length > 0 ? `: ${String(reason)}` : "."}`));
+		});
+		relayDebugLog("app_server.shared_socket.connected", {
+			ownership: this.sharedAppServerOwnership(),
+			socketPath: sharedCodexAppServerSocketPath()
 		});
 	}
+	handleSharedSocketFailure(socket, error) {
+		if (this.socket !== socket) return;
+		this.socket = void 0;
+		this.rejectAll(error);
+		this.initialized = void 0;
+		relayDebugLog("app_server.shared_socket.disconnected", {
+			message: error.message,
+			ownership: this.sharedAppServerOwnership()
+		});
+		this.scheduleSharedSocketReconnect();
+	}
+	sharedAppServerOwnership() {
+		return this.sharedServer ? "relay-owned" : "attached";
+	}
+	scheduleSharedSocketReconnect() {
+		if (this.closed || this.reconnecting) return;
+		const reconnecting = this.reconnectSharedCodexAppServer();
+		this.reconnecting = reconnecting;
+		this.initialized = reconnecting;
+		reconnecting.then(() => {
+			if (this.reconnecting === reconnecting) this.reconnecting = void 0;
+		}, (error) => {
+			relayDebugLog("app_server.shared_socket.reconnect_failed", {
+				message: asError(error).message,
+				ownership: this.sharedAppServerOwnership()
+			});
+			if (this.initialized === reconnecting) this.initialized = void 0;
+			if (this.reconnecting === reconnecting) this.reconnecting = void 0;
+		});
+	}
+	async reconnectSharedCodexAppServer() {
+		let lastError;
+		for (const delayMs of sharedSocketReconnectDelaysMs) {
+			await setTimeout$1(delayMs);
+			if (this.closed) return;
+			try {
+				await this.connectSharedCodexAppServer();
+				await this.initializeAppServer();
+				relayDebugLog("app_server.shared_socket.reconnected", {
+					ownership: this.sharedAppServerOwnership(),
+					socketPath: sharedCodexAppServerSocketPath()
+				});
+				return;
+			} catch (error) {
+				lastError = asError(error);
+				const socket = this.socket;
+				this.socket = void 0;
+				socket?.close();
+				relayDebugLog("app_server.shared_socket.reconnect_retry", {
+					delayMs,
+					message: lastError.message,
+					ownership: this.sharedAppServerOwnership()
+				});
+			}
+		}
+		throw lastError ?? /* @__PURE__ */ new Error("Unable to reconnect to the shared Codex app-server.");
+	}
 	requestRaw(method, params) {
 		const id = this.nextId++;
 		const request = JSON.stringify({
@@ -376,11 +554,11 @@ async function startSharedCodexAppServer() {
 	child.once("exit", (code, signal) => {
 		exitReason = signal ?? code ?? 1;
 	});
-	const socketPath = sharedCodexAppServerSocketPath();
+	const remoteAddress = resolveCodexSharedAppServerRemoteAddress();
 	for (let attempt = 0; attempt < 100; attempt += 1) {
 		if (spawnError) throw new Error(`Failed to start the shared Codex app-server: ${spawnError.message}`);
 		try {
-			await access(socketPath);
+			await waitForSharedCodexAppServer(remoteAddress);
 			return child;
 		} catch {
 			if (exitReason !== void 0) {
@@ -391,11 +569,34 @@ async function startSharedCodexAppServer() {
 		}
 	}
 	child.kill();
-	throw new Error(`Timed out waiting for the shared Codex app-server socket at ${socketPath}.`);
+	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 onError = (error) => reject(error);
+		socket.once("error", onError);
+		socket.once("connect", () => {
+			socket.off("error", onError);
+			socket.destroy();
+			resolve();
+		});
+	});
 }
 function sharedCodexAppServerSocketPath() {
 	return join(process.env.CODEX_HOME?.trim() || join(homedir(), ".codex"), "app-server-control", "app-server-control.sock");
 }
+function asError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
 function debugAppServer(kind, method, id, detail) {
 	if (process.env.CODEX_RELAY_DEBUG_APP_SERVER !== "1") return;
 	console.log(`[app-server] ${kind}${id === void 0 ? "" : ` #${id}`}${method ? ` ${method}` : ""}${detail ? ` ${detail}` : ""}`);
@@ -585,41 +786,79 @@ function sumPositiveIntegers(values) {
 	return found ? sum : null;
 }
 //#endregion
-//#region src/debug-log.ts
-function isRelayDebugEnabled() {
-	return process.env.CODEX_RELAY_DEBUG === "1" || process.env.CODEX_RELAY_DEBUG_STREAM === "1";
+//#region src/push-notifications.ts
+const expoPushEndpoint = "https://exp.host/--/api/v2/push/send";
+const expoPushChunkSize = 100;
+function createExpoPushNotificationSender(fetchImpl = fetch) {
+	return { async send(notifications) {
+		const invalidExpoPushTokens = /* @__PURE__ */ new Set();
+		for (const chunk of chunks(notifications, expoPushChunkSize)) {
+			const response = await fetchImpl(expoPushEndpoint, {
+				body: JSON.stringify(chunk.map((notification) => ({
+					body: notification.body,
+					channelId: "default",
+					data: notification.data,
+					priority: "high",
+					sound: "default",
+					title: notification.title,
+					to: notification.to
+				}))),
+				headers: {
+					accept: "application/json",
+					"content-type": "application/json"
+				},
+				method: "POST"
+			});
+			const body = await response.json().catch(() => void 0);
+			if (!response.ok) throw new Error(`Expo push service returned ${response.status}.`);
+			const tickets = expoPushTickets(body);
+			for (const [index, ticket] of tickets.entries()) {
+				const notification = chunk[index];
+				if (notification && isDeviceNotRegistered(ticket)) invalidExpoPushTokens.add(notification.to);
+			}
+		}
+		return { invalidExpoPushTokens: [...invalidExpoPushTokens] };
+	} };
 }
-function relayDebugLog(event, fields = {}) {
-	if (!isRelayDebugEnabled()) return;
-	const entry = sanitizeDebugValue({
-		ts: (/* @__PURE__ */ new Date()).toISOString(),
-		event,
-		...fields
-	});
-	const line = `${JSON.stringify(entry)}\n`;
-	const path = process.env.CODEX_RELAY_DEBUG_LOG_PATH?.trim();
-	if (path) mkdir(dirname(path), { recursive: true }).then(() => appendFile(path, line, { mode: 384 })).catch(() => void 0);
-	console.log(`[debug] ${event} ${formatDebugFields(fields)}`.trimEnd());
+function createPushNotificationDispatcher(input) {
+	return { async dispatch(event) {
+		const subscriptions = await input.sessions.listActivePushNotificationSubscriptions(Date.now());
+		const selectedTokens = new Set(subscriptions.filter((subscription) => notificationEnabled(subscription, event.intent)).map((subscription) => subscription.expoPushToken));
+		if (selectedTokens.size === 0) return;
+		const delivery = await input.sender.send([...selectedTokens].map((expoPushToken) => notificationForEvent(expoPushToken, event)));
+		await Promise.all(delivery.invalidExpoPushTokens.map((expoPushToken) => input.sessions.deletePushNotificationSubscriptionsByExpoPushToken(expoPushToken)));
+	} };
 }
-function sanitizeDebugValue(value) {
-	if (value instanceof Error) return {
-		message: value.message,
-		name: value.name,
-		stack: value.stack
+function notificationEnabled(subscription, intent) {
+	return intent === "action_required" ? subscription.actionRequired : subscription.turnTerminal;
+}
+function notificationForEvent(expoPushToken, event) {
+	return {
+		body: event.intent === "action_required" ? "Codex needs your attention." : "A Codex turn has finished.",
+		data: {
+			intent: event.intent,
+			threadId: event.threadId,
+			...event.turnId ? { turnId: event.turnId } : {}
+		},
+		title: "Codex Relay",
+		to: expoPushToken
 	};
-	if (Array.isArray(value)) return value.map(sanitizeDebugValue);
-	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitizeDebugValue(item)]));
-	return value;
 }
-function formatDebugFields(fields) {
-	return Object.entries(fields).map(([key, value]) => `${key}=${formatDebugValue(value)}`).join(" ");
+function expoPushTickets(value) {
+	if (!value || typeof value !== "object") return [];
+	const data = value.data;
+	return Array.isArray(data) ? data : [];
 }
-function formatDebugValue(value) {
-	if (value === void 0) return "undefined";
-	if (value === null) return "null";
-	if (typeof value === "string") return value.includes(" ") ? JSON.stringify(value) : value;
-	if (typeof value === "number" || typeof value === "boolean") return String(value);
-	return JSON.stringify(sanitizeDebugValue(value));
+function isDeviceNotRegistered(ticket) {
+	if (!ticket || typeof ticket !== "object") return false;
+	const record = ticket;
+	if (record.status !== "error" || !record.details || typeof record.details !== "object") return false;
+	return record.details.error === "DeviceNotRegistered";
+}
+function chunks(items, size) {
+	const result = [];
+	for (let index = 0; index < items.length; index += size) result.push(items.slice(index, index + size));
+	return result;
 }
 //#endregion
 //#region src/preferences-store.ts
@@ -1179,6 +1418,7 @@ function createApp(options = {}) {
 	const pendingApprovals = /* @__PURE__ */ new Map();
 	const resolvedApprovals = /* @__PURE__ */ new Map();
 	const queuedInputsByThreadId = /* @__PURE__ */ new Map();
+	const threadOperationTails = /* @__PURE__ */ new Map();
 	const workspaceTerminalSessions = /* @__PURE__ */ new Map();
 	const activeAppServerTurnIdsByThreadId = /* @__PURE__ */ new Map();
 	const appServerHistoryLoadsByThreadId = /* @__PURE__ */ new Map();
@@ -1186,6 +1426,20 @@ function createApp(options = {}) {
 	const secureSessionsByTokenHash = /* @__PURE__ */ new Map();
 	const activeStreamControllers = /* @__PURE__ */ new Set();
 	const threadOptions = { workingDirectory: workspacePath };
+	function runThreadOperation(threadId, operation) {
+		const result = (threadOperationTails.get(threadId) ?? Promise.resolve()).then(operation, operation);
+		const tail = result.then(() => void 0, () => void 0);
+		threadOperationTails.set(threadId, tail);
+		tail.finally(() => {
+			if (threadOperationTails.get(threadId) === tail) threadOperationTails.delete(threadId);
+		});
+		return result;
+	}
+	const pushNotificationDispatcher = options.pairing ? createPushNotificationDispatcher({
+		sender: options.pushNotificationSender ?? createExpoPushNotificationSender(),
+		sessions: options.pairing.sessions
+	}) : void 0;
+	if (appServer && pushNotificationDispatcher) observeAppServerPushNotifications(appServer, pushNotificationDispatcher);
 	const scheduleAppServerHistoryLoad = (threadId, cachedMessages) => {
 		if (!appServer || appServerHistoryLoadsByThreadId.has(threadId)) return;
 		const startedAt = Date.now();
@@ -1410,6 +1664,48 @@ function createApp(options = {}) {
 		});
 		return secureJson(c, options.pairing, secureSessionsByTokenHash, response);
 	});
+	app.get(apiPaths.pushNotifications, async (c) => {
+		const clientSessionId = await pairedClientSessionIdForAuthorization(c.req.header("authorization"), options.pairing);
+		if (!clientSessionId) return secureJson(c, options.pairing, secureSessionsByTokenHash, apiError("push_notifications_unavailable", "Pair this device again to manage notifications."), 401);
+		const subscription = await options.pairing.sessions.getPushNotificationSubscription(clientSessionId);
+		const response = PushNotificationSettingsResponseSchema.parse({
+			preferences: subscription ? {
+				actionRequired: subscription.actionRequired,
+				turnTerminal: subscription.turnTerminal
+			} : defaultPushNotificationPreferences(),
+			registered: Boolean(subscription)
+		});
+		return secureJson(c, options.pairing, secureSessionsByTokenHash, response);
+	});
+	app.put(apiPaths.pushNotifications, async (c) => {
+		if (!options.pairing) return secureJson(c, options.pairing, secureSessionsByTokenHash, apiError("pairing_required", "Pair this device before registering notifications."), 404);
+		const parsed = await parseRequestJson(c, options.pairing, secureSessionsByTokenHash, RegisterPushNotificationRequestSchema);
+		if (!parsed.success) return secureJson(c, options.pairing, secureSessionsByTokenHash, validationError(parsed.error), 400);
+		const clientSessionId = await pairedClientSessionIdForAuthorization(c.req.header("authorization"), options.pairing);
+		if (!clientSessionId) return secureJson(c, options.pairing, secureSessionsByTokenHash, apiError("push_notifications_unavailable", "Pair this device again to manage notifications."), 401);
+		await options.pairing.sessions.upsertPushNotificationSubscription({
+			actionRequired: parsed.data.preferences.actionRequired,
+			clientSessionId,
+			expoPushToken: parsed.data.expoPushToken,
+			platform: parsed.data.platform,
+			turnTerminal: parsed.data.preferences.turnTerminal
+		});
+		const response = PushNotificationSettingsResponseSchema.parse({
+			preferences: parsed.data.preferences,
+			registered: true
+		});
+		return secureJson(c, options.pairing, secureSessionsByTokenHash, response);
+	});
+	app.delete(apiPaths.pushNotifications, async (c) => {
+		const clientSessionId = await pairedClientSessionIdForAuthorization(c.req.header("authorization"), options.pairing);
+		if (!clientSessionId) return secureJson(c, options.pairing, secureSessionsByTokenHash, apiError("push_notifications_unavailable", "Pair this device again to manage notifications."), 401);
+		await options.pairing.sessions.deletePushNotificationSubscription(clientSessionId);
+		const response = PushNotificationSettingsResponseSchema.parse({
+			preferences: defaultPushNotificationPreferences(),
+			registered: false
+		});
+		return secureJson(c, options.pairing, secureSessionsByTokenHash, response);
+	});
 	app.get(apiPaths.workspaceDirectories, async (c) => {
 		const targetPath = resolve(c.req.query("path") ?? workspacePath);
 		try {
@@ -2106,44 +2402,46 @@ function createApp(options = {}) {
 	});
 	app.post("/v1/threads/:threadId/input", async (c) => {
 		const threadId = c.req.param("threadId");
-		const knownThread = await ensureKnownThread({
-			appServer,
-			threadId,
-			messagesByThreadId,
-			threads
-		});
-		if (!knownThread) return secureJson(c, options.pairing, secureSessionsByTokenHash, apiError("not_found", `Thread ${threadId} is not known to this server.`), 404);
-		if (!appServer) return secureJson(c, options.pairing, secureSessionsByTokenHash, apiError("unsupported", "Running-thread input requires the Codex app-server."), 409);
-		if (knownThread.state !== "running") return secureJson(c, options.pairing, secureSessionsByTokenHash, apiError("thread_not_running", `Thread ${threadId} is not currently running.`), 409);
-		const parsed = await parseRequestJson(c, options.pairing, secureSessionsByTokenHash, RunThreadRequestSchema);
-		if (!parsed.success) return secureJson(c, options.pairing, secureSessionsByTokenHash, validationError(parsed.error), 400);
-		const runOptions = withRuntimePreferences(await preferences.read(knownThread.cwd ?? workspacePath), parsed.data);
-		const skills = runOptions.skills ?? [];
-		const prompt = runOptions.prompt;
-		const queuedInputs = queuedInputsByThreadId.get(threadId) ?? [];
-		const queuedInput = {
-			attachments: runOptions.attachments ?? [],
-			id: randomUUID(),
-			prompt,
-			runOptions,
-			skills,
-			workspacePath: knownThread.cwd ?? workspacePath
-		};
-		queuedInputs.push(queuedInput);
-		queuedInputsByThreadId.set(threadId, queuedInputs);
-		const thread = updateThread(threads, messagesByThreadId, threadId, {
-			state: "running",
-			lastPrompt: promptWithAttachmentReferences(prompt, runOptions.attachments ?? []),
-			lastError: void 0,
-			...runtimeMetadataFromOptions(runOptions)
-		});
-		const response = SubmitThreadInputResponseSchema.parse({
-			acceptedAs: "queued",
-			input: queuedThreadInputSummary(queuedInput),
-			queueLength: queuedInputsByThreadId.get(threadId)?.length ?? 0,
-			thread
+		return runThreadOperation(threadId, async () => {
+			const knownThread = await ensureKnownThread({
+				appServer,
+				threadId,
+				messagesByThreadId,
+				threads
+			});
+			if (!knownThread) return secureJson(c, options.pairing, secureSessionsByTokenHash, apiError("not_found", `Thread ${threadId} is not known to this server.`), 404);
+			if (!appServer) return secureJson(c, options.pairing, secureSessionsByTokenHash, apiError("unsupported", "Running-thread input requires the Codex app-server."), 409);
+			if (knownThread.state !== "running") return secureJson(c, options.pairing, secureSessionsByTokenHash, apiError("thread_not_running", `Thread ${threadId} is not currently running.`), 409);
+			const parsed = await parseRequestJson(c, options.pairing, secureSessionsByTokenHash, RunThreadRequestSchema);
+			if (!parsed.success) return secureJson(c, options.pairing, secureSessionsByTokenHash, validationError(parsed.error), 400);
+			const runOptions = withRuntimePreferences(await preferences.read(knownThread.cwd ?? workspacePath), parsed.data);
+			const skills = runOptions.skills ?? [];
+			const prompt = runOptions.prompt;
+			const queuedInputs = queuedInputsByThreadId.get(threadId) ?? [];
+			const queuedInput = {
+				attachments: runOptions.attachments ?? [],
+				id: randomUUID(),
+				prompt,
+				runOptions,
+				skills,
+				workspacePath: knownThread.cwd ?? workspacePath
+			};
+			queuedInputs.push(queuedInput);
+			queuedInputsByThreadId.set(threadId, queuedInputs);
+			const thread = updateThread(threads, messagesByThreadId, threadId, {
+				state: "running",
+				lastPrompt: promptWithAttachmentReferences(prompt, runOptions.attachments ?? []),
+				lastError: void 0,
+				...runtimeMetadataFromOptions(runOptions)
+			});
+			const response = SubmitThreadInputResponseSchema.parse({
+				acceptedAs: "queued",
+				input: queuedThreadInputSummary(queuedInput),
+				queueLength: queuedInputsByThreadId.get(threadId)?.length ?? 0,
+				thread
+			});
+			return secureJson(c, options.pairing, secureSessionsByTokenHash, response, 202);
 		});
-		return secureJson(c, options.pairing, secureSessionsByTokenHash, response, 202);
 	});
 	app.delete("/v1/threads/:threadId/input/:inputId", async (c) => {
 		const threadId = c.req.param("threadId");
@@ -2364,6 +2662,7 @@ function createApp(options = {}) {
 					messagesByThreadId,
 					pendingApprovals,
 					queuedInputsByThreadId,
+					runThreadOperation,
 					prompt: rawPrompt,
 					attachments: runOptions.attachments ?? [],
 					secureSession,
@@ -2406,6 +2705,18 @@ function createApp(options = {}) {
 function parseBearerToken(value) {
 	return (value?.match(/^Bearer\s+(.+)$/i))?.[1];
 }
+async function pairedClientSessionIdForAuthorization(authorization, pairing) {
+	if (!pairing) return;
+	const token = parseBearerToken(authorization);
+	if (!token) return;
+	return (await pairing.sessions.getValidSession(pairing.hashClientToken(token), Date.now()))?.clientSessionId;
+}
+function defaultPushNotificationPreferences() {
+	return {
+		actionRequired: false,
+		turnTerminal: false
+	};
+}
 function normalizeApprovalCode(value) {
 	const normalized = value.toUpperCase().replace(/[^A-Z0-9]/g, "").replaceAll("O", "0").replaceAll("I", "1");
 	return normalized.length === 8 ? `${normalized.slice(0, 4)}-${normalized.slice(4)}` : normalized;
@@ -2564,6 +2875,7 @@ async function runPromptStreamed(input) {
 			messagesByThreadId: input.messagesByThreadId,
 			pendingApprovals: input.pendingApprovals,
 			queuedInputsByThreadId: input.queuedInputsByThreadId,
+			runThreadOperation: input.runThreadOperation,
 			prompt: input.prompt,
 			runOptions: input.runOptions,
 			secureSession: input.secureSession,
@@ -3395,11 +3707,16 @@ async function runAppServerPromptStreamed(input) {
 					case "turn/failed": {
 						const state = terminalTurnState(notification.method, params);
 						const terminalTurnId = firstString(params, ["turnId"]) ?? turnIdFromParams(params) ?? activeTurnId;
-						finishTerminalTurn({
-							lastError: state === "failed" ? turnErrorMessage(params) : void 0,
-							method: notification.method,
-							state,
-							turnId: terminalTurnId
+						input.runThreadOperation(activeThreadId, async () => {
+							finishTerminalTurn({
+								lastError: state === "failed" ? turnErrorMessage(params) : void 0,
+								method: notification.method,
+								state,
+								turnId: terminalTurnId
+							});
+						}).catch((error) => {
+							cleanupNotificationHandler();
+							rejectCompleted(error);
 						});
 						return;
 					}
@@ -5421,6 +5738,74 @@ function structuredStreamMessage(role, event, fallbackContent) {
 function isApprovalServerRequest(method) {
 	return method === "item/commandExecution/requestApproval" || method === "item/fileChange/requestApproval" || method === "item/permissions/requestApproval" || method === "item/tool/requestUserInput" || method === "mcpServer/elicitation/request" || method === "execCommandApproval" || method === "applyPatchApproval";
 }
+function observeAppServerPushNotifications(appServer, dispatcher) {
+	const dispatchedEventIds = /* @__PURE__ */ new Set();
+	const subagentThreadIds = /* @__PURE__ */ new Set();
+	const rememberEventId = (eventId) => {
+		if (dispatchedEventIds.size >= 1e3) dispatchedEventIds.clear();
+		dispatchedEventIds.add(eventId);
+	};
+	const dispatch = (event, eventId) => {
+		if (dispatchedEventIds.has(eventId)) return;
+		rememberEventId(eventId);
+		dispatcher.dispatch(event).catch((error) => {
+			relayDebugLog("push_notification.dispatch_failed", {
+				error: errorMessage(error),
+				intent: event.intent,
+				threadId: event.threadId,
+				turnId: event.turnId
+			});
+		});
+	};
+	appServer.onNotification((notification) => {
+		rememberSubagentThreadIds(notification, subagentThreadIds);
+		const event = pushNotificationEventFromTerminalNotification(notification);
+		if (!event) return;
+		const eventId = `${event.intent}:${event.threadId}:${event.turnId ?? ""}`;
+		if (subagentThreadIds.delete(event.threadId)) {
+			rememberEventId(eventId);
+			return;
+		}
+		dispatch(event, eventId);
+	});
+	appServer.onRequest((request) => {
+		const event = pushNotificationEventFromApprovalRequest(request);
+		if (!event) return;
+		dispatch(event, `${event.intent}:${event.threadId}:${event.turnId ?? ""}:${request.id}`);
+	});
+}
+function rememberSubagentThreadIds(notification, subagentThreadIds) {
+	const item = objectRecord(recordParams(notification)?.item);
+	if (item?.type !== "collabAgentToolCall" || ![
+		"spawnAgent",
+		"sendInput",
+		"resumeAgent"
+	].includes(String(item.tool))) return;
+	for (const threadId of stringArray(item.receiverThreadIds)) subagentThreadIds.add(threadId);
+}
+function pushNotificationEventFromTerminalNotification(notification) {
+	if (notification.method !== "turn/completed" && notification.method !== "turn/failed") return;
+	const params = recordParams(notification);
+	const status = turnStatus(params);
+	if (status === "aborted" || status === "cancelled" || status === "canceled" || status === "interrupted") return;
+	const threadId = firstString(params, ["threadId", "conversationId"]);
+	if (!threadId) return;
+	return {
+		intent: "turn_terminal",
+		threadId,
+		turnId: firstString(params, ["turnId"]) ?? turnIdFromParams(params)
+	};
+}
+function pushNotificationEventFromApprovalRequest(request) {
+	if (!isApprovalServerRequest(request.method)) return;
+	const approval = approvalMessageFromRequest(request);
+	if (!approval) return;
+	return {
+		intent: "action_required",
+		threadId: approval.threadId,
+		turnId: approval.turnId
+	};
+}
 function approvalMessageFromRequest(request) {
 	const params = recordParams(request);
 	const threadId = firstString(params, ["threadId", "conversationId"]);
@@ -6480,7 +6865,7 @@ serve({
 		listenUrl,
 		pairingPayload,
 		port: info.port,
-		sharedAppServer: appServerMode === "socket"
+		sharedAppServerRemoteAddress: appServerMode === "socket" ? resolveCodexSharedAppServerRemoteAddress() : void 0
 	}));
 });
 function stopSharedAppServer(exitCode) {
@@ -6499,9 +6884,9 @@ function formatStartupInstructions(details) {
 			`${color.prompt("›")} Server: ${color.muted(details.listenUrl)}`,
 			"",
 			`${color.prompt("›")} Pairing: ${color.url(details.pairingPayload)}`,
-			...details.sharedAppServer ? [
+			...details.sharedAppServerRemoteAddress ? [
 				"",
-				`${color.prompt("›")} Terminal: ${color.command("codex resume --remote unix://")}`,
+				`${color.prompt("›")} Terminal: ${color.command(`codex resume --remote ${details.sharedAppServerRemoteAddress}`)}`,
 				`  ${color.muted("Connect through the shared Codex app-server to follow and steer the same live sessions.")}`
 			] : [],
 			"",