@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/oauth/generic-account-failover.ts

@@ -148,30 +148,51 @@ export function hasFailoverAccountQuorum(providerName: string, now = Date.now())
 }
 
 /**
- * Whether generic rotation is active for this provider.
+ * Whether REACTIVE 429 rotation is active for this provider.
  *
- * Precedence, most specific first:
+ * Presence is the only rule: two or more eligible stored accounts. The
+ * `oauthAccountFailover.enabled` booleans no longer suppress it.
  *
- *   1. `providers.<name>.oauthAccountFailover.enabled` — an operator may accept rotation on one
- *      provider and refuse it on another, because provider terms differ.
- *   2. `oauthAccountFailover.enabled` — the global switch. Anyone who already wrote `false` keeps
- *      strict single-account behaviour across this change.
- *   3. Presence: 2 or more eligible stored accounts (#2568d, owner decision).
+ * That is a deliberate narrowing of #2568d. Rotation here runs only after upstream has already
+ * refused the request, so the choice the old knob offered was between "retry on the second
+ * account you deliberately logged in" and "return a 429 while that account sits idle". The
+ * second is a defect, not a preference — and an operator who does not want rotation expresses
+ * that by not storing a second account, exactly as they do for `apiKeyPool`.
  *
- * Only an explicit boolean overrides presence. A malformed value falls through instead of
- * throwing, because a typo in a knob must not take a provider out of service.
+ * The knob is not gone. It still governs {@link isProactivePreferenceEnabled}, which decides
+ * whether a HEALTHY request may be steered to a different account before dispatch — a real
+ * behavioural choice that remains refusable — and it still carries `strategy` and
+ * `autoSwitchThreshold`.
  */
 export function isGenericOAuthFailoverEnabled(
   config: OcxConfig,
   providerName: string,
   now = Date.now(),
 ): boolean {
+  const provider = config.providers?.[providerName];
+  if (!provider || !isGenericFailoverProvider(providerName, provider)) return false;
+  return hasFailoverAccountQuorum(providerName, now);
+}
+
+/**
+ * Whether the pre-dispatch account PREFERENCE may run for this provider.
+ *
+ * Unlike reactive rotation, this moves a request that upstream has not refused, so it stays
+ * refusable: an explicit provider value wins over the global default, and a global `false`
+ * turns it off only when the provider has no override. A malformed value falls through rather
+ * than taking a provider out of service.
+ */
+function isProactivePreferenceEnabled(config: OcxConfig, providerName: string, now: number): boolean {
   const provider = config.providers?.[providerName];
   if (!provider || !isGenericFailoverProvider(providerName, provider)) return false;
   const perProvider = provider.oauthAccountFailover?.enabled;
-  if (typeof perProvider === "boolean") return perProvider;
-  const global = config.oauthAccountFailover?.enabled;
-  if (typeof global === "boolean") return global;
+  // Preserve the published narrow-over-broad precedence. A provider-specific true may
+  // opt this provider into proactive preference even when the global default is false;
+  // a provider-specific false refuses it even when the global setting is true.
+  if (typeof perProvider === "boolean") {
+    return perProvider && hasFailoverAccountQuorum(providerName, now);
+  }
+  if (config.oauthAccountFailover?.enabled === false) return false;
   return hasFailoverAccountQuorum(providerName, now);
 }
 
@@ -265,7 +286,9 @@ export function preferredInitialAccount(
   providerName: string,
   now = Date.now(),
 ): string | null {
-  if (!isGenericOAuthFailoverEnabled(config, providerName)) return null;
+  // The PROACTIVE predicate, not the reactive one: this steers a request upstream has not
+  // refused, so `oauthAccountFailover.enabled: false` must still be able to refuse it.
+  if (!isProactivePreferenceEnabled(config, providerName, now)) return null;
   // This runs on the initial resolution of EVERY request, and `loadAuthStore` has no
   // cache: each call chmods the config dir, chmods the secret, reads the whole file and
   // normalizes it (store.ts:136-151). So the store is consulted at most ONCE here, behind

package/src/oauth/index.ts

@@ -1,7 +1,8 @@
 import type { KiroOAuthMetadata, OAuthController, OAuthCredentials } from "./types";
+import { initializeProviderModelSelection } from "../providers/initial-model-selection";
 import { parseCallbackInput } from "./callback-server";
 import type { OcxConfig, OcxProviderConfig, RefreshPolicy } from "../types";
-import { ConfigMutationLockError, loadConfig, saveConfig } from "../config";
+import { ConfigMutationLockError, loadConfig, mutatePersistedConfig, saveConfig } from "../config";
 import { resolveProviderApiKey } from "../providers/key-store";
 import { maskEmail } from "../lib/privacy";
 import { KiroTokenRefreshError, environmentKiroRoutingMetadata, loginKiro, refreshKiroToken, settleKiroLoginTransaction } from "./kiro";
@@ -1247,42 +1248,134 @@ function migrateLegacyAntigravityStaticCatalog(config: OcxConfig): boolean {
   return true;
 }
 
-export function reconcileOAuthProviders(config: OcxConfig): boolean {
-  let changed = migrateLegacyAntigravityStaticCatalog(config);
-  for (const [name, prov] of Object.entries(config.providers)) {
+interface OAuthReconcileProjection {
+  config: OcxConfig;
+  changed: boolean;
+  touchedProviders: string[];
+  touchedAntigravityVersion: boolean;
+}
+
+/** Pure projection over a clone: apply every reconciliation rule and report what it touched. */
+function projectOAuthProviderReconciliation(config: OcxConfig): OAuthReconcileProjection {
+  const projected = structuredClone(config);
+  const touchedProviders = new Set<string>();
+  const beforeAntigravity = JSON.stringify(projected.providers[GOOGLE_ANTIGRAVITY_PROVIDER]);
+  const beforeAntigravityVersion = projected.googleAntigravityStaticCatalogVersion;
+  let changed = migrateLegacyAntigravityStaticCatalog(projected);
+  if (JSON.stringify(projected.providers[GOOGLE_ANTIGRAVITY_PROVIDER]) !== beforeAntigravity) {
+    touchedProviders.add(GOOGLE_ANTIGRAVITY_PROVIDER);
+  }
+  const touchedAntigravityVersion = projected.googleAntigravityStaticCatalogVersion !== beforeAntigravityVersion;
+
+  for (const [name, prov] of Object.entries(projected.providers)) {
+    const beforeProvider = JSON.stringify(prov);
     const def = OAUTH_PROVIDERS[name];
     if (name === "command-code" && isLegacyCommandCodeStaticCatalog(prov)) {
       // The former experimental preset was the exact three-model seed above. It was not a user
       // choice to disable discovery, so promote only that shape to the account live catalog.
       prov.liveModels = true;
-      changed = true;
     }
-    if (!def || prov.authMode !== "oauth") continue;
-    const preset = def.providerConfig;
-    for (const field of OAUTH_RECONCILE_FIELDS) {
-      if (JSON.stringify(prov[field]) === JSON.stringify(preset[field])) continue;
-      if (preset[field] !== undefined) {
-        prov[field] = cloneProviderField(preset[field]) as never;
-      } else {
-        delete prov[field];
+    if (def && prov.authMode === "oauth") {
+      const preset = def.providerConfig;
+      for (const field of OAUTH_RECONCILE_FIELDS) {
+        if (JSON.stringify(prov[field]) === JSON.stringify(preset[field])) continue;
+        if (preset[field] !== undefined) {
+          prov[field] = cloneProviderField(preset[field]) as never;
+        } else {
+          delete prov[field];
+        }
+      }
+      if (prov.liveModels === undefined && preset.liveModels !== undefined) {
+        prov.liveModels = preset.liveModels;
+      }
+      // Heal a defaultModel that no longer exists in the refreshed list (e.g. a deprecated snapshot).
+      // Skip providers without a static preset `models` list: for live-discovery providers
+      // (e.g. command-code OAuth) the account-scoped catalog is not enumerable here, so any
+      // persisted defaultModel is a user selection and must not be overwritten by the seed.
+      if (prov.defaultModel && preset.defaultModel && preset.models && preset.models.length > 0 && !(prov.models ?? []).includes(prov.defaultModel)) {
+        prov.defaultModel = preset.defaultModel;
       }
-      changed = true;
-    }
-    if (prov.liveModels === undefined && preset.liveModels !== undefined) {
-      prov.liveModels = preset.liveModels;
-      changed = true;
     }
-    // Heal a defaultModel that no longer exists in the refreshed list (e.g. a deprecated snapshot).
-    // Skip providers without a static preset `models` list: for live-discovery providers
-    // (e.g. command-code OAuth) the account-scoped catalog is not enumerable here, so any
-    // persisted defaultModel is a user selection and must not be overwritten by the seed.
-    if (prov.defaultModel && preset.defaultModel && preset.models && preset.models.length > 0 && !(prov.models ?? []).includes(prov.defaultModel)) {
-      prov.defaultModel = preset.defaultModel;
+    if (JSON.stringify(prov) !== beforeProvider) {
       changed = true;
+      touchedProviders.add(name);
     }
   }
-  if (changed) saveConfig(config);
-  return changed;
+
+  return {
+    config: projected,
+    changed,
+    touchedProviders: [...touchedProviders],
+    touchedAntigravityVersion,
+  };
+}
+
+/**
+ * Copy only the keys the projection actually touched back onto the caller's live object.
+ *
+ * Deliberately key-by-key rather than a wholesale clear-and-reassign: a live reference held
+ * elsewhere to an untouched provider sub-object must survive startup reconciliation.
+ */
+function adoptOAuthReconciliation(config: OcxConfig, projection: OAuthReconcileProjection): void {
+  for (const name of projection.touchedProviders) {
+    const provider = projection.config.providers[name];
+    if (provider) config.providers[name] = structuredClone(provider);
+    else delete config.providers[name];
+  }
+  if (projection.touchedAntigravityVersion) {
+    config.googleAntigravityStaticCatalogVersion = projection.config.googleAntigravityStaticCatalogVersion;
+  }
+}
+
+/**
+ * Union the keys the on-disk rebase touched with the keys the live projection touched.
+ *
+ * The rebase runs against the persisted snapshot, which may already carry a reconciliation
+ * another process committed. Adopting only its touched set would leave the live object stale
+ * for a key it decided was already correct on disk.
+ */
+function withOAuthReconciliationTouchedKeys(
+  projection: OAuthReconcileProjection,
+  required: OAuthReconcileProjection,
+): OAuthReconcileProjection {
+  return {
+    ...projection,
+    touchedProviders: [...new Set([...projection.touchedProviders, ...required.touchedProviders])],
+    touchedAntigravityVersion: projection.touchedAntigravityVersion || required.touchedAntigravityVersion,
+  };
+}
+
+/**
+ * Refresh OAuth provider presets against the registry, rebasing the write on the persisted config.
+ *
+ * This runs on the boot path (`startServer`), so persistence failure must never be fatal: a
+ * missing, malformed or contended config degrades to a warning plus an in-memory adopt, exactly
+ * as every other `mutatePersistedConfig` consumer does (`src/storage/policy.ts`,
+ * `src/codex/plan-from-token.ts`, `src/server/management/agent-settings-routes.ts`). Throwing
+ * here would take the whole proxy down over a config file the operator can still repair.
+ */
+export function reconcileOAuthProviders(config: OcxConfig, persist = true): boolean {
+  const projection = projectOAuthProviderReconciliation(config);
+  if (!projection.changed) return false;
+  if (!persist) {
+    adoptOAuthReconciliation(config, projection);
+    return true;
+  }
+  const outcome = mutatePersistedConfig(fresh => {
+    const next = projectOAuthProviderReconciliation(fresh);
+    if (next.changed) adoptOAuthReconciliation(fresh, next);
+    return { changed: next.changed, value: next };
+  });
+  if (outcome.status === "unavailable") {
+    console.warn(
+      `[opencodex] OAuth provider reconciliation could not be persisted (${outcome.reason}); `
+      + "applying it in memory for this run only.",
+    );
+    adoptOAuthReconciliation(config, projection);
+    return true;
+  }
+  adoptOAuthReconciliation(config, withOAuthReconciliationTouchedKeys(outcome.value, projection));
+  return true;
 }
 
 /** Runtime guards: provider config is intentionally passthrough, so persisted fields may be malformed. */
@@ -1353,6 +1446,13 @@ export function upsertOAuthProvider(config: OcxConfig, provider: string): void {
   if (existing?.commandCodeVersion !== undefined) {
     next.commandCodeVersion = existing.commandCodeVersion;
   }
+  // Reauth/add-account refreshes credentials, not the operator's post-upgrade wire choice.
+  if (provider === "xai") {
+    if (existing?.modelAdapters !== undefined) next.modelAdapters = { ...existing.modelAdapters };
+    if (existing?.xaiResponsesDefaultVersion !== undefined) {
+      next.xaiResponsesDefaultVersion = existing.xaiResponsesDefaultVersion;
+    }
+  }
   // User-configured price overlays are operator data, not preset state; a
   // re-login, add-account, or reauth must not silently drop them from the
   // Logs/Usage estimates.
@@ -1389,6 +1489,7 @@ export function upsertOAuthProvider(config: OcxConfig, provider: string): void {
       if (previousModeAllowsKey) next.authMode = "key";
     }
   }
+  initializeProviderModelSelection(provider, next, existing, config);
   config.providers[provider] = next;
 }
 

package/src/oauth/login-cli.ts

@@ -1,4 +1,6 @@
 import * as readline from "node:readline";
+import { modelSelectionGuidance } from "../cli/model-selection-guidance";
+import { initializeProviderModelSelection } from "../providers/initial-model-selection";
 import { openUrl } from "../lib/open-url";
 import { loadConfig, saveConfig } from "../config";
 import { findLiveProxy } from "../server/proxy-liveness";
@@ -93,6 +95,7 @@ async function handleOAuthLogin(name: string): Promise<void> {
   }
   const reload = await notifyRunningProxyAfterOAuthLogin(name);
   console.log(`\n✅ Logged in to ${name}. Try: ocx sync`);
+  for (const line of modelSelectionGuidance(name)) console.log(line);
   warnIfLiveReloadSkipped(reload);
 }
 
@@ -156,6 +159,7 @@ export async function commitKeyLoginProvider(
   onLiveReload?: (result: LocalProviderReloadResult | null) => void,
 ): Promise<OcxProviderConfig> {
   const mergedProvider = mergeKeyLoginProviderRow(provider, config.providers[name]);
+  initializeProviderModelSelection(name, mergedProvider, config.providers[name], config);
   config.providers[name] = mergedProvider;
   saveConfig(config);
   // Evaluate the reload BEFORE the optional call: `onLiveReload?.(await ...)` short-circuits
@@ -211,6 +215,7 @@ async function handleKeyLogin(name: string): Promise<void> {
   let reload: LocalProviderReloadResult | null = null;
   await commitKeyLoginProvider(config, name, provider, result => { reload = result; });
   console.log(`✅ ${def.label} added. Try: ocx sync`);
+  for (const line of modelSelectionGuidance(name)) console.log(line);
   warnIfLiveReloadSkipped(reload);
 }
 

package/src/oauth/meta-muse.ts

@@ -45,7 +45,7 @@ const CONSENT_WARNING = [
   "Meta scopes the Muse Code credential to the Muse Code CLI.",
   "Using it here is UNSUPPORTED: Meta does not authorize subscription coverage outside its own CLI,",
   "how these calls settle is not observable from the API, and you should treat every call as billable.",
-  "The imported key is copied into OpenCodex's auth store (~/.opencodex/auth.json, 0600).",
+  "The key you import or paste is copied into OpenCodex's auth store (~/.opencodex/auth.json, 0600).",
   "Supported alternative: the meta-model provider with your own key (META_MODEL_API_KEY).",
 ].join(" ");
 
@@ -114,6 +114,43 @@ async function defaultReadKeychain(signal?: AbortSignal): Promise<string | null>
 const INSTALL_HINT =
   "Install it from https://dev.meta.ai/install.sh, run `muse login`, then retry.";
 
+/**
+ * Where a user without the CLI gets a key by hand.
+ *
+ * The Muse Code API key is visible in Meta's own developer console, so a host with no
+ * CLI is not out of options ??it is out of an IMPORT path. That distinction is the whole
+ * reason this branch exists: refusing a platform because our importer cannot read its
+ * store, while the vendor hands the same key to the user in a browser, is a limitation
+ * of the importer being reported as a limitation of the platform.
+ */
+const MANUAL_KEY_URL = "https://dev.meta.ai";
+
+/**
+ * Accept a hand-entered Muse Code API key.
+ *
+ * Every guarantee the import path makes still holds here, because they are enforced
+ * BELOW this function rather than inside it: the same `LLM|` grammar check, the same
+ * live validation against the Model API, and the same consent warning, which has
+ * already fired before any of this runs. What is missing is only the pointer, so the
+ * credential carries no email and `source` is `manual` rather than `local-cli`.
+ */
+async function manualKeyCredential(
+  ctrl: OAuthController,
+  reason: string,
+): Promise<string | null> {
+  if (!ctrl.onManualCodeInput) return null;
+  // Resolve the login flow first so the GUI renders its paste field; otherwise
+  // onManualCodeInput blocks and the dashboard never sees a response (kiro.ts:405).
+  ctrl.onAuth?.({
+    url: MANUAL_KEY_URL,
+    instructions:
+      `${reason} Sign in at ${MANUAL_KEY_URL}, copy your Muse Code API key, and paste it below.`,
+  });
+  ctrl.onProgress?.(`Paste a Muse Code API key from ${MANUAL_KEY_URL} (it starts with "LLM|").`);
+  const pasted = (await ctrl.onManualCodeInput()).trim();
+  return pasted.length > 0 ? pasted : null;
+}
+
 function normalizedEmail(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim().toLowerCase();
@@ -133,11 +170,29 @@ export async function loginMetaMuse(
   ctrl.onProgress?.(CONSENT_WARNING);
 
   const platform = deps.platform ?? process.platform;
+  // Off darwin there is no store this importer can read: Meta ships no native Windows
+  // CLI, and the Linux credential shape has never been measured. That is a limitation
+  // of the IMPORT, not of the platform ??the same key is visible in Meta's console ??
+  // so these hosts get a paste field instead of a dead end. The pasted key then goes
+  // through the identical grammar check and live validation as an imported one.
   if (platform !== "darwin") {
-    throw new Error(
-      "Meta Muse Code login is macOS-only: the CLI stores its credential in the macOS Keychain, "
-        + "and no other platform's storage has been verified. Use the meta-model provider with your own key instead.",
-    );
+    // The two platforms are unavailable for DIFFERENT reasons, and saying so matters:
+    // Meta ships no Windows build at all, while the Linux CLI exists and only its
+    // credential storage is unmeasured. Collapsing them into "no CLI here" would tell
+    // a Linux user something false about their own machine.
+    const reason = platform === "win32"
+      ? "Meta ships no native Windows Muse Code CLI, so there is no credential to import."
+      : "The Muse Code CLI runs here, but where it stores its credential has not been measured, "
+        + "so importing one is refused rather than guessed.";
+    const pasted = await manualKeyCredential(ctrl, reason);
+    if (pasted === null) {
+      throw new Error(
+        `${reason} This client cannot prompt for a key, so run \`ocx login meta-muse\` from the CLI `
+          + `or the dashboard and paste yours from ${MANUAL_KEY_URL}, `
+          + "or use the meta-model provider with your own key (META_MODEL_API_KEY).",
+      );
+    }
+    return await validatedMetaMuseCredential(pasted, ctrl, deps, undefined, "manual");
   }
 
   const pointerRaw = await (deps.readPointer ?? defaultReadPointer)();
@@ -178,15 +233,48 @@ export async function loginMetaMuse(
   }
 
   // access_token is present but 401s against the Model API (003 §B) — never fall back to it.
-  const apiKey = sanitizeApiKeyValue(secret.api_key);
+  return await validatedMetaMuseCredential(
+    secret.api_key,
+    ctrl,
+    deps,
+    normalizedEmail(meta.user_email),
+    "local-cli",
+  );
+}
+
+/**
+ * The single gate every credential passes, imported or pasted.
+ *
+ * Both paths share it deliberately. A pasted key that skipped the grammar check or the
+ * live validation would be a weaker credential wearing the same provider id, and the
+ * difference would surface only as a 401 in the middle of a session.
+ */
+async function validatedMetaMuseCredential(
+  candidate: unknown,
+  ctrl: OAuthController,
+  deps: MuseImportDeps,
+  email: string | undefined,
+  source: "local-cli" | "manual",
+): Promise<OAuthCredentials> {
+  const retry = source === "manual"
+    ? `Copy it again from ${MANUAL_KEY_URL}.`
+    : "Run `muse login` again.";
+  const apiKey = sanitizeApiKeyValue(candidate);
   if (!apiKey) {
-    throw new Error("The Muse Code Keychain entry carries no usable API key. Run `muse login` again.");
+    // The macOS wording is preserved verbatim. Extraction is a refactor, and a refactor
+    // that quietly rewrites a user-facing error is a behavior change in disguise.
+    throw new Error(source === "manual"
+      ? `The pasted Muse Code credential carries no usable API key. ${retry}`
+      : "The Muse Code Keychain entry carries no usable API key. Run `muse login` again.");
   }
   if (!/^LLM\|\d+\|[A-Za-z0-9_-]{10,}$/.test(apiKey)) {
-    throw new Error("The Muse Code credential is not in the expected Meta API key format. Run `muse login` again.");
+    throw new Error(source === "manual"
+      ? `The pasted Muse Code credential is not in the expected Meta API key format. ${retry}`
+      : "The Muse Code credential is not in the expected Meta API key format. Run `muse login` again.");
   }
-
-  ctrl.onProgress?.("Validating the imported Meta credential…");
+  ctrl.onProgress?.(source === "manual"
+    ? "Validating the pasted Meta credential..."
+    : "Validating the imported Meta credential...");
   const fetchImpl = deps.fetchImpl ?? fetch;
   // ctrl.signal is OPTIONAL and the CLI controller supplies none: AbortSignal.any([undefined])
   // throws a TypeError, which would fail every CLI login right after the warning printed.
@@ -205,7 +293,7 @@ export async function loginMetaMuse(
   }
   if (!response.ok) {
     throw new Error(
-      `The Muse Code credential was rejected by the Meta Model API (HTTP ${response.status}). Run \`muse login\` again.`,
+      `The Muse Code credential was rejected by the Meta Model API (HTTP ${response.status}). ${retry}`,
     );
   }
 
@@ -216,8 +304,8 @@ export async function loginMetaMuse(
     expires: Number.MAX_SAFE_INTEGER,
     // `email`, not `accountId`: the account list masks email for display, and store.ts
     // already falls back to it for slot identity, so multi-account still works.
-    ...(normalizedEmail(meta.user_email) ? { email: normalizedEmail(meta.user_email) } : {}),
-    source: "local-cli",
+    ...(email ? { email } : {}),
+    source,
   };
 }
 
@@ -228,8 +316,22 @@ export async function loginMetaMuse(
  * the slot being refreshed, so if the user ran `muse login` with a DIFFERENT account in
  * between, a re-import would silently overwrite one stored identity with another. Only an
  * explicit login may import.
+ *
+ * It also does not assert a source. `merged()` in index.ts keeps the previous source for
+ * anything that is not `local-cli`, so returning `local-cli` here would relabel a
+ * hand-pasted key as an imported one on its first refresh and misreport where the
+ * credential came from.
  */
-export async function refreshMetaMuseToken(apiKey: string): Promise<OAuthCredentials> {
+export async function refreshMetaMuseToken(
+  apiKey: string,
+  _signal?: AbortSignal,
+  credential?: OAuthCredentials,
+): Promise<OAuthCredentials> {
   if (!apiKey) throw new Error("Meta Muse Code API key missing; run `ocx login meta-muse`");
-  return { access: apiKey, refresh: apiKey, expires: Number.MAX_SAFE_INTEGER, source: "local-cli" };
+  return {
+    access: apiKey,
+    refresh: apiKey,
+    expires: Number.MAX_SAFE_INTEGER,
+    source: credential?.source === "manual" ? "manual" : "local-cli",
+  };
 }

package/src/oauth/pool-settings-capability.ts

@@ -6,8 +6,13 @@ import type { OcxProviderConfig } from "../types";
  *
  * `codex` and `anthropic` keep their own routes and storage untouched. `generic` is every
  * other OAuth provider the generic failover module admits; its settings persist on
- * `providers.<name>.oauthAccountFailover`. Settings stored for a generic provider are a
- * declared contract the selector can consume in a later slice; today they change nothing.
+ * `providers.<name>.oauthAccountFailover`.
+ *
+ * `strategy` and `autoSwitchThreshold` are still a declared contract the selector does not
+ * consume — that is what `inert` reports. `enabled` is NOT inert any more: an explicit
+ * `false` refuses the pre-dispatch account preference (`preferredInitialAccount`). What it can
+ * no longer do is refuse reactive 429 rotation, which activates on account presence and is not
+ * disableable.
  */
 export type PoolSettingsKind = "codex" | "anthropic" | "generic";
 
@@ -37,7 +42,14 @@ export interface GenericPoolSettingsDto {
   enabled: boolean | null;
   strategy: GenericPoolStrategy | null;
   autoSwitchThreshold: number | null;
-  /** Slice-1 marker: persisted, not yet consumed by the selector. */
+  /**
+   * Slice-1 marker for `strategy` and `autoSwitchThreshold` only: persisted, not yet consumed
+   * by the selector.
+   *
+   * It deliberately does NOT describe `enabled`, which governs the pre-dispatch preference.
+   * Widening it to the whole DTO would tell a dashboard that `enabled` changes nothing, which
+   * has been false since reactive and proactive activation were split.
+   */
   inert: true;
 }
 
@@ -52,4 +64,3 @@ export function genericPoolSettingsDto(name: string, provider: OcxProviderConfig
     inert: true,
   };
 }
-

package/src/providers/api-keys.ts

@@ -4,13 +4,14 @@
  * `provider.apiKey` stays the single source of truth for routing — it always mirrors the
  * ACTIVE pool entry, so the router/adapters never learn about the pool. The pool itself
  * lives in `provider.apiKeyPool` in config.json (same file that already holds apiKey).
- * A provider with a legacy bare `apiKey` is seeded into a one-entry pool on first touch.
+ * A legacy bare `apiKey` is projected as one row on reads and seeded on first mutation.
  */
 import { createHash } from "node:crypto";
 import { saveConfigPreservingClaudeCode } from "../config";
 import type { OcxConfig, OcxProviderConfig } from "../types";
+import type { AccountQuotaFields } from "./quota-types";
 
-export interface ProviderApiKeyInfo {
+export interface ProviderApiKeyInfo extends AccountQuotaFields {
   id: string;
   label?: string;
   /** First/last 4 chars only; env references (`${VAR}`) are shown verbatim (not secrets). */
@@ -57,17 +58,14 @@ function ensurePool(provider: OcxProviderConfig): NonNullable<OcxProviderConfig[
   return provider.apiKeyPool;
 }
 
-function activeEntryId(provider: OcxProviderConfig): string | null {
-  const pool = provider.apiKeyPool ?? [];
-  if (pool.length === 0) return null;
-  return (pool.find(e => e.key === provider.apiKey) ?? pool[0]!).id;
-}
-
 export function listProviderApiKeys(config: OcxConfig, name: string): { activeId: string | null; keys: ProviderApiKeyInfo[] } {
   const provider = config.providers[name];
   if (!provider || !isKeyAuthProvider(provider)) return { activeId: null, keys: [] };
-  const pool = ensurePool(provider);
-  const activeId = activeEntryId(provider);
+  // A GET projects a legacy key without seeding/mutating live configuration.
+  const pool = provider.apiKeyPool?.length
+    ? provider.apiKeyPool
+    : provider.apiKey ? [{ id: apiKeyPoolEntryId(provider.apiKey), key: provider.apiKey }] : [];
+  const activeId = (pool.find(entry => entry.key === provider.apiKey) ?? pool[0])?.id ?? null;
   return {
     activeId,
     keys: pool.map(entry => ({

package/src/providers/default-aliases.ts

@@ -1,3 +1,42 @@
+
+import { PROVIDER_REGISTRY } from "./registry";
+
+export function effectiveProviderAlias(
+  providerName: string,
+  provider?: Pick<OcxProviderConfig, "alias">,
+  config?: Pick<OcxConfig, "providers">,
+): string | undefined {
+  if (provider && provider.alias !== undefined) {
+    const trimmed = provider.alias.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+  const regAlias = PROVIDER_REGISTRY.find(e => e.id === providerName)?.alias;
+  if (!regAlias) return undefined;
+  if (config?.providers) {
+    const lower = regAlias.toLowerCase();
+    const claimedByOther = Object.entries(config.providers).some(([name, p]) =>
+      name !== providerName && typeof p.alias === "string" && p.alias.trim().toLowerCase() === lower
+    );
+    if (claimedByOther) return undefined;
+  }
+  return regAlias;
+}
+
+export function effectiveProviderAliasDecision(
+  providerName: string,
+  provider?: Pick<OcxProviderConfig, "alias">,
+  config?: Pick<OcxConfig, "providers">,
+): string | null | undefined {
+  const active = effectiveProviderAlias(providerName, provider, config);
+  if (active !== undefined) return active;
+  const hasRegistryAlias = Boolean(PROVIDER_REGISTRY.find(e => e.id === providerName)?.alias);
+  const hasConfiguredAlias = provider?.alias !== undefined;
+  if (hasRegistryAlias || hasConfiguredAlias) {
+    return null;
+  }
+  return undefined;
+}
+
 import type { OcxConfig, OcxProviderConfig } from "../types";
 
 export const MODEL_ALIAS_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;

package/src/providers/derive.ts

@@ -218,6 +218,7 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     baseUrl: entry.baseUrl,
     ...(entry.apiKeyTransport !== undefined ? { apiKeyTransport: entry.apiKeyTransport } : {}),
     ...(entry.responsesPath ? { responsesPath: entry.responsesPath } : {}),
+    ...(entry.alias ? { alias: entry.alias } : {}),
     // Preserve the registry auth kind verbatim (including "local") so fail-closed gates that
     // distinguish local runtimes from API-key providers keep working after the seed round-trip.
     authMode: entry.authKind,
@@ -403,7 +404,7 @@ function serviceTierModelDefaultsFor(
  * The catalog hint pass must not read PROVIDER_REGISTRY: a gather flight captures its registry
  * authority up front and forbids any later read, so consulting the registry per model turned
  * every hint pass into a post-lookup read and dropped a custom-destination flight's own
- * discovery result (tests/codex-gather-authority.test.ts).
+ * discovery result (tests/codex-integration/codex-gather-authority.test.ts).
  *
  * Registry values go in first so an explicit user entry still wins, matching
  * `applyReasoningSummaryDefaults`. `supportsVerbosity` is the provider-wide default, expanded
@@ -490,7 +491,14 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if ((!prov.reasoningEfforts || hasLegacyClinePassReasoningEfforts(name, prov)) && seed.reasoningEfforts) {
     prov.reasoningEfforts = [...seed.reasoningEfforts];
   }
-  if (!prov.modelReasoningEfforts && seed.modelReasoningEfforts) prov.modelReasoningEfforts = cloneRecordOfArrays(seed.modelReasoningEfforts);
+  // Per-model fill for the same reason as modelInputModalities above: an all-or-nothing
+  // copy let ONE customized model hide the registry's ladder for every other model on the
+  // provider. That split the two planes apart — routing merges these maps per key
+  // (mergeRecordFill in src/router.ts), so the wire honored the effort while /v1/models and
+  // every client export showed no effort control at all.
+  if (seed.modelReasoningEfforts) {
+    prov.modelReasoningEfforts = fillRecordOfArrays(seed.modelReasoningEfforts, prov.modelReasoningEfforts);
+  }
   if (!prov.modelDefaultReasoningEfforts && seed.modelDefaultReasoningEfforts) prov.modelDefaultReasoningEfforts = { ...seed.modelDefaultReasoningEfforts };
   if (!prov.reasoningEffortMap && seed.reasoningEffortMap) prov.reasoningEffortMap = { ...seed.reasoningEffortMap };
   if (!prov.modelReasoningEffortMap && seed.modelReasoningEffortMap) prov.modelReasoningEffortMap = cloneNestedRecord(seed.modelReasoningEffortMap);