@bitkyc08/opencodex 2.56.0 → 2.57.0

package/src/cli/combo.ts

@@ -15,7 +15,8 @@ const USAGE = `Usage:
   ocx combo show <id> [--json]
   ocx combo set <id> --targets <provider/model[:weight],...>
       [--strategy <failover|round-robin|random|least-used|reset-window>] [--sticky <1-100>]
-      [--effort <low|medium|high|xhigh|max|ultra|->] [--alias <name|->]
+      [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force>]
+      (force overrides valid client effort and can increase cost/latency) [--alias <name|->]
       [--native-alias] [--display-name <label|->]
       [--rename-from <id>] [--json]
   ocx combo remove <id> --yes [--json]`;
@@ -80,6 +81,10 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     if (strategy !== "round-robin") throw new CliUsageError("--sticky applies only to round-robin", USAGE);
   }
   const effort = takeOption(args, "--effort");
+  const effortMode = takeOption(args, "--effort-mode");
+  if (effortMode !== undefined && effortMode !== "fallback" && effortMode !== "force") {
+    throw new CliUsageError("--effort-mode must be fallback or force", USAGE);
+  }
   const alias = takeOption(args, "--alias");
   const nativeAlias = takeFlag(args, "--native-alias");
   const displayName = takeOption(args, "--display-name");
@@ -91,12 +96,16 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     targets: parseTargets(targetsRaw),
   };
   if (effort !== undefined) combo.defaultEffort = effort === "-" ? null : effort;
+  if (effortMode !== undefined) combo.defaultEffortMode = effortMode;
   if (alias !== undefined) combo.alias = alias === "-" ? "" : alias;
   if (nativeAlias) combo.nativeAlias = true;
   if (displayName !== undefined) combo.displayName = displayName === "-" ? "" : displayName;
   const current = await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", {}, deps);
   const existing = (current.combos ?? []).find(row => row.id === (renameFrom ?? id));
   if (existing?.imageInput === "disabled") combo.imageInput = "disabled";
+  if (effortMode === undefined && existing?.defaultEffortMode === "force") {
+    combo.defaultEffortMode = effort === "-" ? "fallback" : "force";
+  }
   const result = await runtimeRequest("/api/combos", {
     method: "PUT",
     body: JSON.stringify({ id, combo, ...(renameFrom ? { renameFrom } : {}) }),

package/src/cli/index.ts

@@ -15,7 +15,7 @@ try {
 }
 import { currentExternalCodexModelProvider, restoreNativeCodex, restoreNativeCodexAsync, shouldInjectApiAuthHeader } from "../codex/inject";
 import { stripGrokConfig } from "../grok/inject";
-import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "../update/stop-contract.mjs";
+import { STOP_HISTORY_DEFERRED_EXIT_CODE, STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "../update/stop-contract.mjs";
 import {
   describeHistoryJobFailure,
   resolveCodexHistoryJobTarget,
@@ -46,6 +46,7 @@ import {
   isPendingTeardownAbandoned,
   listPendingTeardowns,
   pendingTeardownPathFor,
+  pendingTeardownsAreExactly,
   quarantinePendingTeardown,
 } from "../config/pending-teardown";
 import { collectStatus, hubStatusLines, remoteHubBannerLine, remoteHubStatusLines, unusedProxyWarningLines } from "./status";
@@ -785,9 +786,16 @@ async function handleRestartStartWhenStopped(): Promise<boolean | "skipped"> {
  *
  * The distinction exists because `ocx update` must proceed for the first and abort for the
  * second, and it can only see an exit code (#3008).
+ *
+ * `historyDeferred` is the third kind (#4718). The Codex history preflight refuses BEFORE
+ * the config half runs, so nothing was restored at all: config, catalog, history and
+ * provenance are untouched and the client is still routed at the proxy that just stopped.
+ * Like `historyOnly` the proxy is genuinely down, so an update may replace package files.
+ * Unlike `historyOnly` the obligation was not performed, so the receipt must survive.
  */
-async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boolean; other: boolean }> {
+async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boolean; historyDeferred: boolean; other: boolean }> {
   let historyOnly = false;
+  let historyDeferred = false;
   let other = false;
   try {
     const result = await restoreNativeCodexAsync();
@@ -798,7 +806,16 @@ async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boole
       // not — a client reads those, so their failure is a real teardown failure.
       const artifacts = result.artifacts;
       const configOrCatalogFailed = artifacts.config.state === "failed" || artifacts.catalog.state === "failed";
-      if (!configOrCatalogFailed && artifacts.history.state === "failed") historyOnly = true;
+      // A preflight refusal reports every artifact as `skipped` because none of them were
+      // attempted. Reading the states alone cannot tell that apart from an ownership
+      // refusal, so the structured reason carries it and the states are still required to
+      // agree — a refusal that somehow reports a failed artifact is not this case.
+      const preflightRefused = result.historyPreflightRefusal !== undefined
+        && artifacts.config.state === "skipped"
+        && artifacts.catalog.state === "skipped"
+        && artifacts.history.state === "skipped";
+      if (preflightRefused) historyDeferred = true;
+      else if (!configOrCatalogFailed && artifacts.history.state === "failed") historyOnly = true;
       else other = true;
       console.error(`⚠️  ${result.message}`);
     }
@@ -816,7 +833,7 @@ async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boole
     other = true;
     console.error(`⚠️  Grok config restore failed: ${error instanceof Error ? error.message : String(error)}`);
   }
-  return { historyOnly, other };
+  return { historyOnly, historyDeferred, other };
 }
 
 async function handleStop() {
@@ -860,6 +877,11 @@ async function handleStop() {
   };
   let stopFailed = false;
   let historyOnlyFailure = false;
+  /**
+   * Obligations this run deliberately kept because the Codex history preflight refused
+   * before restoring anything (#4718). Non-null selects the deferred exit code.
+   */
+  let historyDeferredNonces: string[] | null = null;
   // Only Task Scheduler respawns after a successful stop (#764), so only it earns the
   // restart-window wait; launchd, systemd and WinSW are down when they say so.
   let schedulerCanRespawn = false;
@@ -1138,6 +1160,7 @@ async function handleStop() {
     }
     const restore = await restoreSharedClientStateAfterStop();
     if (restore.other) stopFailed = true;
+    else if (restore.historyDeferred) historyDeferredNonces = teardownNonce ? [teardownNonce, ...recoveredNonces] : recoveredNonces;
     else if (restore.historyOnly) historyOnlyFailure = true;
     // The obligation is discharged whether or not history metadata finalized: config and
     // catalog are what a client reads, and `restore.other` already fails the stop.
@@ -1145,7 +1168,16 @@ async function handleStop() {
     // Each nonce names its own file, so a clear can only ever remove the obligation it
     // names — never one a concurrent stop wrote. Both this run's claim and every inherited
     // receipt it proved discharged are released together.
-    if (!restore.other) {
+    //
+    // A history-preflight refusal is the exception: it restored nothing, so there is
+    // nothing to discharge. Clearing here would drop a real obligation on the floor and
+    // leave the client config pointing at a proxy that is gone, with nothing on disk
+    // saying so — which is the whole failure the receipt exists to prevent (#4718).
+    if (restore.historyDeferred) {
+      console.error("   The shared teardown was refused before it changed anything, so it is still owed.");
+      console.error("   Its receipt is preserved; run 'ocx stop' again once Codex is closed to retry the restore.");
+    }
+    if (!restore.other && !restore.historyDeferred) {
       const discharged = teardownNonce ? [teardownNonce, ...recoveredNonces] : recoveredNonces;
       for (const nonce of discharged) {
         // A receipt that survives its discharge re-triggers recovery forever, so a failed
@@ -1185,6 +1217,17 @@ async function handleStop() {
   // still wins: it is the stronger signal.
   if (stopFailed) process.exitCode = 1;
   else if (historyOnlyFailure) process.exitCode = STOP_HISTORY_INCOMPLETE_EXIT_CODE;
+  // The deferred code says "the only obligations left are the ones I just decided to
+  // keep". It is read across a process boundary by an updater that will replace package
+  // files on the strength of it, so this run has to be able to prove the claim: if any
+  // other obligation is sitting in the home — quarantined, or a concurrent stop's — the
+  // claim is false and the ordinary failure code is the honest answer. That is also the
+  // behaviour before #4718, so the fallback loses nothing that used to work.
+  else if (historyDeferredNonces) {
+    process.exitCode = pendingTeardownsAreExactly(historyDeferredNonces)
+      ? STOP_HISTORY_DEFERRED_EXIT_CODE
+      : 1;
+  }
   return !stopFailed;
 }
 

package/src/cli/registry.ts

@@ -407,7 +407,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "Ensures the proxy is running, then execs `claude` with ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN,",
       "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 and model slots from config.claudeCode.",
       "When Claude routing is explicitly disabled, it launches natively after removing proven OpenCodex-owned proxy state.",
-      "Routed models appear in the native /model picker with stable claude-opus-4-8-2026MMDD slot aliases (Claude Code >= 2.1.129).",
+      "Routed models appear in the native /model picker with stable claude-opus-4-8-YYYYMMDD slot aliases,",
+      "where the year runs 2026-2035 and 2026 slots are allocated first (Claude Code >= 2.1.129).",
       "Older versions: pick models via ANTHROPIC_MODEL or /model <id> directly (any string passes through).",
       "User-exported ANTHROPIC_* variables take precedence for routed launches; native fallback removes only proven OpenCodex-owned proxy values.",
       "",

package/src/cli/system-command.ts

@@ -130,14 +130,14 @@ export async function handleSystemCommand(argv: string[], deps: RuntimeApiDeps =
       const args = [...rest]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE);
       printData(await runtimeRequest("/api/system/codex-app-server", {}, deps), wantsJson);
     } else if (sub === "codex-restart") {
-      // --yes required: this restarts the user's running Codex app-server, so it is exactly the
-      // class of action that must not happen because an agent guessed a subcommand.
+      // --yes required: this fully quits and relaunches the user's Codex desktop app as well as
+      // restarting app-servers; an agent guessing a subcommand must not interrupt that session.
       const args = [...rest];
       const wantsJson = takeFlag(args, "--json");
       const yes = takeFlag(args, "--yes");
-      if (!yes) throw new CliUsageError("system codex-restart requires --yes", USAGE);
+      if (!yes) throw new CliUsageError("system codex-restart requires --yes: this fully quits and relaunches the Codex desktop app and restarts its app-servers", USAGE);
       rejectArgs(args, USAGE);
-      printData(await runtimeRequest("/api/system/codex-restart", { method: "POST" }, deps), wantsJson, ["Codex app-server restart requested."]);
+      printData(await runtimeRequest("/api/system/codex-restart", { method: "POST" }, deps), wantsJson, ["Codex desktop app and app-server restart requested."]);
     } else if (sub === "update") await update(rest, deps);
     else throw new CliUsageError(`unknown system command ${sub}`, USAGE);
   });

package/src/clients/config-export.ts

@@ -812,6 +812,7 @@ export interface OpenclawModelEntry {
   id: string;
   name: string;
   contextWindow?: number;
+  input?: string[];
 }
 
 export interface OpenclawProviderBlock {
@@ -839,15 +840,15 @@ export interface KimiProviderBlock {
 /**
  * `max_context_size` is mandatory and must be positive, so a model with no
  * authoritative context window is omitted from the document entirely rather
- * than guessed at. `capabilities` is never emitted: our catalog does not
- * assert them, and Kimi's own inference works off OpenAI-style name prefixes
- * that a routed selector will not match.
+ * than guessed at. Catalog image input becomes `image_in`; other capabilities
+ * are not inferred from routed model names.
  */
 export interface KimiModelBlock {
   provider: string;
   model: string;
   max_context_size: number;
   display_name?: string;
+  capabilities?: ["image_in"];
 }
 
 export interface KimiGeneratedConfig {
@@ -974,10 +975,12 @@ function buildHermesClientConfig(ctx: ExportContext): HermesGeneratedConfig {
 function buildOpenclawClientConfig(ctx: ExportContext): OpenclawGeneratedConfig {
   const models: OpenclawModelEntry[] = normalizeExportModels(ctx.models).map(model => {
     const context = authoritativeContextWindow(model.contextWindow);
+    const input = [...new Set(model.inputModalities?.filter(value => ["text", "image", "video", "audio"].includes(value)))];
     return {
       id: model.namespaced,
       name: exportModelLabel(model),
       ...(context !== undefined ? { contextWindow: context } : {}),
+      ...(input.length > 0 ? { input } : {}),
     };
   });
   const headers = proxyAdmissionHeaders(ctx.config, OPENCLAW_API_KEY_ENV_REF);
@@ -1015,6 +1018,7 @@ function buildKimiClientConfig(ctx: ExportContext): KimiGeneratedConfig {
       model: model.namespaced,
       max_context_size: context,
       ...(model.displayName ? { display_name: model.displayName } : {}),
+      ...(model.inputModalities?.includes("image") ? { capabilities: ["image_in"] as ["image_in"] } : {}),
     };
   }
   return {

package/src/codex/account-label.ts

@@ -1,17 +1,19 @@
 import { createHash, randomBytes } from "node:crypto";
 import type { CodexAccount, OcxConfig } from "../types";
 import type { CodexAuthContext } from "./auth-context";
+import type { ProviderApiKeySelection } from "../types/provider";
 import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
 
 export const CODEX_ACCOUNT_LOG_LABEL_RE = /^p[a-f0-9]{6}$/;
 
 /**
- * Account log labels come in two families (#2699):
+ * Account log labels come in three families:
  *
  * - `p<hex6>` (plus the literal `main`) — a Codex pool account.
  * - `o<hex6>` — a non-Codex OAuth provider account (xai, cursor, and siblings).
+ * - `k<hex32>` — a request-owned API-key selection, scoped to provider and reference.
  *
- * Both are sha256-derived digests, never an email and never a raw provider account id. That is
+ * Labels never contain an email, raw key/reference, or raw provider account id. That is
  * a privacy requirement, not a formatting preference: these labels are written to the usage log
  * and served over the management API.
  *
@@ -20,7 +22,16 @@ export const CODEX_ACCOUNT_LOG_LABEL_RE = /^p[a-f0-9]{6}$/;
  * accepted cost of keeping the existing `p` format byte-compatible.
  */
 export const OAUTH_ACCOUNT_LOG_LABEL_RE = /^o[a-f0-9]{6}$/;
-export const ACCOUNT_LOG_LABEL_RE = /^(?:main|[po][a-f0-9]{6})$/;
+export const KEY_ACCOUNT_LOG_LABEL_RE = /^k[a-f0-9]{32}$/;
+export const ACCOUNT_LOG_LABEL_RE = /^(?:main|[po][a-f0-9]{6}|k[a-f0-9]{32})$/;
+
+/** Digest the request-owned configured selection, never serialize its key/reference. */
+export function apiKeyAccountLogLabel(provider: string, selection: ProviderApiKeySelection | undefined): `k${string}` | undefined {
+  if (!selection || typeof selection.reference !== "string" || !selection.reference.length) return undefined;
+  return `k${createHash("sha256").update(JSON.stringify([
+    "ocx-key-account-v1", provider, selection.entryId ?? null, selection.reference,
+  ])).digest("hex").slice(0, 32)}`;
+}
 
 export function oauthAccountLogLabel(accountId: string, provider = ""): string {
   return `o${createHash("sha256").update(`${provider}\0${accountId}`).digest("hex").slice(0, 6)}`;

package/src/codex/account-store.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { closeSync, existsSync, readFileSync, mkdirSync, openSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, fstatSync, readFileSync, mkdirSync, openSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import {
   ConfigMutationLockError,
@@ -268,6 +268,23 @@ export function readCodexAccountRecord(id: string): CodexAccountCredentialRecord
   return loadCodexAccountRecordStore()[id] ?? null;
 }
 
+/**
+ * One store load, every record, for a caller that resolves MANY ids in a single synchronous pass.
+ *
+ * `readCodexAccountRecord` reloads, reparses and renormalizes the whole file per id. That is the
+ * right shape for one lookup and the wrong shape for a loop: the entitlement denial reader holds
+ * up to 64 accounts with four client versions each, so scoring one warm flagship request could
+ * perform up to 256 full-store reads on the request path.
+ *
+ * These are the same normalized records `readCodexAccountRecord` hands out, tombstones included,
+ * so the caller keeps its own `deletedAt` and `generation` checks instead of trusting a filtered
+ * view. That is the difference from `loadCodexAccountStore`, which drops both and cannot answer a
+ * question about credential generation.
+ */
+export function loadCodexAccountRecordSnapshot(): Readonly<Record<string, CodexAccountCredentialRecord>> {
+  return loadCodexAccountRecordStore();
+}
+
 const QUOTA_HISTORY_IDENTITY_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 
 function validQuotaHistoryIdentity(value: unknown): value is string {
@@ -655,10 +672,43 @@ function isRefreshLockStale(path: string): boolean {
     const parsed = JSON.parse(readFileSync(path, "utf-8")) as { acquiredAt?: unknown };
     return typeof parsed.acquiredAt !== "number" || Date.now() - parsed.acquiredAt > REFRESH_LOCK_STALE_MS;
   } catch {
-    return true;
+    // The owner creates the file and writes its metadata in two steps, so a live lock is
+    // briefly unreadable. Age the file itself instead of calling that window stale, which
+    // let a waiter delete a lock whose owner was still inside its critical section.
+    try {
+      return Date.now() - statSync(path).mtimeMs > REFRESH_LOCK_STALE_MS;
+    } catch {
+      return false;
+    }
   }
 }
 
+function releaseCodexRefreshFileLock(path: string, fd: number): void {
+  let owned: { dev: bigint; ino: bigint } | null = null;
+  try {
+    const info = fstatSync(fd, { bigint: true });
+    if (info.dev >= 0n && info.ino > 0n) owned = { dev: info.dev, ino: info.ino };
+  } catch { /* Unknown descriptor identity never authorizes unlink. */ }
+  try {
+    withConfigMutationLockSync(() => {
+      let current: { dev: bigint; ino: bigint } | null = null;
+      try {
+        const info = statSync(path, { bigint: true });
+        if (info.dev >= 0n && info.ino > 0n) current = { dev: info.dev, ino: info.ino };
+      } catch { /* Keep the lock and the callback outcome when the path probe fails. */ }
+      if (owned && current && current.dev === owned.dev && current.ino === owned.ino) {
+        try { unlinkSync(path); } catch (err) {
+          if (errCode(err) !== "ENOENT") throw err;
+        }
+      }
+    });
+  } catch (err) {
+    // Keep the descriptor alive through comparison/unlink so its inode cannot be recycled.
+    // Unavailable coordination leaves the path without masking the completed refresh.
+    if (!(err instanceof ConfigMutationLockError)) throw err;
+  } finally { closeSync(fd); }
+}
+
 export async function withCodexRefreshFileLock<T>(lockKey: string, signal: AbortSignal, fn: () => Promise<T>): Promise<T> {
   hardenConfigDir();
   const dir = getConfigDir();
@@ -670,33 +720,45 @@ export async function withCodexRefreshFileLock<T>(lockKey: string, signal: Abort
   while (fd == null) {
     if (signal.aborted) throw signal.reason;
     try {
-      fd = openSync(path, "wx", 0o600);
-      writeFileSync(fd, JSON.stringify({ acquiredAt: Date.now(), pid: process.pid }) + "\n");
-      break;
-    } catch (err) {
-      if (errCode(err) !== "EEXIST") throw err;
-      if (isRefreshLockStale(path)) {
+      // Serialize only metadata operations, never the async refresh callback. Cooperating
+      // contenders cannot reclaim a successor between stale observation and path mutation.
+      withConfigMutationLockSync(() => {
         try {
-          unlinkSync(path);
-        } catch (unlinkErr) {
-          if (errCode(unlinkErr) !== "ENOENT") throw unlinkErr;
+          fd = openSync(path, "wx", 0o600);
+          writeFileSync(fd, JSON.stringify({ acquiredAt: Date.now(), pid: process.pid }) + "\n");
+        } catch (err) {
+          if (fd != null) {
+            const failedFd = fd;
+            fd = null;
+            try { releaseCodexRefreshFileLock(path, failedFd); } catch { /* Preserve write failure. */ }
+            throw err;
+          }
+          if (errCode(err) !== "EEXIST") throw err;
+          if (isRefreshLockStale(path)) {
+            try { unlinkSync(path); } catch (unlinkErr) {
+              if (errCode(unlinkErr) !== "ENOENT") throw unlinkErr;
+            }
+          }
         }
-        continue;
+      });
+    } catch (err) {
+      // A failed SQLite commit can follow successful file creation; it still owns an fd.
+      if (fd != null) {
+        const failedFd = fd;
+        fd = null;
+        try { releaseCodexRefreshFileLock(path, failedFd); } catch { /* Preserve admission failure. */ }
       }
-      if (Date.now() >= deadline) throw new CodexCredentialRefreshLockTimeoutError();
-      await sleep(REFRESH_LOCK_POLL_MS, signal);
+      if (!(err instanceof ConfigMutationLockError)) throw err;
     }
+    if (fd != null) break;
+    if (Date.now() >= deadline) throw new CodexCredentialRefreshLockTimeoutError();
+    await sleep(REFRESH_LOCK_POLL_MS, signal);
   }
 
   try {
     return await fn();
   } finally {
-    if (fd != null) closeSync(fd);
-    try {
-      unlinkSync(path);
-    } catch (err) {
-      if (errCode(err) !== "ENOENT") throw err;
-    }
+    releaseCodexRefreshFileLock(path, fd);
   }
 }
 
@@ -1137,9 +1199,20 @@ async function resolveCodexToken(
       let errDesc: string;
       let errCodeExact: string | undefined;
       try {
-        const parsed = JSON.parse(errText) as { error?: string; error_description?: string };
-        errCodeExact = typeof parsed.error === "string" ? parsed.error.trim() : undefined;
-        errDesc = [parsed.error, parsed.error_description].filter(Boolean).join(": ") || `HTTP ${res.status}`;
+        const parsed = JSON.parse(errText) as {
+          error?: string | { code?: string; message?: string };
+          error_description?: string;
+        };
+        if (typeof parsed.error === "string") {
+          errCodeExact = parsed.error.trim();
+          errDesc = [parsed.error, parsed.error_description].filter(Boolean).join(": ");
+        } else if (parsed.error && typeof parsed.error === "object") {
+          errCodeExact = typeof parsed.error.code === "string" ? parsed.error.code.trim() : undefined;
+          errDesc = [parsed.error.code, parsed.error.message, parsed.error_description].filter(Boolean).join(": ");
+        } else {
+          errDesc = parsed.error_description || `HTTP ${res.status}`;
+        }
+        if (!errDesc) errDesc = `HTTP ${res.status}`;
       } catch { errDesc = `HTTP ${res.status}`; }
       // `invalid_grant` is the standard OAuth code for a refresh token that is no longer
       // usable, and upstream sends it bare with no description. Without it here the dead
@@ -1149,9 +1222,23 @@ async function resolveCodexToken(
       // Matched on the exact `error` CODE, not anywhere in the combined text: a transient
       // `server_error` whose description happens to mention invalid_grant would otherwise
       // retire a healthy account, which is the failure this whole change exists to remove.
-      const reason = errCodeExact === "invalid_grant"
-          || errDesc.includes("invalidated") || errDesc.includes("revoked") ? "revoked" as const
-        : errDesc.includes("expired") ? "expired" as const
+      //
+      // That rule binds the DESCRIPTION words too. "invalidated", "revoked" and "expired" read
+      // as terminal prose, but upstream puts arbitrary text there: a `server_error` whose
+      // description says "token was revoked" or "session expired" is still a 5xx blip, and
+      // retiring the account on it is exactly the false quarantine #2887 exists to prevent.
+      // So a body that carries a structured code is classified by that code ALONE. The
+      // substring fallback survives only where there is no structured code to read at all --
+      // a description-only body, or one this parser could not decode -- because there the
+      // prose is the only signal upstream gave us.
+      const structuredCode = errCodeExact ? errCodeExact : undefined;
+      const proseIsOnlySignal = structuredCode === undefined;
+      const reason = structuredCode === "invalid_grant"
+          || structuredCode === "refresh_token_invalidated"
+          || (proseIsOnlySignal
+            && (errDesc.includes("invalidated") || errDesc.includes("revoked"))) ? "revoked" as const
+        : structuredCode === "refresh_token_expired"
+          || (proseIsOnlySignal && errDesc.includes("expired")) ? "expired" as const
         : "unknown" as const;
       throw new TokenRefreshError(reason, `Codex token refresh failed (${reason}); reauthenticate the account.`);
     }

package/src/codex/account-usability.ts

@@ -18,6 +18,27 @@ export interface CodexAccountUsabilityOptions {
   isMainAccountTokenLive?: typeof isMainAccountTokenLive;
   /** Confirmed account ids for an account-gated model; omitted for ordinary native models. */
   modelEligibleAccountIds?: ReadonlySet<string>;
+  /**
+   * Accounts whose own confirmed roster definitively omits the requested model (#4768).
+   *
+   * Deliberately NOT read by this module. `modelEligibleAccountIds` is an eligibility boundary and
+   * produces `model_not_entitled`; this is an ORDERING preference applied once, in
+   * `getEligiblePoolAccounts`, and dropped whenever honouring it would leave no candidate. Reading
+   * it here would turn a preference into a refusal and re-create the fail-closed behaviour the
+   * flagships were deliberately taken out of.
+   */
+  deniedModelAccountIds?: ReadonlySet<string>;
+  /**
+   * This request's conversation carries live uploaded-file references (#4778).
+   *
+   * Also not read by this module, and for the same reason: it is a retention preference, never an
+   * eligibility boundary. Uploaded files are scoped to the account that issued them, so moving
+   * such a conversation orphans the reference and every later turn is refused with
+   * `409 account_change_file_scope` -- the reference stays in history, so the conversation is
+   * effectively dead. Retention makes that refusal rarer; it can never replace it, because an
+   * account can always become unable to serve.
+   */
+  retainAccountForUploadedFiles?: boolean;
 }
 
 /**

package/src/codex/auth-api/login-flow.ts

@@ -10,7 +10,7 @@ import { clearAccountNeedsReauth, isAccountNeedsReauth, markAccountNeedsReauth }
 import { clearCodexPoolRefreshFailure } from "../pool-refresh-backoff";
 import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
 import { emailMaskingEnabled, projectEmail } from "../../lib/privacy";
-import { codexWarmupFailureReason, isCodexWarmupProvisioningFailure, warmCodexAccount } from "../warmup";
+import { CodexWarmupError, codexWarmupFailureReason, isCodexWarmupProvisioningFailure, warmCodexAccount } from "../warmup";
 import type { CodexAccount, CodexAccountCredentials, OcxConfig } from "../../types";
 import type { CatalogDisposition } from "../convergence-types";
 import { isValidCodexAccountId } from "../account-id";
@@ -51,6 +51,17 @@ export async function verifyCodexAccountWarmup(
     return { ok: true, validatedAt: Date.now() };
   } catch (err) {
     const reason = codexWarmupFailureReason(err);
+    if (err instanceof CodexWarmupError && err.code === "http_status" && err.status === 429) {
+      return {
+        ok: false,
+        response: jsonResponse({
+          error: "Codex account warmup was rate limited. Retry later or after the account's usage limit resets.",
+          code: "codex_warmup_rate_limited",
+          reason,
+          accountId,
+        }, 429),
+      };
+    }
     return {
       ok: false,
       response: jsonResponse({
@@ -322,10 +333,11 @@ export async function handleCodexAuthLoginStart(req: Request, config: OcxConfig,
                 ? { ok: true as const, validatedAt: undefined }
                 : await verifyCodexAccountWarmup(accountId, cred.access, oauthAccountId);
               if (!warmup.ok) {
-                const body = await warmup.response.json().catch(() => ({})) as { error?: string; reason?: string };
+                const body = await warmup.response.json().catch(() => ({})) as { error?: string; code?: string; reason?: string };
                 setCodexLoginState(flowId, {
                   status: "error",
                   error: body.reason ? `${body.error ?? "Codex account warmup failed"} (${body.reason})` : body.error ?? "Codex account warmup failed",
+                  code: body.code,
                   doneAt: Date.now(),
                 });
                 completed = true;

package/src/codex/auth-api/reset-credit-service.ts

@@ -153,7 +153,9 @@ export function createResetCreditWhamClient(config: OcxConfig, accountId: string
         signal: AbortSignal.timeout(10_000),
       });
       if (!resp.ok) { await resp.body?.cancel().catch(() => {}); throw new Error(`upstream ${resp.status}`); }
-      return safeResetCreditConsumeDto(await resp.json());
+      const parsed = await readResetCreditJson(resp, AbortSignal.timeout(10_000));
+      if (!parsed.ok) throw new Error("invalid upstream reset-credit consume response");
+      return safeResetCreditConsumeDto(parsed.value);
     }),
   };
 }
@@ -383,7 +385,14 @@ export async function consumeResetCredits(config: OcxConfig, accountId: string,
         if (identity) markManualResetCreditOperationAmbiguous(identity);
         return jsonResponse({ error: `Upstream error ${resp.status}` }, resp.status);
       }
-      const result = safeResetCreditConsumeDto(await resp.json());
+      const consumed = await readResetCreditJson(resp, AbortSignal.timeout(10_000));
+      if (!consumed.ok) {
+        // The spend may already have landed upstream and its outcome code is unreadable,
+        // so this id must never come back as a new operation.
+        if (identity) markManualResetCreditOperationAmbiguous(identity);
+        return jsonResponse({ error: "Invalid upstream reset-credit consume response" }, 502);
+      }
+      const result = safeResetCreditConsumeDto(consumed.value);
       if (identity) {
         // Narrow explicitly rather than casting: `safeResetCreditConsumeDto`
         // normalizes anything unrecognized to "unknown", and settling that