@openclaw/codex 2026.10.5-beta.4 → 2026.10.10-beta.1

package/README.md

@@ -26,7 +26,7 @@ Local discovery reads native provenance from plain or compressed rollouts. A fai
 
 With `appServer.remoteWorkspaceRoot`, OpenClaw maps workspace-relative paths to the remote root. Local filesystem-root workspaces, including `/` and Windows drive roots, follow the same mapping.
 
-A supervised OpenClaw Chat cannot be deleted while its model-selection lock protects the native binding. Before native archive, OpenClaw checks the exact target and every non-archived spawned descendant reported by Codex; any active OpenClaw binding blocks the operation. Descendant pagination errors, cycles, and safety-limit exhaustion also fail closed. Codex still does not expose a conditional archive operation or cross-process runner lease, so the confirmation covers unknown native clients and the race between the status read and archive request.
+A supervised OpenClaw Chat cannot be deleted while its model-selection lock protects the native binding. Before native archive, OpenClaw checks the exact target and every non-archived spawned descendant reported by Codex; any active OpenClaw binding blocks the operation. Descendant pagination errors, cycles, and safety-limit exhaustion also block archive. Codex still does not expose a conditional archive operation or cross-process runner lease, so the confirmation covers unknown native clients and the race between the status read and archive request.
 
 Disabling or uninstalling the plugin leaves supervised Chats locked and unavailable rather than rerouting them. Reinstall or re-enable the same plugin and restart the Gateway to resume those Chats.
 
@@ -34,9 +34,9 @@ These shell commands differ from the in-chat `/codex` runtime commands. In parti
 
 Native Codex plugin catalogs are discoverable with `/codex plugins available`, including repository marketplaces declared in `.agents/plugins/marketplace.json` in the bound workspace. An owner or `operator.admin` can install and authorize an exact plugin with `/codex plugins install <plugin>@<marketplace>`. The owner-scoped `codex_plugins` agent tool only reads marketplace metadata; installation and policy changes stay on authenticated `/codex` management commands. Explicitly installing a plugin trusts its skills, apps, MCP servers, and hooks.
 
-Cached app inventory diagnostics reflect the current refresh or invalidation. Failures from superseded requests remain logged without replacing that newer status.
+Catalog and app-inventory refreshes are best effort while settings, installed plugins, or desktop artifacts change. An in-flight read can publish its captured metadata; a later refresh, cache expiry, or restart picks up the change. Normal parallel refreshes retain unrelated apps, while authorization is checked separately when work executes. An app-server or desktop replacement during an operation may return an error instead of automatically replaying the operation.
 
-For a supervised branch, Codex App Server selects the snapshot fork's model and provider from its current native configuration. OpenClaw starts the canonical harness thread with exactly that returned pair. Codex persists the canonical thread's native selection, and later resumes preserve it because OpenClaw omits model and provider overrides. OpenClaw cannot substitute its outer runtime, model, or fallback. The returned initial pair can differ from the source's last recorded model.
+For a supervised branch, Codex App Server selects the snapshot fork's model and provider from its current native configuration. OpenClaw starts the OpenClaw harness thread with exactly that returned pair. Codex persists the harness thread's native selection, and later resumes preserve it because OpenClaw omits model and provider overrides. OpenClaw cannot substitute its outer runtime, model, or fallback. The returned initial pair can differ from the source's last recorded model.
 
 The visible-history mirror keeps at most 200 user or assistant messages, 512 KiB total, and 64 KiB per message. Image inputs become `[Image attachment]`; image data and local paths are not copied.
 
@@ -46,4 +46,11 @@ Settled-turn finalization uses the same configured Codex App Server transport as
 
 When settled-turn recovery rejects history, the `codex settled-turn finalization context capture failed` warning includes a stable `reason`, such as `item_limit`, `byte_limit`, `field_limit`, `unsupported_user_image`, or `snapshot_invalidated`. Unknown failures use `history_read_failed`. The warning excludes transcript content and exception text. Rejected history remains unavailable for finalization, and completed actions are never replayed.
 
+The `codex_app_server.item` agent-event stream includes native item lifecycle events
+and raw function, custom/code-mode, local-shell, and tool-search call receipts.
+Calls publish `phase: "started"` and recorded outputs publish `phase: "completed"`,
+correlated by `itemId` (the native `call_id`). Raw receipt events carry only phase,
+item ID, and type, not arguments or results. An outer code-mode call remains open
+even when its child command items have completed.
+
 See the [Codex harness](https://docs.openclaw.ai/plugins/codex-harness) and [Codex supervision](https://docs.openclaw.ai/plugins/codex-supervision) guides.

package/dist/.setup/{account-usage-runtime-CoVpNIlD.mjs → account-usage-runtime-DDCDkvtl.mjs}

@@ -1,13 +1,14 @@
 import { n as isCodexAppServerProxyLaunch } from "./launch-args-DbFCehO7.mjs";
-import { t as buildCodexAppServerUsageSnapshot } from "./rate-limits-CI8pTPqL.mjs";
-import { t as readCodexAppServerUsage } from "./request-Bo0kKABI.mjs";
-import "./config-C1YVVLEA.mjs";
-import { n as resolveCodexAppServerRuntimeOptions } from "./config-runtime-DWzK-k0n.mjs";
-import { a as resolveCodexAppServerAuthProfileStore } from "./auth-profile-CgHQ8Vot.mjs";
+import { t as buildCodexAppServerUsageSnapshot } from "./rate-limits-BpfURnuy.mjs";
+import { t as readCodexAppServerUsage } from "./request-ePeNJrOd.mjs";
+import "./config-BfrAlTMT.mjs";
+import { n as resolveCodexAppServerRuntimeOptions } from "./config-runtime-BZRizyuG.mjs";
+import { a as resolveCodexAppServerAuthProfileStore } from "./auth-profile-auwzSwwy.mjs";
 import { isDeepStrictEqual } from "node:util";
 import { listAgentIds, resolveAgentDir } from "openclaw/plugin-sdk/agent-scope-runtime";
 import { z } from "zod";
 import { ErrorCodes, errorShape } from "openclaw/plugin-sdk/gateway-runtime";
+import { ensureAuthProfileStore } from "openclaw/plugin-sdk/provider-auth";
 //#region extensions/codex/src/account-usage-runtime.ts
 const paramsSchema = z.object({
 	agentId: z.string().min(1),
@@ -28,19 +29,24 @@ async function handleCodexAccountUsage({ params, respond, context, signal, hasCu
 	}
 	try {
 		const agentDir = resolveAgentDir(config, agentId);
-		const readStore = () => resolveCodexAppServerAuthProfileStore({
+		const store = structuredClone(await resolveCodexAppServerAuthProfileStore({
 			agentDir,
 			authProfileId: profileId,
 			config
-		});
-		const store = structuredClone(readStore());
+		}));
 		const credential = store.profiles[profileId];
 		if (!credential || credential.provider !== "openai" || credential.type === "api_key") {
 			invalid("Select a saved Codex subscription login.");
 			return;
 		}
 		const assertCurrent = () => {
-			if (signal?.aborted || hasCurrentClientAuthority?.() === false || context.getRuntimeConfig() !== config || !isDeepStrictEqual(readStore().profiles[profileId], store.profiles[profileId])) throw new Error("Account credentials changed. Refresh Models and try again.");
+			if (signal?.aborted || hasCurrentClientAuthority?.() === false || context.getRuntimeConfig() !== config || !isDeepStrictEqual(ensureAuthProfileStore(agentDir, {
+				profileId,
+				allowKeychainPrompt: false,
+				config,
+				externalCliProviderIds: ["openai"],
+				externalCliProfileIds: [profileId]
+			}).profiles[profileId], store.profiles[profileId])) throw new Error("Account credentials changed. Refresh Models and try again.");
 		};
 		assertCurrent();
 		const { start } = resolveCodexAppServerRuntimeOptions({ pluginConfig: config.plugins?.entries?.codex?.config });

package/dist/.setup/{app-server-policy-D_zv8J7V.mjs → app-server-policy-Cog6mm2i.mjs}

@@ -1,4 +1,4 @@
-import { n as canUseCodexModelBackedApprovalsReviewerForModel } from "./config-C1YVVLEA.mjs";
+import { n as canUseCodexModelBackedApprovalsReviewerForModel } from "./config-BfrAlTMT.mjs";
 //#region extensions/codex/src/app-server/app-server-policy.ts
 function resolveCodexAppServerForModelProvider(params) {
 	return params.appServer.approvalsReviewer === "user" || canUseCodexModelBackedApprovalsReviewerForModel({

package/dist/.setup/{apply-BXDMd05l.mjs → apply-BVSXYkTV.mjs}

@@ -1,13 +1,13 @@
-import { s as resolveCodexAppServerFallbackApiKeyCacheKey } from "./auth-cache-key-f8ODJ_OX.mjs";
-import { a as defaultCodexAppInventoryCache, r as buildCodexPluginAppCacheKey } from "./plugin-app-cache-key-Bg9DbDI6.mjs";
-import { r as requestCodexAppServerJson } from "./request-Bo0kKABI.mjs";
-import { r as isOpenAiCuratedMarketplaceName, u as CODEX_PLUGINS_MARKETPLACE_NAME } from "./plugin-inventory-CYgdo14P.mjs";
-import "./config-C1YVVLEA.mjs";
-import { n as resolveCodexAppServerRuntimeOptions } from "./config-runtime-DWzK-k0n.mjs";
-import { i as resolveCodexAppServerAuthProfileIdForAgent } from "./auth-profile-CgHQ8Vot.mjs";
-import { c as getLeasedSharedCodexAppServerClient, h as releaseLeasedSharedCodexAppServerClient, o as clearSharedCodexAppServerClientIfCurrentAndWait, tt as resolveCodexAppServerAuthAccountCacheKey } from "./shared-client-BCx1wbyA.mjs";
-import { t as ensureCodexPluginActivation } from "./plugin-activation-D7WkJMvU.mjs";
-import { CODEX_PLUGIN_CONFIG_PATH, buildCodexMigrationPlan, buildCodexPluginsConfigValue, hasCodexPluginConfigConflict, n as resolveCodexConfigPatchMode, readCodexPluginMigrationConfigEntry, t as createCodexAuthItemApplier } from "./plan-41-YOBMq.mjs";
+import { s as resolveCodexAppServerFallbackApiKeyCacheKey } from "./auth-cache-key-CVcYw8HD.mjs";
+import { a as defaultCodexAppInventoryCache, r as buildCodexPluginAppCacheKey } from "./plugin-app-cache-key-DRb-niJc.mjs";
+import { r as requestCodexAppServerJson } from "./request-ePeNJrOd.mjs";
+import { r as isOpenAiCuratedMarketplaceName, u as CODEX_PLUGINS_MARKETPLACE_NAME } from "./plugin-inventory-DE9wcaeH.mjs";
+import "./config-BfrAlTMT.mjs";
+import { n as resolveCodexAppServerRuntimeOptions } from "./config-runtime-BZRizyuG.mjs";
+import { i as resolveCodexAppServerAuthProfileIdForAgent } from "./auth-profile-auwzSwwy.mjs";
+import { Z as resolveCodexAppServerAuthAccountCacheKey, f as releaseLeasedSharedCodexAppServerClient, i as clearSharedCodexAppServerClientIfCurrentAndWait, o as getLeasedSharedCodexAppServerClient } from "./shared-client-CE_uY0A1.mjs";
+import { t as ensureCodexPluginActivation } from "./plugin-activation-CXPWe-hl.mjs";
+import { CODEX_PLUGIN_CONFIG_PATH, buildCodexMigrationPlan, buildCodexPluginsConfigValue, hasCodexPluginConfigConflict, n as resolveCodexConfigPatchMode, readCodexPluginMigrationConfigEntry, t as createCodexAuthItemApplier } from "./plan-B4cHgqNv.mjs";
 import { uniqueStrings } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { parseStrictNonNegativeInteger } from "openclaw/plugin-sdk/number-runtime";
 import path from "node:path";
@@ -250,7 +250,7 @@ function isCodexPluginLoadWarningItem(item) {
 async function buildTargetCodexPluginAppCacheKey(ctx) {
 	const targets = resolvePlannedMigrationTargets(ctx);
 	const appServer = resolveTargetCodexAppServer(ctx);
-	const authProfileId = resolveCodexAppServerAuthProfileIdForAgent({
+	const authProfileId = await resolveCodexAppServerAuthProfileIdForAgent({
 		agentDir: targets.agentDir,
 		config: ctx.config
 	});

package/dist/.setup/{attempt-client-cleanup-zNuNTKVr.mjs → attempt-client-cleanup-6OcbMH46.mjs}

@@ -1,9 +1,9 @@
-import { w as retireSharedCodexAppServerClientIfCurrent } from "./auth-cache-key-f8ODJ_OX.mjs";
-import { a as codexPrewriteRejectionCause, o as isCodexAppServerOverloadError, r as CodexAppServerRpcError } from "./rpc-error-C98SHchT.mjs";
-import { Y as unsubscribeCodexAppServerLiveThread, pt as isCodexAppServerStartupError, u as isCodexAppServerStartSelectionChangedError } from "./shared-client-BCx1wbyA.mjs";
-import { I as isCodexAppServerBrokenPipeError, c as isCodexAppServerRequestTimeoutError } from "./client-D93nbdB8.mjs";
-import { n as getCodexAppServerTurnRouter } from "./turn-router-DBVMToGo.mjs";
-import { t as __exportAll } from "./session-binding-sidecars-DD-enC8w.mjs";
+import { D as retireSharedCodexAppServerClientIfCurrent } from "./auth-cache-key-CVcYw8HD.mjs";
+import { a as codexPrewriteRejectionCause, o as isCodexAppServerOverloadError, r as CodexAppServerRpcError } from "./rpc-error-DemqqaxE.mjs";
+import { H as unsubscribeCodexAppServerLiveThread, lt as isCodexAppServerStartupError } from "./shared-client-CE_uY0A1.mjs";
+import { N as isCodexAppServerBrokenPipeError, s as isCodexAppServerRequestTimeoutError } from "./client-BS8X7HmG.mjs";
+import { n as getCodexAppServerTurnRouter } from "./turn-router-Dbw17k3K.mjs";
+import { t as __exportAll } from "./session-binding-sidecars-BNSS6WL4.mjs";
 import { createDeferred } from "openclaw/plugin-sdk/extension-shared";
 import { AgentHarnessPreflightError, embeddedAgentLog } from "openclaw/plugin-sdk/agent-harness-runtime";
 //#region extensions/codex/src/app-server/attempt-client-cleanup.ts
@@ -71,8 +71,12 @@ async function interruptCodexTurnAndWaitBestEffort(client, params) {
 	};
 	let cancelWatch;
 	try {
+		params.assertCurrent?.();
 		if (!params.turnId) {
-			await client.request("turn/interrupt", requestParams, { timeoutMs });
+			await client.request("turn/interrupt", requestParams, {
+				timeoutMs,
+				assertCurrent: params.assertCurrent
+			});
 			return true;
 		}
 		const deadline = performance.now() + timeoutMs;
@@ -87,7 +91,9 @@ async function interruptCodexTurnAndWaitBestEffort(client, params) {
 		if (completion.state !== "pending") return await completion.completion;
 		const requestInterrupt = async () => {
 			try {
+				params.assertCurrent?.();
 				await client.request("turn/interrupt", requestParams, {
+					assertCurrent: params.assertCurrent,
 					timeoutMs: Math.max(1, deadline - performance.now()),
 					signal: completion.settledSignal
 				});
@@ -149,7 +155,7 @@ async function unsubscribeCodexThreadBestEffort(client, params) {
 function shouldRetireCodexStartupClient(error, spawnedBy, signal) {
 	const cause = codexPrewriteRejectionCause(error);
 	if (signal.aborted || isCodexAppServerStartupError(cause) || isCodexAppServerRequestTimeoutError(cause)) return true;
-	return !isCodexAppServerStartSelectionChangedError(cause) && !isCodexAppServerOverloadError(cause) && !(cause instanceof AgentHarnessPreflightError && cause.scope === void 0) && (isCodexAppServerBrokenPipeError(cause) || !spawnedBy);
+	return !isCodexAppServerOverloadError(cause) && !(cause instanceof AgentHarnessPreflightError && cause.scope === void 0) && (isCodexAppServerBrokenPipeError(cause) || !spawnedBy);
 }
 //#endregion
 export { attempt_client_cleanup_exports as a, isCodexNoActiveTurnInterruptError as c, terminateCodexBackgroundTerminals as d, unsubscribeCodexThreadBestEffort as f, assertCodexThreadResumeSubscription as i, retireUnsafeCodexTurnClientBestEffort as l, CODEX_APP_SERVER_UNSUBSCRIBE_TIMEOUT_MS as n, closeCodexStartupClientBestEffort as o, CodexAppServerUnsafeSubscriptionError as r, interruptCodexTurnAndWaitBestEffort as s, CODEX_APP_SERVER_INTERRUPT_TIMEOUT_MS as t, shouldRetireCodexStartupClient as u };

package/dist/.setup/attempt-terminal-sZutF0WY.mjs

@@ -0,0 +1 @@
+export { agentHarnessAttemptTerminal as t } from "openclaw/plugin-sdk/agent-harness-runtime";

package/dist/.setup/{attempt-workspace-context-CcwP3DA3.mjs → attempt-workspace-context-GYPLawX6.mjs}

@@ -1,5 +1,5 @@
-import { r as flattenCodexDynamicToolFunctions } from "./protocol-CANUwXJ3.mjs";
-import { I as isMessageOnlyCodexSourceReply } from "./thread-requests-BgzJwJtS.mjs";
+import { n as flattenCodexDynamicToolFunctions } from "./protocol-CaPAVwe9.mjs";
+import { I as isMessageOnlyCodexSourceReply } from "./thread-requests-BjawdIVV.mjs";
 import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
 import path from "node:path";
 import { buildAgentWorkspaceInstructionSnapshot, buildBootstrapContextForFiles, embeddedAgentLog, prepareAgentWorkspaceContext } from "openclaw/plugin-sdk/agent-harness-runtime";

package/dist/.setup/{auth-binding-BaxlhaNx.mjs → auth-binding-830RLAJW.mjs}

@@ -1,5 +1,5 @@
-import { i as isCodexResponsesOAuthCredential, o as resolveCodexResponsesOAuthProfileFingerprint } from "./responses-oauth-twnuTaAa.mjs";
-import { t as __exportAll } from "./session-binding-sidecars-DD-enC8w.mjs";
+import { i as isCodexResponsesOAuthCredential, o as resolveCodexResponsesOAuthProfileFingerprint } from "./responses-oauth-CCV7aVYF.mjs";
+import { t as __exportAll } from "./session-binding-sidecars-BNSS6WL4.mjs";
 import { resolveApiKeyForProfile } from "openclaw/plugin-sdk/agent-runtime";
 import { fingerprintResolvedAuthProfileCredential } from "openclaw/plugin-sdk/agent-harness-runtime";
 import { resolveOpenAICodexAuthIdentity } from "openclaw/plugin-sdk/provider-auth";

package/dist/.setup/{auth-cache-key-f8ODJ_OX.mjs → auth-cache-key-CVcYw8HD.mjs}

@@ -1,6 +1,6 @@
-import { n as defineCodexBuildState } from "./build-state-Ds14X10-.mjs";
-import { u as resolveMacOSDesktopCodexAppPathCandidates } from "./managed-binary-BtIjV7yN.mjs";
-import { n as resolveCodexAppServerSpawnEnv } from "./transport-stdio-CRWTkKOn.mjs";
+import { n as defineCodexBuildState } from "./build-state-VcujMRqP.mjs";
+import { y as resolveMacOSDesktopCodexAppPathCandidates } from "./managed-binary-DbKvGXKl.mjs";
+import { n as resolveCodexAppServerSpawnEnv } from "./transport-stdio-Bq160Dhv.mjs";
 import { isRecord, normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { createHash } from "node:crypto";
 import fs, { constants, existsSync, watch } from "node:fs";
@@ -10,6 +10,7 @@ import fs$1 from "node:fs/promises";
 import { extractErrorCode } from "openclaw/plugin-sdk/error-runtime";
 import { sha256File } from "openclaw/plugin-sdk/file-access-runtime";
 import { sleepWithAbort } from "openclaw/plugin-sdk/retry-runtime";
+import { racePromiseWithAbortSignal } from "openclaw/plugin-sdk/time-runtime";
 import { readSecretFile } from "openclaw/plugin-sdk/secret-file";
 //#region extensions/codex/src/app-server/desktop-generation-fingerprint.ts
 const MAX_COMPUTER_USE_PLUGIN_TREE_ENTRIES = 4096;
@@ -77,7 +78,6 @@ async function readCodexDesktopArtifactTreeFingerprint(root) {
 			if (entryStat.isDirectory()) await visit(entryPath, relativePath, entryStat);
 			else hash.update(`entry\0${relativePath}\0${await statFingerprint(entryPath)}\0`);
 		}
-		if (!sameStat(before, await fs$1.lstat(directory, { bigint: true }))) throw new Error(`Codex desktop artifact changed while fingerprinting: ${directory}`);
 	};
 	await visit(root, ".", rootStat);
 	return hash.digest("hex");
@@ -87,35 +87,28 @@ async function statFingerprint(filePath) {
 		const entry = await fs$1.lstat(filePath, { bigint: true });
 		const type = entry.isSymbolicLink() ? "link" : entry.isDirectory() ? "directory" : entry.isFile() ? "file" : "other";
 		const own = statTuple(entry);
-		if (!entry.isSymbolicLink()) return `${type}:${own}:${entry.isFile() ? await readFileFingerprint(filePath, entry, false) : ""}`;
+		if (!entry.isSymbolicLink()) return `${type}:${own}:${entry.isFile() ? await readFileFingerprint(filePath, false) : ""}`;
 		const [link, realPath, target] = await Promise.all([
 			fs$1.readlink(filePath),
 			fs$1.realpath(filePath),
 			fs$1.stat(filePath, { bigint: true })
 		]);
-		const content = target.isFile() ? await readFileFingerprint(filePath, target, true) : "";
+		const content = target.isFile() ? await readFileFingerprint(filePath, true) : "";
 		return `${type}:${own}:${link}:${realPath}:${statTuple(target)}:${content}`;
 	} catch (error) {
 		return missingFingerprint(error);
 	}
 }
-async function readFileFingerprint(filePath, expected, followsSymlink) {
+async function readFileFingerprint(filePath, followsSymlink) {
 	const noFollow = followsSymlink ? 0 : constants.O_NOFOLLOW ?? 0;
 	const handle = await fs$1.open(filePath, constants.O_RDONLY | noFollow);
 	try {
 		const before = await handle.stat({ bigint: true });
-		if (!sameStat(before, expected)) throw new Error(`Codex desktop artifact changed while fingerprinting: ${filePath}`);
-		const hash = await sha256File(handle, { maxBytes: Number(before.size) });
-		const after = await handle.stat({ bigint: true });
-		if (BigInt(hash.bytes) !== before.size || !sameStat(before, after)) throw new Error(`Codex desktop artifact changed while fingerprinting: ${filePath}`);
-		return hash.digest;
+		return (await sha256File(handle, { maxBytes: Number(before.size) })).digest;
 	} finally {
 		await handle.close();
 	}
 }
-function sameStat(left, right) {
-	return statTuple(left) === statTuple(right);
-}
 function statTuple(stat) {
 	return [
 		stat.dev,
@@ -137,34 +130,29 @@ const SETTLE_DELAY_MS = 1e3;
 /** Coalesces filesystem invalidations into one stable desktop generation. */
 function createCodexDesktopGenerationOwner(params) {
 	let generation = params.initialGeneration;
-	let invalidation = 0;
-	let settledInvalidation = 0;
+	let dirty = false;
 	let refresh;
 	const markDirty = () => {
-		invalidation += 1;
+		dirty = true;
 	};
 	const reconcile = () => {
 		if (refresh) return refresh;
 		refresh = (async () => {
-			for (;;) {
-				params.signal.throwIfAborted();
-				const observedInvalidation = invalidation;
-				const first = await params.readFingerprint();
-				await sleepWithAbort(SETTLE_DELAY_MS, params.signal, { ref: false });
-				params.signal.throwIfAborted();
-				const second = await params.readFingerprint();
-				params.signal.throwIfAborted();
-				if (observedInvalidation !== invalidation || first !== second) continue;
-				const previous = generation;
-				generation = previous?.fingerprint === second ? previous : {
-					epoch: (previous?.epoch ?? 0) + 1,
-					fingerprint: second
-				};
-				settledInvalidation = invalidation;
-				if (previous && generation !== previous) params.onGenerationChange?.(generation);
-				return generation;
-			}
-		})().finally(() => {
+			await sleepWithAbort(SETTLE_DELAY_MS, params.signal, { ref: false });
+			dirty = false;
+			const fingerprint = await params.readFingerprint();
+			params.signal.throwIfAborted();
+			const previous = generation;
+			generation = previous?.fingerprint === fingerprint ? previous : {
+				epoch: (previous?.epoch ?? 0) + 1,
+				fingerprint
+			};
+			if (previous && generation !== previous) params.onGenerationChange?.(generation);
+			return generation;
+		})().catch((error) => {
+			dirty = true;
+			throw error;
+		}).finally(() => {
 			refresh = void 0;
 		});
 		return refresh;
@@ -172,12 +160,11 @@ function createCodexDesktopGenerationOwner(params) {
 	return {
 		read: () => generation,
 		markDirty,
-		wait: () => settledInvalidation !== invalidation ? reconcile() : Promise.resolve(generation),
+		wait: () => dirty ? reconcile() : refresh ?? Promise.resolve(generation),
 		refresh: () => {
 			markDirty();
 			return reconcile();
 		},
-		isCurrent: (candidate) => Boolean(candidate && !params.signal.aborted && settledInvalidation === invalidation && generation && candidate.epoch === generation.epoch && candidate.fingerprint === generation.fingerprint),
 		waitForIdle: async () => {
 			await refresh?.catch(() => {});
 		}
@@ -188,13 +175,11 @@ function createCodexDesktopGenerationOwner(params) {
 /** Lifecycle-owned generation for managed macOS Codex desktop artifacts. */
 const APPLICATIONS_PATH = "/Applications";
 const REARM_INITIAL_DELAY_MS = 100;
-const REARM_MAX_DELAY_MS = 3e4;
 const state = defineCodexBuildState("openclaw.codexDesktopGenerationState", () => ({}));
 function waitForCodexDesktopGeneration() {
-	return state().owner?.wait() ?? Promise.resolve(void 0);
-}
-function isCodexDesktopGenerationCurrent(generation) {
-	return state().owner?.isCurrent(generation) ?? false;
+	const current = state();
+	const owner = current.owner;
+	return (current.watchHealthy === false ? owner?.refresh() : owner?.wait()) ?? Promise.resolve(void 0);
 }
 function createCodexDesktopGenerationService(params, runtime = {
 	platform: process.platform,
@@ -218,7 +203,7 @@ function createCodexDesktopGenerationService(params, runtime = {
 				initialGeneration: current.lastGeneration
 			});
 			armWatchers(current);
-			refreshGeneration(current, current.owner, current.owner.refresh());
+			refreshGeneration(current, current.owner.refresh());
 		},
 		async stop() {
 			const current = state();
@@ -230,14 +215,12 @@ function createCodexDesktopGenerationService(params, runtime = {
 			current.context = void 0;
 			current.runtime = void 0;
 			current.watchHealthy = void 0;
-			current.rearmDelayMs = void 0;
-			current.rearmPending = false;
 			closeWatchers(current);
 			await Promise.all([scheduler?.stop(), owner?.waitForIdle()]);
 		}
 	};
 }
-function armWatchers(current) {
+function armWatchers(current, retryOnFailure = true) {
 	const owner = current.owner;
 	const runtime = current.runtime;
 	if (!owner || !runtime || current.watchers) return false;
@@ -249,25 +232,22 @@ function armWatchers(current) {
 		if (!runtime.pathExists(watchedPath)) continue;
 		try {
 			const watcher = runtime.watchPath(watchedPath, { recursive: watchedPath !== APPLICATIONS_PATH }, (_eventType, filename) => {
-				if (!isCurrentArm(current, owner, watchers)) return;
 				if (watchedPath === APPLICATIONS_PATH && filename && !candidateNames.has(filename.toString().split(path.sep)[0] ?? "")) return;
 				owner.markDirty();
 				scheduleRearm(current, owner);
 			});
 			watchers.add(watcher);
 			watcher.on("error", (error) => {
-				if (!isCurrentArm(current, owner, watchers)) return;
 				reportWatcherFailure(current, owner, error);
 				scheduleRearm(current, owner);
 			});
 		} catch (error) {
 			complete = false;
 			reportWatcherFailure(current, owner, error);
-			scheduleRearm(current, owner);
 		}
 	}
 	current.watchHealthy = complete;
-	if (complete) current.rearmDelayMs = REARM_INITIAL_DELAY_MS;
+	if (!complete && retryOnFailure) scheduleRearm(current, owner, false);
 	return complete;
 }
 function reportWatcherFailure(current, owner, error) {
@@ -277,32 +257,24 @@ function reportWatcherFailure(current, owner, error) {
 	current.context?.serviceHealth?.reportFailure(error);
 	current.context?.logger.warn(`codex desktop generation watcher failed: ${String(error)}`);
 }
-function isCurrentArm(current, owner, watchers) {
-	return isCurrentOwner(current, owner) && current.watchers === watchers;
-}
-function scheduleRearm(current, owner) {
-	if (current.rearmPending && current.watchHealthy === false) return;
-	const delayMs = current.watchHealthy === false ? current.rearmDelayMs ?? REARM_INITIAL_DELAY_MS : REARM_INITIAL_DELAY_MS;
-	if (current.watchHealthy === false) current.rearmDelayMs = Math.min(delayMs * 2, REARM_MAX_DELAY_MS);
-	current.rearmPending = true;
+function scheduleRearm(current, owner, retryOnFailure = true) {
+	if (current.context?.scheduler.signal.aborted) return;
 	current.context?.scheduler.schedule({
 		id: "watcher-rearm",
-		delayMs,
+		delayMs: REARM_INITIAL_DELAY_MS,
 		run: async () => {
-			current.rearmPending = false;
-			if (!isCurrentOwner(current, owner)) return;
 			const wasUnhealthy = current.watchHealthy === false;
 			closeWatchers(current);
-			if (!armWatchers(current) || wasUnhealthy) owner.markDirty();
-			await refreshGeneration(current, owner, owner.wait());
+			if (!armWatchers(current, retryOnFailure) || wasUnhealthy) owner.markDirty();
+			await refreshGeneration(current, owner.wait());
 		}
 	});
 }
-function refreshGeneration(current, owner, refresh) {
+function refreshGeneration(current, refresh) {
 	return refresh.then(() => {
-		if (isCurrentOwner(current, owner) && current.watchHealthy) current.context?.serviceHealth?.clearFailure();
+		if (!current.context?.scheduler.signal.aborted && current.watchHealthy) current.context?.serviceHealth?.clearFailure();
 	}).catch((error) => {
-		if (!isCurrentOwner(current, owner)) return;
+		if (!current.context || current.context.scheduler.signal.aborted) return;
 		current.context?.serviceHealth?.reportFailure(error);
 		current.context?.logger.warn(`codex desktop generation refresh failed: ${String(error)}`);
 	});
@@ -312,9 +284,6 @@ function closeWatchers(current) {
 	current.watchers = void 0;
 	for (const watcher of watchers ?? []) watcher.close();
 }
-function isCurrentOwner(current, owner) {
-	return current.owner === owner && !current.context?.scheduler.signal.aborted;
-}
 //#endregion
 //#region extensions/codex/src/app-server/shared-client-lifecycle.ts
 /** Client ownership and synchronous retirement, independent of startup/auth execution. */
@@ -351,11 +320,36 @@ function getOrCreateSharedClientEntry(state, key) {
 	}
 	return entry;
 }
+var SharedCodexFallbackJoinError = class extends Error {
+	constructor() {
+		super("Shared Codex fallback already has a startup owner");
+		this.code = "CODEX_SHARED_FALLBACK_JOIN";
+		this.name = "SharedCodexFallbackJoinError";
+	}
+};
+function isSharedCodexFallbackJoinError(error) {
+	return error instanceof Error && "code" in error && error.code === "CODEX_SHARED_FALLBACK_JOIN";
+}
+/**
+* Moves a current entry to the fallback key. False means the caller must
+* re-acquire instead of starting a second client under an already-owned key.
+*/
+function rekeySharedClientEntry(entry, key) {
+	const state = getSharedCodexAppServerClientState();
+	if (state.clients.get(entry.key) !== entry) return false;
+	const target = state.clients.get(key);
+	if (target) return target === entry;
+	state.clients.delete(entry.key);
+	entry.key = key;
+	state.clients.set(key, entry);
+	return true;
+}
 function closeSharedClientEntryIfUnclaimed(entry) {
 	if (entry.activeLeases > 0 || entry.pendingAcquires > 0) return false;
 	const state = getSharedCodexAppServerClientState();
 	if (state.clients.get(entry.key) !== entry) return false;
 	state.clients.delete(entry.key);
+	cancelSharedClientIdleRetirement(entry);
 	entry.client?.close();
 	return Boolean(entry.client);
 }
@@ -374,7 +368,6 @@ const getSharedCodexAppServerClientState = defineCodexBuildState("openclaw.codex
 	liveClients: /* @__PURE__ */ new Set(),
 	isolatedClients: /* @__PURE__ */ new Set(),
 	entriesByClient: /* @__PURE__ */ new WeakMap(),
-	desktopGenerationDrainChecks: /* @__PURE__ */ new Set(),
 	startup: createCodexAppServerStartupLifetime(),
 	startMetadata: /* @__PURE__ */ new WeakMap()
 }));
@@ -408,6 +401,7 @@ function retireSharedCodexAppServerClientIfCurrent(client, opts) {
 	const currentEntry = getCurrentSharedClientEntry(client);
 	const entry = currentEntry ?? state.entriesByClient.get(client);
 	if (!entry || entry.client !== client && !entry.closeError) return;
+	cancelSharedClientIdleRetirement(entry);
 	if (currentEntry) {
 		state.clients.delete(entry.key);
 		entry.closeWhenIdle = true;
@@ -442,6 +436,7 @@ function closeRetiredSharedClientEntry(entry) {
 	const client = entry.client;
 	if (!client) return false;
 	entry.client = void 0;
+	cancelSharedClientIdleRetirement(entry);
 	client.close();
 	return true;
 }
@@ -468,7 +463,7 @@ function waitForCodexAppServerClientExit(client) {
 	return exited;
 }
 /** Acquire the recorded owner atomically, or join its exit before a replacement writes. */
-async function retainSharedCodexAppServerClientByInstanceId(clientId) {
+async function retainSharedCodexAppServerClientByInstanceId(clientId, options) {
 	const id = clientId?.trim();
 	if (!id) return;
 	const state = getSharedCodexAppServerClientState();
@@ -476,7 +471,8 @@ async function retainSharedCodexAppServerClientByInstanceId(clientId) {
 		if (client.getInstanceId() !== id) continue;
 		const entry = state.entriesByClient.get(client);
 		if (entry?.client !== client || entry.closeError || client.getCloseError()) {
-			await waitForCodexAppServerClientExit(client);
+			if (options?.waitForExit === false && client.getCloseError()) return;
+			await racePromiseWithAbortSignal(waitForCodexAppServerClientExit(client), options?.signal, options?.createAbortError);
 			return;
 		}
 		const release = retainSharedClientEntry(entry);
@@ -484,16 +480,32 @@ async function retainSharedCodexAppServerClientByInstanceId(clientId) {
 			client,
 			release: (waitForRetirement = false) => {
 				release();
-				return client.getCloseError() || waitForRetirement && entry.closeWhenIdle ? waitForCodexAppServerClientExit(client) : void 0;
+				return options?.waitForExit !== false && (client.getCloseError() || waitForRetirement && entry.closeWhenIdle) ? waitForCodexAppServerClientExit(client) : void 0;
 			}
 		};
 	}
 }
-function notifyDesktopGenerationDrainChecks(state) {
-	for (const check of state.desktopGenerationDrainChecks) check();
+const CODEX_APP_SERVER_CLIENT_IDLE_GRACE_MS = 3e4;
+function cancelSharedClientIdleRetirement(entry) {
+	clearTimeout(entry.idleTimer);
+	entry.idleTimer = void 0;
+}
+function refreshSharedClientIdleRetirement(client) {
+	const entry = getCurrentSharedClientEntry(client);
+	if (entry) scheduleSharedClientIdleRetirement(entry);
+}
+function scheduleSharedClientIdleRetirement(entry) {
+	cancelSharedClientIdleRetirement(entry);
+	if (entry.activeLeases > 0 || entry.pendingAcquires > 0 || !entry.client || entry.hasOwnedThreads?.() || getCurrentSharedClientEntry(entry.client) !== entry) return;
+	entry.idleTimer = setTimeout(() => {
+		entry.idleTimer = void 0;
+		if (entry.activeLeases === 0 && entry.pendingAcquires === 0 && !entry.hasOwnedThreads?.()) retireSharedCodexAppServerClientIfCurrent(entry.client);
+	}, CODEX_APP_SERVER_CLIENT_IDLE_GRACE_MS);
+	entry.idleTimer.unref?.();
 }
 function retainSharedClientEntry(entry, counter = "activeLeases") {
 	let released = false;
+	cancelSharedClientIdleRetirement(entry);
 	entry[counter] += 1;
 	return () => {
 		if (released) return;
@@ -504,7 +516,7 @@ function retainSharedClientEntry(entry, counter = "activeLeases") {
 function releaseSharedClientEntry(entry, counter) {
 	entry[counter] -= 1;
 	closeRetiredSharedClientEntryIfIdle(entry);
-	notifyDesktopGenerationDrainChecks(getSharedCodexAppServerClientState());
+	scheduleSharedClientIdleRetirement(entry);
 }
 //#endregion
 //#region extensions/codex/src/app-server/auth-cache-key.ts
@@ -514,7 +526,7 @@ const CODEX_APP_SERVER_API_KEY_ENV_VARS = ["CODEX_API_KEY", "OPENAI_API_KEY"];
 function resolveCodexAppServerFallbackApiKeyCacheKey(params) {
 	if (params.startOptions.transport !== "stdio") return;
 	const apiKey = readFirstNonEmptyEnvEntry(resolveCodexAppServerSpawnEnv(params.startOptions, params.baseEnv ?? process.env, params.platform ?? process.platform), CODEX_APP_SERVER_API_KEY_ENV_VARS);
-	if (!apiKey) return resolveCodexCliAuthFileApiKeyCacheKey(params.baseEnv ?? process.env);
+	if (!apiKey) return params.allowNativeAuthFile === false ? void 0 : resolveCodexCliAuthFileApiKeyCacheKey(params.baseEnv ?? process.env);
 	return fingerprintAuthCacheKey(apiKey.key, "env-api-key", apiKey.key, apiKey.value);
 }
 /** Secret-free cache identity for an API key already resolved by the runtime plan. */
@@ -576,4 +588,4 @@ function readFirstNonEmptyEnvEntry(env, keys) {
 	}
 }
 //#endregion
-export { waitForCodexDesktopGeneration as A, retirePendingSharedClientEntryIfUnclaimed as C, waitForUnclaimedSharedClientStartup as D, waitForCodexAppServerClientExit as E, createCodexDesktopGenerationService as O, retainSharedCodexAppServerClientByInstanceId as S, retireSharedCodexAppServerClientsBeforeDesktopGeneration as T, observeSharedClientAcquire as _, readCodexCliAuthFileApiKey as a, releaseSharedClientEntry as b, resolveCodexAppServerPreparedApiKeyCacheKey as c, getCurrentSharedClientEntry as d, getOrCreateSharedClientEntry as f, observeAcquire as g, notifyDesktopGenerationDrainChecks as h, fingerprintTokenAuthProfileCacheKey as i, readCodexDesktopArtifactTreeFingerprint as j, isCodexDesktopGenerationCurrent as k, closeSharedClientEntryIfUnclaimed as l, hasActiveSharedCodexAppServerWork as m, CODEX_AUTH_JSON_FILENAME as n, readFirstNonEmptyEnv as o, getSharedCodexAppServerClientState as p, fingerprintApiKeyAuthProfileCacheKey as r, resolveCodexAppServerFallbackApiKeyCacheKey as s, CODEX_APP_SERVER_API_KEY_ENV_VARS as t, createCodexAppServerStartupLifetime as u, ownCodexStartup as v, retireSharedCodexAppServerClientIfCurrent as w, retainSharedClientEntry as x, recordSharedClientAcquireBoundary as y };
+export { waitForUnclaimedSharedClientStartup as A, releaseSharedClientEntry as C, retireSharedCodexAppServerClientIfCurrent as D, retirePendingSharedClientEntryIfUnclaimed as E, waitForCodexDesktopGeneration as M, readCodexDesktopArtifactTreeFingerprint as N, retireSharedCodexAppServerClientsBeforeDesktopGeneration as O, rekeySharedClientEntry as S, retainSharedCodexAppServerClientByInstanceId as T, observeAcquire as _, readCodexCliAuthFileApiKey as a, recordSharedClientAcquireBoundary as b, resolveCodexAppServerPreparedApiKeyCacheKey as c, createCodexAppServerStartupLifetime as d, getCurrentSharedClientEntry as f, isSharedCodexFallbackJoinError as g, hasActiveSharedCodexAppServerWork as h, fingerprintTokenAuthProfileCacheKey as i, createCodexDesktopGenerationService as j, waitForCodexAppServerClientExit as k, SharedCodexFallbackJoinError as l, getSharedCodexAppServerClientState as m, CODEX_AUTH_JSON_FILENAME as n, readFirstNonEmptyEnv as o, getOrCreateSharedClientEntry as p, fingerprintApiKeyAuthProfileCacheKey as r, resolveCodexAppServerFallbackApiKeyCacheKey as s, CODEX_APP_SERVER_API_KEY_ENV_VARS as t, closeSharedClientEntryIfUnclaimed as u, observeSharedClientAcquire as v, retainSharedClientEntry as w, refreshSharedClientIdleRetirement as x, ownCodexStartup as y };