@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/providers/key-failover.ts

@@ -11,6 +11,8 @@
 import { commitProviderApiKeySelection } from "./api-key-selection";
 import type { ProviderApiKeySelection } from "../types/provider";
 import { routedProviderConfig } from "../router";
+import { getProviderRegistryEntry } from "./registry";
+import { normalizedBaseUrl } from "./quota/vendor-probes-key";
 import type { OcxConfig, OcxProviderConfig, RateLimitRetryPolicy, TransientRetryPolicy } from "../types";
 import { OPENCODE_GO_SESSION_HEADER } from "./opencode-go-transport";
 import { resolveProviderTransport, type OcxProviderTransport } from "./xai-transport";
@@ -29,6 +31,243 @@ interface KeyCooldown {
 const DEFAULT_COOLDOWN_MS = 60_000;
 const MAX_COOLDOWN_MS = 10 * 60_000; // cap at 10 min for api-key rotation
 
+/**
+ * Cap for a cooldown the upstream itself dated, as opposed to one we inferred.
+ *
+ * `MAX_COOLDOWN_MS` is deliberately short because an undated 429 is a guess: ten
+ * minutes bounds how long a transient limit can park a working key. A free-tier
+ * quota is not a guess — OpenRouter replies `Weekly/Monthly Limit Exhausted ...
+ * will reset at <date>`, and until that date the key cannot serve anything. Held
+ * for ten minutes instead, it comes back, takes a 429, and rotates again, every
+ * ten minutes for the rest of the week (#4024).
+ *
+ * 32 days rather than unbounded. The wording this parses is
+ * `Weekly/Monthly Limit Exhausted`, so the cap has to clear a monthly window —
+ * 31 days plus a day of slack for timezone and month length. An earlier 8-day
+ * cap looked generous against the weekly case in the issue and silently clamped
+ * every monthly reset to ~23 days early, which puts the key back into exactly
+ * the 429 loop this exists to stop. Caught by the cap's own test.
+ *
+ * Bounded at all because the date is upstream-controlled input: a malformed or
+ * hostile `reset at 2999-01-01` must not park a working key past any horizon an
+ * operator would think to look at.
+ */
+const MAX_QUOTA_COOLDOWN_MS = 32 * 24 * 60 * 60_000;
+const QUOTA_RESET_PEEK_TIMEOUT_MS = 250;
+
+interface QuotaResetReadOptions {
+  now?: number;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+function rebuiltResponse(response: Response, body: ReadableStream<Uint8Array>): Response {
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}
+
+function replayOnlyResponse(response: Response, chunks: readonly Uint8Array[]): Response {
+  return rebuiltResponse(response, new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const chunk of chunks) controller.enqueue(chunk);
+      controller.close();
+    },
+  }));
+}
+
+/**
+ * Read a bounded prefix of a 429 body and pull the upstream's declared reset instant.
+ *
+ * The returned response replays the bounded prefix and any boundary-chunk overflow
+ * before streaming the unread remainder. A rotation storm must not be gated on
+ * reading N full error payloads. Any failure — no body, already consumed, slow,
+ * malformed — returns undefined and leaves the `Retry-After` path in charge.
+ */
+export async function readQuotaResetAt(
+  response: Response,
+  nowOrOptions: number | QuotaResetReadOptions = {},
+): Promise<{ at: number | undefined; response: Response }> {
+  if (!response.body) return { at: undefined, response };
+  const options = typeof nowOrOptions === "number" ? { now: nowOrOptions } : nowOrOptions;
+  const now = options.now ?? Date.now();
+  let reader: ReadableStreamDefaultReader<Uint8Array>;
+  try {
+    reader = response.body.getReader();
+  } catch {
+    return { at: undefined, response };
+  }
+  const chunks: Uint8Array[] = [];
+  let transferred = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new AbortController();
+  const timeoutReason = new DOMException("Quota reset body peek timed out", "TimeoutError");
+  try {
+    const decoder = new TextDecoder();
+    let seen = 0;
+    let text = "";
+    timer = setTimeout(() => deadline.abort(timeoutReason), options.timeoutMs ?? QUOTA_RESET_PEEK_TIMEOUT_MS);
+    const signal = options.signal
+      ? AbortSignal.any([options.signal, deadline.signal])
+      : deadline.signal;
+    while (seen < QUOTA_RESET_SCAN_BYTES) {
+      const read = reader.read();
+      let rejectAbort: ((reason: unknown) => void) | undefined;
+      const onAbort = () => rejectAbort?.(signal.reason);
+      const aborted = new Promise<never>((_resolve, reject) => {
+        rejectAbort = reject;
+        if (signal.aborted) reject(signal.reason);
+        else signal.addEventListener("abort", onAbort, { once: true });
+      });
+      // Derived from the reader rather than named directly: Bun's lib types
+      // `ReadableStreamDefaultReader.read()` as returning
+      // `ReadableStreamDefaultReadResult`, which is not assignable to the
+      // `ReadableStreamReadResult` alias.
+      let result: Awaited<ReturnType<typeof reader.read>>;
+      try {
+        result = await Promise.race([read, aborted]);
+      } finally {
+        signal.removeEventListener("abort", onAbort);
+      }
+      const { done, value } = result;
+      if (done) break;
+      const remaining = QUOTA_RESET_SCAN_BYTES - seen;
+      const prefix = value.byteLength > remaining ? value.subarray(0, remaining) : value;
+      const overflow = value.byteLength > remaining ? value.subarray(remaining) : undefined;
+      chunks.push(prefix);
+      if (overflow?.byteLength) chunks.push(overflow);
+      seen += prefix.byteLength;
+      text += decoder.decode(prefix, { stream: true });
+    }
+    // Hand back a Response carrying the bytes already pulled followed by whatever
+    // is left, so the caller can still read or cancel it. `response.clone()` is
+    // NOT usable here: it tees, and with the original branch undrained the tee
+    // stalls once its buffer fills — a 5MB error body hangs the rotation path,
+    // which is worse than the unbounded read this replaced.
+    const rest = new ReadableStream<Uint8Array>({
+      start(controller) {
+        for (const c of chunks) controller.enqueue(c);
+      },
+      async pull(controller) {
+        try {
+          const { done, value } = await reader.read();
+          if (done) {
+            controller.close();
+            reader.releaseLock();
+            return;
+          }
+          controller.enqueue(value);
+        } catch (error) {
+          controller.error(error);
+          reader.releaseLock();
+        }
+      },
+      async cancel(reason) {
+        try {
+          await reader.cancel(reason);
+        } finally {
+          reader.releaseLock();
+        }
+      },
+    });
+    transferred = true;
+    return { at: parseQuotaResetAt(text, now), response: rebuiltResponse(response, rest) };
+  } catch (error) {
+    const clientAborted = options.signal?.aborted === true;
+    void reader.cancel(error).catch(() => {}).finally(() => {
+      try { reader.releaseLock(); } catch { /* already released */ }
+    });
+    if (clientAborted) throw options.signal!.reason ?? error;
+    return { at: undefined, response: replayOnlyResponse(response, chunks) };
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (!transferred) {
+      try { reader.releaseLock(); } catch { /* already released */ }
+    }
+  }
+}
+
+/**
+ * How much of a 429 body is read and scanned for the reset instant.
+ *
+ * Bounds the READ, not just the parse: this runs on the rotation path, once per
+ * rotated key under a rate-limit storm, and the body is upstream-controlled.
+ * OpenRouter's rate_limit_error JSON is a few hundred bytes.
+ */
+const QUOTA_RESET_SCAN_BYTES = 4_096;
+
+/**
+ * Reset instant an upstream declared in a 429 *body*, in epoch ms.
+ *
+ * Only the body carries this: OpenRouter sends no `Retry-After` for a quota
+ * exhaustion, so the header path (`parseRetryAfterMs`) sees nothing and falls
+ * back to `DEFAULT_COOLDOWN_MS`. Returns undefined for anything it cannot read
+ * as a date, so an unparsable body keeps today's behaviour exactly.
+ */
+/**
+ * Whether `YYYY-MM-DD…` names a day that exists.
+ *
+ * `Date.parse` does NOT reject an out-of-range day: measured on Bun,
+ * `2026-02-30T00:00:00Z` yields March 2 and `2026-04-31T00:00:00Z` yields
+ * May 1, so a malformed upstream body would park a key past the instant it
+ * actually named. Only the month is rejected outright (`2026-13-01` is NaN).
+ *
+ * Checked on the date text alone rather than by round-tripping the parsed
+ * instant, because a value carrying an explicit offset (`…T23:00+05:30`)
+ * legitimately lands on a different UTC day than the one written.
+ */
+function isRealCalendarDate(value: string): boolean {
+  const [year, month, day] = value.slice(0, 10).split("-").map(Number);
+  if (month < 1 || month > 12 || day < 1) return false;
+  const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+  const lengths = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return day <= lengths[month - 1]!;
+}
+
+export function parseQuotaResetAt(body: string | null | undefined, now = Date.now()): number | undefined {
+  const text = body?.slice(0, QUOTA_RESET_SCAN_BYTES);
+  if (!text) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== "object") return undefined;
+  const error = (parsed as { error?: unknown }).error;
+  if (!error || typeof error !== "object") return undefined;
+  const code = (error as { code?: unknown }).code;
+  const message = (error as { message?: unknown }).message;
+  if ((code !== "rate_limit_error" && code !== 429) || typeof message !== "string") return undefined;
+  if (!/^(?:Weekly|Monthly) Limit Exhausted\b/i.test(message.trim())) return undefined;
+  // `will reset at 2026-09-09 03:30:06` / `... at 2026-09-09T03:30:06Z` / `resets at <date>`
+  const match = /reset[s]?\s+at\s+([0-9]{4}-[0-9]{2}-[0-9]{2}(?:[T ][0-9]{2}:[0-9]{2}(?::[0-9]{2})?(?:\.[0-9]+)?(?:Z|[+-][0-9]{2}:?[0-9]{2})?)?)/i.exec(message);
+  if (!match) return undefined;
+  // Pin a bare `YYYY-MM-DD hh:mm:ss` to UTC explicitly.
+  //
+  // ECMA-262 says a date-TIME form with no offset is LOCAL time, and Node follows
+  // that: `Date.parse("2026-09-09 03:30:06")` differs from the UTC reading by the
+  // host offset (7h on a PDT box, measured). Bun currently returns the UTC value
+  // for the same string, so on this runtime the normalisation is a no-op today —
+  // which is exactly why it is written out rather than relied upon. If Bun ever
+  // conforms, an un-normalised parse would silently shift every park-until by the
+  // operator's offset, and the early direction resumes the 429 loop.
+  //
+  // A consequence worth knowing: no Bun test can observe this branch being
+  // removed. The explicit-zone case below is the part the suite can pin.
+  const raw = match[1].includes("T") || /(?:Z|[+-][0-9]{2}:?[0-9]{2})$/.test(match[1])
+    ? match[1]
+    : `${match[1].replace(" ", "T")}Z`;
+  if (!isRealCalendarDate(match[1])) return undefined;
+  const at = Date.parse(raw);
+  if (!Number.isFinite(at)) return undefined;
+  // Already past, or beyond the cap: not usable as a park-until instant.
+  if (at <= now) return undefined;
+  return Math.min(at, now + MAX_QUOTA_COOLDOWN_MS);
+}
+
 /**
  * Default same-target 429 retry policy used when a provider opts in via a bare
  * `retryOn429: {}` (presence = opt-in with these defaults).
@@ -41,6 +280,43 @@ const DEFAULT_RATE_LIMIT_RETRY = {
   respectRetryAfter: true,
 } as const satisfies Required<RateLimitRetryPolicy>;
 
+/**
+ * Patient same-target 429 fallback for the OpenCode Go destination
+ * (https://opencode.ai/zen/go/v1), which serves subscription traffic such as Muse Spark.
+ * Single-key pools cannot fail over, so without this a burst 429 surfaces immediately and
+ * the client retry budget aborts the goal. Six 10s-paced attempts absorb a short burst
+ * window (effective replays are additionally bounded by the shared per-request send
+ * budget); Retry-After is still honored and capped. An explicit `retryOn429` (including
+ * `enabled: false`) always overrides this fallback.
+ */
+const OPENCODE_GO_RATE_LIMIT_RETRY = {
+  enabled: true,
+  attempts: 6,
+  intervalMs: 10_000,
+  maxIntervalMs: 60_000,
+  respectRetryAfter: true,
+} as const satisfies Required<RateLimitRetryPolicy>;
+
+/** True when the provider row points at the OpenCode Go destination. */
+export function isOpenCodeGoDestination(
+  provider: Partial<Pick<OcxProviderConfig, "baseUrl" | "authMode">>,
+): boolean {
+  const raw = typeof provider.baseUrl === "string" ? provider.baseUrl : "";
+  if (!raw.trim()) return false;
+  // Endpoint identity, not adapter identity: the runtime adapter is already overridden
+  // per model by the time the recovery loop runs (muse-spark rides `openai-responses`
+  // while the preset declares `openai-chat`), so an adapter-strict lookup misses it.
+  // Canonicalize with the shared quota-probe normalizer so host case and explicit
+  // default ports compare equal; userinfo, query, and fragment never match
+  // (follow-up to the review on #5067).
+  const endpoint = normalizedBaseUrl(raw.trim());
+  if (!endpoint) return false;
+  const entry = getProviderRegistryEntry("opencode-go");
+  if (!entry) return false;
+  const candidates = [entry.baseUrl, ...(entry.destinationAliases ?? []).map(alias => alias.baseUrl)];
+  return candidates.some(url => normalizedBaseUrl(url.trim()) === endpoint);
+}
+
 /**
  * Default transient-5xx retry used when a provider opts in with a bare
  * `transientRetryOn5xx: {}`. `attempts` is a TOTAL send budget, not extra retries.
@@ -276,38 +552,47 @@ export function selectProactiveApiKeyTransport(
 }
 
 /**
- * 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.
+ * Normalize a provider's `retryOn429` policy. An explicit object always wins (including
+ * `enabled: false` to opt out). When the knob is absent, the OpenCode Go destination
+ * (subscription traffic such as Muse Spark) falls back to a patient same-key policy so a
+ * burst 429 waits and replays instead of surfacing to the client and aborting a long
+ * session; every other provider without the knob keeps today's fail-fast behavior.
+ * OAuth/forward/local credentials are never replayed on the same token. The returned
+ * policy is fully defaulted so callers never re-check fields.
  */
 export function rateLimitRetryPolicyFor(
-  provider: Pick<OcxProviderConfig, "retryOn429" | "authMode">,
+  provider: Pick<OcxProviderConfig, "retryOn429" | "authMode"> &
+    Partial<Pick<OcxProviderConfig, "baseUrl" | "adapter">>,
 ): 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 (policy) {
+    if (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,
+    };
+  }
+  // No explicit knob: patient fallback for the OpenCode Go destination only.
   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,
-  };
+  if (!isOpenCodeGoDestination(provider)) return null;
+  return { ...OPENCODE_GO_RATE_LIMIT_RETRY };
 }
 
 /**
  * Normalize a provider's `transientRetryOn5xx` policy, or return null when it is absent,
- * explicitly disabled, not key-auth, or not the `openai-chat` adapter.
+ * explicitly disabled, not key-auth, or not an adapter this policy governs.
  *
- * The adapter gate is part of the accepted scope, not incidental: this first version covers
- * key-auth `openai-chat` only, and without an explicit check any generic key-auth adapter
- * could opt in. Auth mode follows the same fail-closed rule as `rateLimitRetryPolicyFor` —
+ * The adapter gate is part of the accepted scope, not incidental: it names the adapters whose
+ * lanes actually read this policy, so no generic key-auth adapter can opt in by accident.
+ * Auth mode follows the same fail-closed rule as `rateLimitRetryPolicyFor` —
  * explicit `key` or the documented omitted default, never OAuth, forward, local, or an
  * unknown value.
  */
@@ -316,7 +601,14 @@ export function transientRetryPolicyFor(
 ): Required<TransientRetryPolicy> | null {
   const policy = provider.transientRetryOn5xx;
   if (!policy || policy.enabled === false) return null;
-  if (provider.adapter !== "openai-chat") return null;
+  // Both adapters this policy governs. The first version covered chat only, which left a
+  // key-auth Responses provider unable to tune its ladder in either direction, because the
+  // Responses passthrough lane hard-coded TRANSIENT_RETRY_MAX_ATTEMPTS (#4893). Widening this
+  // gate is necessary and not sufficient: the lane also has to call this function, which it
+  // now does. Still an explicit list, so no generic key-auth adapter opts in by accident, and
+  // the auth check below keeps the ChatGPT forward pool out -- those providers are
+  // `authMode: "forward"` and keep the default ladder they have always had.
+  if (provider.adapter !== "openai-chat" && provider.adapter !== "openai-responses") return null;
   if (provider.authMode !== undefined && provider.authMode !== "key") return null;
   return {
     enabled: policy.enabled ?? DEFAULT_TRANSIENT_RETRY.enabled,
@@ -363,6 +655,7 @@ function rotateKeyAfterFailure(
   now = Date.now(),
   attemptedKey?: string,
   attemptedSelection?: ProviderApiKeySelection,
+  quotaResetAt?: number,
 ): OcxProviderConfig | null {
   const provider = config.providers[providerName];
   if (!provider) return null;
@@ -421,7 +714,12 @@ function rotateKeyAfterFailure(
     // full cap instead of the 429 default so a dead key is not re-tried once a minute.
     const cooldownMs = failureStatus === 401
       ? MAX_COOLDOWN_MS
-      : parseRetryAfterMs(retryAfterHeader, now) ?? DEFAULT_COOLDOWN_MS;
+      // A reset instant the upstream dated outranks both the header and the
+      // default: it is the only one of the three that knows when the quota
+      // actually returns (#4024).
+      : quotaResetAt !== undefined
+        ? Math.max(quotaResetAt - now, 1)
+        : parseRetryAfterMs(retryAfterHeader, now) ?? DEFAULT_COOLDOWN_MS;
     keyCooldowns.set(cooldownKey(providerName, outcome.value.failedId), { cooldownUntil: now + cooldownMs });
     sweepExpiredOnWrite(now);
   }
@@ -448,8 +746,9 @@ export function rotateKeyOn429(
   now = Date.now(),
   attemptedKey?: string,
   attemptedSelection?: ProviderApiKeySelection,
+  quotaResetAt?: number,
 ): OcxProviderConfig | null {
-  return rotateKeyAfterFailure(config, providerName, 429, retryAfterHeader, now, attemptedKey, attemptedSelection);
+  return rotateKeyAfterFailure(config, providerName, 429, retryAfterHeader, now, attemptedKey, attemptedSelection, quotaResetAt);
 }
 
 /**
@@ -482,6 +781,8 @@ export function sweepExpiredApiKeyCooldowns(now = Date.now()): number {
 
 interface RotateProviderTransportOptions {
   retryAfter?: string | null;
+  /** Epoch ms from `parseQuotaResetAt`, when the upstream dated the reset in its body. */
+  quotaResetAt?: number;
   now?: number;
   attemptedKey?: string;
   attemptedSelection?: ProviderApiKeySelection;
@@ -507,6 +808,7 @@ export function rotateProviderTransportOn429(
     options.now,
     options.attemptedKey,
     options.attemptedSelection ?? routedProvider._apiKeyAttempt,
+    options.quotaResetAt,
   );
   if (!rotated) return null;
   return applyRotatedTransport(providerName, routedProvider, rotated, options.promptCacheKey);

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

@@ -14,9 +14,12 @@
 // 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.
+// replacement — and it skips a field where the retired entry is registry residue
+// with nothing left to carry forward (see `isRegistryResidue`, issue #5066).
+// Everything else in the row is left alone.
 
 import { PROVIDER_REGISTRY } from "./registry";
+import { providerConfigSeed } from "./derive";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 
 export interface ModelRename {
@@ -86,6 +89,7 @@ const MODEL_KEYED_RECORDS = [
   "modelMaxOutputTokens",
   "modelInputModalities",
   "modelReasoningEfforts",
+  "modelSuppressSyntheticMax",
   "modelDefaultReasoningEfforts",
   "modelReasoningEffortMap",
 ] as const;
@@ -193,6 +197,54 @@ function registrySeedsTarget(rename: ModelRename): boolean {
   return !!entry?.models?.includes(rename.to);
 }
 
+/** The row the registry contributes to a saved config, or `undefined` when it dropped the id. */
+function registrySeed(provider: string): Record<string, unknown> | undefined {
+  const entry = PROVIDER_REGISTRY.find(row => row.id === provider);
+  return entry ? (providerConfigSeed(entry) as unknown as Record<string, unknown>) : undefined;
+}
+
+/** Whether a saved list or model-keyed record names this id at all. */
+function publishes(container: unknown, id: string): boolean {
+  if (Array.isArray(container)) return container.includes(id);
+  if (!container || typeof container !== "object") return false;
+  return id in (container as Record<string, unknown>);
+}
+
+/**
+ * Whether this field’s retired entry is registry residue rather than something to repair.
+ *
+ * Two things have to be true. The registry’s own seed — `providerConfigSeed`, the row both the
+ * OAuth preset (`deriveOAuthProviderConfig`) and `enrichProviderFromRegistry` contribute — must
+ * still publish the retired id in this field, so the entry arrives in the config on its own. And
+ * the saved field must already carry the supported id, so the rename would only DELETE a key,
+ * with nothing to carry forward.
+ *
+ * Under those two conditions the rewrite is worse than a no-op, because it never converges.
+ * `startServer` runs this migration and then `reconcileOAuthProviders`, and
+ * `applyOAuthPresetCatalog` copies the preset’s record over the saved one whenever the two
+ * differ. The deletion is undone inside the same boot, the config is written twice, and the user
+ * is told about a rename that never sticks on every single start. Issue #5066 is exactly that:
+ * `ANTIGRAVITY_MODEL_CONTEXT_WINDOWS` derives a window for every compatibility alias, so
+ * `modelContextWindows` holds a key for all nine retired Flash ids beside the live ones — the
+ * nine `[model-rename-migration]` lines the reporter saw at every `ocx start`, none of which
+ * required them to have selected any of those nine models.
+ *
+ * Those registry entries are deliberate and stay: a request that still names `gemini-3.6-flash`
+ * routes to 3.7 and needs a context window under the id it asked for. The second condition is
+ * what keeps this narrow. A row that saved `{ "gemini-3.6-flash": 1048576 }` and nothing else
+ * still gets the value carried onto the supported id, because dropping it there would blank the
+ * record instead of moving it (`tests/adapters/google/gemini-37-flash-migration.test.ts`).
+ */
+function isRegistryResidue(
+  seed: Record<string, unknown> | undefined,
+  field: string,
+  saved: unknown,
+  rename: ModelRename,
+): boolean {
+  if (!seed) return false;
+  return publishes(seed[field], rename.from) && publishes(saved, rename.to);
+}
+
 export interface ModelRenameProjection {
   config: OcxConfig;
   changed: boolean;
@@ -225,14 +277,17 @@ export function projectModelRenames(
     // 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>;
+    const seed = registrySeed(rename.provider);
     let touched = false;
     for (const field of MODEL_ID_LISTS) {
+      if (isRegistryResidue(seed, field, row[field], rename)) continue;
       const next = renameInList(row[field], rename.from, rename.to);
       if (!next) continue;
       row[field] = next;
       touched = true;
     }
     for (const field of MODEL_KEYED_RECORDS) {
+      if (isRegistryResidue(seed, field, row[field], rename)) continue;
       const next = rename.dropReasoningEffortMap && field === "modelReasoningEffortMap"
         ? dropFromRecord(row[field], rename.from)
         : renameInRecord(row[field], rename.from, rename.to);

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

@@ -1,12 +1,13 @@
 import { mutatePersistedConfig } from "../config";
 import { projectModelRenames } from "./model-rename-migration";
 import { projectStaleContextWindows } from "./stale-context-window-migration";
+import { projectStaleVisionClassifications } from "./stale-vision-classification-migration";
 import { projectDevinCliAuthMode } from "./devin-cli-authmode-migration";
 import type { OcxConfig } from "../types";
 
 /**
- * The startup projection: registry model renames, then the context-window
- * repair. Both fix a saved row the registry can no longer reach on its own —
+ * The startup projection: registry model renames, then the context-window and
+ * vision-classification repairs. All three fix a saved row the registry can no longer reach on its own —
  * `enrichProviderFromRegistry` backfills a missing field and never rewrites a
  * present one — so they share this pass rather than adding a second boot step
  * with its own persistence, adopt, and failure handling.
@@ -14,11 +15,12 @@ import type { OcxConfig } from "../types";
 export function projectStartupConfigRepairs(config: OcxConfig): ReturnType<typeof projectModelRenames> {
   const renames = projectModelRenames(config);
   const windows = projectStaleContextWindows(renames.config);
-  const devinCli = projectDevinCliAuthMode(windows.config);
+  const vision = projectStaleVisionClassifications(windows.config);
+  const devinCli = projectDevinCliAuthMode(vision.config);
   return {
     config: devinCli.config,
-    changed: renames.changed || windows.changed || devinCli.changed,
-    warnings: [...renames.warnings, ...windows.warnings, ...devinCli.warnings],
+    changed: renames.changed || windows.changed || vision.changed || devinCli.changed,
+    warnings: [...renames.warnings, ...windows.warnings, ...vision.warnings, ...devinCli.warnings],
   };
 }
 

package/src/providers/openai-sidecar.ts

@@ -32,6 +32,8 @@ export interface ResolvedOpenAiForwardSidecar extends OpenAiForwardSidecarCandid
   authContext: CodexAuthContext;
   headers: Headers;
   recordOutcome?: (outcome: CodexUpstreamOutcome) => void;
+  /** Hand back an acquired recovery probe when no sidecar request reached upstream. */
+  releaseProbeLease?: () => void;
 }
 
 /**
@@ -189,6 +191,7 @@ export async function resolveFirstUsableOpenAiSidecar(
             ...(authContext.kind === "pool" ? { credentialGeneration: authContext.generation } : {}),
           },
         ),
+        releaseProbeLease: () => releaseCodexAuthContextProbeLease(authContext),
       };
     }
     if (candidate.accountMode === "direct") {
@@ -237,6 +240,7 @@ export async function resolveFirstUsableOpenAiSidecar(
               ...(authContext.kind === "pool" ? { credentialGeneration: authContext.generation } : {}),
             },
           ),
+          releaseProbeLease: () => releaseCodexAuthContextProbeLease(authContext),
         }
         : {}),
     };

package/src/providers/openai-virtual-models.ts

@@ -3,6 +3,9 @@ import { OPENAI_API_PROVIDER_ID } from "./openai-tiers";
 import type { OcxParsedRequest } from "../types";
 import type { RouteResult } from "../router";
 import type { RequestLogContext } from "../server/request-log";
+import type { InboundWire } from "./registry/types";
+import { providerMatchesRegistryTransportWithStaticGuards } from "./static-model-discovery";
+import { resolveModelPolicy } from "./resolved-model-policy";
 
 export interface OpenAiVirtualModelResolution {
   selectedModelId: string;
@@ -49,18 +52,55 @@ export function resolveOpenAiVirtualModel(
   return validateOpenAiVirtualModelDefinition(selectedModelId, definition);
 }
 
+export function captureOpenAiVirtualWirePolicy(
+  route: RouteResult,
+  resolution: OpenAiVirtualModelResolution,
+  inboundWire: InboundWire = "responses",
+): void {
+  // applyOpenAiVirtualModel is also a public mutation helper with older focused callers that
+  // construct only providerName/modelId/provider. Production RouteResult builders always capture
+  // staticPolicy; a legacy partial shape has no authority to recapture and keeps the old rewrite.
+  if (!route.staticPolicy) return;
+  const entry = PROVIDER_REGISTRY.find(candidate => candidate.id === route.providerName);
+  route.staticPolicy = resolveModelPolicy({
+    providerName: route.providerName,
+    modelId: resolution.wireModelId,
+    provider: route.provider,
+    registryEntry: entry,
+    transportMatchedRegistry: !!entry
+      && providerMatchesRegistryTransportWithStaticGuards(route.providerName, route.provider),
+    inboundWire,
+    modelCapabilities: route.provider.modelCapabilities?.[resolution.wireModelId],
+    ...(route.provider.authMode ? { effectiveAuth: { authMode: route.provider.authMode } } : {}),
+    ...(route.staticPolicy?.effectiveAlias !== undefined
+      ? { effectiveAlias: route.staticPolicy.effectiveAlias }
+      : {}),
+  });
+}
+
 export function applyOpenAiVirtualModel(
   parsed: OcxParsedRequest,
   route: RouteResult,
   logCtx: RequestLogContext,
+  inboundWire: InboundWire = "responses",
 ): OpenAiVirtualModelResolution | undefined {
-  const selectedModelId = logCtx.model && logCtx.model !== route.modelId ? logCtx.model : route.modelId;
-  const resolution = resolveOpenAiVirtualModel(route.providerName, selectedModelId);
+  // Routing has already removed the provider namespace and resolved model aliases. Never use
+  // logCtx.model for identity: it is reporting state and can still contain a namespaced selector.
+  const resolution = resolveOpenAiVirtualModel(route.providerName, route.modelId)
+    ?? (() => {
+      // Preserve the public helper's idempotent second-call contract from its own mutation
+      // provenance, without promoting reporting state back into routing authority.
+      const selected = parsed._openAiVirtualSelectedModelId;
+      if (typeof selected !== "string") return undefined;
+      const remembered = resolveOpenAiVirtualModel(route.providerName, selected);
+      return remembered?.wireModelId === route.modelId ? remembered : undefined;
+    })();
   if (!resolution) return undefined;
 
   logCtx.model = resolution.selectedModelId;
   logCtx.resolvedModel = resolution.wireModelId;
   route.modelId = resolution.wireModelId;
+  captureOpenAiVirtualWirePolicy(route, resolution, inboundWire);
   parsed.modelId = resolution.wireModelId;
   parsed._openAiVirtualSelectedModelId = resolution.selectedModelId;