@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/providers/fastwire.ts

@@ -244,9 +244,22 @@ export function resolveFastPolicy(
   };
 }
 
-export function canonicalFastTierMarker(callerTier: string | undefined): "priority" | undefined {
+/**
+ * Fold a caller's service tier onto a canonical fast marker.
+ *
+ * `ultrafast` is recognised as INTENT even though no shipped catalog advertises it and
+ * `DEFAULT_SERVICE_TIER_FAST_WIRE` has no wire mapping for it. That asymmetry is
+ * deliberate: a caller who sends `ultrafast` (which #3429's reporter did, via their own
+ * catalog edit) was previously folded to `undefined`, which made `fastIntent` false and
+ * recorded `fastOutcome: "not-requested"` — the log asserting the user asked for nothing.
+ * Recognising the intent without a wire mapping lands the attempt on `unknown` instead,
+ * which is the truth: the tier was requested, and we cannot confirm it was honored.
+ */
+export function canonicalFastTierMarker(callerTier: string | undefined): "priority" | "ultrafast" | undefined {
   const folded = callerTier?.trim().toLowerCase();
-  return folded === "priority" || folded === "fast" ? "priority" : undefined;
+  if (folded === "priority" || folded === "fast") return "priority";
+  if (folded === "ultrafast") return "ultrafast";
+  return undefined;
 }
 
 /** Capture Fast demand before the final A1 serialization action rewrites the parsed tier view. */
@@ -298,7 +311,18 @@ export function createAdapterTierMetadata(
 ): AdapterTierMetadata | undefined {
   if (!context || !decision) return undefined;
 
-  const callerCanonicalFast = canonicalFastTierMarker(context.callerTier) === "priority";
+  const callerMarker = canonicalFastTierMarker(context.callerTier);
+  // Two different questions, and conflating them mislabels the record.
+  //
+  // "Did the caller ask for FAST?" governs the drop and suppression facts: the Fast
+  // toggle suppressing a request is only true of the 1.5x Fast tier, so an `ultrafast`
+  // caller turned away by `fastMode: false` was NOT a suppressed Fast request and must
+  // still read as `callerTierDropped`.
+  //
+  // "Did the caller ask for SOME fast-family tier?" is the wider question, and only
+  // `fastIntent` below is entitled to it.
+  const callerCanonicalFast = callerMarker === "priority";
+  const callerFastFamilyIntent = callerMarker !== undefined;
   const callerTierDropped = context.callerTier !== undefined
     && !callerCanonicalFast
     && wireValue === null;
@@ -338,7 +362,7 @@ export function createAdapterTierMetadata(
   // Known-unsupported routes still need a downgrade when the caller/config expressed Fast intent,
   // but they are deliberately outside the effective-demand calculation above.
   const fastIntent = context.demandDecision === "force-fast"
-    || (context.demandDecision === "inherit" && callerCanonicalFast);
+    || (context.demandDecision === "inherit" && callerFastFamilyIntent);
 
   if (!fastIntent) {
     outcome.fastOutcome = "not-requested";
@@ -421,9 +445,14 @@ export function decideTier(
   const callerCanonicalFast = canonicalFastTierMarker(callerTier);
   if (callerCanonicalFast !== undefined) {
     const value = policy.fastWire.canonicalToWire[callerCanonicalFast];
-    return typeof value === "string" && value.length > 0
-      ? { kind: "set", value }
-      : { kind: "drop" };
+    if (typeof value === "string" && value.length > 0) return { kind: "set", value };
+    // A canonical marker with NO wire mapping is not a reason to drop the tier.
+    //
+    // `ultrafast` is recognised as intent but deliberately unmapped, because no wire
+    // advertises it. Dropping here would have made recognition strictly worse than not
+    // recognising it at all: before, `ultrafast` was a foreign tier and
+    // `foreignCallerTiers: "verbatim"` forwarded it untouched. Falling through keeps that
+    // behavior, so an operator-supplied tier still reaches the provider.
   }
   if (callerTier !== undefined && !policy.forwardCallerTier) return { kind: "drop" };
   if (

package/src/providers/initial-model-selection-runtime.ts

@@ -0,0 +1,90 @@
+import { mutatePersistedConfig, validateConfigCandidate } from "../config";
+import { isDeepStrictEqual } from "node:util";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import type { CatalogModel } from "../codex/catalog";
+import {
+  adoptInitialModelSelections,
+  initialModelSelection,
+  initialModelSelectionPending,
+  reconcileInitialModelSelections,
+} from "./initial-model-selection";
+
+interface InitialSelectionBaseline {
+  providers: string[];
+  inventory: unknown;
+  disabled: string;
+}
+
+function inventoryIdentity(config: OcxConfig): unknown {
+  const validated = validateConfigCandidate(config);
+  if (!validated.ok) return null;
+  // Compare all inventory-producing configuration, including custom rows and combos.
+  // Normalize schema defaults, ignoring completed-selection state and switch values.
+  // Listener binding intentionally differs between live and disk after a port/host edit;
+  // it cannot affect provider discovery and must not leave registration pending forever.
+  // The incarnation remains: identical delete/re-add is NOT the same registration.
+  const providers = Object.fromEntries(Object.entries(validated.config.providers).map(([name, provider]) => [name, {
+    ...provider,
+    initialModelSelection: initialModelSelection(provider)?.registrationId,
+  }]));
+  // Ephemeral only: never log this value, which may contain credentials.
+  return JSON.parse(JSON.stringify({ ...validated.config, providers, disabledModels: undefined, port: undefined, hostname: undefined }));
+}
+
+export function captureInitialSelectionBaseline(config: OcxConfig): InitialSelectionBaseline | null {
+  const providers = Object.entries(config.providers)
+    .filter(([, provider]) => initialModelSelectionPending(provider))
+    .map(([name]) => name);
+  if (!providers.length) return null;
+  const inventory = inventoryIdentity(config);
+  return inventory === null ? null : { providers, inventory, disabled: JSON.stringify(config.disabledModels ?? []) };
+}
+
+/** Commit only decisions whose provider and user-selection snapshot still match. */
+export function finalizeInitialModelSelection(
+  config: OcxConfig,
+  baseline: InitialSelectionBaseline | null,
+  models: readonly CatalogModel[],
+  authoritativeProviders: readonly string[],
+): void {
+  if (!baseline || JSON.stringify(config.disabledModels ?? []) !== baseline.disabled) return;
+  if (!isDeepStrictEqual(inventoryIdentity(config), baseline.inventory)) return;
+  try {
+    const outcome = mutatePersistedConfig(fresh => {
+      if (!isDeepStrictEqual(inventoryIdentity(fresh), baseline.inventory)) return { changed: false, value: null };
+      const providers: Record<string, OcxProviderConfig> = {};
+      for (const name of baseline.providers) {
+        const provider = fresh.providers[name];
+        if (!provider || !initialModelSelection(provider)) continue;
+        // A concurrent successful initializer may already have committed its result.
+        // Adopt that result, including any later manual switch edits; never initialize twice.
+        if (initialModelSelectionPending(provider) && JSON.stringify(fresh.disabledModels ?? []) !== baseline.disabled) continue;
+        providers[name] = provider;
+      }
+      const projection = { ...fresh, providers };
+      const changed = reconcileInitialModelSelections(projection, models, authoritativeProviders);
+      if (changed) fresh.disabledModels = projection.disabledModels;
+      return { changed, value: { ...projection, disabledModels: fresh.disabledModels } };
+    });
+    if (outcome.status === "unavailable" || !outcome.value) return;
+    adoptInitialModelSelections(config, outcome.value);
+    if (Object.keys(outcome.value.providers).length) {
+      config.disabledModels = outcome.value.disabledModels === undefined ? undefined : [...outcome.value.disabledModels];
+    }
+  } catch {
+    // Keep pending publication fenced on contention or failed persistence. A later ordinary
+    // model refresh retries; no dedicated timer and no private exception/path output.
+    console.warn("[initial-model-selection] Could not save initial model choices; model exposure remains pending. Retry model discovery.");
+  }
+}
+
+/** Ordinary discovery, before retained catalog evidence is captured. */
+export async function resolvePendingInitialModelSelection(config: OcxConfig): Promise<void> {
+  const baseline = captureInitialSelectionBaseline(config);
+  if (!baseline) return;
+  const { gatherRoutedModels, uniqueCatalogModelsForPublicList } = await import("../codex/catalog");
+  const outcomes: Array<{ provider: string; state: "authoritative" | "degraded" }> = [];
+  const models = await gatherRoutedModels(config, { providerModelOutcomes: outcomes });
+  finalizeInitialModelSelection(config, baseline, uniqueCatalogModelsForPublicList(models),
+    outcomes.filter(outcome => outcome.state === "authoritative").map(outcome => outcome.provider));
+}

package/src/providers/initial-model-selection.ts

@@ -0,0 +1,120 @@
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import { randomUUID } from "node:crypto";
+import { getProviderRegistryEntry, providerMatchesRegistryTransport } from "./registry";
+import { routedSlug, slugEquivalenceKey } from "./slug-codec";
+import { comboDisabledModelSelectors } from "../combos/types";
+import { providerUsesKeyAuthOverride, resolveProviderApiKey } from "./key-store";
+
+export const INITIAL_MODEL_SELECTION_THRESHOLD = 20;
+type Selection = NonNullable<OcxProviderConfig["initialModelSelection"]>;
+
+/** Read only the public, non-secret shape; editor input never owns this state. */
+export function initialModelSelection(provider: OcxProviderConfig | undefined): Selection | undefined {
+  const value = provider?.initialModelSelection;
+  if (!value || value.version !== 1 || typeof value.registrationId !== "string"
+    || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value.registrationId)
+    || !["pending", "ready", "all-off"].includes(value.status)) return undefined;
+  return {
+    version: 1,
+    registrationId: value.registrationId,
+    status: value.status,
+    ...(Number.isSafeInteger(value.modelCount) && value.modelCount! >= 0 ? { modelCount: value.modelCount } : {}),
+  };
+}
+
+export function initialModelSelectionPending(provider: OcxProviderConfig | undefined): boolean {
+  return initialModelSelection(provider)?.status === "pending";
+}
+
+function loginConnection(name: string, provider: OcxProviderConfig): boolean {
+  const entry = getProviderRegistryEntry(name);
+  if (entry && providerMatchesRegistryTransport(name, provider)) {
+    if (entry.authKind === "forward") return true;
+    if (entry.authKind === "oauth") {
+      return !providerUsesKeyAuthOverride(entry, provider, resolveProviderApiKey(provider.apiKey));
+    }
+  }
+  return provider.authMode === "oauth" || provider.authMode === "forward";
+}
+
+/** Registration only: absence on an existing row is legacy/exempt, never a migration trigger. */
+export function initializeProviderModelSelection(
+  name: string,
+  next: OcxProviderConfig,
+  existing?: OcxProviderConfig,
+  config?: Pick<OcxConfig, "disabledModels" | "combos" | "modelDiscovery">,
+): void {
+  delete next.initialModelSelection;
+  if (existing) {
+    for (const key of ["selectedModels", "modelPreset", "newModelPolicy"] as const) {
+      if (next[key] === undefined && existing[key] !== undefined) {
+        Object.assign(next, { [key]: structuredClone(existing[key]) });
+      }
+    }
+    if (existing.initialModelSelection !== undefined) next.initialModelSelection = structuredClone(existing.initialModelSelection);
+  } else {
+    // A deleted provider's discovery history belongs to that old registration too.
+    if (config?.modelDiscovery?.knownModels) delete config.modelDiscovery.knownModels[name];
+    if (config?.modelDiscovery?.recentArrivals) delete config.modelDiscovery.recentArrivals[name];
+    if (config?.disabledModels) {
+      const comboSelectors = new Set(Object.entries(config.combos ?? {})
+        .flatMap(([id, combo]) => comboDisabledModelSelectors(id, combo)));
+      config.disabledModels = config.disabledModels.filter(selector =>
+        !selector.startsWith(`${name}/`) || comboSelectors.has(selector));
+    }
+    if (!loginConnection(name, next)) {
+      next.initialModelSelection = { version: 1, registrationId: randomUUID(), status: "pending" };
+    }
+  }
+}
+
+/** Count the canonical switch identities that the Models inventory displays. */
+export function reconcileInitialModelSelections(
+  config: OcxConfig,
+  models: Iterable<{ provider: string; id: string }>,
+  authoritativeProviders: Iterable<string>,
+): boolean {
+  const selectors = new Map<string, Set<string>>();
+  for (const model of models) {
+    const ids = selectors.get(model.provider) ?? new Set<string>();
+    ids.add(routedSlug(model.provider, model.id));
+    selectors.set(model.provider, ids);
+  }
+  const authoritative = new Set(authoritativeProviders);
+  let changed = false;
+  for (const [name, provider] of Object.entries(config.providers)) {
+    const initial = initialModelSelection(provider);
+    if (initial?.status !== "pending") continue;
+    if (loginConnection(name, provider)) {
+      provider.initialModelSelection = { version: 1, registrationId: initial.registrationId, status: "ready" };
+      changed = true;
+      continue;
+    }
+    if (!authoritative.has(name)) continue;
+    const ids = selectors.get(name) ?? new Set<string>();
+    const allOff = ids.size >= INITIAL_MODEL_SELECTION_THRESHOLD;
+    if (allOff) {
+      const disabled = config.disabledModels ??= [];
+      const keys = new Set(disabled.map(slugEquivalenceKey));
+      for (const id of ids) {
+        const key = slugEquivalenceKey(id);
+        if (!keys.has(key)) { disabled.push(id); keys.add(key); }
+      }
+    }
+    provider.initialModelSelection = { version: 1, registrationId: initial.registrationId, status: allOff ? "all-off" : "ready", modelCount: ids.size };
+    changed = true;
+  }
+  return changed;
+}
+
+export function adoptInitialModelSelections(target: OcxConfig, source: OcxConfig): void {
+  for (const [name, provider] of Object.entries(source.providers)) {
+    if (target.providers[name] && provider.initialModelSelection !== undefined) {
+      target.providers[name].initialModelSelection = structuredClone(provider.initialModelSelection);
+    }
+  }
+}
+
+export function pendingModelSelectionProviders(config: Pick<OcxConfig, "providers">): Set<string> {
+  return new Set(Object.entries(config.providers).filter(([, provider]) => initialModelSelectionPending(provider)).map(([name]) => name));
+}

package/src/providers/key-failover.ts

@@ -8,8 +8,10 @@
  *
  * Modelled after src/codex/routing.ts cooldown logic but scoped to plain API-key pools.
  */
-import { saveConfigPreservingClaudeCode } from "../config";
+import { mutatePersistedConfig } from "../config";
+import { routedProviderConfig } from "../router";
 import type { OcxConfig, OcxProviderConfig, RateLimitRetryPolicy, TransientRetryPolicy } from "../types";
+import { OPENCODE_GO_SESSION_HEADER } from "./opencode-go-transport";
 import { resolveProviderTransport, type OcxProviderTransport } from "./xai-transport";
 import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
 
@@ -174,11 +176,13 @@ export function rateLimitRetryDelayMs(
  * The returned object is a snapshot of the PERSISTED config — it carries none of the
  * registry backfills `routedProviderConfig` merges in at request time. Request paths must
  * not assign it to an active route wholesale; use `rotateProviderTransportOn429`, which
- * takes only the swapped key and keeps the routed provider intact.
+ * rebuilds from this committed row, reapplies registry metadata, and retains only explicit
+ * runtime transport state (`fetch` and generated OpenCode session affinity).
  */
-export function rotateKeyOn429(
+function rotateKeyAfterFailure(
   config: OcxConfig,
   providerName: string,
+  failureStatus: 401 | 429,
   retryAfterHeader: string | null | undefined,
   now = Date.now(),
   attemptedKey?: string,
@@ -187,50 +191,101 @@ export function rotateKeyOn429(
   if (!provider) return null;
   if (provider.authMode === "oauth" || provider.authMode === "forward") return null;
 
-  const pool = provider.apiKeyPool;
-  if (!pool || pool.length < 2) return null;
-
-  // Cool the key that ACTUALLY failed. Under concurrent 429s another request may already have
-  // rotated provider.apiKey — cooling the live key would punish an innocent replacement and can
-  // exhaust a 2-key pool from a single bad key. CAS semantics: callers pass the key they used.
   const failedKey = attemptedKey ?? provider.apiKey;
-  const currentEntry = pool.find(e => e.key === failedKey);
-  if (currentEntry) {
-    const cooldownMs = parseRetryAfterMs(retryAfterHeader, now) ?? DEFAULT_COOLDOWN_MS;
-    keyCooldowns.set(cooldownKey(providerName, currentEntry.id), {
-      cooldownUntil: now + cooldownMs,
-    });
-    sweepExpiredOnWrite(now);
-  }
+  type Rotation =
+    | { provider: OcxProviderConfig; failedId?: string; candidateId?: string }
+    | { exhaustedCount: number; failedId?: string };
+  const outcome = mutatePersistedConfig<Rotation | null>(fresh => {
+    const freshProvider = fresh.providers[providerName];
+    if (!freshProvider || freshProvider.authMode === "oauth" || freshProvider.authMode === "forward") {
+      return { changed: false, value: null };
+    }
+    const pool = freshProvider.apiKeyPool;
+    if (!pool || pool.length < 2) return { changed: false, value: null };
 
-  // Lost the race: someone already rotated away from the failed key. If the live key is healthy,
-  // retry with it as-is instead of rotating a second time.
-  if (attemptedKey !== undefined && provider.apiKey !== attemptedKey) {
-    const liveEntry = pool.find(e => e.key === provider.apiKey);
-    if (liveEntry && !isKeyInCooldown(providerName, liveEntry.id, now)) {
-      return { ...provider };
+    // The callback can be rerun after rebasing, so identify the failed key here but
+    // defer the in-memory cooldown side effect until persistence has succeeded.
+    const failedEntry = pool.find(entry => entry.key === failedKey);
+
+    if (freshProvider.apiKey !== failedKey) {
+      const activeEntry = pool.find(entry => entry.key === freshProvider.apiKey);
+      if (activeEntry && !isKeyInCooldown(providerName, activeEntry.id, now)) {
+        return {
+          changed: false,
+          value: { provider: structuredClone(freshProvider), failedId: failedEntry?.id },
+        };
+      }
     }
-  }
 
-  // Pick the next key that is NOT in cooldown
-  const currentIndex = currentEntry ? pool.indexOf(currentEntry) : -1;
-  for (let i = 1; i < pool.length; i++) {
-    const candidate = pool[(currentIndex + i) % pool.length]!;
-    if (!isKeyInCooldown(providerName, candidate.id, now)) {
-      // Swap active key
-      provider.apiKey = candidate.key;
-      saveConfigPreservingClaudeCode(config);
-      console.warn(
-        // Log ids only — labels are user-supplied free text and could carry secret material.
-        `[key-failover] ${providerName}: 429 on key ${currentEntry?.id ?? "?"}; rotating to key ${candidate.id}`,
-      );
-      return { ...provider };
+    const currentIndex = failedEntry ? pool.indexOf(failedEntry) : -1;
+    const candidateCount = failedEntry ? pool.length - 1 : pool.length;
+    for (let offset = 1; offset <= candidateCount; offset += 1) {
+      const candidate = pool[(currentIndex + offset) % pool.length]!;
+      if (isKeyInCooldown(providerName, candidate.id, now)) continue;
+      freshProvider.apiKey = candidate.key;
+      return {
+        changed: true,
+        value: {
+          provider: structuredClone(freshProvider),
+          failedId: failedEntry?.id,
+          candidateId: candidate.id,
+        },
+      };
     }
+    return { changed: false, value: { exhaustedCount: pool.length, failedId: failedEntry?.id } };
+  });
+  if (outcome.status === "unavailable" || outcome.value === null) return null;
+  if (outcome.value.failedId) {
+    // A 401 is a verdict about the credential itself, not a timing signal: the key is rejected
+    // until an operator replaces it, and upstreams send no Retry-After for it. Hold it for the
+    // 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;
+    keyCooldowns.set(cooldownKey(providerName, outcome.value.failedId), { cooldownUntil: now + cooldownMs });
+    sweepExpiredOnWrite(now);
+  }
+  if ("exhaustedCount" in outcome.value) {
+    console.warn(`[key-failover] ${providerName}: all ${outcome.value.exhaustedCount} keys in cooldown after ${failureStatus}; returning the upstream status to the client`);
+    return null;
+  }
+
+  const committed = structuredClone(outcome.value.provider);
+  config.providers[providerName] = committed;
+  if (outcome.value.candidateId) {
+    console.warn(
+      // Log ids only — labels are user-supplied free text and could carry secret material.
+      `[key-failover] ${providerName}: ${failureStatus} on key ${outcome.value.failedId ?? "?"}; rotating to key ${outcome.value.candidateId}`,
+    );
   }
+  return structuredClone(committed);
+}
+
+export function rotateKeyOn429(
+  config: OcxConfig,
+  providerName: string,
+  retryAfterHeader: string | null | undefined,
+  now = Date.now(),
+  attemptedKey?: string,
+): OcxProviderConfig | null {
+  return rotateKeyAfterFailure(config, providerName, 429, retryAfterHeader, now, attemptedKey);
+}
 
-  // All keys in cooldown
-  console.warn(`[key-failover] ${providerName}: all ${pool.length} keys in cooldown; returning 429 to client`);
-  return null;
+/**
+ * Record a 401 for the current key and attempt to switch to the next available one.
+ *
+ * A static key pool can recover a credential-scoped 401 without abandoning the provider: one
+ * revoked or mistyped key in a pool of several says nothing about its siblings. OAuth and
+ * forward providers never reach here — they refresh or re-authenticate instead, and
+ * `rotateKeyAfterFailure` rejects both auth modes outright.
+ */
+export function rotateKeyOn401(
+  config: OcxConfig,
+  providerName: string,
+  now = Date.now(),
+  attemptedKey?: string,
+): OcxProviderConfig | null {
+  return rotateKeyAfterFailure(config, providerName, 401, null, now, attemptedKey);
 }
 
 export function sweepExpiredApiKeyCooldowns(now = Date.now()): number {
@@ -253,13 +308,8 @@ interface RotateProviderTransportOptions {
 /**
  * Rotate a failed key and re-apply provider-specific transport metadata to the replacement.
  *
- * `routedProvider` is the request's active provider (the `routedProviderConfig` output the
- * route was built with). The result inherits it and swaps ONLY the API key: the persisted
- * config that `rotateKeyOn429` snapshots predates registry backfill, so building the retry
- * provider from that snapshot would silently drop every field the registry merged in at
- * routing time (scalar flags like `promptCacheKey`/`parallelToolCalls`, merged model
- * metadata such as `noTemperatureModels`, a pinned baseUrl). Mirrors the OAuth-401 replay
- * path in src/server/responses/core.ts, which spreads `route.provider` for the same reason.
+ * Route the authoritative committed row again so concurrent provider edits take effect, then
+ * restore only transport-only state that can never come from persisted configuration.
  */
 export function rotateProviderTransportOn429(
   config: OcxConfig,
@@ -274,13 +324,43 @@ export function rotateProviderTransportOn429(
     options.now,
     options.attemptedKey,
   );
-  return rotated
-    ? resolveProviderTransport(
-        providerName,
-        { ...routedProvider, apiKey: rotated.apiKey },
-        options.promptCacheKey,
-      )
-    : null;
+  if (!rotated) return null;
+  return applyRotatedTransport(providerName, routedProvider, rotated, options.promptCacheKey);
+}
+
+/** 401 counterpart of `rotateProviderTransportOn429`; shares its transport-rebuild rules. */
+export function rotateProviderTransportOn401(
+  config: OcxConfig,
+  providerName: string,
+  routedProvider: OcxProviderTransport,
+  options: Omit<RotateProviderTransportOptions, "retryAfter"> = {},
+): OcxProviderTransport | null {
+  const rotated = rotateKeyOn401(config, providerName, options.now, options.attemptedKey);
+  if (!rotated) return null;
+  return applyRotatedTransport(providerName, routedProvider, rotated, options.promptCacheKey);
+}
+
+function applyRotatedTransport(
+  providerName: string,
+  routedProvider: OcxProviderTransport,
+  rotated: OcxProviderConfig,
+  promptCacheKey?: string,
+): OcxProviderTransport {
+  const committedRoute = routedProviderConfig(providerName, rotated);
+  const routedSession = routedProvider.headers?.[OPENCODE_GO_SESSION_HEADER];
+  const retryProvider: OcxProviderTransport = {
+    ...committedRoute,
+    ...(routedProvider.fetch !== undefined ? { fetch: routedProvider.fetch } : {}),
+    ...(routedSession !== undefined
+      ? {
+          headers: {
+            ...(committedRoute.headers ?? {}),
+            [OPENCODE_GO_SESSION_HEADER]: routedSession,
+          },
+        }
+      : {}),
+  };
+  return resolveProviderTransport(providerName, retryProvider, promptCacheKey);
 }
 
 /** Clear cooldown state for a provider (e.g. after manual key management). */

package/src/providers/key-store.ts

@@ -1,6 +1,17 @@
 import { createRequire } from "node:module";
 import { resolveEnvValue, saveConfigPreservingClaudeCode } from "../config";
 import type { OcxConfig, OcxProviderConfig } from "../types";
+import type { ProviderRegistryEntry } from "./registry";
+
+/** Shared with routing: a key-mode override is effective only while its key resolves. */
+export function providerUsesKeyAuthOverride(
+  entry: Pick<ProviderRegistryEntry, "authKind" | "allowKeyAuthOverride">,
+  provider: Pick<OcxProviderConfig, "authMode">,
+  resolvedKey: string | undefined,
+): boolean {
+  return entry.authKind === "oauth" && entry.allowKeyAuthOverride === true
+    && provider.authMode === "key" && typeof resolvedKey === "string" && resolvedKey.trim().length > 0;
+}
 
 /**
  * Opt-in OS keychain storage for provider API keys (#1221).
@@ -194,4 +205,3 @@ export function restoreProviderKeyFromKeychain(config: OcxConfig, name: string):
   saveConfigPreservingClaudeCode(config);
   return { ok: true, restored: resolved.size };
 }
-

package/src/providers/label.ts

@@ -36,7 +36,7 @@ export function baseProviderLabel(provider: string): string {
  * It lives here rather than in `account-label.ts` because it needs `baseProviderLabel`, and this
  * module already imports from that one -- the reverse direction would be an import cycle. This
  * file stays Lab-clean, which matters because `core.ts` is one of the three files
- * `tests/core-lab-boundary.test.ts` guards.
+ * `tests/lab/core-lab-boundary.test.ts` guards.
  */
 export function stampOAuthAccountLabel(
   logCtx: { accountLogLabel?: string },

package/src/providers/model-discovery.ts

@@ -158,6 +158,82 @@ function appendDiscoveryQuery(url: URL, query: Readonly<Record<string, string>>
   return url;
 }
 
+/**
+ * Whether a model-discovery request URL is a registry-owned fixed discovery
+ * URL — the canonical-URL proof for the transparent fake-IP (Clash/Surge/
+ * Mihomo TUN) exception in provider-outbound.
+ *
+ * The proof is on the FINAL URL, not the provider name: an OAuth/forward name
+ * matches any baseUrl by design (`providerMatchesRegistryTransport` returns
+ * true regardless of destination), while the bearer is pinned to the registry
+ * destination independently in `buildModelsRequest`. Comparing the fetched URL
+ * against registry spec URLs keeps a renamed custom row fetching an
+ * attacker-controlled URL from gaining the exception.
+ *
+ * Both spec shapes are covered: an absolute `url` spec matches its own URL
+ * (plus the spec's fixed query), and a `path` spec matches the URL it resolves
+ * to against the registry's own baseUrl (plus the spec's fixed query) — so the
+ * `commandcode` key preset's `path: "models"` proves the same
+ * `https://api.commandcode.ai/provider/v1/models` string the `command-code`
+ * OAuth `url` spec proves, and the `nebius` `path: "models"` plus
+ * `query: { verbose: "true" }` proves
+ * `https://api.tokenfactory.nebius.com/v1/models?verbose=true`.
+ *
+ * Registry-owned fixed query parameters are canonical only on EXACT match:
+ * a missing, changed, or additional parameter is not canonical, so `?token=`
+ * smuggling on the right origin+path stays rejected. Fragments are never
+ * canonical.
+ */
+export function isRegistryModelDiscoveryUrl(providerName: string, url: string): boolean {
+  const entry = getProviderRegistryEntry(providerName);
+  const spec = entry?.modelDiscovery;
+  if (!spec) return false;
+  let candidate: URL;
+  try {
+    candidate = new URL(url);
+  } catch {
+    return false;
+  }
+  if (candidate.protocol !== "https:") return false;
+  if (candidate.username || candidate.password) return false;
+  if (candidate.hash) return false;
+  const sameUrl = (canonical: string): boolean => {
+    let expected: URL;
+    try {
+      expected = new URL(canonical);
+    } catch {
+      return false;
+    }
+    return candidate.origin === expected.origin
+      && candidate.pathname.replace(/\/+$/, "") === expected.pathname.replace(/\/+$/, "")
+      && candidate.search === expected.search;
+  };
+  // One shared construction with `resolveProviderModelDiscoveryUrl` below: the
+  // absolute `url` form carries the spec's fixed query (if any), and the `path`
+  // form resolves against the REGISTRY's own baseUrl (never a configured one)
+  // before appending the spec's fixed query. The candidate's own query must
+  // equal the registry-owned query exactly — no subset/superset matching.
+  if ("url" in spec && spec.url) {
+    try {
+      return sameUrl(appendDiscoveryQuery(new URL(spec.url), spec.query).toString());
+    } catch {
+      return false;
+    }
+  }
+  if ("path" in spec && spec.path) {
+    try {
+      const base = new URL(entry.baseUrl.endsWith("/") ? entry.baseUrl : `${entry.baseUrl}/`);
+      const resolved = spec.path.startsWith("/")
+        ? new URL(spec.path, base.origin)
+        : new URL(spec.path, base);
+      return sameUrl(appendDiscoveryQuery(resolved, spec.query).toString());
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
 /** Apply a registry-owned URL/path/query policy to the adapter's normal discovery endpoint. */
 export function resolveProviderModelDiscoveryUrl(
   providerName: string,