@zvada/agent-server 0.3.1 → 0.3.3

package/src/core/agents/codex-app-server/codex-app-server-agent.ts

@@ -39,11 +39,19 @@ export interface AppServerSession {
 	sandbox: string;
 	systemPromptAppend?: string;
 	envFingerprint: string;
-	/** Engine permission broker for the CURRENT turn (set per execute). */
-	permissionHandler?: PermissionRequestHandler;
+	/** Native CLI auth and externally managed tokens cannot share a warm process. */
+	authMode?: CodexAppServerAuth["type"];
+	/** Credentials and permission broker belong only to the current execute. */
+	turn?: AppServerTurn;
 	idleTimer?: ReturnType<typeof setTimeout>;
 }
 
+interface AppServerTurn {
+	auth?: CodexAppServerAuth;
+	permissionHandler?: PermissionRequestHandler;
+	signal: AbortSignal;
+}
+
 export function appServerSessionCompatible(
 	existing: AppServerSession | undefined,
 	options: AgentExecuteOptions,
@@ -145,17 +153,42 @@ const IDLE_TIMEOUT_MS = 5 * 60_000;
 /** How long a retryable error may go unanswered before the turn is failed. */
 const RETRY_STALL_TIMEOUT_MS = 120_000;
 
+/** Access credentials for Codex's experimental, externally managed ChatGPT auth mode. */
+export interface CodexChatGptAuthTokens {
+	accessToken: string;
+	chatgptAccountId: string;
+	chatgptPlanType?: string | null;
+}
+
+/** The host owns login, durable token storage, refresh serialization, and revocation. */
+export interface CodexChatGptAuth {
+	type: "chatgptAuthTokens";
+	tokens: CodexChatGptAuthTokens;
+	refresh(previousAccountId: string): Promise<CodexChatGptAuthTokens>;
+}
+
+export type CodexAppServerAuth = { type: "apiKey"; apiKey: string } | CodexChatGptAuth;
+
 export interface CodexAppServerAgentOptions {
 	createClient?: (options: CodexAppServerClientOptions) => CodexAppServerClient;
 	idleTimeoutMs?: number;
 	/** Fail a turn if the app-server goes silent this long after a retryable error. */
 	retryStallTimeoutMs?: number;
+	/** Deadline for interrupt acknowledgement and the cancelled turn to drain. */
+	cancelGraceMs?: number;
 	/**
 	 * Resolve the `codex` binary to spawn (typically the provisioner's,
 	 * memoized). Falls back to `$CODEX_CLI_PATH`, then PATH. Operator-level
 	 * only — never sourced from the wire.
 	 */
 	resolveCliPath?: () => Promise<string | undefined>;
+	/**
+	 * Resolve the selected API key or ChatGPT account before EVERY turn, including warm
+	 * sessions. Operator-only: neither callbacks nor tokens belong in RunConfig.
+	 * Return undefined to select native CLI auth; throw when the selected external
+	 * account is unavailable. Switching back to native auth recreates the process.
+	 */
+	resolveAuth?: (sessionId: string) => Promise<CodexAppServerAuth | undefined>;
 }
 
 /** Retryable v2 `error` notifications do not end the turn; Codex keeps going. */
@@ -176,12 +209,22 @@ export class CodexAppServerAgent extends BaseAgent {
 	readonly harness = "codex-app-server" as const;
 	readonly capabilities = CAPABILITIES;
 	private readonly sessions = new SessionStore<AppServerSession>();
+	/** A cancel acknowledgement belongs to one invocation, even after it drains. */
+	private readonly turnInterruptState = new WeakMap<
+		AbortController,
+		{ acknowledgement?: Promise<boolean> }
+	>();
 
 	constructor(private readonly agentOptions: CodexAppServerAgentOptions = {}) {
 		super();
 	}
 
-	private async resolveSession(options: AgentExecuteOptions): Promise<AppServerSession> {
+	private async resolveSession(
+		options: AgentExecuteOptions,
+		turn: AppServerTurn,
+	): Promise<AppServerSession> {
+		const { signal } = turn;
+		signal.throwIfAborted();
 		const approvalPolicy = approvalPolicyFor(options);
 		const sandbox = mapSandbox(options.permissionMode);
 		const existing = this.sessions.get(options.sessionId);
@@ -190,9 +233,21 @@ export class CodexAppServerAgent extends BaseAgent {
 		// survives. `resumeThreadId` carries that over to the spawn below.
 		let resumeThreadId = options.resumeSessionId;
 		if (existing && !existing.client.closed) {
-			if (appServerSessionCompatible(existing, options)) {
+			if (appServerSessionCompatible(existing, options) && existing.authMode === turn.auth?.type) {
 				this.sessions.clearIdle(existing);
-				return existing;
+				existing.turn = turn;
+				const onAbort = () => existing.client.close();
+				signal.addEventListener("abort", onAbort, { once: true });
+				try {
+					await this.authenticate(existing);
+					return existing;
+				} catch (error) {
+					existing.turn = undefined;
+					existing.client.close();
+					throw error;
+				} finally {
+					signal.removeEventListener("abort", onAbort);
+				}
 			}
 			// Preserve context within the same cwd/env boundary (mirrors the
 			// claude-code restart policy); an explicit resumeSessionId always wins.
@@ -211,63 +266,134 @@ export class CodexAppServerAgent extends BaseAgent {
 				(await this.agentOptions.resolveCliPath?.()) ?? process.env.CODEX_CLI_PATH ?? "codex",
 			cwd: options.cwd,
 			env: options.env ? ({ ...process.env, ...options.env } as NodeJS.ProcessEnv) : process.env,
+			...(turn.auth?.type === "chatgptAuthTokens" && { experimentalApi: true }),
 		};
+		signal.throwIfAborted();
 		const client =
 			this.agentOptions.createClient?.(clientOptions) ?? new CodexAppServerClient(clientOptions);
 		// Self-heal: if the subprocess ever exits, drop it so the next turn respawns.
 		client.onClose(() => this.sessions.dropIfCurrent(options.sessionId, client));
-		await client.initialize();
-
-		const startParams: Record<string, unknown> = {
-			cwd: options.cwd,
-			sandbox,
-			approvalPolicy,
-			experimentalRawEvents: false,
-			persistExtendedHistory: false,
-		};
-		if (options.model) startParams.model = options.model;
-		if (options.systemPromptAppend) startParams.developerInstructions = options.systemPromptAppend;
-
-		// A dead/unknown resume target ("no rollout found ...") must not kill the
-		// turn: ANY resume failure falls back to a fresh thread, and the fresh id
-		// ≠ requested id makes execute() report resumed:false — the structured
-		// fallback signal (claude/acp parity). Systemic failures (auth, dead
-		// subprocess) fail thread/start identically, so nothing is masked.
-		const startThread = async (): Promise<string> => {
-			const r = (await client.request("thread/start", startParams)) as {
-				thread?: { id?: string };
-			};
-			if (!r?.thread?.id) throw new Error("codex app-server thread/start returned no thread id");
-			return r.thread.id;
-		};
-		let threadId: string | undefined;
-		if (resumeThreadId) {
-			threadId = await client
-				.request("thread/resume", { threadId: resumeThreadId, ...startParams })
-				.then((r) => (r as { thread?: { id?: string } })?.thread?.id ?? resumeThreadId)
-				.catch(() => undefined);
-		}
-		threadId ??= await startThread();
-
+		const untrack = this.sessions.trackPending(options.sessionId, client);
+		const onAbort = () => client.close();
+		signal.addEventListener("abort", onAbort, { once: true });
 		const session: AppServerSession = {
 			client,
-			threadId,
+			threadId: "",
 			cwd: options.cwd,
 			approvalPolicy,
 			sandbox,
 			systemPromptAppend: options.systemPromptAppend,
 			envFingerprint: configFingerprint(options.env),
+			authMode: turn.auth?.type,
+			turn,
 		};
+		this.bindRequests(session);
+		try {
+			signal.throwIfAborted();
+			await client.initialize();
+			await this.authenticate(session);
+
+			const startParams: Record<string, unknown> = {
+				cwd: options.cwd,
+				sandbox,
+				approvalPolicy,
+				experimentalRawEvents: false,
+				persistExtendedHistory: false,
+			};
+			if (options.model) startParams.model = options.model;
+			if (options.systemPromptAppend)
+				startParams.developerInstructions = options.systemPromptAppend;
+
+			// A dead/unknown resume target falls back to a fresh thread. Auth was
+			// established above, outside this fallback, so a login failure cannot
+			// silently start a different conversation or use ambient credentials.
+			let threadId: string | undefined;
+			if (resumeThreadId) {
+				threadId = await client
+					.request("thread/resume", { threadId: resumeThreadId, ...startParams })
+					.then((r) => (r as { thread?: { id?: string } })?.thread?.id ?? resumeThreadId)
+					.catch(() => undefined);
+			}
+			signal.throwIfAborted();
+			if (!threadId) {
+				const result = (await client.request("thread/start", startParams)) as {
+					thread?: { id?: string };
+				};
+				threadId = result?.thread?.id;
+				if (!threadId) throw new Error("codex app-server thread/start returned no thread id");
+			}
+			signal.throwIfAborted();
+			session.threadId = threadId;
+			this.sessions.set(options.sessionId, session);
+			return session;
+		} catch (error) {
+			session.turn = undefined;
+			client.setRequestHandler(undefined);
+			client.close();
+			throw error;
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+			untrack();
+		}
+	}
+
+	private async authenticate(session: AppServerSession): Promise<void> {
+		session.turn?.signal.throwIfAborted();
+		const auth = session.turn?.auth;
+		if (auth) {
+			await session.client.request(
+				"account/login/start",
+				auth.type === "apiKey"
+					? { type: "apiKey", apiKey: auth.apiKey }
+					: {
+							type: "chatgptAuthTokens",
+							accessToken: auth.tokens.accessToken,
+							chatgptAccountId: auth.tokens.chatgptAccountId,
+							chatgptPlanType: auth.tokens.chatgptPlanType ?? null,
+						},
+			);
+		}
+		session.turn?.signal.throwIfAborted();
+	}
+
+	private bindRequests(session: AppServerSession): void {
 		// Approval requests (server→client) resolve against the engine broker of
 		// whichever turn is current; thread mismatches and broker-less turns decline.
-		client.setRequestHandler(async (method, params) => {
+		session.client.setRequestHandler(async (method, params) => {
+			const turn = session.turn;
+			if (method === "account/chatgptAuthTokens/refresh") {
+				if (
+					turn?.auth?.type !== "chatgptAuthTokens" ||
+					turn.signal.aborted ||
+					session.client.closed
+				) {
+					throw new Error("Codex ChatGPT refresh has no active authenticated turn");
+				}
+				const accountId = turn.auth.tokens.chatgptAccountId;
+				if (params.previousAccountId != null && params.previousAccountId !== accountId) {
+					throw new Error("Codex ChatGPT refresh account does not match the selected account");
+				}
+				const tokens = await turn.auth.refresh(accountId);
+				if (session.turn !== turn || turn.signal.aborted || session.client.closed) {
+					throw new Error("Codex ChatGPT refresh outlived its turn");
+				}
+				if (tokens.chatgptAccountId !== accountId) {
+					throw new Error("Codex ChatGPT refresh returned a different account");
+				}
+				return {
+					accessToken: tokens.accessToken,
+					chatgptAccountId: tokens.chatgptAccountId,
+					chatgptPlanType: tokens.chatgptPlanType ?? null,
+				};
+			}
 			const requestThread = params.threadId ?? params.conversationId;
 			const v2 = method.startsWith("item/");
 			const decline = v2 ? { decision: "decline" } : { decision: "denied" };
 			if (requestThread && requestThread !== session.threadId) return decline;
-			const handler = session.permissionHandler;
-			if (!handler) return decline;
+			const handler = turn?.permissionHandler;
+			if (!handler || turn?.signal.aborted) return decline;
 			const decision = await handler(approvalToolCall(method, params));
+			if (session.turn !== turn || turn?.signal.aborted) return decline;
 			// Codex's approval reply is a bare verdict — no slot for
 			// `decision.updatedInput`, so an edited input cannot be honoured here
 			// (only claude-code's `canUseTool` can execute the edit). An edited
@@ -283,8 +409,6 @@ export class CodexAppServerAgent extends BaseAgent {
 					return decline;
 			}
 		});
-		this.sessions.set(options.sessionId, session);
-		return session;
 	}
 
 	async *execute(
@@ -292,19 +416,31 @@ export class CodexAppServerAgent extends BaseAgent {
 		options: AgentExecuteOptions,
 	): AsyncIterableIterator<RawAgentEvent> {
 		const controller = this.trackTurn(options.sessionId, options.signal);
+		const turn: AppServerTurn = {
+			permissionHandler: options.onPermissionRequest,
+			signal: controller.signal,
+		};
+		const interruptState: { acknowledgement?: Promise<boolean> } = {};
+		this.turnInterruptState.set(controller, interruptState);
 		const queue = new AsyncQueue<CodexNotification>();
 		// A retryable error promises more notifications. If none arrive, the
 		// subprocess is wedged-but-alive and the turn would hang forever — bound it.
 		let stallTimer: ReturnType<typeof setTimeout> | undefined;
+		let cancelTimer: ReturnType<typeof setTimeout> | undefined;
 		const clearStall = () => {
 			if (stallTimer) clearTimeout(stallTimer);
 			stallTimer = undefined;
 		};
 		const unsubscribe: Array<() => void> = [];
 		let session: AppServerSession | undefined;
+		let turnEnded = false;
 		try {
-			session = await this.resolveSession(options);
-			session.permissionHandler = options.onPermissionRequest;
+			controller.signal.throwIfAborted();
+			if (this.agentOptions.resolveAuth) {
+				turn.auth = await this.agentOptions.resolveAuth(options.sessionId);
+			}
+			controller.signal.throwIfAborted();
+			session = await this.resolveSession(options, turn);
 			options.onNativeSession?.(session.threadId, {
 				resumed: session.threadId === options.resumeSessionId,
 			});
@@ -312,11 +448,31 @@ export class CodexAppServerAgent extends BaseAgent {
 			const client = session.client;
 
 			let turnId: string | undefined;
-			let aborted = false;
-			const interrupt = () => {
-				if (turnId) {
-					void client.request("turn/interrupt", { threadId, turnId }).catch(() => {});
+			const forceCancel = () => {
+				if (turnEnded) return;
+				queue.fail(new Error("turn aborted"));
+				client.close();
+			};
+			const onAbort = () => {
+				clearStall();
+				if (interruptState.acknowledgement) return;
+				if (!turnId) {
+					interruptState.acknowledgement = Promise.resolve(false);
+					forceCancel();
+					return;
 				}
+				const graceMs = this.agentOptions.cancelGraceMs ?? 2_000;
+				cancelTimer = setTimeout(forceCancel, graceMs);
+				cancelTimer.unref?.();
+				interruptState.acknowledgement = client
+					.request("turn/interrupt", { threadId, turnId }, graceMs)
+					.then(
+						() => true,
+						() => {
+							forceCancel();
+							return false;
+						},
+					);
 			};
 
 			unsubscribe.push(
@@ -326,17 +482,21 @@ export class CodexAppServerAgent extends BaseAgent {
 						const turn = n.params.turn as { id?: string } | undefined;
 						if (turn?.id) {
 							turnId = turn.id;
-							if (aborted) interrupt(); // abort arrived before the turn id was known
 						}
 					}
+					if (appServerNotificationEndsTurn(n)) turnEnded = true;
+					if (turnEnded && controller.signal.aborted) {
+						queue.fail(new Error("turn aborted"));
+						return;
+					}
 					queue.push(n);
 					if (appServerNotificationEndsTurn(n)) queue.end();
-					if (n.method === "error" && n.params.willRetry === true) {
+					if (!controller.signal.aborted && n.method === "error" && n.params.willRetry === true) {
 						clearStall();
-						stallTimer = setTimeout(
-							() => queue.fail(new Error("codex app-server went silent after a retryable error")),
-							this.agentOptions.retryStallTimeoutMs ?? RETRY_STALL_TIMEOUT_MS,
-						);
+						stallTimer = setTimeout(() => {
+							queue.fail(new Error("codex app-server went silent after a retryable error"));
+							client.close();
+						}, this.agentOptions.retryStallTimeoutMs ?? RETRY_STALL_TIMEOUT_MS);
 						stallTimer.unref?.();
 					} else {
 						clearStall();
@@ -345,19 +505,17 @@ export class CodexAppServerAgent extends BaseAgent {
 			);
 			// If the subprocess dies mid-turn, fail the turn instead of hanging.
 			unsubscribe.push(
-				client.onClose((err) => queue.fail(err ?? new Error("codex app-server exited mid-turn"))),
+				client.onClose((err) =>
+					queue.fail(
+						controller.signal.aborted
+							? new Error("turn aborted")
+							: (err ?? new Error("codex app-server exited mid-turn")),
+					),
+				),
 			);
 
-			controller.signal.addEventListener(
-				"abort",
-				() => {
-					aborted = true;
-					interrupt();
-					// Surface as a cancellation: the runtime classifies this as aborted.
-					queue.fail(new Error("turn aborted"));
-				},
-				{ once: true },
-			);
+			controller.signal.addEventListener("abort", onAbort, { once: true });
+			unsubscribe.push(() => controller.signal.removeEventListener("abort", onAbort));
 
 			const turnParams: Record<string, unknown> = {
 				threadId,
@@ -366,7 +524,12 @@ export class CodexAppServerAgent extends BaseAgent {
 			if (options.model) turnParams.model = options.model;
 			if (options.thinkingLevel) turnParams.effort = codexReasoningEffort(options.thinkingLevel);
 
+			if (controller.signal.aborted) throw new Error("turn aborted");
 			client.request("turn/start", turnParams).catch((err: unknown) => {
+				if (controller.signal.aborted) {
+					forceCancel();
+					return;
+				}
 				queue.push({ method: "error", params: { message: String(err) } });
 				queue.end();
 			});
@@ -374,22 +537,41 @@ export class CodexAppServerAgent extends BaseAgent {
 			for await (const notification of queue) {
 				yield notification as RawAgentEvent;
 			}
+		} catch (error) {
+			throw controller.signal.aborted ? new Error("turn aborted") : error;
 		} finally {
+			turnEnded = true;
 			clearStall();
+			if (cancelTimer) clearTimeout(cancelTimer);
 			for (const off of unsubscribe) off();
 			this.endTurn(options.sessionId, controller);
-			if (session && !session.client.closed) {
-				this.sessions.armIdle(
-					options.sessionId,
-					session,
-					this.agentOptions.idleTimeoutMs ?? IDLE_TIMEOUT_MS,
-				);
+			if (session?.turn === turn) {
+				session.turn = undefined;
+				if (!session.client.closed) {
+					this.sessions.armIdle(
+						options.sessionId,
+						session,
+						this.agentOptions.idleTimeoutMs ?? IDLE_TIMEOUT_MS,
+					);
+				}
 			}
 		}
 	}
 
 	override async cancel(sessionId: string): Promise<CancelResult> {
-		return await super.cancel(sessionId);
+		// Snapshot the in-flight controllers before super.cancel() aborts them:
+		// the abort unblocks execute()'s queue and finally's endTurn drains the
+		// set on a later microtask, so reading afterwards would race that drain.
+		const controllers = [...(this.inflight.get(sessionId) ?? [])];
+		const base = await super.cancel(sessionId);
+		if (!base.hadTurn) return base;
+		const acknowledgements = await Promise.all(
+			controllers.map(
+				(controller) => this.turnInterruptState.get(controller)?.acknowledgement ?? false,
+			),
+		);
+		const confirmed = acknowledgements.every(Boolean);
+		return { confirmed, hadTurn: true };
 	}
 
 	override async release(sessionId: string): Promise<void> {

package/src/core/agents/codex-sdk/adapter.ts

@@ -44,6 +44,7 @@ interface CodexEvent {
 	usage?: {
 		input_tokens?: number;
 		cached_input_tokens?: number;
+		cache_write_input_tokens?: number;
 		output_tokens?: number;
 		reasoning_output_tokens?: number;
 	};
@@ -83,18 +84,17 @@ export class CodexSdkTransformer implements EventTransformer<unknown> {
 				this.finishReason = "completed";
 				this.stopReason = "end_turn";
 				if (!ev.usage) return [];
+				const totalInput = ev.usage.input_tokens ?? 0;
+				const cached = ev.usage.cached_input_tokens ?? 0;
+				const written = ev.usage.cache_write_input_tokens ?? 0;
 				this.usage = {
-					input: ev.usage.input_tokens ?? 0,
+					// Input and cache buckets are disjoint in the normalized protocol.
+					input: Math.max(totalInput - cached - written, 0),
 					output: ev.usage.output_tokens ?? 0,
 					reasoning: ev.usage.reasoning_output_tokens ?? 0,
-					cache: { read: ev.usage.cached_input_tokens ?? 0, write: 0 },
+					cache: { read: cached, write: written },
 				};
-				// The SDK reports usage only at turn end; input covers the full prompt
-				// context, so it doubles as the context gauge.
-				const used =
-					(ev.usage.input_tokens ?? 0) +
-					(ev.usage.cached_input_tokens ?? 0) +
-					(ev.usage.output_tokens ?? 0);
+				const used = totalInput + (ev.usage.output_tokens ?? 0);
 				return [{ kind: "usage", used }];
 			}
 			case "turn.failed":

package/src/core/agents/codex-sdk/codex-sdk-agent.ts

@@ -1,6 +1,6 @@
 import type { Codex, Thread, ThreadEvent, ThreadOptions } from "@openai/codex-sdk";
 import type { AgentCapabilities, AgentInput, PermissionMode } from "../../../protocol/index.ts";
-import { codexReasoningEffort } from "../../../protocol/index.ts";
+import { codexReasoningEffort, isCancellation } from "../../../protocol/index.ts";
 import type { AgentExecuteOptions, RawAgentEvent } from "../base.ts";
 import { BaseAgent } from "../base.ts";
 import { configFingerprint } from "../config-fingerprint.ts";
@@ -19,6 +19,7 @@ const CAPABILITIES: AgentCapabilities = {
 
 export interface LiveThread {
 	thread: Thread;
+	codexPathOverride?: string;
 	model?: string;
 	thinkingLevel?: string;
 	cwd: string;
@@ -49,8 +50,10 @@ function directoriesFingerprint(
  */
 function instanceFingerprint(
 	options: Pick<AgentExecuteOptions, "apiKey" | "env" | "systemPromptAppend">,
+	codexPathOverride: string | undefined,
 ): string {
 	return configFingerprint({
+		codexPathOverride,
 		apiKey: options.apiKey,
 		env: options.env,
 		// One equality convention with codexThreadCompatible: absent == empty.
@@ -115,9 +118,9 @@ function threadOptions(options: AgentExecuteOptions): ThreadOptions {
 
 export interface CodexSdkAgentOptions {
 	/**
-	 * Resolve the `codex` binary to spawn (typically the provisioner's,
-	 * memoized). `undefined` defers to the SDK's own lookup. Operator-level
-	 * only — never sourced from the wire.
+	 * Resolve the `codex` binary before each execution, including warm turns.
+	 * `undefined` defers to the SDK's own lookup. Operator-level only — never
+	 * sourced from the wire.
 	 */
 	resolveCliPath?: () => Promise<string | undefined>;
 }
@@ -134,7 +137,7 @@ export class CodexSdkAgent extends BaseAgent {
 	readonly capabilities = CAPABILITIES;
 	private readonly threads = new Map<string, LiveThread>();
 	// Instance-level config (credentials AND developer_instructions) is fixed
-	// at construction, so one instance per distinct (apiKey, env, append) —
+	// at construction, so one instance per distinct (path, apiKey, env, append) —
 	// keying by a fingerprint prevents one session's key or instructions from
 	// bleeding into another's.
 	private readonly codexByCreds = new Map<string, Codex>();
@@ -143,11 +146,13 @@ export class CodexSdkAgent extends BaseAgent {
 		super();
 	}
 
-	private async getCodex(options: AgentExecuteOptions): Promise<Codex> {
-		const fingerprint = instanceFingerprint(options);
+	private async getCodex(
+		options: AgentExecuteOptions,
+		codexPathOverride: string | undefined,
+	): Promise<Codex> {
+		const fingerprint = instanceFingerprint(options, codexPathOverride);
 		const cached = this.codexByCreds.get(fingerprint);
 		if (cached) return cached;
-		const codexPathOverride = await this.agentOptions.resolveCliPath?.();
 		const { Codex } = await import("@openai/codex-sdk");
 		const codex = new Codex({
 			...(codexPathOverride ? { codexPathOverride } : {}),
@@ -161,12 +166,23 @@ export class CodexSdkAgent extends BaseAgent {
 		return codex;
 	}
 
-	private async resolveThread(options: AgentExecuteOptions): Promise<LiveThread> {
+	private async resolveThread(
+		options: AgentExecuteOptions,
+		signal?: AbortSignal,
+	): Promise<LiveThread> {
+		// The SDK spawns again on every run, even when the Thread is reused.
+		const codexPathOverride = await this.agentOptions.resolveCliPath?.();
 		const existing = this.threads.get(options.sessionId);
 		const effort = options.thinkingLevel;
-		if (existing && codexThreadCompatible(existing, options)) return existing;
+		if (
+			existing &&
+			existing.codexPathOverride === codexPathOverride &&
+			codexThreadCompatible(existing, options)
+		)
+			return existing;
 
-		const codex = await this.getCodex(options);
+		const codex = await this.getCodex(options, codexPathOverride);
+		if (signal?.aborted) throw new Error("turn aborted");
 		const fingerprint = credentialsFingerprint(options);
 		// Preserve context within the same cwd/credential boundary (mirrors the
 		// claude-code restart policy); an explicit resumeSessionId always wins.
@@ -180,6 +196,7 @@ export class CodexSdkAgent extends BaseAgent {
 			: codex.startThread(threadOptions(options));
 		const live: LiveThread = {
 			thread,
+			codexPathOverride,
 			model: options.model,
 			thinkingLevel: effort,
 			cwd: options.cwd,
@@ -198,26 +215,51 @@ export class CodexSdkAgent extends BaseAgent {
 	): AsyncIterableIterator<RawAgentEvent> {
 		const controller = this.trackTurn(options.sessionId, options.signal);
 		try {
-			const live = await this.resolveThread(options);
-			// Codex keeps the thread id on resume, so honored = same id came back.
-			const resumeInfo = (id: string) => ({ resumed: id === options.resumeSessionId });
-			if (live.thread.id) options.onNativeSession?.(live.thread.id, resumeInfo(live.thread.id));
-
-			const { events } = await live.thread.runStreamed(toCodexInput(input), {
-				signal: controller.signal,
-			});
-
-			let reported = Boolean(live.thread.id);
-			for await (const event of events as AsyncGenerator<ThreadEvent>) {
-				if (!reported && event.type === "thread.started" && event.thread_id) {
-					reported = true;
-					options.onNativeSession?.(event.thread_id, resumeInfo(event.thread_id));
+			for (let attempt = 0; attempt < 2; attempt++) {
+				if (controller.signal.aborted) throw new Error("turn aborted");
+				const attemptOptions = attempt === 0 ? options : { ...options, resumeSessionId: undefined };
+				const live = await this.resolveThread(attemptOptions, controller.signal);
+				if (controller.signal.aborted) throw new Error("turn aborted");
+				const resumeThreadId = live.thread.id;
+				let sawOutput = false;
+				let reported = false;
+				const reportSession = (id: string | null) => {
+					if (!reported && id) {
+						reported = true;
+						options.onNativeSession?.(id, { resumed: id === options.resumeSessionId });
+					}
+				};
+				try {
+					const { events } = await live.thread.runStreamed(toCodexInput(input), {
+						signal: controller.signal,
+					});
+					for await (const event of events as AsyncGenerator<ThreadEvent>) {
+						sawOutput = true;
+						reportSession(event.type === "thread.started" ? event.thread_id : live.thread.id);
+						yield event as RawAgentEvent;
+					}
+					reportSession(live.thread.id);
+					return;
+				} catch (error) {
+					// Only a proven missing rollout is safe to retry without its history.
+					// Temporary failures and cancellation must retain a valid native id.
+					const missingId =
+						error instanceof Error
+							? /no rollout found for thread id ([^\s]+)/.exec(error.message)?.[1]
+							: undefined;
+					if (
+						attempt !== 0 ||
+						!resumeThreadId ||
+						missingId !== resumeThreadId ||
+						sawOutput ||
+						controller.signal.aborted ||
+						isCancellation(error)
+					) {
+						throw error;
+					}
+					if (this.threads.get(options.sessionId) === live) this.threads.delete(options.sessionId);
 				}
-				yield event as RawAgentEvent;
 			}
-			// thread.id is populated once the turn has started.
-			if (!reported && live.thread.id)
-				options.onNativeSession?.(live.thread.id, resumeInfo(live.thread.id));
 		} finally {
 			this.endTurn(options.sessionId, controller);
 		}