@iislee/opencodex 2.11.0 → 2.31.0

package/src/providers/key-failover.ts

@@ -9,7 +9,7 @@
  * Modelled after src/codex/routing.ts cooldown logic but scoped to plain API-key pools.
  */
 import { saveConfigPreservingClaudeCode } from "../config";
-import type { OcxConfig, OcxProviderConfig } from "../types";
+import type { OcxConfig, OcxProviderConfig, RateLimitRetryPolicy } from "../types";
 import { resolveProviderTransport, type OcxProviderTransport } from "./xai-transport";
 import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
 
@@ -22,6 +22,18 @@ interface KeyCooldown {
 const DEFAULT_COOLDOWN_MS = 60_000;
 const MAX_COOLDOWN_MS = 10 * 60_000; // cap at 10 min for api-key rotation
 
+/**
+ * Default same-target 429 retry policy used when a provider opts in via a bare
+ * `retryOn429: {}` (presence = opt-in with these defaults).
+ */
+const DEFAULT_RATE_LIMIT_RETRY = {
+  enabled: true,
+  attempts: 3,
+  intervalMs: 5_000,
+  maxIntervalMs: 60_000,
+  respectRetryAfter: true,
+} as const satisfies Required<RateLimitRetryPolicy>;
+
 /** Map<`${providerName}\0${keyId}`, KeyCooldown> */
 const keyCooldowns = new Map<string, KeyCooldown>();
 
@@ -29,21 +41,32 @@ function cooldownKey(providerName: string, keyId: string): string {
   return `${providerName}\0${keyId}`;
 }
 
+/**
+ * Parse an upstream `Retry-After` header: numeric seconds (including `0`) or an HTTP-date.
+ * Returns a bounded delay in ms (1..MAX_COOLDOWN_MS), or undefined when the value is
+ * malformed. An HTTP-date already in the past yields an immediate (1 ms) retry.
+ */
 function parseRetryAfterMs(value: string | null | undefined, now = Date.now()): number | undefined {
   const text = value?.trim();
   if (!text) return undefined;
   if (/^\d+(?:\.\d+)?$/.test(text)) {
     const seconds = Number(text);
-    if (Number.isFinite(seconds) && seconds > 0) {
+    if (Number.isFinite(seconds) && seconds >= 0) {
       return Math.min(Math.max(Math.ceil(seconds * 1000), 1), MAX_COOLDOWN_MS);
     }
   }
   const timestamp = Date.parse(text);
   if (!Number.isFinite(timestamp)) return undefined;
   const delay = timestamp - now;
-  return delay > 0 ? Math.min(delay, MAX_COOLDOWN_MS) : undefined;
+  // A valid HTTP-date whose retry time has already passed is an immediate retry, exactly like
+  // numeric `Retry-After: 0` — never a malformed-header fallback to the fixed interval.
+  return Math.min(Math.max(delay, 1), MAX_COOLDOWN_MS);
 }
 
+/**
+ * True while the given key is inside its 429 cooldown window (lazily evicting the entry once the
+ * window expires). Used to skip keys that the upstream just rate-limited during failover.
+ */
 function isKeyInCooldown(providerName: string, keyId: string, now = Date.now()): boolean {
   const entry = keyCooldowns.get(cooldownKey(providerName, keyId));
   if (!entry) return false;
@@ -65,6 +88,51 @@ export function hasKeyPoolFailover(provider: OcxProviderConfig): boolean {
   return (provider.apiKeyPool?.length ?? 0) >= 2;
 }
 
+/**
+ * Normalize a provider's `retryOn429` policy, or return null when the knob is absent,
+ * explicitly disabled, or the provider is not key-auth (OAuth/forward credentials must not be
+ * replayed on the same token, forward passthrough never reaches the recovery loop anyway, and
+ * local runtimes have no remote key to preserve). The returned policy is fully defaulted so
+ * callers never re-check fields.
+ */
+export function rateLimitRetryPolicyFor(
+  provider: Pick<OcxProviderConfig, "retryOn429" | "authMode">,
+): Required<RateLimitRetryPolicy> | null {
+  const policy = provider.retryOn429;
+  if (!policy || policy.enabled === false) return null;
+  // Fail closed: only explicit key auth or the documented omitted-default (undefined == key for
+  // custom API-key providers) may use same-key replays. OAuth/forward are never replayed on the
+  // same token, local runtimes have no remote key to preserve, and unknown/custom values are
+  // rejected rather than guessed at.
+  if (provider.authMode !== undefined && provider.authMode !== "key") return null;
+  return {
+    enabled: policy.enabled ?? DEFAULT_RATE_LIMIT_RETRY.enabled,
+    attempts: policy.attempts ?? DEFAULT_RATE_LIMIT_RETRY.attempts,
+    intervalMs: policy.intervalMs ?? DEFAULT_RATE_LIMIT_RETRY.intervalMs,
+    maxIntervalMs: policy.maxIntervalMs ?? DEFAULT_RATE_LIMIT_RETRY.maxIntervalMs,
+    respectRetryAfter: policy.respectRetryAfter ?? DEFAULT_RATE_LIMIT_RETRY.respectRetryAfter,
+  };
+}
+
+/**
+ * Wait before the next same-target replay: upstream Retry-After (seconds or HTTP-date) when
+ * `respectRetryAfter` is on and the header parses, capped at `maxIntervalMs`; otherwise the
+ * fixed `intervalMs`, also capped at `maxIntervalMs` (a single wait never exceeds the cap).
+ * Malformed headers fall back to the fixed interval.
+ */
+export function rateLimitRetryDelayMs(
+  policy: Required<RateLimitRetryPolicy>,
+  retryAfterHeader: string | null | undefined,
+  now = Date.now(),
+): number {
+  const raw = retryAfterHeader?.trim();
+  if (policy.respectRetryAfter && raw) {
+    const parsed = parseRetryAfterMs(raw, now);
+    if (parsed !== undefined) return Math.min(parsed, policy.maxIntervalMs);
+  }
+  return Math.min(policy.intervalMs, policy.maxIntervalMs);
+}
+
 /**
  * Record a 429 for the current key and attempt to switch to the next available one.
  *

package/src/providers/label.ts

@@ -1,6 +1,6 @@
 import { CODEX_ACCOUNT_LOG_LABEL_RE } from "../codex/account-label";
 
-function canonicalUsageProviderLabel(provider: string): string {
+export function canonicalUsageProviderLabel(provider: string): string {
   return provider === "chatgpt" || provider === "openai-multi" ? "openai" : provider;
 }
 

package/src/providers/model-discovery-limits.ts

@@ -0,0 +1,16 @@
+/** Hard process-wide limits shared by all live model-discovery parsers. */
+export const MODEL_DISCOVERY_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+export const MODEL_DISCOVERY_MAX_MODELS = 2_000;
+export const MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH = 1_024;
+
+const MODEL_DISCOVERY_MODEL_ID_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+
+/** Reject model IDs that cannot safely be published as callable catalog selectors. */
+export function isValidModelDiscoveryModelId(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const normalized = value.trim();
+  return Boolean(normalized)
+    && normalized === value
+    && normalized.length <= MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH
+    && !MODEL_DISCOVERY_MODEL_ID_CONTROL_CHARS.test(normalized);
+}

package/src/providers/model-discovery.ts

@@ -1,20 +1,28 @@
 import type { OcxProviderConfig } from "../types";
+import {
+  isValidModelDiscoveryModelId,
+  MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH,
+  MODEL_DISCOVERY_MAX_MODELS,
+  MODEL_DISCOVERY_MAX_RESPONSE_BYTES,
+} from "./model-discovery-limits";
+export {
+  isValidModelDiscoveryModelId,
+  MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH,
+  MODEL_DISCOVERY_MAX_MODELS,
+  MODEL_DISCOVERY_MAX_RESPONSE_BYTES,
+} from "./model-discovery-limits";
 import {
   getProviderRegistryEntry,
   providerMatchesRegistryTransport,
+  registryEntryForProviderDestination,
   type ProviderModelDiscoveryFilter,
   type ProviderModelDiscoveryPredicate,
   type ProviderModelDiscoveryScalar,
   type ProviderModelDiscoverySpec,
 } from "./registry";
 
-/** Hard process-wide limits. Registry entries may lower, but never raise, these ceilings. */
-export const MODEL_DISCOVERY_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
-export const MODEL_DISCOVERY_MAX_MODELS = 2_000;
-export const MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH = 1_024;
 const MODEL_DISCOVERY_MAX_FILTER_VALUES = 256;
 const MODEL_DISCOVERY_MAX_FILTER_STRING_LENGTH = 1_024;
-const MODEL_DISCOVERY_MODEL_ID_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
 
 export interface ResolvedProviderModelDiscovery {
   spec?: ProviderModelDiscoverySpec;
@@ -91,7 +99,12 @@ export function providerModelDiscoverySpecError(spec: ProviderModelDiscoverySpec
       return "discovery path must be a query-free relative/origin path";
     }
     if (path.includes("\\")) return "discovery path must use forward slashes";
-    if (path.split("/").some(segment => segment.replace(/%2e/gi, ".") === "..")) {
+    const segments = path.split("/");
+    if (segments.some((segment, index) => {
+      const decoded = segment.replace(/%2e/gi, ".");
+      if (decoded !== "..") return false;
+      return index !== 0 || segments.filter(s => s.replace(/%2e/gi, ".") === "..").length !== 1;
+    })) {
       return "discovery path must not contain parent-directory segments";
     }
   }
@@ -124,9 +137,14 @@ export function resolveProviderModelDiscovery(
   providerName: string,
   provider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>,
 ): ResolvedProviderModelDiscovery {
-  const entry = providerMatchesRegistryTransport(providerName, provider)
-    ? getProviderRegistryEntry(providerName)
-    : undefined;
+  // The dashboard permits a canonical preset to be saved under a different name. Recover its
+  // registry-owned discovery policy by transport in that case. The destination helper is limited
+  // to exact fixed-key baseUrl + adapter matches, so custom endpoints, OAuth rows, templates, and
+  // overridable destinations cannot acquire another provider's discovery URL or filter.
+  const namedEntry = getProviderRegistryEntry(providerName);
+  const entry = namedEntry
+    ? (providerMatchesRegistryTransport(providerName, provider) ? namedEntry : undefined)
+    : registryEntryForProviderDestination(provider);
   const spec = entry?.modelDiscovery;
   return {
     ...(spec ? { spec } : {}),
@@ -313,12 +331,83 @@ export function extractModelEnvelopeRows(
 }
 
 /** Validate, bound, deduplicate, and declaratively filter OpenAI `{data:[...]}` or top-level arrays (Together `#617`). */
+/**
+ * Metadata a sibling `models[]` array may contribute to an ALREADY-ADMITTED
+ * `data[]` row (#1797).
+ *
+ * llama.cpp serves a dual-envelope body: an Ollama-style `models[]` array
+ * carrying `capabilities` alongside the OpenAI-style `data[]` array carrying
+ * `meta`, so the two halves of one model's metadata never meet and a server
+ * that truthfully advertises "multimodal" produced an image-blind row.
+ *
+ * Two boundaries make this safe, and both were added after review found the
+ * first attempt unsound:
+ *
+ * 1. It runs AFTER admission filtering. Enriching first let a sibling supply
+ *    the exact field a provider filter requires — reproduced against the real
+ *    Chutes policy, where a row lacking `supported_features: ["tools"]` was
+ *    admitted once a same-id sibling provided it. Enrichment may change what is
+ *    KNOWN about a model, never WHICH models are published.
+ * 2. Only the capability keys #1797 needs are copied. A blanket "fill every
+ *    absent key" made the untrusted `models[]` array a way into any field the
+ *    pipeline consumes.
+ *
+ *    The list deliberately EXCLUDES `supported_features` and `features`, even
+ *    though both are capability-shaped: they are the two keys real provider
+ *    filters test (`registry.ts:1591` requires `supported_features` to contain
+ *    "tools"; `registry.ts:1883` tests `features.tool_use`). Ordering already
+ *    prevents a sibling from flipping an admission verdict, but a key that is
+ *    both enrichable and filter-relevant is one refactor away from becoming a
+ *    bypass again. #1797 does not need them.
+ */
+const SIBLING_ENRICHABLE_KEYS = new Set(["capabilities", "modalities", "input_modalities"]);
+
+type SiblingIndex = Map<string, Record<string, unknown> | null>;
+
+function buildSiblingIndex(value: unknown, limit: number): SiblingIndex | null {
+  const record = plainObject(value);
+  const sibling = record?.models;
+  if (!Array.isArray(sibling) || sibling.length === 0 || sibling.length > limit) return null;
+
+  const byId: SiblingIndex = new Map();
+  for (const raw of sibling) {
+    const entry = plainObject(raw);
+    if (!entry) continue;
+    for (const key of ["id", "model", "name"]) {
+      const id = entry[key];
+      if (typeof id !== "string" || id.length === 0) continue;
+      // `null` marks an ambiguous id: two sibling entries claim it, so neither
+      // can be attributed with confidence and both are ignored.
+      byId.set(id, byId.has(id) && byId.get(id) !== entry ? null : entry);
+    }
+  }
+  return byId.size > 0 ? byId : null;
+}
+
+function enrichAdmittedModel(item: ProviderModelsApiItem, siblings: SiblingIndex): ProviderModelsApiItem {
+  const extra = siblings.get(item.id);
+  if (!extra) return item;
+  let merged: Record<string, unknown> | null = null;
+  for (const key of SIBLING_ENRICHABLE_KEYS) {
+    if (!(key in extra) || key in item) continue;
+    merged ??= { ...(item as Record<string, unknown>) };
+    merged[key] = extra[key];
+  }
+  return (merged ?? item) as ProviderModelsApiItem;
+}
+
+function plainObject(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
 export function extractProviderModelItems(
   value: unknown,
   discovery: ResolvedProviderModelDiscovery,
 ): ProviderModelItemsResult {
   const limit = positiveIntegerAtMost(discovery.maxModels, MODEL_DISCOVERY_MAX_MODELS);
   let data: unknown[];
+  let siblings: SiblingIndex | null = null;
   if (Array.isArray(value)) {
     // Together-style top-level /models arrays. Catalog discovery must not treat a stray
     // `models` key on openai-chat responses as valid — only `data` envelopes or top-level arrays.
@@ -328,6 +417,7 @@ export function extractProviderModelItems(
     const envelope = extractModelEnvelopeRows(value, discovery.maxModels, ["data"]);
     if (!envelope.ok) return envelope;
     data = envelope.rows;
+    siblings = buildSiblingIndex(value, limit);
   }
 
   const items: ProviderModelsApiItem[] = [];
@@ -337,20 +427,23 @@ export function extractProviderModelItems(
       return { ok: false, reason: "invalid_shape" };
     }
     const id = (raw as { id?: unknown }).id;
-    if (typeof id !== "string") return { ok: false, reason: "invalid_shape" };
-    const normalizedId = id.trim();
-    if (
-      !normalizedId
-      || normalizedId !== id
-      || normalizedId.length > MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH
-      || MODEL_DISCOVERY_MODEL_ID_CONTROL_CHARS.test(normalizedId)
-    ) {
-      return { ok: false, reason: "invalid_shape" };
+    if (!isValidModelDiscoveryModelId(id)) return { ok: false, reason: "invalid_shape" };
+    const prefix = discovery.spec?.stripIdPrefix;
+    let finalId = id;
+    if (prefix && finalId.startsWith(prefix)) {
+      finalId = finalId.slice(prefix.length);
+      if (!isValidModelDiscoveryModelId(finalId)) continue;
     }
-    const item = raw as ProviderModelsApiItem;
-    if (!providerModelMatchesDiscoveryFilter(item, discovery.spec?.filter) || seen.has(normalizedId)) continue;
-    seen.add(normalizedId);
-    items.push(item);
+    const item = finalId === id ? raw as ProviderModelsApiItem : { ...(raw as ProviderModelsApiItem), id: finalId };
+    // Admission is decided on the ORIGINAL `data[]` row, before any sibling
+    // enrichment. Merging first let a `models[]` entry supply the very field a
+    // provider filter requires — reproduced against the real Chutes policy,
+    // where a row lacking `supported_features: ["tools"]` was admitted once a
+    // same-id sibling provided it. Enrichment must never change WHICH models
+    // are published, only what is known about an already-admitted one.
+    if (!providerModelMatchesDiscoveryFilter(item, discovery.spec?.filter) || seen.has(finalId)) continue;
+    seen.add(finalId);
+    items.push(siblings ? enrichAdmittedModel(item, siblings) : item);
   }
   return { ok: true, items, rawCount: data.length };
 }

package/src/providers/model-rename-migration.ts

@@ -0,0 +1,255 @@
+// Registry model renames do not reach a saved provider config on their own.
+//
+// `reconcileOAuthProviders` refuses to touch a row whose `authMode` is not
+// `oauth` (src/oauth/index.ts), and `enrichProviderFromRegistry` is fill-only by
+// design: it backfills a MISSING field and never rewrites a present one, so a
+// user's hand-edited model list survives an upgrade. Both postures are correct.
+// Their gap is the case where the registry did not ADD a model but RENAMED one:
+// the saved row keeps a retired id forever, the supported id never appears, and
+// the capability metadata stays keyed to an id the vendor is taking offline
+// (issue #1610 — `qwen3.8-max-preview` persisted through the `qwen3.8-max`
+// rename in six separate fields, including a reasoning ladder that had since
+// diverged from the registry's).
+//
+// This migration is deliberately NOT general reconciliation. It rewrites exactly
+// one thing: an id this file declares retired, on a provider that still carries
+// the registry's transport, and only when the registry currently seeds the
+// replacement. Everything else in the row is left alone.
+
+import { PROVIDER_REGISTRY } from "./registry";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+
+export interface ModelRename {
+  /** Registry provider id whose saved rows may carry the retired model id. */
+  provider: string;
+  from: string;
+  to: string;
+  /** Why the vendor retired it, for the startup warning and future readers. */
+  reason: string;
+  /**
+   * Drop the retired key from `modelReasoningEffortMap` instead of renaming it.
+   *
+   * Renaming preserves the VALUE, which is right for records whose values describe the
+   * model — a context window or an effort ladder survives a rename — and wrong for the
+   * one record whose values are themselves wire ids. An effort map saved as
+   * `high -> gemini-3.6-flash-high` would keep naming a dead wire id under the new key,
+   * and the adapter maps effort BEFORE resolving CCA routing, so that value arrives as
+   * an unrecognised effort and silently degrades to the default tier.
+   *
+   * Only that one record is dropped. Emptying the others would be worse than the bug:
+   * catalog enrichment treats an existing `{}` as "already populated" and will not
+   * restore the registry's records, so the migrated user would keep routing correctly
+   * but lose the reasoning picker entirely.
+   */
+  dropReasoningEffortMap?: boolean;
+}
+
+/**
+ * Renames already applied to `PROVIDER_REGISTRY`. An entry stays here after the
+ * registry moves on: it is what repairs configs saved before that move. Removing
+ * one strands every config that has not started since the rename shipped.
+ */
+export const MODEL_RENAMES: readonly ModelRename[] = [
+  {
+    provider: "alibaba-token-plan",
+    from: "qwen3.8-max-preview",
+    to: "qwen3.8-max",
+    reason: "Alibaba shipped Qwen3.8-Max as stable and documents the preview endpoint as liable to be taken offline once preview concludes",
+  },
+  {
+    provider: "alibaba-token-plan-intl",
+    from: "qwen3.8-max-preview",
+    to: "qwen3.8-max",
+    reason: "Alibaba shipped Qwen3.8-Max as stable and documents the preview endpoint as liable to be taken offline once preview concludes",
+  },
+  // Antigravity Flash generations. Google takes the previous Flash model off Cloud Code
+  // Assist almost immediately when the next ships, so a saved 3.6 (or older 3.5) id is a
+  // dead selection rather than a merely outdated one. Routing already redirects these ids
+  // at request time; this migration repairs the saved config so the picker, the allowlist
+  // and the capability maps stop naming a model the backend no longer serves.
+  ...(["gemini-3.6-flash", "gemini-3.6-flash-low", "gemini-3.6-flash-medium", "gemini-3.6-flash-high",
+    "gemini-3.5-flash-extra-low", "gemini-3.5-flash-low", "gemini-3.5-flash-mid", "gemini-3.5-flash-high",
+    "gemini-3-flash-agent"] as const).map(from => ({
+    provider: "google-antigravity",
+    from,
+    to: "gemini-3.7-flash",
+    reason: "Google retires the previous Antigravity Flash generation from Cloud Code Assist when its successor ships, so the saved id no longer resolves to a live model",
+    // The retired Flash tiers were wire ids, so any saved per-model record keyed by one
+    // may also hold one as a value. 3.7 expresses tiers as thinkingLevel names instead.
+    dropReasoningEffortMap: true,
+  })),
+];
+
+/** Provider fields that key metadata by model id. */
+const MODEL_KEYED_RECORDS = [
+  "modelContextWindows",
+  "modelMaxOutputTokens",
+  "modelInputModalities",
+  "modelReasoningEfforts",
+  "modelDefaultReasoningEfforts",
+  "modelReasoningEffortMap",
+] as const;
+
+/** Provider fields that are flat lists of model ids. */
+const MODEL_ID_LISTS = [
+  "models",
+  // A retired id left here is worse than a stale label: `filterCatalogModels` treats
+  // `selectedModels` as an exact-match allowlist, so a user who allowlisted only the
+  // retired model gets NO replacement row at all — the model silently vanishes from
+  // their catalog instead of being renamed. OAuth reconciliation does not cover this
+  // field, so the rename has to.
+  "selectedModels",
+  "noVisionModels",
+  "noReasoningModels",
+  "noTemperatureModels",
+  "noTopPModels",
+  "noPenaltyModels",
+  "autoToolChoiceOnlyModels",
+  "preserveReasoningContentModels",
+  "thinkingBudgetModels",
+  "directReasoningEffortModels",
+] as const;
+
+function renameInList(value: unknown, from: string, to: string): string[] | null {
+  if (!Array.isArray(value) || !value.includes(from)) return null;
+  const seen = new Set<string>();
+  const next: string[] = [];
+  // Rename in place to preserve ordering, and collapse a duplicate if the target
+  // id was already present alongside the retired one.
+  for (const entry of value) {
+    if (typeof entry !== "string") continue;
+    const mapped = entry === from ? to : entry;
+    if (seen.has(mapped)) continue;
+    seen.add(mapped);
+    next.push(mapped);
+  }
+  return next;
+}
+
+function renameInRecord(value: unknown, from: string, to: string): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (!(from in record)) return null;
+  const next: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(record)) {
+    const mapped = key === from ? to : key;
+    if (mapped in next) continue;
+    // An explicit entry already saved under the new id is the newer intent.
+    next[mapped] = key === from && to in record ? record[to] : entry;
+  }
+  return next;
+}
+
+/** Drop the retired key entirely, leaving any entry already saved under the new id. */
+function dropFromRecord(value: unknown, from: string): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (!(from in record)) return null;
+  const next: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(record)) {
+    if (key === from) continue;
+    next[key] = entry;
+  }
+  return next;
+}
+
+/**
+ * `provider/model` rows in the top-level `disabledModels` list.
+ *
+ * The retired row is DROPPED rather than renamed: carrying its disabled state to
+ * the new id would hide the supported model behind a toggle the user set for a
+ * different model. An existing row for the new id is left untouched.
+ */
+function renameDisabledModels(config: OcxConfig, rename: ModelRename): boolean {
+  const list = config.disabledModels;
+  if (!Array.isArray(list)) return false;
+  const retired = `${rename.provider}/${rename.from}`;
+  if (!list.includes(retired)) return false;
+  config.disabledModels = list.filter(entry => entry !== retired);
+  return true;
+}
+
+/**
+ * Only migrate a row that still points at the registry's own endpoint. A user who
+ * repointed `baseUrl` at a different vendor owns their model ids.
+ */
+function providerStillMatchesRegistry(name: string, prov: OcxProviderConfig): boolean {
+  const entry = PROVIDER_REGISTRY.find(row => row.id === name);
+  if (!entry) return false;
+  if (!prov.baseUrl || !entry.baseUrl) return true;
+  const choices = entry.baseUrlChoices?.map(choice => choice.baseUrl) ?? [];
+  const known = [entry.baseUrl, ...choices]
+    .filter((url): url is string => typeof url === "string")
+    .map(url => url.replace(/\/+$/, ""));
+  return known.includes(prov.baseUrl.replace(/\/+$/, ""));
+}
+
+/** Guard against a stale rename: only apply when the registry actually seeds `to`. */
+function registrySeedsTarget(rename: ModelRename): boolean {
+  const entry = PROVIDER_REGISTRY.find(row => row.id === rename.provider);
+  return !!entry?.models?.includes(rename.to);
+}
+
+export interface ModelRenameProjection {
+  config: OcxConfig;
+  changed: boolean;
+  warnings: string[];
+}
+
+/**
+ * Pure projection: apply every applicable rename and report what changed. The
+ * caller decides whether to persist.
+ */
+export function projectModelRenames(
+  config: OcxConfig,
+  renames: readonly ModelRename[] = MODEL_RENAMES,
+): ModelRenameProjection {
+  const warnings: string[] = [];
+  let changed = false;
+
+  for (const rename of renames) {
+    const prov = config.providers?.[rename.provider];
+    if (!prov) continue;
+    if (!registrySeedsTarget(rename)) {
+      warnings.push(
+        `registry no longer seeds "${rename.to}" for "${rename.provider}"; skipping the `
+        + `"${rename.from}" rename rather than writing an id the registry does not know.`,
+      );
+      continue;
+    }
+    if (!providerStillMatchesRegistry(rename.provider, prov)) continue;
+
+    // Provider config is a closed interface, so index through one unknown-cast
+    // view rather than casting at each assignment.
+    const row = prov as unknown as Record<string, unknown>;
+    let touched = false;
+    for (const field of MODEL_ID_LISTS) {
+      const next = renameInList(row[field], rename.from, rename.to);
+      if (!next) continue;
+      row[field] = next;
+      touched = true;
+    }
+    for (const field of MODEL_KEYED_RECORDS) {
+      const next = rename.dropReasoningEffortMap && field === "modelReasoningEffortMap"
+        ? dropFromRecord(row[field], rename.from)
+        : renameInRecord(row[field], rename.from, rename.to);
+      if (!next) continue;
+      row[field] = next;
+      touched = true;
+    }
+    if (prov.defaultModel === rename.from) {
+      prov.defaultModel = rename.to;
+      touched = true;
+    }
+    if (renameDisabledModels(config, rename)) touched = true;
+
+    if (touched) {
+      changed = true;
+      warnings.push(
+        `renamed "${rename.provider}/${rename.from}" to "${rename.to}" in the saved config: ${rename.reason}.`,
+      );
+    }
+  }
+
+  return { config, changed, warnings };
+}

package/src/providers/model-rename-startup.ts

@@ -0,0 +1,28 @@
+import { saveConfig } from "../config";
+import { projectModelRenames } from "./model-rename-migration";
+import type { OcxConfig } from "../types";
+
+export interface ModelRenameStartupDeps {
+  project: typeof projectModelRenames;
+  save: (config: OcxConfig) => void;
+}
+
+/**
+ * Apply registry model renames to the saved config at startup (issue #1610).
+ *
+ * No backup is taken, unlike the OpenAI tier and Alibaba region migrations: those
+ * rewrite credentials and provider identity, where a bad projection is not
+ * recoverable from the config alone. This one only rewrites model ids that the
+ * registry itself no longer seeds, and the pre-migration value is a string this
+ * file still names, so the change is reversible by hand.
+ */
+export function runModelRenameStartupMigration(
+  config: OcxConfig,
+  deps: ModelRenameStartupDeps = { project: projectModelRenames, save: saveConfig },
+): OcxConfig {
+  const projection = deps.project(config);
+  for (const warning of projection.warnings) console.warn(`[model-rename-migration] ${warning}`);
+  if (!projection.changed) return projection.config;
+  deps.save(projection.config);
+  return projection.config;
+}