@bitkyc08/opencodex 2.7.23 → 2.7.24

package/src/oauth/token-guardian.ts

@@ -24,6 +24,9 @@ import {
   TokenRefreshError,
 } from "../codex/account-store";
 import { codexWarmupFailureReason, warmCodexAccount } from "../codex/warmup";
+import { getMainAccountToken, MAIN_CODEX_ACCOUNT_ID } from "../codex/main-account";
+import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
+import { providerCodexAccountMode } from "../providers/registry";
 
 export interface TokenGuardianHandle {
   stop(): void;
@@ -147,9 +150,41 @@ export async function guardianSweep(nowMs: number = Date.now()): Promise<Guardia
     }
   }
 
-  // B) multi-account Codex pool (gated on the chatgpt provider's policy)
-  if (resolveRefreshPolicy("chatgpt", config) === "proactive") {
-    for (const id of listCodexAccountIds()) {
+  // B) canonical OpenAI Codex login. Direct warms main only; pool additionally maintains every
+  // added account. The direct branch returns before the managed account store is enumerated.
+  const openai = config.providers[OPENAI_CODEX_PROVIDER_ID];
+  if (
+    openai
+    && openai.disabled !== true
+    && isCanonicalOpenAiForwardProvider(openai)
+    && resolveRefreshPolicy(OPENAI_CODEX_PROVIDER_ID, config) === "proactive"
+  ) {
+    const mode = providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, openai) ?? "pool";
+    if (opts.codexWarmupEnabled) {
+      const mainToken = getMainAccountToken();
+      const key = `codex:${MAIN_CODEX_ACCOUNT_ID}`;
+      if (mainToken && !inBackoff(key, nowMs)) {
+        tasks.push(async () => {
+          try {
+            await warmCodexAccount({
+              accessToken: mainToken.accessToken,
+              chatgptAccountId: mainToken.chatgptAccountId,
+              model: opts.codexWarmupModel,
+            });
+            backoff.delete(key);
+            result.warmed.push(key);
+          } catch (err) {
+            recordFailure(key, nowMs, opts.backoffBaseSeconds, opts.backoffMaxSeconds, false);
+            result.failed.push(key);
+          }
+        });
+      } else if (mainToken) {
+        result.skippedBackoff.push(key);
+      }
+    }
+
+    const addedAccountIds = mode === "pool" ? listCodexAccountIds() : [];
+    for (const id of addedAccountIds) {
       const record = readCodexAccountRecord(id);
       if (!record || record.deletedAt != null) continue;
       const cred = record.credential;

package/src/providers/derive.ts

@@ -1,4 +1,4 @@
-import type { OcxProviderConfig } from "../types";
+import type { CodexAccountMode, OcxProviderConfig } from "../types";
 import { PROVIDER_REGISTRY, type ProviderRegistryEntry } from "./registry";
 
 export interface DerivedKeyLoginProvider {
@@ -12,8 +12,10 @@ export interface DerivedKeyLoginProvider {
   contextWindow?: number;
   modelContextWindows?: Record<string, number>;
   modelInputModalities?: Record<string, string[]>;
+  modelMaxInputTokens?: Record<string, number>;
   reasoningEfforts?: string[];
   modelReasoningEfforts?: Record<string, string[]>;
+  modelDefaultReasoningEfforts?: Record<string, string>;
   reasoningEffortMap?: Record<string, string>;
   modelReasoningEffortMap?: Record<string, Record<string, string>>;
   noVisionModels?: string[];
@@ -26,6 +28,9 @@ export interface DerivedKeyLoginProvider {
   thinkingToggleModels?: string[];
   thinkingBudgetModels?: string[];
   escapeBuiltinToolNames?: boolean;
+  googleMode?: "ai-studio" | "vertex" | "cloud-code-assist";
+  project?: string;
+  location?: string;
 }
 
 export interface DerivedInitProvider {
@@ -34,6 +39,7 @@ export interface DerivedInitProvider {
   adapter: string;
   baseUrl: string;
   kind: "forward" | "oauth" | "key" | "local";
+  codexAccountMode?: CodexAccountMode;
   dashboardUrl?: string;
   defaultModel?: string;
 }
@@ -45,10 +51,15 @@ export interface DerivedProviderPreset {
   baseUrl: string;
   defaultModel?: string;
   auth: "oauth" | "forward" | "key" | "local";
+  codexAccountMode?: CodexAccountMode;
   oauthProvider?: string;
   dashboardUrl?: string;
   note?: string;
   keyOptional?: boolean;
+  /** Free pricing (may still require a key). */
+  freeTier?: boolean;
+  /** Immutable canonical provider config seed for the reserved canonical `openai` forward preset. */
+  provider?: OcxProviderConfig;
 }
 
 export function listRegistryEntries(): readonly ProviderRegistryEntry[] {
@@ -68,7 +79,9 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     adapter: entry.adapter,
     baseUrl: entry.baseUrl,
     authMode: entry.authKind === "local" ? undefined : entry.authKind,
+    ...(entry.codexAccountMode ? { codexAccountMode: entry.codexAccountMode } : {}),
     ...(entry.keyOptional !== undefined ? { keyOptional: entry.keyOptional } : {}),
+    ...(entry.freeTier !== undefined ? { freeTier: entry.freeTier } : {}),
     ...(entry.modelSuffixBracketStrip !== undefined ? { modelSuffixBracketStrip: entry.modelSuffixBracketStrip } : {}),
     ...(entry.staticHeaders ? { headers: { ...entry.staticHeaders } } : {}),
     ...(entry.defaultModel ? { defaultModel: entry.defaultModel } : {}),
@@ -77,8 +90,10 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     ...(entry.contextWindow !== undefined ? { contextWindow: entry.contextWindow } : {}),
     ...(entry.modelContextWindows ? { modelContextWindows: { ...entry.modelContextWindows } } : {}),
     ...(entry.modelInputModalities ? { modelInputModalities: cloneRecordOfArrays(entry.modelInputModalities) } : {}),
+    ...(entry.modelMaxInputTokens ? { modelMaxInputTokens: { ...entry.modelMaxInputTokens } } : {}),
     ...(entry.reasoningEfforts ? { reasoningEfforts: [...entry.reasoningEfforts] } : {}),
     ...(entry.modelReasoningEfforts ? { modelReasoningEfforts: cloneRecordOfArrays(entry.modelReasoningEfforts) } : {}),
+    ...(entry.modelDefaultReasoningEfforts ? { modelDefaultReasoningEfforts: { ...entry.modelDefaultReasoningEfforts } } : {}),
     ...(entry.reasoningEffortMap ? { reasoningEffortMap: { ...entry.reasoningEffortMap } } : {}),
     ...(entry.modelReasoningEffortMap ? { modelReasoningEffortMap: cloneNestedRecord(entry.modelReasoningEffortMap) } : {}),
     ...(entry.noVisionModels ? { noVisionModels: [...entry.noVisionModels] } : {}),
@@ -114,8 +129,10 @@ export function deriveKeyLoginMap(): Record<string, DerivedKeyLoginProvider> {
       ...(entry.contextWindow !== undefined ? { contextWindow: entry.contextWindow } : {}),
       ...(entry.modelContextWindows ? { modelContextWindows: { ...entry.modelContextWindows } } : {}),
       ...(entry.modelInputModalities ? { modelInputModalities: cloneRecordOfArrays(entry.modelInputModalities) } : {}),
+      ...(entry.modelMaxInputTokens ? { modelMaxInputTokens: { ...entry.modelMaxInputTokens } } : {}),
       ...(entry.reasoningEfforts ? { reasoningEfforts: [...entry.reasoningEfforts] } : {}),
       ...(entry.modelReasoningEfforts ? { modelReasoningEfforts: cloneRecordOfArrays(entry.modelReasoningEfforts) } : {}),
+      ...(entry.modelDefaultReasoningEfforts ? { modelDefaultReasoningEfforts: { ...entry.modelDefaultReasoningEfforts } } : {}),
       ...(entry.reasoningEffortMap ? { reasoningEffortMap: { ...entry.reasoningEffortMap } } : {}),
       ...(entry.modelReasoningEffortMap ? { modelReasoningEffortMap: cloneNestedRecord(entry.modelReasoningEffortMap) } : {}),
       ...(entry.noVisionModels ? { noVisionModels: [...entry.noVisionModels] } : {}),
@@ -143,6 +160,7 @@ export function deriveInitProviders(): DerivedInitProvider[] {
     adapter: entry.adapter,
     baseUrl: entry.baseUrl,
     kind: entry.authKind,
+    ...(entry.codexAccountMode ? { codexAccountMode: entry.codexAccountMode } : {}),
     ...(entry.dashboardUrl ? { dashboardUrl: entry.dashboardUrl } : {}),
     ...(entry.defaultModel ? { defaultModel: entry.defaultModel } : {}),
   }));
@@ -173,6 +191,8 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if (!entry) return;
   const seed = providerConfigSeed(entry);
   if (!prov.defaultModel && seed.defaultModel) prov.defaultModel = seed.defaultModel;
+  // Fill mode only when absent: an explicit persisted `direct` must never be overwritten.
+  if (prov.codexAccountMode === undefined && seed.codexAccountMode !== undefined) prov.codexAccountMode = seed.codexAccountMode;
   if (!prov.models && seed.models) prov.models = [...seed.models];
   if (prov.liveModels === undefined && seed.liveModels !== undefined) prov.liveModels = seed.liveModels;
   if (prov.contextWindow === undefined && seed.contextWindow !== undefined) prov.contextWindow = seed.contextWindow;
@@ -180,6 +200,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if (!prov.modelInputModalities && seed.modelInputModalities) prov.modelInputModalities = cloneRecordOfArrays(seed.modelInputModalities);
   if (!prov.reasoningEfforts && seed.reasoningEfforts) prov.reasoningEfforts = [...seed.reasoningEfforts];
   if (!prov.modelReasoningEfforts && seed.modelReasoningEfforts) prov.modelReasoningEfforts = cloneRecordOfArrays(seed.modelReasoningEfforts);
+  if (!prov.modelDefaultReasoningEfforts && seed.modelDefaultReasoningEfforts) prov.modelDefaultReasoningEfforts = { ...seed.modelDefaultReasoningEfforts };
   if (!prov.reasoningEffortMap && seed.reasoningEffortMap) prov.reasoningEffortMap = { ...seed.reasoningEffortMap };
   if (!prov.modelReasoningEffortMap && seed.modelReasoningEffortMap) prov.modelReasoningEffortMap = cloneNestedRecord(seed.modelReasoningEffortMap);
   if (!prov.noVisionModels && seed.noVisionModels) prov.noVisionModels = [...seed.noVisionModels];
@@ -194,6 +215,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if (!prov.thinkingBudgetModels && seed.thinkingBudgetModels) prov.thinkingBudgetModels = [...seed.thinkingBudgetModels];
   if (prov.escapeBuiltinToolNames === undefined && seed.escapeBuiltinToolNames !== undefined) prov.escapeBuiltinToolNames = seed.escapeBuiltinToolNames;
   if (prov.keyOptional === undefined && seed.keyOptional !== undefined) prov.keyOptional = seed.keyOptional;
+  if (prov.freeTier === undefined && seed.freeTier !== undefined) prov.freeTier = seed.freeTier;
   if (prov.modelSuffixBracketStrip === undefined && seed.modelSuffixBracketStrip !== undefined) prov.modelSuffixBracketStrip = seed.modelSuffixBracketStrip;
   if (!prov.headers && seed.headers) prov.headers = { ...seed.headers };
 }
@@ -226,11 +248,14 @@ function entryToPreset(entry: ProviderRegistryEntry): DerivedProviderPreset {
     adapter: entry.adapter,
     baseUrl: entry.baseUrl,
     auth: entry.authKind === "forward" ? "forward" : entry.authKind === "oauth" ? "oauth" : entry.authKind === "local" ? "local" : "key",
+    ...(entry.codexAccountMode ? { codexAccountMode: entry.codexAccountMode } : {}),
+    ...(entry.codexAccountMode ? { provider: providerConfigSeed(entry) } : {}),
     ...(entry.defaultModel ? { defaultModel: entry.defaultModel } : {}),
     ...(entry.authKind === "oauth" ? { oauthProvider: entry.oauthId ?? entry.id } : {}),
     ...(entry.dashboardUrl ? { dashboardUrl: entry.dashboardUrl } : {}),
     ...(entry.note ? { note: entry.note } : {}),
     ...(entry.keyOptional ? { keyOptional: true } : {}),
+    ...(entry.freeTier ? { freeTier: true } : {}),
   };
 }
 
@@ -250,7 +275,7 @@ function customPreset(): DerivedProviderPreset {
 }
 
 function formatInitLabel(entry: ProviderRegistryEntry): string {
-  if (entry.authKind === "forward") return "OpenAI — ChatGPT login (no key)";
+  if (entry.authKind === "forward") return "OpenAI — ChatGPT login (no key; account pool default, Direct selectable)";
   if (entry.authKind === "oauth") {
     if (entry.id === "xai") return "xAI (Grok) — account login";
     if (entry.id === "anthropic") return "Anthropic (Claude) — account login";

package/src/providers/kiro-models.ts

@@ -1,5 +1,9 @@
 export const KIRO_MODELS = [
   "kiro-auto",
+  // OpenAI GPT-5.6 (Kiro experimental, us-east-1) — added to official catalog 2026-07-13
+  "gpt-5.6-sol",
+  "gpt-5.6-terra",
+  "gpt-5.6-luna",
   "claude-sonnet-5",
   "claude-opus-4.8",
   "claude-opus-4.7",
@@ -17,11 +21,12 @@ export const KIRO_MODELS = [
 ];
 
 // Per-model context windows as documented on Kiro's official model catalog
-// (https://kiro.dev/docs/models/ — "Quick comparison", page updated 2026-06-19).
-// claude-sonnet-5 is pre-seeded from Anthropic/OpenRouter 1M metadata until Kiro's
-// public catalog catches up.
+// (https://kiro.dev/docs/models/ — "Quick comparison", page updated 2026-07-14).
 // "Auto" is a router with no fixed window on Kiro's table, so it is intentionally omitted.
 export const KIRO_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
+  "gpt-5.6-sol": 272_000,
+  "gpt-5.6-terra": 272_000,
+  "gpt-5.6-luna": 272_000,
   "claude-sonnet-5": 1_000_000,
   "claude-opus-4.8": 1_000_000,
   "claude-opus-4.7": 1_000_000,

package/src/providers/label.ts

@@ -1,10 +1,12 @@
 import { CODEX_ACCOUNT_LOG_LABEL_RE } from "../codex/account-label";
 
 function canonicalUsageProviderLabel(provider: string): string {
-  return provider === "chatgpt" ? "openai" : provider;
+  return provider === "chatgpt" || provider === "openai-multi" ? "openai" : provider;
 }
 
 export function baseProviderLabel(provider: string): string {
+  const canonical = canonicalUsageProviderLabel(provider);
+  if (canonical !== provider) return canonical;
   const cut = provider.lastIndexOf("-");
   if (cut <= 0) return canonicalUsageProviderLabel(provider);
   const suffix = provider.slice(cut + 1);

package/src/providers/openai-sidecar.ts

@@ -0,0 +1,94 @@
+import { resolveEnvValue } from "../config";
+import {
+  headersForCodexAuthContext,
+  hasCallerCodexBearer,
+  isCodexAuthContextUsable,
+  resolveCodexAuthContext,
+  type CodexAuthContext,
+} from "../codex/auth-context";
+import { recordCodexUpstreamOutcome, type CodexUpstreamOutcome } from "../codex/routing";
+import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "../server/auth-cors";
+import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
+import {
+  isCanonicalOpenAiForwardProvider,
+  OPENAI_API_PROVIDER_ID,
+  OPENAI_CODEX_PROVIDER_ID,
+} from "./openai-tiers";
+import { providerCodexAccountMode } from "./registry";
+
+export interface OpenAiForwardSidecarCandidate {
+  providerName: typeof OPENAI_CODEX_PROVIDER_ID;
+  provider: OcxProviderConfig;
+  accountMode: CodexAccountMode;
+}
+
+export interface ResolvedOpenAiForwardSidecar extends OpenAiForwardSidecarCandidate {
+  authContext: CodexAuthContext;
+  headers: Headers;
+  recordOutcome?: (outcome: CodexUpstreamOutcome) => void;
+}
+
+export interface OpenAiImagesProviderSelection {
+  forwardCandidates: OpenAiForwardSidecarCandidate[];
+  keyed?: {
+    providerName: typeof OPENAI_API_PROVIDER_ID;
+    provider: OcxProviderConfig;
+    apiKey: string;
+  };
+}
+
+export function listOpenAiForwardSidecarCandidates(config: OcxConfig): OpenAiForwardSidecarCandidate[] {
+  const provider = config.providers[OPENAI_CODEX_PROVIDER_ID];
+  if (!provider || provider.disabled === true || !isCanonicalOpenAiForwardProvider(provider)) return [];
+  return [{
+    providerName: OPENAI_CODEX_PROVIDER_ID,
+    provider,
+    accountMode: providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, provider) ?? "pool",
+  }];
+}
+
+export async function resolveFirstUsableOpenAiSidecar(
+  candidates: readonly OpenAiForwardSidecarCandidate[],
+  incomingHeaders: Headers,
+  config: OcxConfig,
+): Promise<ResolvedOpenAiForwardSidecar | undefined> {
+  let callerBearerMayBeForwarded = true;
+  try {
+    validateForwardAdmissionCredential(incomingHeaders, config);
+  } catch (error) {
+    if (!(error instanceof ForwardAdmissionCredentialError)) throw error;
+    callerBearerMayBeForwarded = false;
+  }
+  for (const candidate of candidates) {
+    if (candidate.accountMode === "direct" && (!callerBearerMayBeForwarded || !hasCallerCodexBearer(incomingHeaders))) continue;
+    const authContext = await resolveCodexAuthContext(incomingHeaders, config, candidate.accountMode);
+    if (!isCodexAuthContextUsable(authContext, config)) continue;
+    return {
+      ...candidate,
+      authContext,
+      headers: headersForCodexAuthContext(incomingHeaders, authContext),
+      ...(authContext.kind === "pool" || authContext.kind === "main-pool"
+        ? { recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(config, authContext.accountId, outcome) }
+        : {}),
+    };
+  }
+  return undefined;
+}
+
+export function selectOpenAiImagesProvider(config: OcxConfig): OpenAiImagesProviderSelection {
+  const selection: OpenAiImagesProviderSelection = {
+    forwardCandidates: listOpenAiForwardSidecarCandidates(config),
+  };
+  const provider = config.providers[OPENAI_API_PROVIDER_ID];
+  if (
+    provider
+    && provider.disabled !== true
+    && provider.adapter === "openai-responses"
+    && provider.authMode !== "forward"
+    && provider.baseUrl.replace(/\/+$/, "") === "https://api.openai.com/v1"
+  ) {
+    const apiKey = resolveEnvValue(provider.apiKey)?.trim();
+    if (apiKey) selection.keyed = { providerName: OPENAI_API_PROVIDER_ID, provider, apiKey };
+  }
+  return selection;
+}

package/src/providers/openai-tier-startup.ts

@@ -0,0 +1,27 @@
+import { backupConfigBeforeOpenAiTierMigration, saveConfig } from "../config";
+import type { OcxConfig } from "../types";
+import { projectOpenAiTierMigration } from "./openai-tiers";
+
+export interface OpenAiTierStartupDeps {
+  project: typeof projectOpenAiTierMigration;
+  backup: () => void;
+  save: (config: OcxConfig) => void;
+}
+
+const DEFAULT_DEPS: OpenAiTierStartupDeps = {
+  project: projectOpenAiTierMigration,
+  backup: backupConfigBeforeOpenAiTierMigration,
+  save: saveConfig,
+};
+
+export function runOpenAiTierStartupMigration(
+  config: OcxConfig,
+  deps: OpenAiTierStartupDeps = DEFAULT_DEPS,
+): OcxConfig {
+  const projection = deps.project(config);
+  if (!projection.changed) return projection.config;
+  deps.backup();
+  deps.save(projection.config);
+  for (const warning of projection.warnings) console.warn(`[openai-provider-migration] ${warning}`);
+  return projection.config;
+}

package/src/providers/openai-tiers.ts

@@ -0,0 +1,283 @@
+import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
+import { OPENAI_PROVIDER_TIER_VERSION } from "../types";
+
+export const OPENAI_CODEX_PROVIDER_ID = "openai";
+export const LEGACY_OPENAI_MULTI_PROVIDER_ID = "openai-multi";
+export const OPENAI_API_PROVIDER_ID = "openai-apikey";
+export const LEGACY_CHATGPT_PROVIDER_ID = "chatgpt";
+
+const CODEX_FORWARD_BASE_URL = "https://chatgpt.com/backend-api/codex";
+const LEGACY_OPENAI_MULTI_PREFIX = `${LEGACY_OPENAI_MULTI_PROVIDER_ID}/`;
+
+function canonicalCodexForwardProvider(mode: CodexAccountMode): OcxProviderConfig {
+  return {
+    adapter: "openai-responses",
+    baseUrl: CODEX_FORWARD_BASE_URL,
+    authMode: "forward",
+    codexAccountMode: mode,
+  };
+}
+
+function normalizedBaseUrl(value: string): string | undefined {
+  try {
+    const url = new URL(value.trim());
+    if (url.username || url.password || url.search || url.hash) return undefined;
+    const path = url.pathname.replace(/\/+$/, "");
+    return `${url.origin}${path}`;
+  } catch {
+    return undefined;
+  }
+}
+
+export function isCanonicalOpenAiForwardProvider(provider: OcxProviderConfig): boolean {
+  return provider.adapter === "openai-responses"
+    && provider.authMode === "forward"
+    && normalizedBaseUrl(provider.baseUrl) === CODEX_FORWARD_BASE_URL;
+}
+
+export interface OpenAiTierMigrationProjection {
+  config: OcxConfig;
+  changed: boolean;
+  resolvedMode: CodexAccountMode;
+  warnings: string[];
+}
+
+export class OpenAiTierMigrationCollisionError extends Error {
+  readonly providerName = LEGACY_OPENAI_MULTI_PROVIDER_ID;
+
+  constructor() {
+    super(`Reserved provider id "${LEGACY_OPENAI_MULTI_PROVIDER_ID}" is already configured with a noncanonical shape`);
+    this.name = "OpenAiTierMigrationCollisionError";
+  }
+}
+
+function managedLegacyMultiOverlay(provider: OcxProviderConfig): Pick<OcxProviderConfig, "disabled" | "selectedModels"> | null {
+  const allowed = new Set(["adapter", "authMode", "baseUrl", "disabled", "selectedModels"]);
+  if (!Object.keys(provider).every(key => allowed.has(key))) return null;
+  if (!isCanonicalOpenAiForwardProvider(provider)) return null;
+  if (provider.disabled !== undefined && typeof provider.disabled !== "boolean") return null;
+  if (provider.selectedModels !== undefined && (
+    !Array.isArray(provider.selectedModels)
+    || provider.selectedModels.some(model => typeof model !== "string")
+  )) return null;
+  return {
+    ...(provider.disabled !== undefined ? { disabled: provider.disabled } : {}),
+    ...(provider.selectedModels !== undefined ? { selectedModels: [...provider.selectedModels] } : {}),
+  };
+}
+
+function rewriteLegacyOpenAiSelectedId(value: string): string {
+  return value.startsWith(LEGACY_OPENAI_MULTI_PREFIX)
+    ? value.slice(LEGACY_OPENAI_MULTI_PREFIX.length)
+    : value;
+}
+
+function rewriteLegacyOpenAiModelList(values: string[] | undefined): string[] | undefined {
+  if (!values) return undefined;
+  return [...new Set(values.map(rewriteLegacyOpenAiSelectedId))];
+}
+
+function mergeLegacyOpenAiProviderRows(
+  openai: OcxProviderConfig | undefined,
+  legacyMulti: OcxProviderConfig | undefined,
+  mode: CodexAccountMode,
+): OcxProviderConfig {
+  const selectedModels = rewriteLegacyOpenAiModelList([
+    ...(openai?.selectedModels ?? []),
+    ...(legacyMulti?.selectedModels ?? []),
+  ]);
+  const formerRows = [openai, legacyMulti].filter((row): row is OcxProviderConfig => row !== undefined);
+  const disabled = formerRows.length > 0 && formerRows.every(row => row.disabled === true);
+  return {
+    ...canonicalCodexForwardProvider(mode),
+    ...(disabled ? { disabled: true } : {}),
+    ...(selectedModels && selectedModels.length > 0 ? { selectedModels } : {}),
+  };
+}
+
+function hasKnownLegacyOpenAiReference(config: OcxConfig): boolean {
+  const matches = (value: unknown): boolean => typeof value === "string" && value.startsWith(LEGACY_OPENAI_MULTI_PREFIX);
+  const matchesList = (value: unknown): boolean => Array.isArray(value) && value.some(matches);
+  const claude = config.claudeCode;
+  return config.defaultProvider === LEGACY_OPENAI_MULTI_PROVIDER_ID
+    || matchesList(config.disabledModels)
+    || matchesList(config.subagentModels)
+    || matches(config.injectionModel)
+    || matches(config.shadowCallIntercept?.model)
+    || matches(config.webSearchSidecar?.model)
+    || matches(config.visionSidecar?.model)
+    || matches(claude?.webSearchSidecar?.model)
+    || matches(claude?.visionSidecar?.model)
+    || matches(claude?.model)
+    || matches(claude?.smallFastModel)
+    || Object.values(claude?.tierModels ?? {}).some(matches)
+    || Object.values(claude?.modelMap ?? {}).some(matches)
+    || matchesList(config.providers[OPENAI_CODEX_PROVIDER_ID]?.selectedModels)
+    || matchesList(config.providers[LEGACY_OPENAI_MULTI_PROVIDER_ID]?.selectedModels)
+    || config.providerContextCaps?.[LEGACY_OPENAI_MULTI_PROVIDER_ID] !== undefined;
+}
+
+function rewriteLegacyOpenAiReferences(config: OcxConfig, warnings: string[]): void {
+  config.disabledModels = rewriteLegacyOpenAiModelList(config.disabledModels);
+  config.subagentModels = rewriteLegacyOpenAiModelList(config.subagentModels);
+  if (config.injectionModel) config.injectionModel = rewriteLegacyOpenAiSelectedId(config.injectionModel);
+  if (config.shadowCallIntercept?.model) {
+    config.shadowCallIntercept.model = rewriteLegacyOpenAiSelectedId(config.shadowCallIntercept.model);
+  }
+  if (config.webSearchSidecar?.model) config.webSearchSidecar.model = rewriteLegacyOpenAiSelectedId(config.webSearchSidecar.model);
+  if (config.visionSidecar?.model) config.visionSidecar.model = rewriteLegacyOpenAiSelectedId(config.visionSidecar.model);
+
+  const claude = config.claudeCode;
+  if (claude?.webSearchSidecar?.model) claude.webSearchSidecar.model = rewriteLegacyOpenAiSelectedId(claude.webSearchSidecar.model);
+  if (claude?.visionSidecar?.model) claude.visionSidecar.model = rewriteLegacyOpenAiSelectedId(claude.visionSidecar.model);
+  if (claude?.model) claude.model = rewriteLegacyOpenAiSelectedId(claude.model);
+  if (claude?.smallFastModel) claude.smallFastModel = rewriteLegacyOpenAiSelectedId(claude.smallFastModel);
+  if (claude?.tierModels) {
+    for (const tier of ["opus", "sonnet", "haiku", "fable"] as const) {
+      const value = claude.tierModels[tier];
+      if (value) claude.tierModels[tier] = rewriteLegacyOpenAiSelectedId(value);
+    }
+  }
+  if (claude?.modelMap) {
+    for (const key of Object.keys(claude.modelMap)) {
+      claude.modelMap[key] = rewriteLegacyOpenAiSelectedId(claude.modelMap[key]!);
+    }
+  }
+
+  const caps = config.providerContextCaps;
+  const legacyCap = caps?.[LEGACY_OPENAI_MULTI_PROVIDER_ID];
+  if (caps && legacyCap !== undefined) {
+    const currentCap = caps[OPENAI_CODEX_PROVIDER_ID];
+    if (currentCap !== undefined) {
+      caps[OPENAI_CODEX_PROVIDER_ID] = Math.min(currentCap, legacyCap);
+      warnings.push("providerContextCaps.openai + providerContextCaps.openai-multi: kept lower positive cap");
+    } else {
+      caps[OPENAI_CODEX_PROVIDER_ID] = legacyCap;
+    }
+    delete caps[LEGACY_OPENAI_MULTI_PROVIDER_ID];
+  }
+}
+
+function isKnownLegacyValuePath(path: readonly string[]): boolean {
+  const joined = path.join(".");
+  if (joined === "defaultProvider") return true;
+  if (/^(disabledModels|subagentModels)\.\d+$/.test(joined)) return true;
+  if (/^providers\.(openai|openai-multi)\.selectedModels\.\d+$/.test(joined)) return true;
+  return new Set([
+    "injectionModel",
+    "shadowCallIntercept.model",
+    "webSearchSidecar.model",
+    "visionSidecar.model",
+    "claudeCode.webSearchSidecar.model",
+    "claudeCode.visionSidecar.model",
+    "claudeCode.model",
+    "claudeCode.smallFastModel",
+    "claudeCode.tierModels.opus",
+    "claudeCode.tierModels.sonnet",
+    "claudeCode.tierModels.haiku",
+    "claudeCode.tierModels.fable",
+  ]).has(joined) || /^claudeCode\.modelMap\..+$/.test(joined);
+}
+
+function unknownLegacyOpenAiWarnings(config: OcxConfig): string[] {
+  const warnings = new Set<string>();
+  const visit = (value: unknown, path: string[]): void => {
+    if (typeof value === "string") {
+      if (value.includes(LEGACY_OPENAI_MULTI_PROVIDER_ID) && !isKnownLegacyValuePath(path)) {
+        warnings.add(`${path.join(".")}: legacy OpenAI provider id left unchanged`);
+      }
+      return;
+    }
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => visit(item, [...path, String(index)]));
+      return;
+    }
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      visit(item, [...path, key]);
+    }
+  };
+  visit(config, []);
+  return [...warnings];
+}
+
+function resolvedOpenAiMode(
+  config: OcxConfig,
+  openai: OcxProviderConfig | undefined,
+  legacyMulti: OcxProviderConfig | undefined,
+  knownLegacyReference: boolean,
+): CodexAccountMode {
+  if (openai?.codexAccountMode === "pool" || openai?.codexAccountMode === "direct") {
+    return openai.codexAccountMode;
+  }
+  if (
+    (legacyMulti && legacyMulti.disabled !== true)
+    || config.defaultProvider === LEGACY_OPENAI_MULTI_PROVIDER_ID
+    || knownLegacyReference
+  ) return "pool";
+  if (config.openaiProviderTierVersion === 1 && openai) return "direct";
+  if (config.openaiProviderTierVersion === 1 && legacyMulti) return "pool";
+  return "pool";
+}
+
+export function projectOpenAiTierMigration(config: OcxConfig): OpenAiTierMigrationProjection {
+  const projected = structuredClone(config);
+  const legacyMulti = projected.providers[LEGACY_OPENAI_MULTI_PROVIDER_ID];
+  if (legacyMulti && !managedLegacyMultiOverlay(legacyMulti)) {
+    throw new OpenAiTierMigrationCollisionError();
+  }
+
+  const openai = projected.providers[OPENAI_CODEX_PROVIDER_ID];
+  const knownLegacyReference = hasKnownLegacyOpenAiReference(projected);
+  const resolvedMode = resolvedOpenAiMode(projected, openai, legacyMulti, knownLegacyReference);
+  if (
+    projected.openaiProviderTierVersion === OPENAI_PROVIDER_TIER_VERSION
+    && !legacyMulti
+    && !Object.hasOwn(projected.providers, LEGACY_CHATGPT_PROVIDER_ID)
+    && projected.defaultProvider !== LEGACY_OPENAI_MULTI_PROVIDER_ID
+    && !knownLegacyReference
+  ) {
+    return { config: projected, changed: false, resolvedMode, warnings: [] };
+  }
+
+  const warnings = unknownLegacyOpenAiWarnings(projected);
+  const referencesCodexForward = !!openai
+    || !!legacyMulti
+    || Object.hasOwn(projected.providers, LEGACY_CHATGPT_PROVIDER_ID)
+    || projected.defaultProvider === OPENAI_CODEX_PROVIDER_ID
+    || projected.defaultProvider === LEGACY_OPENAI_MULTI_PROVIDER_ID
+    || projected.defaultProvider === LEGACY_CHATGPT_PROVIDER_ID
+    || knownLegacyReference;
+  const mergedOpenAi = referencesCodexForward
+    ? mergeLegacyOpenAiProviderRows(openai, legacyMulti, resolvedMode)
+    : undefined;
+
+  const nextProviders: Array<[string, OcxProviderConfig]> = [];
+  let inserted = false;
+  for (const [name, provider] of Object.entries(projected.providers)) {
+    if (name === OPENAI_CODEX_PROVIDER_ID) {
+      if (mergedOpenAi && !inserted) nextProviders.push([OPENAI_CODEX_PROVIDER_ID, mergedOpenAi]);
+      inserted = true;
+      continue;
+    }
+    if (name === LEGACY_OPENAI_MULTI_PROVIDER_ID || name === LEGACY_CHATGPT_PROVIDER_ID) {
+      if (mergedOpenAi && !inserted && !openai) {
+        nextProviders.push([OPENAI_CODEX_PROVIDER_ID, mergedOpenAi]);
+        inserted = true;
+      }
+      continue;
+    }
+    nextProviders.push([name, provider]);
+  }
+  if (mergedOpenAi && !inserted) nextProviders.push([OPENAI_CODEX_PROVIDER_ID, mergedOpenAi]);
+  projected.providers = Object.fromEntries(nextProviders);
+
+  if (
+    projected.defaultProvider === LEGACY_OPENAI_MULTI_PROVIDER_ID
+    || projected.defaultProvider === LEGACY_CHATGPT_PROVIDER_ID
+  ) projected.defaultProvider = OPENAI_CODEX_PROVIDER_ID;
+
+  rewriteLegacyOpenAiReferences(projected, warnings);
+  projected.openaiProviderTierVersion = OPENAI_PROVIDER_TIER_VERSION;
+  return { config: projected, changed: true, resolvedMode, warnings: [...new Set(warnings)] };
+}