@bitkyc08/opencodex 2.55.0 → 2.57.0

package/src/chat/inbound.ts

@@ -313,7 +313,18 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
         // here keeps that adjacency intact.
         const reasoningText = assistantReasoningText(msg);
         if (reasoningText !== undefined) {
-          input.push({ type: "reasoning", content: [{ type: "reasoning_text", text: reasoningText }] });
+          // `summary` is required on a reasoning input item by the OpenAI Responses API, and our
+          // own responsesRequestSchema marks it optional, so a summary-less item validated locally
+          // and was refused upstream with `Missing required parameter: 'input[N].summary'`. It also
+          // has to carry the text, not just satisfy the field: sanitizeReasoningInputContent blanks
+          // `content` for every destination except a `preserveResponsesReasoningContent` provider,
+          // so summary is the only channel that survives to a native backend. This mirrors the
+          // Claude ingress (src/claude/inbound.ts), which has always minted both.
+          input.push({
+            type: "reasoning",
+            summary: [{ type: "summary_text", text: reasoningText }],
+            content: [{ type: "reasoning_text", text: reasoningText }],
+          });
         }
         const blocks = assistantContentToBlocks(msg.content);
         if (blocks.length > 0) input.push({ type: "message", role: "assistant", content: blocks });

package/src/claude/desktop-profile.ts

@@ -22,8 +22,34 @@ export interface RenderedDesktopModel extends DesktopProfileModel {
   supports1m: boolean;
 }
 
-const DATE_ALIAS = /^claude-opus-4-8-(2026\d{4})$/;
-const DAY_COUNT_2026 = 365;
+// Managed-namespace date aliases run 2026-2035. The original 2026-only
+// (365 slots) design failed with "all 365 encoded date slots are occupied"
+// once a catalog exceeded 365 routes (stale assignments are retained by
+// design, so the set only grows). Years before 2026 stay rejected: dated
+// ids like `claude-opus-4-8-20250201` are real model snapshot ids, not
+// managed aliases, and the inbound decoder relies on that distinction.
+// Every emitted suffix stays 8 digits so modelMap date-stripping keeps
+// working.
+const DATE_ALIAS = /^claude-opus-4-8-(202[6-9]\d{4}|203[0-5]\d{4})$/;
+const LEGACY_YEAR = 2026;
+const LEGACY_DAY_COUNT = 365;
+const ALIAS_FIRST_YEAR = 2026;
+const ALIAS_LAST_YEAR = 2035;
+
+function isLeapYear(year: number): boolean {
+  return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+}
+
+function daysInAliasYear(year: number): number {
+  return isLeapYear(year) ? 366 : 365;
+}
+
+export const TOTAL_ALIAS_SLOTS = (() => {
+  let total = 0;
+  for (let year = ALIAS_FIRST_YEAR; year <= ALIAS_LAST_YEAR; year += 1) total += daysInAliasYear(year);
+  return total;
+})();
+export const ALIAS_YEAR_RANGE = { first: ALIAS_FIRST_YEAR, last: ALIAS_LAST_YEAR } as const;
 
 export class DesktopProfileError extends Error {
   constructor(message: string, readonly path = "profile") {
@@ -119,7 +145,7 @@ export function parseDesktopProfile(value: unknown): DesktopProfile {
     if (isRealAnthropicRoute(route)) {
       if (raw.alias !== routeModelId(route)) throw new DesktopProfileError("real Anthropic routes must keep their exact model id", `profile.assignments.${route}.alias`);
     } else if (!validDateAlias(raw.alias)) {
-      throw new DesktopProfileError("must be a valid claude-opus-4-8-2026MMDD alias", `profile.assignments.${route}.alias`);
+      throw new DesktopProfileError("must be a valid claude-opus-4-8-YYYYMMDD alias", `profile.assignments.${route}.alias`);
     }
     if (aliases.has(raw.alias)) throw new DesktopProfileError(`duplicate alias "${raw.alias}"`, `profile.assignments.${route}.alias`);
     aliases.add(raw.alias);
@@ -144,26 +170,57 @@ export function parseDesktopProfile(value: unknown): DesktopProfile {
   return { version: 1, assignments, defaults, ...appliedMarkers(value) };
 }
 
-function dayOfYearAlias(dayIndex: number): string {
-  const date = new Date(Date.UTC(2026, 0, dayIndex + 1));
+function formatSlotDate(year: number, dayOfYear: number): string {
+  const date = new Date(Date.UTC(year, 0, dayOfYear));
   const y = date.getUTCFullYear();
   const m = String(date.getUTCMonth() + 1).padStart(2, "0");
   const d = String(date.getUTCDate()).padStart(2, "0");
   return `claude-opus-4-8-${y}${m}${d}`;
 }
 
+// Legacy 2026 ring, byte-identical to the original allocator: the same route
+// must keep resolving to the same 2026 alias it always had, and a probe over
+// a nearly-full 2026 set must land on the same free date as before.
+function legacyDayAlias(dayIndex: number): string {
+  return formatSlotDate(LEGACY_YEAR, dayIndex + 1);
+}
+
+// Overflow ring for catalogs past 365 routes (2027-2035). Probed only after
+// every legacy slot is taken, so existing profiles never shift into it.
+const OVERFLOW_FIRST_YEAR = LEGACY_YEAR + 1;
+const OVERFLOW_SLOT_COUNT = TOTAL_ALIAS_SLOTS - LEGACY_DAY_COUNT;
+
+function overflowSlotAlias(slotIndex: number): string {
+  let remaining = ((slotIndex % OVERFLOW_SLOT_COUNT) + OVERFLOW_SLOT_COUNT) % OVERFLOW_SLOT_COUNT;
+  for (let year = OVERFLOW_FIRST_YEAR; year <= ALIAS_LAST_YEAR; year += 1) {
+    const days = daysInAliasYear(year);
+    if (remaining < days) return formatSlotDate(year, remaining + 1);
+    remaining -= days;
+  }
+  throw new DesktopProfileError("slot index out of range", "profile.assignments");
+}
+
 function routeStartDay(route: string): number {
-  return createHash("sha256").update(route).digest().readUInt32BE(0) % DAY_COUNT_2026;
+  return createHash("sha256").update(route).digest().readUInt32BE(0) % LEGACY_DAY_COUNT;
+}
+
+function routeOverflowStart(route: string): number {
+  return createHash("sha256").update(route).digest().readUInt32BE(4) % OVERFLOW_SLOT_COUNT;
 }
 
 function allocateAlias(route: string, used: Set<string>): string {
   if (isRealAnthropicRoute(route)) return routeModelId(route);
   const start = routeStartDay(route);
-  for (let offset = 0; offset < DAY_COUNT_2026; offset += 1) {
-    const alias = dayOfYearAlias((start + offset) % DAY_COUNT_2026);
+  for (let offset = 0; offset < LEGACY_DAY_COUNT; offset += 1) {
+    const alias = legacyDayAlias((start + offset) % LEGACY_DAY_COUNT);
+    if (!used.has(alias)) return alias;
+  }
+  const overflowStart = routeOverflowStart(route);
+  for (let offset = 0; offset < OVERFLOW_SLOT_COUNT; offset += 1) {
+    const alias = overflowSlotAlias((overflowStart + offset) % OVERFLOW_SLOT_COUNT);
     if (!used.has(alias)) return alias;
   }
-  throw new DesktopProfileError("all 365 encoded date slots are occupied", `profile.assignments.${route}.alias`);
+  throw new DesktopProfileError(`all ${TOTAL_ALIAS_SLOTS} encoded date slots are occupied`, `profile.assignments.${route}.alias`);
 }
 
 export function reconcileDesktopProfile(

package/src/claude/outbound.ts

@@ -212,6 +212,8 @@ interface OpenBlock {
   argsBuf?: string;
   argsBufBytes?: number;
   webSearchArgsEmitted?: boolean;
+  /** True once ordinary function-call arguments were emitted to Anthropic SSE. */
+  toolArgsEmitted?: boolean;
   callId?: string;
   /** Last fixed-size reasoning identity (item + summary/content index) seen by this block. */
   reasoningPartKey?: string;
@@ -488,6 +490,7 @@ export function responsesSseToAnthropicSse(
               argsBuf: "",
               argsBufBytes: 0,
               webSearchArgsEmitted: false,
+              toolArgsEmitted: false,
             };
             break;
           }
@@ -518,6 +521,14 @@ export function responsesSseToAnthropicSse(
               type: "content_block_delta", index: open.index,
               delta: { type: "input_json_delta", partial_json: data.delta },
             });
+            open.toolArgsEmitted = true;
+            break;
+          }
+          case "response.function_call_arguments.done": {
+            if (!open || open.kind !== "tool_use" || open.bufferWebSearchArgs || open.toolArgsEmitted) break;
+            if (typeof data.arguments !== "string" || data.arguments.length === 0) break;
+            emit("content_block_delta", { type: "content_block_delta", index: open.index, delta: { type: "input_json_delta", partial_json: data.arguments } });
+            open.toolArgsEmitted = true;
             break;
           }
           case "response.output_item.done": {
@@ -565,6 +576,13 @@ export function responsesSseToAnthropicSse(
                   delta: { type: "input_json_delta", partial_json: JSON.stringify(sanitizeWebSearchInput(parsed)) },
                 });
                 open.webSearchArgsEmitted = true;
+              } else if (!open.bufferWebSearchArgs && !open.toolArgsEmitted
+                && typeof item.arguments === "string" && item.arguments.length > 0) {
+                emit("content_block_delta", {
+                  type: "content_block_delta", index: open.index,
+                  delta: { type: "input_json_delta", partial_json: item.arguments },
+                });
+                open.toolArgsEmitted = true;
               }
               closeOpenBlock();
             }

package/src/cli/account-main.ts

@@ -245,7 +245,7 @@ export async function cmdNativeMainAccount(args: string[], deps: AccountDeps): P
     }
     if (noWait) {
       printStatus({ flowId: startFlowId, ...pending });
-      console.log("follow up: ocx account main reauth status --flow " + startFlowId);
+      if (!wantsJson) console.log("follow up: ocx account main reauth status --flow " + startFlowId);
       return 0;
     }
     // Blocking wait bounded by the service flow expiry (15-minute grant + margin).

package/src/cli/capabilities.ts

@@ -710,10 +710,10 @@ export const CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["system", "codex-restart"],
-    summary: "Restart the Codex app-server.",
+    summary: "Restart the Codex desktop app and app-servers.",
     routes: [{ method: "POST", path: "/api/system/codex-restart" }],
     flags: [
-      { name: "--yes", value: "boolean", summary: "Required: restarts the operator's running Codex app-server." },
+      { name: "--yes", value: "boolean", summary: "Required: fully quits and relaunches the operator's Codex desktop app and restarts its app-servers." },
       { name: "--json", value: "boolean", summary: "Emit the restart result as JSON." },
     ],
     mutates: true,

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-lifecycle.ts

@@ -11,6 +11,8 @@ import { getMainChatgptAccountId, readCodexTokensResult } from "./auth-collision
 import { MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./main-account";
 import { clearAccountQuota } from "./quota";
 import { clearCodexUpstreamHealthForAccount, clearThreadAccountMapForAccount } from "./routing";
+
+import { clearCodexPoolRefreshFailure } from "./pool-refresh-backoff";
 import { invalidateCodexWebSocketsForAccount } from "./websocket-registry";
 import { clearMainAccountCredentialPresence, clearMainAccountInfoCache, observeMainQuotaCredential, observeMainQuotaIdentity } from "./main-account-cache";
 import { extractAccountIdClaims } from "../oauth/chatgpt";
@@ -41,6 +43,7 @@ export function purgeCodexAccountRuntimeState(accountId: string): void {
   clearAccountQuota(accountId);
   clearThreadAccountMapForAccount(accountId);
   clearCodexUpstreamHealthForAccount(accountId);
+  clearCodexPoolRefreshFailure(accountId);
   if (accountId === MAIN_CODEX_ACCOUNT_ID) {
     clearMainAccountInfoCache();
     clearMainAccountCredentialPresence();