@bitkyc08/opencodex 2.7.40 → 2.7.41

package/src/oauth/index.ts

@@ -16,6 +16,27 @@ import { deriveOAuthDefaultModel, deriveOAuthProviderConfig } from "../providers
 import { effectiveGoogleMode } from "../providers/registry";
 import { resolveProviderTransport } from "../providers/xai-transport";
 import { detectClaudeCodeToken, detectGrokCliToken, hasComparableGrokIdentity, isSameGrokIdentity, shouldAdoptGrokGeneration } from "./local-token-detect";
+import { logOAuthEvent } from "./log";
+export {
+  CODEX_HEALTH_UNAVAILABLE_NOTE,
+  MASKED_ACCOUNT_FALLBACK,
+  collectOAuthHealthEntries,
+  collectOAuthHealthEntriesForCli,
+  detectOAuthWarning,
+  oauthAccountHealthFields,
+  oauthHealthLabel,
+  oauthHealthSummary,
+  projectCodexAccountHealth,
+  projectOAuthAccountHealth,
+  projectStoredOAuthAccountHealth,
+  type CodexHealthSource,
+  type OAuthAccountHealth,
+  type OAuthAccountHealthFields,
+  type OAuthCliHealthReport,
+  type OAuthHealthEntry,
+  type OAuthHealthLabel,
+} from "./health";
+export { OAUTH_REFRESH_LOCK_WAIT_MS, peekAuthStore, peekOAuthRefreshIntent } from "./store";
 
 const REFRESH_SKEW_MS = 60_000;
 export interface OAuthAccessSnapshot {
@@ -30,6 +51,7 @@ const XAI_PERMANENT_FAILURE_TTL_MS=30_000;
 const permanentRefreshFailures=new Map<string,number>();
 interface XaiRefreshDeps { intentLock?:ReturnType<typeof createOAuthRefreshIntentLock>; now?:()=>number; afterPrePersistRead?:()=>void|Promise<void> }
 interface AnthropicRefreshDeps { intentLock?:ReturnType<typeof createOAuthRefreshIntentLock>; now?:()=>number; afterPrePersistRead?:()=>void|Promise<void> }
+interface GenericRefreshDeps { intentLock?:ReturnType<typeof createOAuthRefreshIntentLock>; afterPrePersistRead?:()=>void|Promise<void> }
 function verdictKey(p:string,a:string,c:OAuthCredentials){return `${p}\0${a}\0${credentialGeneration(c)}`;}
 function cached(p:string,a:string,c:OAuthCredentials,now:()=>number){const k=verdictKey(p,a,c),u=permanentRefreshFailures.get(k);if(u===undefined)return false;if(u<=now()){permanentRefreshFailures.delete(k);return false;}return true;}
 
@@ -195,7 +217,10 @@ async function resolveAccessSnapshotForAccount(
 
   const key = `${provider}\u0000${accountId}`;
   const existing = tokenRefreshes.get(key);
-  if (existing) return existing;
+  if (existing) {
+    logOAuthEvent("OAuth refresh joined existing operation", { provider, accountId });
+    return existing;
+  }
 
   const refresh = (async (): Promise<OAuthAccessSnapshot> => {
     const accessToken = await refreshAndPersistAccessToken(provider, accountId, def, cred);
@@ -349,6 +374,48 @@ export async function refreshAnthropicAccountWithLock(
   }
 }
 
+export async function refreshGenericAccountWithLock(
+  provider: string,
+  accountId: string,
+  def: OAuthProviderDef,
+  callerCredential: OAuthCredentials,
+  deps: GenericRefreshDeps = {},
+): Promise<string> {
+  logOAuthEvent("OAuth refresh started", { provider, accountId });
+  const guard = await (deps.intentLock ?? createOAuthRefreshIntentLock(provider, accountId)).acquire();
+  try {
+    const stored = getAccountCredential(provider, accountId);
+    if (!stored) throw new OAuthLoginRequiredError(provider);
+    if (
+      credentialGeneration(stored) !== credentialGeneration(callerCredential)
+      && stored.expires > Date.now() + REFRESH_SKEW_MS
+    ) {
+      logOAuthEvent("OAuth refresh joined existing operation", { provider, accountId });
+      return stored.access;
+    }
+    const generation = credentialGeneration(stored);
+    try {
+      const fresh = merged(await def.refresh(stored.refresh), stored);
+      const outcome = await mergeAccountCredential(provider, accountId, fresh, {
+        expectedGeneration: generation,
+        afterPrePersistRead: deps.afterPrePersistRead,
+      });
+      if (outcome.superseded) {
+        if (outcome.stored.expires > Date.now() + REFRESH_SKEW_MS) return outcome.stored.access;
+        throw new OAuthLoginRequiredError(provider);
+      }
+      logOAuthEvent("OAuth credentials rotated and persisted", { provider, accountId });
+      return fresh.access;
+    } catch (error) {
+      if (!isTerminalRefreshError(error)) throw error;
+      await markAccountNeedsReauthIfGeneration(provider, accountId, generation);
+      throw new OAuthLoginRequiredError(provider);
+    }
+  } finally {
+    guard.release();
+  }
+}
+
 async function refreshAndPersistAccessToken(
   provider: string,
   accountId: string,
@@ -368,23 +435,7 @@ async function refreshAndPersistAccessToken(
   if (provider === "xai") return refreshXaiAccountWithLock(provider, accountId, def, cred);
   if (provider === "anthropic") return refreshAnthropicAccountWithLock(provider, accountId, def, cred);
   try {
-    const fresh = await def.refresh(cred.refresh);
-    const detachedLocalCli = provider === "xai" && cred.source === "local-cli";
-    if (detachedLocalCli) console.warn(XAI_LOCAL_CLI_DETACH_WARNING);
-    // Persist to THIS account (rotation-safe: new refresh token hits disk before use) without
-    // touching activeAccountId.
-    await saveAccountCredential(provider, accountId, {
-      ...fresh,
-      source: detachedLocalCli ? "oauth" : fresh.source ?? cred.source ?? "oauth",
-      // Preserve a previously-discovered project id when a refresh-time re-discovery comes back empty
-      // (e.g. a transient network blip), so Antigravity does not lose its CCA project across refresh.
-      ...(fresh.projectId === undefined && cred.projectId ? { projectId: cred.projectId } : {}),
-      ...(fresh.apiBaseUrl === undefined && cred.apiBaseUrl ? { apiBaseUrl: cred.apiBaseUrl } : {}),
-      // Preserve identity fields the refresh response may omit, so identity matching stays stable.
-      ...(fresh.email === undefined && cred.email ? { email: cred.email } : {}),
-      ...(fresh.accountId === undefined && cred.accountId ? { accountId: cred.accountId } : {}),
-    });
-    return fresh.access;
+    return await refreshGenericAccountWithLock(provider, accountId, def, cred);
   } catch (err) {
     if (provider === "kiro" && isActive) {
       const imported = readFreshKiroCliCredential();
@@ -393,10 +444,6 @@ async function refreshAndPersistAccessToken(
         return imported.access;
       }
     }
-    if (isTerminalRefreshError(err)) {
-      await markAccountNeedsReauth(provider, accountId, true);
-      throw new OAuthLoginRequiredError(provider);
-    }
     throw err;
   }
 }

package/src/oauth/kiro.ts

@@ -80,15 +80,17 @@ export async function loginKiro(ctrl: OAuthController): Promise<OAuthCredentials
       url: "",
       instructions:
         "No kiro-cli token found. Paste a Kiro access token below (starts with 'aoa'). " +
-        "Run `kiro-cli login` first, or set KIRO_ACCESS_TOKEN.",
+        "Otherwise install the Kiro CLI (`curl -fsSL https://cli.kiro.dev/install | bash`), " +
+        "run `kiro-cli login`, and retry — or set KIRO_ACCESS_TOKEN.",
     });
-    ctrl.onProgress?.("No kiro-cli token found. Paste a Kiro access token (starts with 'aoa').");
+    ctrl.onProgress?.("No kiro-cli token found. Paste a Kiro access token (starts with 'aoa'), or install the Kiro CLI and run `kiro-cli login` first.");
     const raw = (await ctrl.onManualCodeInput()).trim();
     if (raw) return { access: raw, refresh: "", expires: Date.now() + 3600_000, source: "manual" };
   }
 
   throw new Error(
-    "Kiro: no token found. Run `kiro-cli login` first (import), or set KIRO_ACCESS_TOKEN. " +
+    "Kiro: no token found. Install the Kiro CLI (`curl -fsSL https://cli.kiro.dev/install | bash`) " +
+      "and run `kiro-cli login` to import its session, or set KIRO_ACCESS_TOKEN. " +
       "Browser login is not supported for Kiro.",
   );
 }

package/src/oauth/log.ts

@@ -0,0 +1,48 @@
+// src/oauth/log.ts
+import { maskAccountId } from "../lib/privacy";
+
+/** Normalize camelCase / snake_case / kebab-case field names before secret checks. */
+function normalizeFieldKey(key: string): string {
+  return key
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/-/g, "_")
+    .toLowerCase();
+}
+
+const FORBIDDEN_NORMALIZED = new Set([
+  "access",
+  "refresh",
+  "authorization",
+  "code",
+  "token",
+  "access_token",
+  "refresh_token",
+  "id_token",
+  "client_secret",
+  "oauth_code",
+  "clientsecret",
+]);
+
+function isForbiddenFieldKey(key: string): boolean {
+  const normalized = normalizeFieldKey(key);
+  if (FORBIDDEN_NORMALIZED.has(normalized)) return true;
+  if (normalized.endsWith("_token") || normalized.endsWith("_secret") || normalized.endsWith("_code")) {
+    return true;
+  }
+  return false;
+}
+
+export function logOAuthEvent(
+  event: string,
+  fields: { provider: string; accountId?: string; [key: string]: unknown },
+): void {
+  const parts = [`[opencodex] ${event}`, `provider=${fields.provider}`];
+  if (fields.accountId) parts.push(`account=${maskAccountId(fields.accountId)}`);
+  for (const [key, value] of Object.entries(fields)) {
+    if (key === "provider" || key === "accountId") continue;
+    if (isForbiddenFieldKey(key)) continue;
+    if (value === undefined) continue;
+    parts.push(`${key}=${String(value)}`);
+  }
+  console.info(parts.join(" "));
+}

package/src/oauth/store.ts

@@ -40,16 +40,41 @@ export function getAuthRefreshIntentPath(provider: string, accountId: string): s
   return `${getAuthRefreshIntentLockPath(provider, accountId)}.json`;
 }
 export interface OAuthRefreshIntent { version: 1; provider: string; accountId: string; generation: string; createdAt: number; uncertain?: true }
+function parseOAuthRefreshIntent(
+  provider: string,
+  accountId: string,
+  raw: string,
+): OAuthRefreshIntent {
+  const value = JSON.parse(raw) as Partial<OAuthRefreshIntent>;
+  if (
+    value.version !== 1
+    || value.provider !== provider
+    || value.accountId !== accountId
+    || typeof value.generation !== "string"
+    || typeof value.createdAt !== "number"
+  ) {
+    return { version: 1, provider, accountId, generation: "", createdAt: 0, uncertain: true };
+  }
+  return value as OAuthRefreshIntent;
+}
+
 export function readOAuthRefreshIntent(provider: string, accountId: string): OAuthRefreshIntent | undefined {
   const path = getAuthRefreshIntentPath(provider, accountId);
   try {
     hardenConfigDir();
     hardenExistingSecret(path);
-    const value = JSON.parse(readFileSync(path, "utf8")) as Partial<OAuthRefreshIntent>;
-    if (value.version !== 1 || value.provider !== provider || value.accountId !== accountId || typeof value.generation !== "string" || typeof value.createdAt !== "number") {
-      return { version: 1, provider, accountId, generation: "", createdAt: 0, uncertain: true };
-    }
-    return value as OAuthRefreshIntent;
+    return parseOAuthRefreshIntent(provider, accountId, readFileSync(path, "utf8"));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    return { version: 1, provider, accountId, generation: "", createdAt: 0, uncertain: true };
+  }
+}
+
+/** Observe-only intent read for diagnostics: no chmod/ACL hardening. */
+export function peekOAuthRefreshIntent(provider: string, accountId: string): OAuthRefreshIntent | undefined {
+  const path = getAuthRefreshIntentPath(provider, accountId);
+  try {
+    return parseOAuthRefreshIntent(provider, accountId, readFileSync(path, "utf8"));
   } catch (error) {
     if (errorCode(error) === "ENOENT") return undefined;
     return { version: 1, provider, accountId, generation: "", createdAt: 0, uncertain: true };
@@ -89,6 +114,20 @@ export function loadAuthStore(): AuthStore {
   return loadAuthStoreInternal().store;
 }
 
+/**
+ * Observe-only auth store read for diagnostics (`ocx doctor` / status).
+ * Does not chmod paths or backup invalid JSON — corrupt files are treated as empty.
+ */
+export function peekAuthStore(): AuthStore {
+  const path = getAuthStorePath();
+  if (!existsSync(path)) return {};
+  try {
+    return normalizeAuthStore(JSON.parse(readFileSync(path, "utf-8"))).store;
+  } catch {
+    return {};
+  }
+}
+
 function persist(store: AuthStore): void {
   const dir = getConfigDir();
   if (!existsSync(dir)) {
@@ -114,7 +153,17 @@ export function createOAuthFileLock(options: OAuthFileLockOptions): { acquire():
  return { async acquire() { hardenConfigDir(); if(!existsSync(getConfigDir())) mkdirSync(getConfigDir(),{recursive:true,mode:0o700}); const ownerId=randomUUID(),started=now(); for(;;){ let fd:number|undefined; try { fd=openSync(options.path,"wx",0o600); const bytes=`${JSON.stringify({version:1,ownerId,pid:process.pid,createdAt:now()})}\n`; write(fd,bytes); const fs=fstatSync(fd); closeSync(fd); fd=undefined; const owned=snapshot(options.path); if(owned.bytes!==bytes||!sameFd(owned,fs)) throw new OAuthFileLockError("OAuth lock changed during creation"); let released=false; return {ownerId,release(){if(released)return;released=true;try{const a=snapshot(options.path);if(!sameSnapshot(owned,a))return;options.beforeReleaseUnlink?.();const b=snapshot(options.path);if(sameSnapshot(owned,b))unlinkSync(options.path);}catch(e){if(errorCode(e)!=="ENOENT")console.warn(`[oauth] lock release failed: ${e instanceof Error?e.message:String(e)}`);}}}; } catch(e) { if(fd!==undefined){let fs;try{fs=fstatSync(fd);}catch{}try{closeSync(fd);}catch{}if(fs)try{const a=snapshot(options.path);if(sameFd(a,fs)){options.beforeFailedCreateUnlink?.();const b=snapshot(options.path);if(sameSnapshot(a,b)&&sameFd(b,fs))unlinkSync(options.path);}}catch{}} if(errorCode(e)!=="EEXIST")throw e instanceof OAuthFileLockError?e:new OAuthFileLockError("Could not create OAuth file lock",{cause:e}); }
  try{const a=snapshot(options.path);let created=a.mtimeMs;try{const p=JSON.parse(a.bytes);if(typeof p.createdAt==="number")created=Math.max(created,p.createdAt);}catch{}if(now()-created>stale){options.beforeStaleUnlink?.();const b=snapshot(options.path);if(sameSnapshot(a,b))unlinkSync(options.path);continue;}}catch(e){if(errorCode(e)==="ENOENT")continue;throw new OAuthFileLockError("Could not inspect OAuth file lock",{cause:e});} const elapsed=now()-started;if(elapsed>=wait)throw new OAuthFileLockError(`Timed out after ${wait}ms waiting for OAuth file lock`);await sleep(Math.min(wait-elapsed,min+Math.floor(random()*(max-min+1)))); } } };
 }
-export function createOAuthRefreshIntentLock(provider:string,accountId:string,overrides:Partial<OAuthFileLockOptions>={}) { return createOAuthFileLock({path:getAuthRefreshIntentLockPath(provider,accountId),staleAfterMs:120000,...overrides}); }
+/** Wait long enough for slow IdP refreshes (e.g. Cursor 15s × 3 attempts) before timing out. */
+export const OAUTH_REFRESH_LOCK_WAIT_MS = 60_000;
+
+export function createOAuthRefreshIntentLock(provider:string,accountId:string,overrides:Partial<OAuthFileLockOptions>={}) {
+  return createOAuthFileLock({
+    path: getAuthRefreshIntentLockPath(provider, accountId),
+    staleAfterMs: 120000,
+    waitTimeoutMs: OAUTH_REFRESH_LOCK_WAIT_MS,
+    ...overrides,
+  });
+}
 
 /**
  * One-time downgrade safety net: the first time we persist the NEW shape over a file that

package/src/providers/alibaba-region-backup.ts

@@ -0,0 +1,75 @@
+import { copyFileSync, existsSync, linkSync, readFileSync, rmSync } from "node:fs";
+import { getConfigPath } from "../config";
+
+export interface AlibabaBackupIO {
+  exists: (path: string) => boolean;
+  read: (path: string) => Buffer;
+  copy: (source: string, destination: string) => void;
+  /** Publish with no-replace semantics: fails with EEXIST if the destination exists. */
+  publishNoReplace: (temp: string, destination: string) => void;
+  remove: (path: string) => void;
+}
+
+const DEFAULT_IO: AlibabaBackupIO = {
+  exists: existsSync,
+  read: path => readFileSync(path),
+  copy: (source, destination) => copyFileSync(source, destination),
+  publishNoReplace: linkSync,
+  remove: path => rmSync(path, { force: true }),
+};
+
+export class AlibabaBackupIntegrityError extends Error {}
+
+/**
+ * Immutable pre-migration snapshot of `config.json`.
+ *
+ * Written to a temp file first and published by `link`, which fails with EEXIST
+ * rather than replacing. Exclusive *creation* alone is not enough: a crash
+ * mid-copy can leave a truncated destination that the next run would accept as a
+ * valid rollback point. Copy-verify-link means a published snapshot is always a
+ * complete one.
+ *
+ * An existing snapshot is NOT required to equal the current config. Demanding
+ * that has a false positive that would brick a working install: a run that
+ * created the snapshot and then aborted for an unrelated reason leaves a
+ * perfectly valid snapshot, the user then edits `config.json` legitimately, and
+ * every subsequent start would throw out of `startServer` and refuse to boot. A
+ * safety net must never become the thing that stops the product.
+ *
+ * So an existing snapshot is reused as-is — it is the earliest one, which is
+ * exactly what a rollback point should be. Integrity is carried by publication.
+ *
+ * Deliberately not built on `backupConfigBeforeOpenAiTierMigration`: that
+ * function's stale/rollback classification exists for a repeatable migration and
+ * would be wrong here.
+ */
+export function backupConfigBeforeAlibabaRegionMigration(
+  configPath = getConfigPath(),
+  io: AlibabaBackupIO = DEFAULT_IO,
+): "absent" | "created" | "reused" {
+  if (!io.exists(configPath)) return "absent";
+  const backup = `${configPath}.pre-alibaba-region-v1.bak`;
+  // The earliest snapshot is the most valuable one: it predates every migration
+  // this config has been through.
+  if (io.exists(backup)) return "reused";
+
+  const source = io.read(configPath);
+  const temp = `${backup}.${process.pid}.tmp`;
+  try {
+    io.copy(configPath, temp);
+    // Verify before publishing: a short copy must never become the snapshot.
+    if (!io.read(temp).equals(source)) {
+      throw new AlibabaBackupIntegrityError(`failed to write a complete backup to ${temp}`);
+    }
+    io.publishNoReplace(temp, backup);
+    return "created";
+  } catch (error) {
+    // Another process published between our `exists` check and the link. It went
+    // through the same copy-verify-link sequence, so it is complete by
+    // construction — nothing else writes this filename.
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return "reused";
+    throw error;
+  } finally {
+    io.remove(temp);
+  }
+}

package/src/providers/alibaba-region-migration.ts

@@ -0,0 +1,143 @@
+import { ALIBABA_INTL_BASE_URL_CHOICES } from "./base-url-choices";
+import { providerConfigSeed } from "./derive";
+import { rewriteProviderReferences } from "./provider-id-rewrite";
+import { PROVIDER_REGISTRY } from "./registry";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+
+const BEIJING_ID = "alibaba-token-plan";
+const INTL_ID = "alibaba-token-plan-intl";
+
+/**
+ * Credentials and switches the user owns directly. Everything else on the moved
+ * row is registry-derived Beijing metadata (`ocx provider add` and the GUI persist
+ * it, and registry enrichment only fills absent fields) and must NOT travel to the
+ * international id — carrying it would leave the intl provider serving Singapore
+ * while advertising the six-model Beijing Personal Edition catalog.
+ *
+ * `baseUrl` is carried deliberately: the migration only fires for a URL that
+ * `ALIBABA_INTL_BASE_URL_CHOICES` recognises, so it is nonblank and
+ * placeholder-free and satisfies the override guard in the router.
+ * `liveModels` is carried because it is directly user-editable, so resetting it
+ * to the seed's `false` would silently undo a deliberate choice.
+ * `authMode` is NOT carried — both entries are key-auth and the seed's value is
+ * the one matching the destination's registry contract.
+ * `defaultModel` and `note` are user-editable too and are handled below.
+ */
+const USER_OWNED_FIELDS = ["apiKey", "apiKeyPool", "disabled", "baseUrl", "allowPrivateNetwork", "liveModels"] as const;
+
+export interface AlibabaRegionMigrationProjection {
+  config: OcxConfig;
+  changed: boolean;
+  warnings: string[];
+}
+
+const normalize = (url: string): string => url.trim().replace(/\/+$/, "").toLowerCase();
+
+/** True when the saved URL is one the international entry actually serves. */
+function isInternationalEndpoint(baseUrl: string): boolean {
+  return ALIBABA_INTL_BASE_URL_CHOICES.some(
+    choice => choice.baseUrl && normalize(choice.baseUrl) === normalize(baseUrl),
+  );
+}
+
+/**
+ * Seed the destination from the international registry entry, then overlay only
+ * what the user owns. `providerConfigSeed` is the same function `ocx provider add`
+ * uses, so the migrated row is indistinguishable from one the user had created
+ * against the international provider directly.
+ */
+function buildIntlRow(source: OcxProviderConfig): OcxProviderConfig {
+  const entry = PROVIDER_REGISTRY.find(e => e.id === INTL_ID);
+  // Fail fast rather than fabricate a row: a missing registry entry means the
+  // destination this migration targets no longer exists.
+  if (!entry) throw new Error(`registry entry "${INTL_ID}" not found; cannot migrate "${BEIJING_ID}"`);
+  const seeded = providerConfigSeed(entry);
+  const writable = seeded as unknown as Record<string, unknown>;
+  const readable = source as unknown as Record<string, unknown>;
+  for (const field of USER_OWNED_FIELDS) {
+    if (readable[field] !== undefined) writable[field] = readable[field];
+  }
+
+  const servable = new Set(entry.models ?? []);
+  // A user-chosen default survives only when the destination can actually serve
+  // it; otherwise the international default already on the seed stands.
+  if (source.defaultModel && servable.has(source.defaultModel)) seeded.defaultModel = source.defaultModel;
+  // Same rule for the allowlist, handled here where the destination catalog is
+  // known — never by the generic reference rewriter.
+  const selected = source.selectedModels?.filter(id => servable.has(id));
+  if (selected && selected.length > 0) seeded.selectedModels = selected;
+  else delete seeded.selectedModels;
+
+  // `providerConfigSeed` does not carry `note`, so seed the destination's registry
+  // note explicitly, then let a genuinely user-authored note win. Comparing
+  // against the SOURCE registry note is what distinguishes "the user typed this"
+  // from "the Beijing entry's stock note came along for the ride".
+  const beijingNote = PROVIDER_REGISTRY.find(e => e.id === BEIJING_ID)?.note;
+  if (entry.note) seeded.note = entry.note;
+  if (source.note && source.note !== beijingNote) seeded.note = source.note;
+
+  return seeded;
+}
+
+/**
+ * Repair a config whose `alibaba-token-plan` entry points at an international
+ * endpoint (issue #457). The Beijing entry is pinned to cn-beijing and does not
+ * take a baseUrl override by design, so such a config routes an international key
+ * to Beijing and fails with 401 on every request.
+ *
+ * The entry is MOVED to `alibaba-token-plan-intl` rather than the Beijing entry
+ * being taught to serve Singapore: the two ids carry different model lists,
+ * context windows, modality maps and dashboards, and a URL override cannot carry
+ * those contracts across. That override fix shipped once, was backed out twice,
+ * and was refused again when PR #459 closed.
+ *
+ * Refuses to act when the destination already holds a value — a provider row or a
+ * key the reference rewrite would land on — because merging two settings is a
+ * user decision, not a migration's.
+ */
+export function projectAlibabaRegionMigration(config: OcxConfig): AlibabaRegionMigrationProjection {
+  const beijing = config.providers[BEIJING_ID];
+  const savedBaseUrl = typeof beijing?.baseUrl === "string" ? beijing.baseUrl : "";
+  if (!beijing || !savedBaseUrl || !isInternationalEndpoint(savedBaseUrl)) {
+    return { config, changed: false, warnings: [] };
+  }
+  if (config.providers[INTL_ID]) {
+    return {
+      config,
+      changed: false,
+      warnings: [
+        `provider "${BEIJING_ID}" is configured with an international endpoint, but "${INTL_ID}" `
+        + `already exists. Both were left untouched: merging two credential sets is not a decision `
+        + `this migration can make. Move the key to "${INTL_ID}" and delete the unused entry.`,
+      ],
+    };
+  }
+
+  const projected = structuredClone(config);
+  delete projected.providers[BEIJING_ID];
+  projected.providers[INTL_ID] = buildIntlRow(beijing);
+  const { changed: rewritten, collisions } = rewriteProviderReferences(projected, BEIJING_ID, INTL_ID);
+  // The rewriter is not transactional, so the clone is already partly rewritten
+  // here. Returning the ORIGINAL config discards it.
+  if (collisions.length > 0) {
+    return {
+      config,
+      changed: false,
+      warnings: [
+        `provider "${BEIJING_ID}" needs to move to "${INTL_ID}", but ${collisions.join(", ")} `
+        + `already hold values for the destination. Nothing was changed: choosing which value `
+        + `survives is not a decision this migration can make. Resolve those entries and restart.`,
+      ],
+    };
+  }
+
+  return {
+    config: projected,
+    changed: true,
+    warnings: [
+      `moved provider "${BEIJING_ID}" to "${INTL_ID}": its saved endpoint is the international one, `
+      + `which the Beijing entry cannot serve. ${rewritten} reference(s) were re-pointed; the `
+      + `international model catalog now applies.`,
+    ],
+  };
+}

package/src/providers/alibaba-region-startup.ts

@@ -0,0 +1,36 @@
+import { saveConfig } from "../config";
+import { backupConfigBeforeAlibabaRegionMigration } from "./alibaba-region-backup";
+import { projectAlibabaRegionMigration } from "./alibaba-region-migration";
+import type { OcxConfig } from "../types";
+
+export interface AlibabaRegionStartupDeps {
+  project: typeof projectAlibabaRegionMigration;
+  backup: () => void;
+  save: (config: OcxConfig) => void;
+}
+
+/**
+ * Run the #457 recovery migration at startup.
+ *
+ * Fail-closed: a backup failure throws, and nothing between here and
+ * `startServer` catches it, so the proxy does not start rather than rewriting
+ * credentials without a rollback point. That is the same posture the OpenAI tier
+ * migration takes.
+ */
+export function runAlibabaRegionStartupMigration(
+  config: OcxConfig,
+  deps: AlibabaRegionStartupDeps = {
+    project: projectAlibabaRegionMigration,
+    backup: () => { backupConfigBeforeAlibabaRegionMigration(); },
+    save: saveConfig,
+  },
+): OcxConfig {
+  const projection = deps.project(config);
+  // Warnings are emitted even on a no-op: the collision case IS the warning.
+  for (const warning of projection.warnings) console.warn(`[alibaba-region-migration] ${warning}`);
+  if (!projection.changed) return projection.config;
+  // Strictly before the save: the snapshot must describe the config as it was.
+  deps.backup();
+  deps.save(projection.config);
+  return projection.config;
+}

package/src/providers/api-keys.ts

@@ -7,7 +7,7 @@
  * A provider with a legacy bare `apiKey` is seeded into a one-entry pool on first touch.
  */
 import { createHash } from "node:crypto";
-import { saveConfig } from "../config";
+import { saveConfigPreservingClaudeCode } from "../config";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 
 export interface ProviderApiKeyInfo {
@@ -87,7 +87,7 @@ export function addProviderApiKey(config: OcxConfig, name: string, key: string,
     pool.push({ id, key: trimmed, ...(label?.trim() ? { label: label.trim() } : {}), addedAt: Date.now() });
   }
   provider.apiKey = trimmed;
-  saveConfig(config);
+  saveConfigPreservingClaudeCode(config);
   return { id };
 }
 
@@ -98,7 +98,7 @@ export function setActiveProviderApiKey(config: OcxConfig, name: string, id: str
   const entry = ensurePool(provider).find(e => e.id === id);
   if (!entry) return false;
   provider.apiKey = entry.key;
-  saveConfig(config);
+  saveConfigPreservingClaudeCode(config);
   return true;
 }
 
@@ -110,7 +110,7 @@ export function setProviderApiKeyLabel(config: OcxConfig, name: string, id: stri
   if (!entry) return false;
   if (label) entry.label = label;
   else delete entry.label;
-  saveConfig(config);
+  saveConfigPreservingClaudeCode(config);
   return true;
 }
 
@@ -128,6 +128,6 @@ export function removeProviderApiKey(config: OcxConfig, name: string, id: string
     else delete provider.apiKey;
   }
   if (provider.apiKeyPool.length === 0) delete provider.apiKeyPool;
-  saveConfig(config);
+  saveConfigPreservingClaudeCode(config);
   return true;
 }

package/src/providers/derive.ts

@@ -27,6 +27,7 @@ export interface DerivedKeyLoginProvider {
   noPenaltyModels?: string[];
   autoToolChoiceOnlyModels?: string[];
   preserveReasoningContentModels?: string[];
+  reasoningSplitModels?: string[];
   thinkingToggleModels?: string[];
   thinkingBudgetModels?: string[];
   escapeBuiltinToolNames?: boolean;
@@ -77,6 +78,23 @@ function cloneRecordOfArrays(input: Record<string, string[]>): Record<string, st
   return Object.fromEntries(Object.entries(input).map(([key, value]) => [key, [...value]]));
 }
 
+/**
+ * Fill registry defaults BENEATH the user's per-model entries.
+ *
+ * Capability maps are keyed per model, so an all-or-nothing fill lets a single
+ * customized model hide the registry's knowledge about every other model. That
+ * is how a partially customized `modelInputModalities` could leave a
+ * vision-capable model advertising no image support, which in turn collapses any
+ * combo containing it to text-only. Routing already merges these maps per key
+ * (`mergeRecordFill` in src/router.ts); catalog enrichment now matches.
+ */
+function fillRecordOfArrays(
+  seed: Record<string, string[]>,
+  user: Record<string, string[]> | undefined,
+): Record<string, string[]> {
+  return { ...cloneRecordOfArrays(seed), ...(user ? cloneRecordOfArrays(user) : {}) };
+}
+
 function cloneNestedRecord(input: Record<string, Record<string, string>>): Record<string, Record<string, string>> {
   return Object.fromEntries(Object.entries(input).map(([key, value]) => [key, { ...value }]));
 }
@@ -113,6 +131,7 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     ...(entry.parallelToolCalls !== undefined ? { parallelToolCalls: entry.parallelToolCalls } : {}),
     ...(entry.autoToolChoiceOnlyModels ? { autoToolChoiceOnlyModels: [...entry.autoToolChoiceOnlyModels] } : {}),
     ...(entry.preserveReasoningContentModels ? { preserveReasoningContentModels: [...entry.preserveReasoningContentModels] } : {}),
+    ...(entry.reasoningSplitModels ? { reasoningSplitModels: [...entry.reasoningSplitModels] } : {}),
     ...(entry.thinkingToggleModels ? { thinkingToggleModels: [...entry.thinkingToggleModels] } : {}),
     ...(entry.thinkingBudgetModels ? { thinkingBudgetModels: [...entry.thinkingBudgetModels] } : {}),
     ...(entry.escapeBuiltinToolNames !== undefined ? { escapeBuiltinToolNames: entry.escapeBuiltinToolNames } : {}),
@@ -153,6 +172,7 @@ export function deriveKeyLoginMap(): Record<string, DerivedKeyLoginProvider> {
       ...(entry.noPenaltyModels ? { noPenaltyModels: [...entry.noPenaltyModels] } : {}),
       ...(entry.autoToolChoiceOnlyModels ? { autoToolChoiceOnlyModels: [...entry.autoToolChoiceOnlyModels] } : {}),
       ...(entry.preserveReasoningContentModels ? { preserveReasoningContentModels: [...entry.preserveReasoningContentModels] } : {}),
+      ...(entry.reasoningSplitModels ? { reasoningSplitModels: [...entry.reasoningSplitModels] } : {}),
       ...(entry.thinkingToggleModels ? { thinkingToggleModels: [...entry.thinkingToggleModels] } : {}),
       ...(entry.thinkingBudgetModels ? { thinkingBudgetModels: [...entry.thinkingBudgetModels] } : {}),
       ...(entry.escapeBuiltinToolNames !== undefined ? { escapeBuiltinToolNames: entry.escapeBuiltinToolNames } : {}),
@@ -208,7 +228,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if (prov.liveModels === undefined && seed.liveModels !== undefined) prov.liveModels = seed.liveModels;
   if (prov.contextWindow === undefined && seed.contextWindow !== undefined) prov.contextWindow = seed.contextWindow;
   if (!prov.modelContextWindows && seed.modelContextWindows) prov.modelContextWindows = { ...seed.modelContextWindows };
-  if (!prov.modelInputModalities && seed.modelInputModalities) prov.modelInputModalities = cloneRecordOfArrays(seed.modelInputModalities);
+  if (seed.modelInputModalities) prov.modelInputModalities = fillRecordOfArrays(seed.modelInputModalities, prov.modelInputModalities);
   if (prov.defaultMaxOutputTokens === undefined && seed.defaultMaxOutputTokens !== undefined) prov.defaultMaxOutputTokens = seed.defaultMaxOutputTokens;
   if (!prov.modelMaxOutputTokens && seed.modelMaxOutputTokens) prov.modelMaxOutputTokens = { ...seed.modelMaxOutputTokens };
   if (!prov.reasoningEfforts && seed.reasoningEfforts) prov.reasoningEfforts = [...seed.reasoningEfforts];
@@ -224,6 +244,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if (prov.parallelToolCalls === undefined && seed.parallelToolCalls !== undefined) prov.parallelToolCalls = seed.parallelToolCalls;
   if (!prov.autoToolChoiceOnlyModels && seed.autoToolChoiceOnlyModels) prov.autoToolChoiceOnlyModels = [...seed.autoToolChoiceOnlyModels];
   if (!prov.preserveReasoningContentModels && seed.preserveReasoningContentModels) prov.preserveReasoningContentModels = [...seed.preserveReasoningContentModels];
+  if (!prov.reasoningSplitModels && seed.reasoningSplitModels) prov.reasoningSplitModels = [...seed.reasoningSplitModels];
   if (!prov.thinkingToggleModels && seed.thinkingToggleModels) prov.thinkingToggleModels = [...seed.thinkingToggleModels];
   if (!prov.thinkingBudgetModels && seed.thinkingBudgetModels) prov.thinkingBudgetModels = [...seed.thinkingBudgetModels];
   if (prov.escapeBuiltinToolNames === undefined && seed.escapeBuiltinToolNames !== undefined) prov.escapeBuiltinToolNames = seed.escapeBuiltinToolNames;