@bitkyc08/opencodex 2.25.0 → 2.26.0

package/src/clients/config-export.ts

@@ -416,6 +416,22 @@ export function mcodeConfigPath(env: OpencodeLaunchEnv = process.env, home: stri
   return join(mcodeHomeDir(env, home), "config.yaml");
 }
 
+/**
+ * ZCode (Z.ai's desktop client) keeps everything under `~/.zcode`; custom
+ * providers live in `v2/config.json`. `ZCODE_DATA_DIR` mirrors the other
+ * clients' override convention; relative overrides are refused for the same
+ * reason as MCode's.
+ */
+export function zcodeHomeDir(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  const override = env.ZCODE_DATA_DIR?.trim();
+  if (override) return absoluteClientPath(override, home, "ZCODE_DATA_DIR");
+  return join(home, ".zcode");
+}
+
+export function zcodeConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  return join(zcodeHomeDir(env, home), "v2", "config.json");
+}
+
 /**
  * One proxy-routed model destined for a client config. Deliberately narrower than
  * `CatalogModel` so a serializer cannot reach for a field that does not survive the
@@ -456,7 +472,8 @@ export type ExportClientId =
   | "kimi"
   | "gajae"
   | "dsh"
-  | "mcode";
+  | "mcode"
+  | "zcode";
 
 export interface ExportClientSpec {
   id: ExportClientId;
@@ -876,6 +893,36 @@ export interface McodeGeneratedConfig {
   custom_provider: Record<string, McodeProviderBlock>;
 }
 
+/**
+ * ZCode's `~/.zcode/v2/config.json` provider entry (observed schema, validated
+ * live against ZCode 3.7.7). `kind: "anthropic"` selects the Anthropic
+ * Messages protocol, which the proxy serves at `/v1/messages`. `apiKeyRequired`
+ * keeps ZCode's UI from prompting for a key it does not need on loopback; the
+ * serialized key is always the non-secret loopback placeholder.
+ */
+export interface ZcodeModelEntry {
+  name?: string;
+  limit?: { context: number; output?: number };
+  modalities: { input: string[]; output: string[] };
+}
+
+export interface ZcodeProviderBlock {
+  name: "OpenCodex";
+  kind: "anthropic";
+  enabled: true;
+  source: "custom";
+  options: {
+    apiKey: string;
+    baseURL: string;
+    apiKeyRequired: true;
+  };
+  models: Record<string, ZcodeModelEntry>;
+}
+
+export interface ZcodeGeneratedConfig {
+  provider: Record<string, ZcodeProviderBlock>;
+}
+
 /**
  * Pi's `~/.pi/agent/models.json` shape. `models` is an ARRAY (identity lives in `id`),
  * unlike OpenCode's keyed object.
@@ -1208,6 +1255,53 @@ function buildMcodeClientConfig(ctx: ExportContext): McodeGeneratedConfig {
   };
 }
 
+/**
+ * ZCode dials the Anthropic Messages surface, so `baseURL` is the proxy origin
+ * without the `/v1` suffix (ZCode appends `/v1/messages` itself — the same
+ * shape its builtin Z.ai providers use). Model ids are the proxy's canonical
+ * `provider/id` selectors, which `/v1/messages` resolves directly. Context
+ * limits follow the authoritative-window rule: a model without one ships
+ * without `limit` rather than guessing. Modalities are ZCode's observed
+ * `text`-floor vocabulary; image-capable rows advertise image input.
+ */
+function buildZcodeClientConfig(ctx: ExportContext): ZcodeGeneratedConfig {
+  const models: Record<string, ZcodeModelEntry> = {};
+  for (const model of normalizeExportModels(ctx.models)) {
+    const input = inputModalitiesForClient("pi", model.inputModalities);
+    if (input === null) continue;
+    const entry: ZcodeModelEntry = {
+      name: exportModelLabel(model),
+      modalities: { input, output: ["text"] },
+    };
+    // `limit.context` follows the authoritative-window rule. `output` is
+    // deliberately absent: ZCode's schema makes it optional and we have no
+    // authoritative output budget to assert (reviewer finding: an emitted
+    // stand-in would be a guessed capability, exactly what "no metadata is
+    // guessed" forbids).
+    const context = authoritativeContextWindow(model.contextWindow);
+    if (context !== undefined) {
+      entry.limit = { context };
+    }
+    models[model.namespaced] = entry;
+  }
+  return {
+    provider: {
+      [OPENCODE_PROVIDER_ID]: {
+        name: "OpenCodex",
+        kind: "anthropic",
+        enabled: true,
+        source: "custom",
+        options: {
+          apiKey: LOOPBACK_API_KEY_PLACEHOLDER,
+          baseURL: ctx.baseUrl.replace(/\/v1\/?$/, ""),
+          apiKeyRequired: true,
+        },
+        models,
+      },
+    },
+  };
+}
+
 /**
  * Per-client model counts, read back off the SERIALIZED document rather than
  * recomputed from the input rows: `modelsWithoutLimits` drives a GUI line about
@@ -1263,6 +1357,11 @@ function summarizeMcode(document: unknown): { modelCount: number; modelsWithoutL
   return { modelCount: models.length, modelsWithoutLimits: 0 };
 }
 
+function summarizeZcode(document: unknown): { modelCount: number; modelsWithoutLimits: number } {
+  const models = Object.values((document as ZcodeGeneratedConfig | undefined)?.provider?.[OPENCODE_PROVIDER_ID]?.models ?? {});
+  return { modelCount: models.length, modelsWithoutLimits: models.filter(model => !model.limit).length };
+}
+
 /** One fragment at `path`, built from this client's own document. */
 function singleFragment(clientId: ExportClientId, path: readonly string[], value: unknown): ManagedContribution {
   return { clientId, fragments: [{ path, value }] };
@@ -1324,6 +1423,11 @@ function buildMcodeContribution(ctx: ExportContext): ManagedContribution {
   return singleFragment("mcode", ["custom_provider", OPENCODE_PROVIDER_ID], doc.custom_provider[OPENCODE_PROVIDER_ID]);
 }
 
+function buildZcodeContribution(ctx: ExportContext): ManagedContribution {
+  const doc = buildZcodeClientConfig(ctx);
+  return singleFragment("zcode", ["provider", OPENCODE_PROVIDER_ID], doc.provider[OPENCODE_PROVIDER_ID]);
+}
+
 export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
   opencode: {
     id: "opencode",
@@ -1447,6 +1551,21 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     // header field, so real keys are never serialized and remote binds refuse.
     loopbackOnly: true,
   },
+  zcode: {
+    id: "zcode",
+    filename: "config.json",
+    destination: env => zcodeConfigPath(env),
+    apiKeyEnv: "",
+    exportHint: "ZCode reads a non-secret placeholder from v2/config.json; loopback needs no key.",
+    build: buildZcodeClientConfig,
+    format: "json",
+    summarize: summarizeZcode,
+    buildContribution: buildZcodeContribution,
+    // ZCode persists the credential in its own file and has no dedicated
+    // proxy-admission header field, so real keys are never serialized and
+    // remote binds refuse — same reasoning as MCode.
+    loopbackOnly: true,
+  },
 };
 
 export const EXPORT_CLIENT_IDS: readonly ExportClientId[] = Object.keys(EXPORT_CLIENTS) as ExportClientId[];

package/src/codex/account-store.ts

@@ -386,6 +386,19 @@ function findFreshCredentialForGrant(
   return null;
 }
 
+async function notePlanFromRefreshedAccessToken(
+  id: string,
+  accessToken: string,
+  generation: number,
+): Promise<void> {
+  try {
+    const { noteCodexAccountAccessToken } = await import("./plan-from-token");
+    noteCodexAccountAccessToken(id, accessToken, generation);
+  } catch {
+    // Derived plan metadata must not fail credential refresh.
+  }
+}
+
 export async function getValidCodexToken(id: string): Promise<CodexTokenResult> {
   const record = readCodexAccountRecord(id);
   const cred = record?.deletedAt == null ? record?.credential : undefined;
@@ -415,10 +428,12 @@ export async function getValidCodexToken(id: string): Promise<CodexTokenResult>
         if (!saveCodexAccountCredentialIfGeneration(id, current.generation, refreshed.credential)) {
           throw new CodexCredentialGenerationConflictError();
         }
+        const generation = current.generation + 1;
+        await notePlanFromRefreshedAccessToken(id, refreshed.credential.accessToken, generation);
         return {
           accessToken: refreshed.credential.accessToken,
           chatgptAccountId: refreshed.credential.chatgptAccountId,
-          generation: current.generation + 1,
+          generation,
         };
       }
       return getValidCodexToken(id);
@@ -520,6 +535,7 @@ export async function getValidCodexToken(id: string): Promise<CodexTokenResult>
   flight = { promise: refreshPromise, startedAt: Date.now(), abort };
   refreshLocks.set(refreshGrantFingerprint, flight);
   const result = await refreshPromise;
+  await notePlanFromRefreshedAccessToken(id, result.accessToken, result.generation);
   return {
     accessToken: result.accessToken,
     chatgptAccountId: result.chatgptAccountId,

package/src/codex/auth-api.ts

@@ -83,7 +83,7 @@ export {
   updateAccountQuota,
 } from "./quota";
 import { extractAccountId } from "../oauth/chatgpt";
-import { getMainAccountPlan, MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./main-account";
+import { getMainAccountPlan, isMainAccountTokenVerifiablyLive, MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./main-account";
 import { captureConfigGeneration, registerStateSweepAfterTick } from "../lib/state-store-sweeper";
 import { reconcileLiveStateStores } from "../lib/state-store-registrations";
 import {
@@ -98,7 +98,7 @@ import {
 } from "./main-account-cache";
 export { clearMainAccountInfoCache } from "./main-account-cache";
 import { maskEmail } from "../lib/privacy";
-import { CodexWarmupError, codexWarmupFailureReason, warmCodexAccount } from "./warmup";
+import { codexWarmupFailureReason, warmCodexAccount } from "./warmup";
 export { maskEmail } from "../lib/privacy";
 import type { CodexAccount, CodexAccountCredentials, OcxConfig } from "../types";
 import type { CatalogDisposition } from "./convergence-types";
@@ -396,13 +396,10 @@ async function verifyCodexAccountWarmup(
     return { ok: true, validatedAt: Date.now() };
   } catch (err) {
     const reason = codexWarmupFailureReason(err);
-    const upstream = err instanceof CodexWarmupError ? err.upstreamDetail : undefined;
     return {
       ok: false,
       response: jsonResponse({
-        error: upstream
-          ? `Codex account warmup failed: ${upstream}`
-          : "Codex account warmup failed. Reauthenticate the account and try again.",
+        error: "Codex account warmup failed. Reauthenticate the account and try again.",
         code: "codex_warmup_failed",
         reason,
         accountId,
@@ -569,12 +566,31 @@ const MAIN_TERMINAL_AUTH_CODES = new Set([
   "invalid_refresh_token",
 ]);
 
-async function isTerminalMainAuthResponse(resp: Response): Promise<boolean> {
-  if (resp.status === 401) return true;
+/**
+ * A WHAM 401 is not itself proof the local credential died. Upstream edges can
+ * transiently reject a still-valid access token (region/anti-abuse/rotation
+ * races), and fail-closing on every bare 401 makes a healthy main account flip
+ * needs-reauth on the next GUI quota poll. Only treat the response as terminal
+ * when the body carries a known terminal code or the local access token is not
+ * verifiably live (`accessTokenLive`). Liveness must be strict: a JWT whose
+ * `exp` cannot be decoded is NOT live — an undecodable token that vouched for
+ * itself would make a real 401 permanently transient.
+ */
+async function isTerminalMainAuthResponse(resp: Response, accessTokenLive: boolean): Promise<boolean> {
+  if (resp.status === 401) {
+    if (!accessTokenLive) return true;
+    const code = await readMainAuthErrorCode(resp);
+    return typeof code === "string" && MAIN_TERMINAL_AUTH_CODES.has(code);
+  }
   if (resp.status !== 403) return false;
+  const code = await readMainAuthErrorCode(resp);
+  return typeof code === "string" && MAIN_TERMINAL_AUTH_CODES.has(code);
+}
+
+async function readMainAuthErrorCode(resp: Response): Promise<unknown> {
   try {
     const body = await readBoundedResponseBody(resp, { totalTimeoutMs: 1_000, inactivityTimeoutMs: 1_000 });
-    if (!body.displaySafe) return false;
+    if (!body.displaySafe) return undefined;
     const parsed = JSON.parse(body.text) as {
       detail?: { code?: unknown } | string;
       error?: { code?: unknown } | string;
@@ -585,9 +601,9 @@ async function isTerminalMainAuthResponse(resp: Response): Promise<boolean> {
       : typeof parsed.error === "object" && parsed.error !== null
         ? parsed.error.code
         : parsed.code;
-    return typeof code === "string" && MAIN_TERMINAL_AUTH_CODES.has(code);
+    return code;
   } catch {
-    return false;
+    return undefined;
   }
 }
 
@@ -707,7 +723,7 @@ async function fetchMainAccountInfoWhileOwned(
       signal: AbortSignal.timeout(8000),
     });
     if (!resp.ok) {
-      const terminalAuthFailure = await isTerminalMainAuthResponse(resp);
+      const terminalAuthFailure = await isTerminalMainAuthResponse(resp, isMainAccountTokenVerifiablyLive());
       const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease);
       if (retried) return retried;
       if (terminalAuthFailure) {
@@ -854,6 +870,15 @@ function reconcileFreshPoolAccountPlans(runtimeConfig: OcxConfig, updates: Fresh
         accepted.push(update);
         if (persistedAccount.plan !== update.plan) {
           persistedAccount.plan = update.plan;
+          // WHAM is the authoritative plan source: stamp provenance so a later JWT
+          // reconcile cannot overwrite this observation within the same credential
+          // generation (src/codex/plan-from-token.ts jwtMayWritePlan). Stamped only
+          // alongside a real plan change: a steady-state refresh whose plan is
+          // unchanged must stay write-free (no-config-write contract), and an
+          // unchanged value needs no fence — a JWT rewrite to the same text is a
+          // no-op under the caller's own equality check.
+          persistedAccount.planSource = "wham";
+          persistedAccount.planCredentialGeneration = update.credentialGeneration;
           changed = true;
         }
       }
@@ -873,6 +898,8 @@ function reconcileFreshPoolAccountPlans(runtimeConfig: OcxConfig, updates: Fresh
     const liveAccount = configuredPoolAccount(runtimeConfig, update.accountId);
     if (liveAccount) {
       liveAccount.plan = update.plan;
+      liveAccount.planSource = "wham";
+      liveAccount.planCredentialGeneration = update.credentialGeneration;
     }
   }
 }
@@ -1791,7 +1818,7 @@ export async function handleCodexAuthAPI(
     const loginOwner: CodexLoginStateRow = { status: "starting", startedAt: Date.now() };
     codexAuthLoginState.set(flowId, loginOwner);
     try {
-      const { startLoginFlow, getLoginStatus } = await import("../oauth");
+      const { startLoginFlow, getLoginStatus, publicOAuthAuthenticationErrorMessage } = await import("../oauth");
       const result = await startLoginFlow("chatgpt", { forceLogin: true });
 
       // Open the browser server-side (same pattern as /api/oauth/login in management-api.ts).
@@ -1993,7 +2020,13 @@ export async function handleCodexAuthAPI(
               break;
             }
             if (st.done && st.error) {
-              setCodexLoginState(flowId, { status: "error", error: st.error, doneAt: Date.now() });
+              setCodexLoginState(flowId, {
+                status: "error",
+                // startLoginFlow projects background failures before storing login status, so
+                // fixed actionable OAuth messages retain their type-derived remediation here.
+                error: st.error,
+                doneAt: Date.now(),
+              });
               completed = true;
               break;
             }
@@ -2011,7 +2044,7 @@ export async function handleCodexAuthAPI(
             ? "Configuration is busy; retry login shortly."
             : error instanceof CodexCredentialRefreshBusyError || error instanceof CodexCredentialRefreshStaleError
               ? "Credential refresh is busy; retry login shortly."
-            : error instanceof Error ? error.message : String(error);
+            : publicOAuthAuthenticationErrorMessage(error);
           setCodexLoginState(flowId, {
             status: "error",
             error: message,
@@ -2028,7 +2061,7 @@ export async function handleCodexAuthAPI(
     } catch (e) {
       if (codexAuthLoginState.get(flowId) === loginOwner) codexAuthLoginState.delete(flowId);
       const msg = e instanceof Error ? e.message : String(e);
-      if (msg.includes("already in progress")) {
+      if (msg === "A login for chatgpt is already in progress") {
         return jsonResponse({ error: msg, status: "pending" }, 409);
       }
       if (e instanceof CodexCredentialRefreshBusyError || e instanceof CodexCredentialRefreshStaleError) {
@@ -2036,7 +2069,8 @@ export async function handleCodexAuthAPI(
         response.headers.set("Retry-After", "1");
         return response;
       }
-      return jsonResponse({ error: msg }, 500);
+      const { publicOAuthAuthenticationErrorMessage } = await import("../oauth");
+      return jsonResponse({ error: publicOAuthAuthenticationErrorMessage(e) }, 500);
     }
   }
 

package/src/codex/catalog/effort.ts

@@ -12,7 +12,7 @@ import { CODEX_REASONING_LEVELS, codexEffortRank, configuredReasoningEfforts, mo
 import { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, resolveMetadataProvider } from "../../generated/model-metadata";
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
 import { getProviderRegistryEntry } from "../../providers/registry";
-import { applyProviderContextCap, providerContextCap } from "../../providers/context-cap";
+import { applyProviderContextCap, providerContextCap, resolveUnknownRoutedContextWindow } from "../../providers/context-cap";
 import { routedSlug, slugEquals, slugsEquivalent } from "../../providers/slug-codec";
 import { CODEX_GPT5_IDENTITY_LINE } from "../../adapters/identity";
 import { filterCursorConfiguredModelsByLiveDiscovery } from "../../adapters/cursor/discovery";
@@ -122,11 +122,14 @@ export function applyCatalogModelMetadata(entry: RawEntry, model?: CatalogModel)
   // so genuine upstream marketing names are preserved untouched.
   const displayName = typeof model.displayName === "string" ? model.displayName.trim() : "";
   if (displayName) entry.display_name = displayName;
-  if (typeof model.contextWindow === "number" && model.contextWindow > 0) {
-    entry.context_window = model.contextWindow;
-    entry.max_context_window = model.contextWindow;
+  const resolvedContext = typeof model.contextWindow === "number" && model.contextWindow > 0
+    ? model.contextWindow
+    : (model.contextCap !== undefined ? resolveUnknownRoutedContextWindow(model.contextCap) : undefined);
+  if (typeof resolvedContext === "number" && resolvedContext > 0) {
+    entry.context_window = resolvedContext;
+    entry.max_context_window = resolvedContext;
     entry.auto_compact_token_limit = Math.min(
-      Math.floor(model.contextWindow * 0.9),
+      Math.floor(resolvedContext * 0.9),
       model.maxInputTokens ?? Number.POSITIVE_INFINITY,
     );
   }

package/src/codex/catalog/provider-fetch.ts

@@ -33,13 +33,13 @@ import { CODEX_REASONING_LEVELS, codexEffortRank, configuredReasoningEfforts, mo
 import { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, resolveMetadataProvider } from "../../generated/model-metadata";
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
 import {
-  captureServiceTierAdapterAuthority,
+  captureFastPolicyAuthority,
   serviceTierSupportForModel,
-  type CapturedServiceTierAdapterAuthority,
 } from "../../providers/service-tier";
+import type { FastPolicyAuthority } from "../../providers/fastwire";
 import { effectiveGoogleMode, getProviderRegistryEntry, providerMatchesRegistryTransport } from "../../providers/registry";
 import { parseAntigravityAvailableModels, registerAntigravityDiscoveredWireModels } from "../../providers/antigravity-models";
-import { applyProviderContextCap, providerContextCap } from "../../providers/context-cap";
+import { applyProviderContextCap, providerContextCap, resolveUnknownRoutedContextWindow } from "../../providers/context-cap";
 import { routedSlug, slugEquals, slugsEquivalent } from "../../providers/slug-codec";
 import { CODEX_GPT5_IDENTITY_LINE } from "../../adapters/identity";
 import { filterCursorConfiguredModelsByLiveDiscovery } from "../../adapters/cursor/discovery";
@@ -155,7 +155,7 @@ interface CapturedProviderGather {
   readonly discovery: ResolvedProviderModelDiscovery;
   readonly policy: CatalogProviderDiscoveryPolicySnapshot;
   readonly request: CapturedModelsRequest;
-  readonly serviceTierAdapterAuthority: CapturedServiceTierAdapterAuthority;
+  readonly fastPolicyAuthority: FastPolicyAuthority;
   readonly observedAuth?: ModelsAuthResolution;
   /**
    * Configured model ids this provider must keep even when live discovery omits
@@ -408,12 +408,12 @@ function captureProviderGather(
   const enriched = detachedClone(withCanonicalOpenAiForwardAuthDefault(name, configured));
   enrichProviderFromRegistry(name, enriched);
   const registryTransportMatch = providerMatchesRegistryTransport(name, enriched);
-  const serviceTierAdapterAuthority = captureServiceTierAdapterAuthority(
+  const provider = recursivelyFreeze(enriched);
+  const fastPolicyAuthority = captureFastPolicyAuthority(
     name,
-    enriched,
+    provider,
     registryTransportMatch,
   );
-  const provider = recursivelyFreeze(enriched);
   const observedAuth = authResolver.kind === "observed"
     && provider.authMode !== "forward"
     && provider.liveModels !== false
@@ -449,7 +449,7 @@ function captureProviderGather(
     discovery,
     policy,
     request,
-    serviceTierAdapterAuthority,
+    fastPolicyAuthority,
     ...(observedAuth ? { observedAuth: Object.freeze({ ...observedAuth }) } : {}),
     ...(retainConfiguredModelIds && retainConfiguredModelIds.size > 0
       ? { retainConfiguredModelIds }
@@ -518,7 +518,7 @@ function captureGatherFlight(
         // It is the one member of a provider row that is legitimately a function,
         // so it is dropped here rather than allowed to break every encode.
         provider: omitProviderTransportExecutor(provider.provider),
-        serviceTierAdapterAuthority: provider.serviceTierAdapterAuthority,
+        fastPolicyAuthority: provider.fastPolicyAuthority,
         // Combo retention is capture-time state, not a provider-row field. Two
         // gathers that share providers but differ in combo targets must not join.
         retainConfiguredModelIds: [...(provider.retainConfiguredModelIds ?? [])].sort(),
@@ -648,15 +648,16 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
   const supportsReasoningSummaries = configuredReasoningSummarySupport(prov, model.id);
   const supportsServiceTier = serviceTierSupportForModel(prov, model.id, name);
   const { supportsServiceTier: _staleServiceTier, ...modelWithoutServiceTier } = model;
+  // 已发现窗口只允许被配置值压低；缺窗口时，已开的 Context cap 就是实际窗口。
+  const discoveredWindow = typeof model.contextWindow === "number" && model.contextWindow > 0
+    ? model.contextWindow
+    : undefined;
+  const hintedWindow = discoveredWindow !== undefined
+    ? (configuredCap !== undefined ? Math.min(discoveredWindow, configuredCap) : discoveredWindow)
+    : (configuredCap ?? (providerCap !== undefined ? resolveUnknownRoutedContextWindow(providerCap) : undefined));
   const hinted = {
     ...modelWithoutServiceTier,
-    ...(configuredCap !== undefined
-      ? {
-        contextWindow: typeof model.contextWindow === "number" && model.contextWindow > 0
-          ? Math.min(model.contextWindow, configuredCap)
-          : configuredCap,
-      }
-      : {}),
+    ...(hintedWindow !== undefined ? { contextWindow: hintedWindow } : {}),
     ...(inputModalities ? { inputModalities } : {}),
     ...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
     ...(configuredMaxInput !== undefined
@@ -695,9 +696,11 @@ export function applyConfigHintsToCachedModels(name: string, prov: OcxProviderCo
 
 
 /**
- * Last-resort context window for combo member synthesis when discovery and
- * provider config both omit one. Matches the catalog entry default in
- * `normalizeRoutedCatalogEntry` so incomplete live rows still catalog.
+ * Last-resort context window for combo member synthesis when discovery,
+ * provider config, and an enabled Context cap all omit one. Matches the
+ * catalog entry default in `normalizeRoutedCatalogEntry` so incomplete live
+ * rows still catalog. An enabled Context cap is the operator-facing window,
+ * not a clamp on this placeholder.
  */
 const COMBO_MEMBER_CONTEXT_FALLBACK = 128_000;
 
@@ -715,9 +718,9 @@ interface ComboCatalogMemberFallback {
  * lacks a positive contextWindow, synthesize from the (registry-enriched)
  * provider config so combos remain catalogued when targets are configured but
  * discovery metadata is incomplete. Disabled providers stay unresolved.
- * When hints still omit contextWindow, prefer known maxInputTokens, else
- * COMBO_MEMBER_CONTEXT_FALLBACK so a live row without ctx does not drop the
- * whole combo from the public catalog.
+ * When hints still omit contextWindow, prefer known maxInputTokens, else the
+ * enabled Context cap, else COMBO_MEMBER_CONTEXT_FALLBACK so a live row
+ * without ctx does not drop the whole combo from the public catalog.
  */
 export function resolveComboCatalogMember(
   target: { provider: string; model: string },
@@ -806,12 +809,15 @@ export function resolveComboCatalogMember(
   const uncappedContext = hintedContext
     ?? knownMaxInput
     ?? fallbackContext
-    ?? (existing || prov ? COMBO_MEMBER_CONTEXT_FALLBACK : undefined);
+    ?? (existing || prov ? resolveUnknownRoutedContextWindow(contextCap) : undefined);
   if (uncappedContext === undefined) return undefined;
-  const usedFallback = hintedContext === undefined;
-  const cappedContext = applyProviderContextCap(uncappedContext, contextCap);
+  // 真发现值才压低。resolveUnknownRoutedContextWindow 已经把 cap 当成窗口填进去了，不能再 min 一次。
+  const usedDiscoveredWindow = hintedContext !== undefined || knownMaxInput !== undefined || fallbackContext !== undefined;
+  const cappedContext = usedDiscoveredWindow
+    ? applyProviderContextCap(uncappedContext, contextCap)
+    : uncappedContext;
   const contextWindow = cappedContext ?? uncappedContext;
-  const fallbackCapped = usedFallback
+  const fallbackCapped = usedDiscoveredWindow
     && contextCap !== undefined
     && cappedContext !== undefined
     && cappedContext !== uncappedContext;
@@ -1208,7 +1214,13 @@ async function fetchProviderModelsWithAuth(
         "degraded",
       );
     }
-    const liveResult = await fetchCursorUsableModels({ apiKey, baseUrl: prov.baseUrl });
+    const cursorFetch = (prov as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch;
+    const liveResult = await fetchCursorUsableModels({
+      apiKey,
+      baseUrl: prov.baseUrl,
+      upstreamHttpVersion: prov.upstreamHttpVersion,
+      ...(cursorFetch ? { fetch: cursorFetch } : {}),
+    });
     if (liveResult.ok) {
       const available = filterCursorConfiguredModelsByLiveDiscovery(configured, liveResult.models);
       const result = available.length > 0 ? available : configured;

package/src/codex/catalog/sync.ts

@@ -307,8 +307,8 @@ export function deriveEntry(
     if (isRouted) {
       // A routed model is NOT the native template: never inherit its context
       // window when /models omits context metadata (#992). Known metadata
-      // restores exact values below; otherwise the strict-fields fallback
-      // supplies the conservative 128k triple.
+      // restores exact values below; an enabled Context cap fills the gap;
+      // otherwise the strict-fields fallback supplies the 128k triple.
       if (!codexForwardNativeCapabilityAlias) {
         delete e.context_window;
         delete e.max_context_window;
@@ -1214,6 +1214,20 @@ interface RetainedCatalogSyncResult {
   skippedReason?: "desired_disabled";
 }
 
+/**
+ * Catalog/cache commit overrides.
+ *
+ * An explicit `ocx sync` is also the refresh path for side profiles that consume
+ * the OpenCodex catalog without injection (for example a custom `model_provider`
+ * that routes to the proxy). In that mode the Codex integration toggle only
+ * governs config/history injection; the catalog and models cache may still be
+ * refreshed, so `allowWhenDesiredDisabled` lets the commit path ignore the OFF
+ * gate that otherwise protects a fully native home.
+ */
+export interface CodexCatalogSyncOptions {
+  allowWhenDesiredDisabled?: boolean;
+}
+
 interface RetainedCatalogSyncWrite {
   readonly config: OcxConfig;
   readonly goModels: CatalogModel[];
@@ -1618,7 +1632,10 @@ function currentDisabledModelsForRestore(): Set<string> | null {
   }
 }
 
-export async function syncCatalogModels(config: OcxConfig): Promise<RetainedCatalogSyncResult> {
+export async function syncCatalogModels(
+  config: OcxConfig,
+  options?: CodexCatalogSyncOptions,
+): Promise<RetainedCatalogSyncResult> {
   const owningCodexHome = getCodexHome();
   const preflightRead = readRetainedCatalogSync(config);
   if (preflightRead === null) {
@@ -1654,8 +1671,10 @@ export async function syncCatalogModels(config: OcxConfig): Promise<RetainedCata
     // evidence revalidation below cannot see that — intent lives in our config,
     // not in the catalog files — so the policy is re-read here, under K, right
     // before the only write. A lost race becomes the discriminated skip instead
-    // of a routed catalog/cache surviving a completed disable.
-    if (!shouldSyncCodexOnStart(loadConfig())) {
+    // of a routed catalog/cache surviving a completed disable. An explicit
+    // catalog-only sync opts out of that gate: the user asked for a refresh even
+    // when injection is OFF, and the toggle only protects config/history writes.
+    if (!shouldSyncCodexOnStart(loadConfig()) && options?.allowWhenDesiredDisabled !== true) {
       return {
         added: 0,
         path: prepared.catalogPath,
@@ -1755,13 +1774,16 @@ export function restoreCodexCatalog(): { removed: number; kept: number; path: st
 export function invalidateCodexModelsCacheWithPermit(
   permit: CatalogWritePermit,
   owningCodexHome: string,
+  options?: CodexCatalogSyncOptions,
 ): boolean {
   try {
     // This permit is a REACQUISITION: refreshCodexModelCatalog's commit released
     // K before this rewrite runs, so the commit-path desired-state check cannot
     // cover it. A disable landing in that gap must not be overwritten by a
     // routed cache write — re-read intent under this permit, same as the commit.
-    if (!shouldSyncCodexOnStart(loadConfig())) return false;
+    // The catalog-only sync override applies here too so an explicit refresh
+    // keeps the cache consistent with the catalog it just wrote.
+    if (!shouldSyncCodexOnStart(loadConfig()) && options?.allowWhenDesiredDisabled !== true) return false;
     const catalogPath = readCodexCatalogPath();
     if (!existsSync(catalogPath)) return false;
     const catalog = JSON.parse(readFileSync(catalogPath, "utf8"));
@@ -1803,11 +1825,11 @@ export function invalidateCodexModelsCacheWithPermit(
   }
 }
 
-export function invalidateCodexModelsCache(): boolean {
+export function invalidateCodexModelsCache(options?: CodexCatalogSyncOptions): boolean {
   const owningCodexHome = getCodexHome();
   const outcome = withCatalogWriteSerialization(
     owningCodexHome,
-    permit => invalidateCodexModelsCacheWithPermit(permit, owningCodexHome),
+    permit => invalidateCodexModelsCacheWithPermit(permit, owningCodexHome, options),
   );
   return outcome.kind === "completed" && outcome.value;
 }