@bitkyc08/opencodex 2.86.0 → 2.87.0

package/src/codex/auth-api/account-pause-group.ts

@@ -1,10 +1,9 @@
+import { observeSignedInCodexIdentity } from "../signed-in-identity";
 import { lstatSync } from "node:fs";
 import type { OcxConfig } from "../../types";
-import { inspectChatGptDomainClaim, extractEmail } from "../../oauth/chatgpt";
-import { MAIN_CODEX_ACCOUNT_ID, isSelectableCodexPoolAccount } from "../account-id";
 import { readCodexTokensResult } from "../auth-collision";
 import type { CodexTokenReadResult } from "../auth-collision";
-import { getCodexAccountCredential } from "../account-store";
+import { linkedCodexAccountIds } from "../account-identity";
 import { resolveCodexHomeDir } from "../home";
 import { tryAcquireNativeMainProfileClaim } from "../native-main-admission";
 import { withNativeMainSharedClaim } from "../native-main-claim";
@@ -12,7 +11,6 @@ import { MAX_AUTH_BYTES, readBounded, resolveNativeProfileContext } from "../nat
 import { NativeProfileError } from "../native-profile-types";
 import { isNativeMainClaimUnavailable, nativeMainProfileBusyResponse } from "./http";
 
-type AccountIdentity = { accountId: string; email: string };
 type MainAuth = CodexTokenReadResult | { status: "api-key-only" };
 
 /** A valid API-key login has no ChatGPT identity; anything else unreadable stays unknown. */
@@ -32,50 +30,6 @@ function readMainAuth(authPath: string): MainAuth {
   }
 }
 
-function identity(accountId: unknown, email: unknown): AccountIdentity | undefined {
-  const normalizedEmail = typeof email === "string" ? email.trim().toLowerCase() : undefined;
-  return typeof accountId === "string" && accountId.trim() && normalizedEmail
-    ? { accountId: accountId.trim(), email: normalizedEmail }
-    : undefined;
-}
-
-/** Resolve only existing entries, under native-main ownership, never on the request path. */
-function linkedAccountIds(config: OcxConfig, selectedId: string, main: MainAuth): string[] | undefined {
-  // Unknown main identity must not produce a successful but incomplete pause.
-  if (main.status === "unreadable" || main.status === "invalid") return undefined;
-  const identities = new Map<string, AccountIdentity | undefined>();
-  if (main.status === "ok") {
-    const tokens = main.tokens;
-    if (typeof tokens.access_token !== "string" || typeof tokens.account_id !== "string"
-      || (tokens.id_token !== undefined && typeof tokens.id_token !== "string")) return undefined;
-    const claims = [tokens.id_token, tokens.access_token]
-      .filter((token): token is string => typeof token === "string")
-      .map(inspectChatGptDomainClaim);
-    if (claims.some(claim => claim.kind === "invalid")) return undefined;
-    const claimIds = claims.flatMap(claim => claim.kind === "valid" ? [claim.accountId] : []);
-    // organizations[] describes memberships, not the selected workspace. Never use its first row.
-    const accountId = tokens.account_id.trim() || claimIds[0];
-    if (claimIds.some(claim => claim !== accountId)) return undefined;
-    // Both tokens must name the same member; otherwise the bearer's identity is unknown.
-    const emails = new Set([extractEmail(tokens.id_token), extractEmail(undefined, tokens.access_token)]
-      .flatMap(email => email?.trim() ? [email.trim().toLowerCase()] : []));
-    if (emails.size > 1) return undefined;
-    identities.set(MAIN_CODEX_ACCOUNT_ID, identity(accountId, [...emails][0]));
-  }
-  for (const account of config.codexAccounts ?? []) {
-    if (!isSelectableCodexPoolAccount(account)) continue;
-    const credential = getCodexAccountCredential(account.id);
-    identities.set(account.id, identity(credential?.chatgptAccountId, account.email));
-  }
-  const selected = identities.get(selectedId);
-  // Missing identity evidence never links unrelated logins, including members of one workspace.
-  if (!selected) return [selectedId];
-  return [selectedId, ...[...identities].flatMap(([id, candidate]) => (
-    id !== selectedId && candidate?.accountId === selected.accountId && candidate.email === selected.email
-      ? [id] : []
-  ))];
-}
-
 /** Hold admission throughout; claim the physical main whenever its home exists. */
 export async function withCodexAccountPauseGroup(
   config: OcxConfig,
@@ -92,13 +46,15 @@ export async function withCodexAccountPauseGroup(
       // Only positive absence permits Pool-only publication. A dangling symlink or access
       // failure is not absence; do not create a home just to coordinate an unused main login.
       if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") return nativeMainProfileBusyResponse();
-      const ids = linkedAccountIds(config, selectedId, { status: "missing" });
+      const ids = linkedCodexAccountIds(config, selectedId, { status: "missing" });
+      if (ids) observeSignedInCodexIdentity();
       return ids ? publish(ids) : nativeMainProfileBusyResponse();
     }
     const context = resolveNativeProfileContext({ codexHome });
     return await withNativeMainSharedClaim(context, async () => {
       const main = readMainAuth(context.authPath);
-      const ids = linkedAccountIds(config, selectedId, main);
+      const ids = linkedCodexAccountIds(config, selectedId, main);
+      if (ids) observeSignedInCodexIdentity(main.status === "ok" ? main.tokens : undefined);
       return ids ? publish(ids) : nativeMainProfileBusyResponse();
     });
   } catch (error) {

package/src/codex/auth-api/account-preservation.ts

@@ -0,0 +1,57 @@
+import { getSignedInCodexIdentity } from "../signed-in-identity";
+import type { OcxConfig } from "../../types";
+import { captureConfigTopLevelRollback } from "../../config/rebase-provenance";
+import { clearCodexAccountPin, pinnedCodexAccountId } from "../account-priority";
+import { clearThreadAccountMapForAccount, previewCodexAccountForRequest } from "../routing";
+import { forgetManualPreference } from "../routing/active-account";
+import { withCodexAccountPauseGroup } from "./account-pause-group";
+import { MAIN_CODEX_ACCOUNT_ID } from "../account-id";
+import { getRuntimeConfig, saveRuntimeConfig } from "./runtime-config";
+import { jsonResponse } from "./http";
+
+/** Management owns the native-main claim; publish before releasing any runtime bindings. */
+export async function handleCodexAccountPreservation(req: Request, config: OcxConfig): Promise<Response> {
+  let update: { enabled: boolean; applyToBound: boolean } | undefined;
+  if (req.method === "PUT") {
+    const body: unknown = await req.json().catch(() => null);
+    if (!body || typeof body !== "object" || Array.isArray(body)
+      || !("enabled" in body) || typeof body.enabled !== "boolean"
+      || Object.keys(body).some(key => key !== "enabled" && key !== "applyToBound")
+      || ("applyToBound" in body && typeof body.applyToBound !== "boolean")) {
+      return jsonResponse({ error: "enabled and optional applyToBound must be booleans" }, 400);
+    }
+    const applyToBound = "applyToBound" in body && body.applyToBound === true;
+    if (applyToBound && !body.enabled) return jsonResponse({ error: "applyToBound requires enabled: true" }, 400);
+    update = { enabled: body.enabled, applyToBound };
+  }
+  const runtime = getRuntimeConfig(config);
+  return withCodexAccountPauseGroup(runtime, MAIN_CODEX_ACCOUNT_ID, affectedAccountIds => {
+    const releasedPin = update?.applyToBound === true && affectedAccountIds.includes(pinnedCodexAccountId(runtime) ?? "");
+    if (update) {
+      const rollback = captureConfigTopLevelRollback(runtime, ["codexPreserveSignedInAccount", "activeCodexAccountPinned"]);
+      try {
+        runtime.codexPreserveSignedInAccount = update.enabled;
+        if (releasedPin) clearCodexAccountPin(runtime);
+        saveRuntimeConfig(config, runtime);
+      } catch (error) { rollback(); throw error; }
+      if (update.applyToBound) {
+        for (const id of affectedAccountIds) {
+          clearThreadAccountMapForAccount(id);
+          forgetManualPreference(id);
+        }
+      }
+    }
+    const enabled = runtime.codexPreserveSignedInAccount === true;
+    const nextAccountId = previewCodexAccountForRequest(null, runtime);
+    return jsonResponse({
+      ok: true, enabled, affectedAccountIds, identityKnown: getSignedInCodexIdentity() !== undefined,
+      nextAccountId,
+      nextUsesSignedInQuota: nextAccountId !== null && affectedAccountIds.includes(nextAccountId),
+      pinnedAccountId: pinnedCodexAccountId(runtime) ?? null,
+      bindings: update?.applyToBound ? "released-for-next-request" : "retained",
+      releasedPin,
+      priorityFailbackEnabled: runtime.codexAccountPriorityFailback === true,
+      fallbackConsumesSignedInQuota: true,
+    });
+  });
+}

package/src/codex/auth-api/routes.ts

@@ -1,5 +1,7 @@
+import { handleCodexAccountPreservation } from "./account-preservation";
 import { persistCodexAccountSelection } from "./account-selection";
 import { CODEX_ACCOUNT_LOG_LABEL_RE, codexAccountLogLabel } from "../account-label";
+import { handleUseRemainingQuotaRoute } from "./use-remaining-route";
 import { poolQuotaHistoryIdentity, readCodexAccountRecord } from "../account-store";
 import { estimateCodexQuotaCapacity, insufficientCodexCapacity } from "../quota-capacity";
 import type { CodexCapacityResult } from "../quota-capacity";
@@ -34,6 +36,12 @@ export async function handleCodexAuthAPI(
   convergeCodexCatalog?: CodexAuthCatalogConvergence,
   principal?: import("../../server/management-auth").ManagementPrincipal,
 ): Promise<Response | null> {
+  if (url.pathname === "/api/codex-auth/preserve-signed-in" && (req.method === "GET" || req.method === "PUT")) {
+    return handleCodexAccountPreservation(req, config);
+  }
+  if (url.pathname === "/api/codex-auth/accounts/use-remaining" && (req.method === "GET" || req.method === "PUT")) {
+    return handleUseRemainingQuotaRoute(req, url, config);
+  }
   if (url.pathname === "/api/codex-auth/accounts" && req.method === "GET") {
     const forceRefresh = url.searchParams.get("refresh") === "1" || url.searchParams.get("refresh") === "true";
     return jsonResponse({ accounts: await listCodexAuthAccounts(config, forceRefresh) });

package/src/codex/auth-api/use-remaining-route.ts

@@ -0,0 +1,36 @@
+import type { OcxConfig } from "../../types";
+import { captureConfigTopLevelRollback } from "../../config/rebase-provenance";
+import { MAIN_CODEX_ACCOUNT_ID, isValidCodexAccountId } from "../account-id";
+import { getEffectiveCodexAutoSwitchThreshold } from "../account-auto-switch";
+import { codexAccountUsesRemainingQuota, setCodexAccountUseRemainingQuota } from "../account-use-remaining";
+import { getMainAccountHardLockStatus } from "../main-account-hard-lock";
+import { configuredPoolAccount, getRuntimeConfig, saveRuntimeConfig } from "./runtime-config";
+import { jsonResponse } from "./http";
+
+/** Called only behind the existing Codex management authentication boundary. */
+export async function handleUseRemainingQuotaRoute(req: Request, url: URL, config: OcxConfig): Promise<Response> {
+  const parsed: unknown = req.method === "PUT" ? await req.json().catch(() => null) : { id: url.searchParams.get("id") };
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return jsonResponse({ error: "body must be an object" }, 400);
+  const body = parsed as { id?: unknown; useRemainingQuota?: unknown };
+  if (typeof body.id !== "string" || (body.id !== MAIN_CODEX_ACCOUNT_ID && !isValidCodexAccountId(body.id))) {
+    return jsonResponse({ error: "Invalid account id format" }, 400);
+  }
+  const runtime = getRuntimeConfig(config);
+  if (body.id !== MAIN_CODEX_ACCOUNT_ID && !configuredPoolAccount(runtime, body.id)) return jsonResponse({ error: "Account not found" }, 404);
+  if (req.method === "PUT") {
+    if (typeof body.useRemainingQuota !== "boolean") return jsonResponse({ error: "useRemainingQuota must be a boolean" }, 400);
+    const rollback = captureConfigTopLevelRollback(runtime, ["codexUseRemainingQuotaAccountIds"]);
+    try {
+      setCodexAccountUseRemainingQuota(runtime, body.id, body.useRemainingQuota);
+      saveRuntimeConfig(config, runtime);
+    } catch (error) {
+      rollback();
+      throw error;
+    }
+  }
+  return jsonResponse({ ok: true, id: body.id,
+    useRemainingQuota: codexAccountUsesRemainingQuota(runtime, body.id),
+    autoSwitchThreshold: getEffectiveCodexAutoSwitchThreshold(runtime, body.id),
+    ...(body.id === MAIN_CODEX_ACCOUNT_ID ? { mainAccountHardLock: getMainAccountHardLockStatus(runtime) } : {}),
+  });
+}

package/src/codex/auth-api.ts

@@ -33,7 +33,6 @@ export {
 } from "./auth-api/pool-mode-gate";
 export { createResetCreditWhamClient } from "./auth-api/reset-credit-service";
 export type { CodexAuthCatalogConvergence } from "./auth-api/login-flow";
-export { handleCodexAuthAPI } from "./auth-api/routes";
 import { getEffectiveActiveCodexAccountId } from "./routing";
 import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
 import type { OcxConfig } from "../types";

package/src/codex/auth-context.ts

@@ -632,7 +632,7 @@ export class CodexRecoveryWithheldError extends CodexAccountCooldownError {
 
 export type CodexAuthPolicyConfig = Readonly<Pick<OcxConfig,
   "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds" | "codexDesktopAuthless" | "runtimeRole" | "pausedCodexAccountIds"
-  | "creditCodexAccountIds" | "codexAccounts"
+  | "creditCodexAccountIds" | "codexAccounts" | "codexUseRemainingQuotaAccountIds"
 >>;
 
 interface CodexAuthMaterializationOptions {
@@ -783,7 +783,7 @@ function mainCreditsHoldResetAt(config: Pick<OcxConfig, "creditCodexAccountIds">
 }
 
 function assertMainAccountPolicy(
-  config: Pick<OcxConfig, "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds" | "creditCodexAccountIds"> | undefined,
+  config: Pick<OcxConfig, "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds" | "creditCodexAccountIds" | "codexUseRemainingQuotaAccountIds"> | undefined,
 ): void {
   if (config) {
     const status = getMainAccountHardLockStatus(config);

package/src/codex/catalog/auto-review.ts

@@ -480,20 +480,37 @@ function configHasProviderAutoReview(config: Pick<OcxConfig, "providers">): bool
     provider.autoReviewModel !== undefined || provider.autoReviewModelOverrides !== undefined);
 }
 
+/**
+ * The global override selector, when the operator enabled it and named a model.
+ *
+ * Occupies the same slot as Codex's root `auto_review_model` fallback and wins over it: an
+ * enabled Model-settings choice is the operator's explicit pick, while a disabled or blank block
+ * leaves the root selector in charge. Provider-scoped stamps keep their precedence separately.
+ */
+export function resolveAutoReviewOverrideSelector(
+  config?: Pick<OcxConfig, "autoReviewOverride">,
+): string | undefined {
+  const block = config?.autoReviewOverride;
+  if (block?.enabled !== true) return undefined;
+  const model = typeof block.model === "string" ? block.model.trim() : "";
+  return model.length > 0 ? model : undefined;
+}
+
 /** Apply the root Codex auto-review selector after the final catalog merge. */
 export function finalizeAutoReviewModelOverride(
   models: RawEntry[] | undefined,
   sourceModels: readonly RawEntry[] = [],
-  config?: Pick<OcxConfig, "providers">,
+  config?: Pick<OcxConfig, "providers" | "autoReviewOverride">,
 ): AutoReviewModelOverrideResult {
   if (models && sourceModels.length > 0) preserveNativeAutoReviewModelOverrides(
     models.filter(entry => !isCodexControlPlaneModel(entry.slug)),
     sourceModels.filter(entry => !isCodexControlPlaneModel(entry.slug)),
   );
+  const rootValue = resolveAutoReviewOverrideSelector(config) ?? readConfiguredAutoReviewModel();
   if (config && configHasProviderAutoReview(config)) {
-    return applyConfiguredAutoReviewModelOverride(models, readConfiguredAutoReviewModel(), config, sourceModels);
+    return applyConfiguredAutoReviewModelOverride(models, rootValue, config, sourceModels);
   }
-  return applyAutoReviewModelOverride(models, readConfiguredAutoReviewModel(), sourceModels);
+  return applyAutoReviewModelOverride(models, rootValue, sourceModels);
 }
 /**
  * Why an account-gated native model stopped being offered, but only when the answer is one the

package/src/codex/catalog/build-entries.ts

@@ -48,7 +48,7 @@ import { NATIVE_RESERVE_MODEL } from "./native-models";
 import { isReserveCatalogProjection, type ReserveCatalogProjection } from "./reserve";
 import { deriveEntry, finishUpstreamNativeEntry, isExactComboCatalogEntry } from "./derive-entry";
 import { PICKER_ORDER_PRIORITY_BASE, SPAWN_PRIORITY_FIELD } from "./subagent-roster";
-import { applyConfiguredUltraFast } from "./configured-tiers";
+import { applyConfiguredUltraFast, configuredUltraFastSlugs } from "./configured-tiers";
 import { applyNativeUltraFastTier } from "./native-ultrafast";
 
 export interface ObservedCatalogEntryBuildInput {
@@ -111,6 +111,14 @@ export function buildCatalogEntries(
     accountNativeSlugs,
     accountNativeSlugsBySelector,
   });
+  // Live discovery does not run the disk merge; use the same captured declarations and row fences.
+  const configured = configuredUltraFastSlugs(goModels);
+  for (const entry of entries) {
+    if (typeof entry.slug !== "string" || !entry.slug.includes("/")
+      || isNativeAliasCatalogEntry(entry) || isExactComboCatalogEntry(entry, exactComboSlugs)
+      || trustedAccountBoundNativeCatalogSlug(entry) !== undefined) continue;
+    applyConfiguredUltraFast(entry, undefined, configured.has(entry.slug), false);
+  }
   applyFullModelPickerOrder(entries, modelPickerOrder);
   return entries;
 }

package/src/codex/catalog/combo-member.ts

@@ -100,7 +100,7 @@ import type {
   CatalogSourceEvidence,
   CatalogTrustedOpenAiApiPolicySnapshot,
 } from "../convergence-types";
-import { applyProviderConfigHints, configuredAutoCompactTokenLimit, positiveSafeInteger } from "./model-hints";
+import { applyProviderConfigHints, configuredAutoCompactTokenLimit, positiveSafeInteger, withVisionSidecarInput } from "./model-hints";
 
 /** Model ids each provider must retain for combo catalog derivation (OCX-111). */
 export function configuredComboTargetModelsByProvider(
@@ -219,6 +219,7 @@ export function resolveComboCatalogMember(
   callerFallback?: ComboCatalogMemberFallback,
   metadataModelIdCaseFold?: boolean,
   metadataConfigDir?: string,
+  visionSidecarEnabled = true,
 ): CatalogModel | undefined {
   const existing = memberByKey.get(targetKey(target));
   const prov = providers.get(target.provider);
@@ -227,6 +228,16 @@ export function resolveComboCatalogMember(
   // is unusable for catalog derivation while the provider is off.
   if (prov?.disabled === true) return undefined;
 
+  /** Preserve custom modality overrides while filling missing provider metadata. */
+  const withProviderHints = (model: CatalogModel): CatalogModel => {
+    const hinted = prov
+      ? applyProviderConfigHints(target.provider, prov, model, contextCap, metadataModelIdCaseFold, undefined, metadataConfigDir, visionSidecarEnabled)
+      : model;
+    return model.catalogKind === CODEX_CUSTOM_MODEL_CATALOG_KIND && model.inputModalities !== undefined
+      ? withVisionSidecarInput({ ...hinted, inputModalities: [...model.inputModalities] }, prov, visionSidecarEnabled)
+      : hinted;
+  };
+
   const withFallbackMetadata = (member: CatalogModel): CatalogModel => {
     const contextWindow = typeof member.contextWindow === "number" && member.contextWindow > 0
       ? member.contextWindow
@@ -276,7 +287,7 @@ export function resolveComboCatalogMember(
     // supplies a vision sidecar. Apply the same provider hints used for thin
     // rows before deriving a combo from this complete row.
     const hinted = prov && isModelVisionSidecarConsumer(prov, existing.id)
-      ? applyProviderConfigHints(target.provider, prov, existing, contextCap, metadataModelIdCaseFold, undefined, metadataConfigDir)
+      ? withProviderHints(existing)
       : existing;
     const capped = applyProviderContextCap(hinted.contextWindow, contextCap);
     if (capped === undefined || capped === existing.contextWindow) {
@@ -298,9 +309,7 @@ export function resolveComboCatalogMember(
     id: target.model,
     provider: target.provider,
   };
-  const hinted = prov
-    ? applyProviderConfigHints(target.provider, prov, base, contextCap, metadataModelIdCaseFold, undefined, metadataConfigDir)
-    : base;
+  const hinted = withProviderHints(base);
   const hintedContext = typeof hinted.contextWindow === "number" && hinted.contextWindow > 0
     ? hinted.contextWindow
     : undefined;

package/src/codex/catalog/configured-tiers.ts

@@ -12,7 +12,7 @@ export function supportsConfiguredUltraFast(policy: ResolvedFastPolicy | undefin
     && policy.fastWire.canonicalToWire.ultrafast === "ultrafast";
 }
 
-/** Carry captured capability to the pure merge without treating persisted metadata as authority. */
+/** Carry captured capability to catalog projection without treating persisted metadata as authority. */
 export function configuredUltraFastSlugs(models: readonly CatalogModel[]): ReadonlySet<string> {
   const declarations = new Map<string, boolean>();
   for (const model of models) {

package/src/codex/catalog/gather-capture.ts

@@ -564,6 +564,7 @@ function providerCatalogFingerprint(name: string, prov: OcxProviderConfig): Reco
   };
 }
 
+/** Coalesce only gathers with the same model inventory and effective sidecar visibility policy. */
 export function gatherFlightKey(config: OcxConfig): string {
   const providers = Object.entries(config.providers)
     .filter(([, prov]) => prov.disabled !== true)
@@ -571,6 +572,7 @@ export function gatherFlightKey(config: OcxConfig): string {
     .sort((a, b) => String(a.n).localeCompare(String(b.n)));
   const assembly = stableJson({
     providers,
+    visionSidecarEnabled: config.visionSidecar?.enabled !== false,
     disabledModels: [...(config.disabledModels ?? [])].sort(),
     combos: config.combos ?? {},
     customModels: (config.customModels ?? []).map((cm) => ({

package/src/codex/catalog/metadata.ts

@@ -276,6 +276,14 @@ function asLimits(input: NativeContextLimitsInput): NativeContextLimits {
   return typeof input === "number" ? { cap: input } : input;
 }
 
+/** Configured hard ceiling only; an advertised default window is not a user limit. */
+export function nativeOpenAiConfiguredContextLimit(slug: string, input?: NativeContextLimitsInput): number | undefined {
+  const limits = asLimits(input);
+  const overlay = positiveInt(limits.modelWindows?.[slug]) ?? positiveInt(limits.providerWindow);
+  const cap = positiveInt(limits.cap);
+  return overlay === undefined ? cap : cap === undefined ? overlay : Math.min(overlay, cap);
+}
+
 /** Read both levers out of a config once, for call sites that hold one. */
 export function nativeContextLimits(
   config: Pick<OcxConfig, "providers" | "providerContextCaps">,
@@ -326,18 +334,12 @@ function longWindowOptInCeiling(slug: string): number | undefined {
 
 function narrowToLimits(raw: number | undefined, slug: string, input: NativeContextLimitsInput): number | undefined {
   if (raw === undefined) return undefined;
-  const limits = asLimits(input);
-  const overlay = positiveInt(limits.modelWindows?.[slug]) ?? positiveInt(limits.providerWindow);
-  const cap = positiveInt(limits.cap);
+  const limit = nativeOpenAiConfiguredContextLimit(slug, input);
   const optInCeiling = longWindowOptInCeiling(slug);
   if (optInCeiling !== undefined) {
-    const ceiling = optInCeiling;
-    const chosen = overlay ?? cap ?? raw;
-    const window = Math.min(chosen, ceiling);
-    return overlay !== undefined && cap !== undefined ? Math.min(window, cap) : window;
+    return Math.min(limit ?? raw, optInCeiling);
   }
-  const narrowed = overlay === undefined ? raw : Math.min(raw, overlay);
-  return applyProviderContextCap(narrowed, cap) ?? narrowed;
+  return applyProviderContextCap(raw, limit);
 }
 
 export function nativeOpenAiContextWindow(slug: string, limits?: NativeContextLimitsInput): number | undefined {

package/src/codex/catalog/model-hints.ts

@@ -252,6 +252,17 @@ export function configuredReasoningSummarySupport(prov: OcxProviderConfig | unde
   return modelRecordValue(prov.modelReasoningSummaryDelivery, id) !== undefined ? true : undefined;
 }
 
+/** Add attachment metadata at publication time, independently of cached provider evidence. */
+export function withVisionSidecarInput(
+  model: CatalogModel,
+  provider: OcxProviderConfig | undefined,
+  enabled = true,
+): CatalogModel {
+  if (!enabled || !provider || !isModelVisionSidecarConsumer(provider, model.id)) return model;
+  const modalities = model.inputModalities ?? ["text"];
+  return modalities.includes("image") ? model : { ...model, inputModalities: [...modalities, "image"] };
+}
+
 /** Reapply configured limits and captured wire capabilities without trusting stale discovery hints. */
 export function applyProviderConfigHints(
   name: string,
@@ -261,6 +272,7 @@ export function applyProviderConfigHints(
   metadataModelIdCaseFold?: boolean,
   effectiveAlias?: string | null,
   metadataConfigDir?: string,
+  includeVisionSidecar = true,
 ): CatalogModel {
   const staticPolicy = resolveModelPolicy({
     providerName: name,
@@ -289,18 +301,7 @@ export function applyProviderConfigHints(
   // Removing an exact capability row therefore returns this projection to legacy-map inference.
   const resolvedModalities = staticPolicy.model.inputModalities ?? model.inputModalities
     ?? (azureMetadata?.input ? modelInputModalities({ id: model.id, input_modalities: azureMetadata.input }, undefined) : undefined);
-  let inputModalities = resolvedModalities ? [...resolvedModalities] : undefined;
-  // The shared vision-sidecar consumer predicate keeps catalog advertisement and request-time
-  // planning aligned. The catalog must still advertise image input — the Codex app
-  // gates attachments client-side on input_modalities, and a text-only entry would block images
-  // before the sidecar ever runs ("This model does not support image inputs"). Discovery-derived
-  // text-only rows stay untouched: the runtime predicate only reads these two config sources, so
-  // it would not convert those.
-  const sidecarCovered = isModelVisionSidecarConsumer(prov, model.id);
-  if (sidecarCovered) {
-    const base = inputModalities ?? model.inputModalities ?? ["text"];
-    inputModalities = base.includes("image") ? [...base] : [...base, "image"];
-  }
+  const inputModalities = resolvedModalities ? [...resolvedModalities] : undefined;
   const reasoningEfforts = configuredReasoningEfforts(prov, model.id);
   const suppressSyntheticMax = modelRecordValue(prov.modelSuppressSyntheticMax, model.id)
     ?? (model.antigravityEffortWireModelIds !== undefined);
@@ -337,7 +338,7 @@ export function applyProviderConfigHints(
     ?? azureWindow
     ?? inferredWindow?.contextWindow
     ?? (providerCap !== undefined ? resolveUnknownRoutedContextWindow(providerCap) : undefined);
-  const hinted = {
+  const hinted = withVisionSidecarInput({
     ...modelWithoutServiceTier,
     ...(!model.contextWindowInference && previousContextCap !== undefined
       ? { contextCap: previousContextCap, contextCapped: previousContextCapped } : {}),
@@ -368,7 +369,7 @@ export function applyProviderConfigHints(
       ? { parallelToolCalls: true }
       : {}),
     ...(prov.codexToolMode !== undefined ? { codexToolMode: prov.codexToolMode } : {}),
-  };
+  }, prov, includeVisionSidecar);
   const capped = applyProviderContextCap(hinted.contextWindow, providerCap);
   const withCap = providerCap !== undefined
     ? capped !== hinted.contextWindow
@@ -397,6 +398,7 @@ export function applyProviderConfigHints(
   };
 }
 
+/** Project a configured row, optionally deferring sidecar attachment metadata until publication. */
 export function catalogHintsFromProviderConfig(
   name: string,
   prov: OcxProviderConfig,
@@ -405,12 +407,14 @@ export function catalogHintsFromProviderConfig(
   metadataModelIdCaseFold?: boolean,
   effectiveAlias?: string | null,
   metadataConfigDir?: string,
+  includeVisionSidecar = true,
 ): Partial<CatalogModel> {
-  const hinted = applyProviderConfigHints(name, prov, { id, provider: name }, contextCap, metadataModelIdCaseFold, effectiveAlias, metadataConfigDir);
+  const hinted = applyProviderConfigHints(name, prov, { id, provider: name }, contextCap, metadataModelIdCaseFold, effectiveAlias, metadataConfigDir, includeVisionSidecar);
   const { provider: _provider, id: _id, ...hints } = hinted;
   return hints;
 }
 
+/** Reapply current hints to cached rows without mutating their provider evidence. */
 export function applyConfigHintsToCachedModels(
   name: string,
   prov: OcxProviderConfig,
@@ -419,8 +423,9 @@ export function applyConfigHintsToCachedModels(
   metadataModelIdCaseFold?: boolean,
   effectiveAlias?: string | null,
   metadataConfigDir?: string,
+  includeVisionSidecar = true,
 ): CatalogModel[] {
-  return models.map(model => applyProviderConfigHints(name, prov, model, contextCap, metadataModelIdCaseFold, effectiveAlias, metadataConfigDir));
+  return models.map(model => applyProviderConfigHints(name, prov, model, contextCap, metadataModelIdCaseFold, effectiveAlias, metadataConfigDir, includeVisionSidecar));
 }
 
 /** Catalog slugs whose configured model must not gain a missing synthetic max rung. */

package/src/codex/catalog/model-visibility.ts

@@ -231,6 +231,7 @@ export function mergeConfiguredModelsIntoLiveCatalog(opts: {
   retainComboTargets?: boolean;
   metadataModelIdCaseFold?: boolean;
   metadataConfigDir?: string;
+  includeVisionSidecar?: boolean;
 }): { models: CatalogModel[]; droppedConfiguredIds: string[] } {
   const {
     name,
@@ -242,6 +243,7 @@ export function mergeConfiguredModelsIntoLiveCatalog(opts: {
     retainComboTargets = true,
     metadataModelIdCaseFold,
     metadataConfigDir,
+    includeVisionSidecar,
   } = opts;
   const out = [...opts.models];
   const present = new Set(out.map(model => model.id));
@@ -250,7 +252,7 @@ export function mergeConfiguredModelsIntoLiveCatalog(opts: {
     if (present.has(candidate.id)) continue;
     const dated = out.find(live => isDatedVariantId(live.id, candidate.id));
     if (dated) {
-      out.push(applyProviderConfigHints(name, prov, { ...dated, id: candidate.id }, contextCap, metadataModelIdCaseFold, undefined, metadataConfigDir));
+      out.push(applyProviderConfigHints(name, prov, { ...dated, id: candidate.id }, contextCap, metadataModelIdCaseFold, undefined, metadataConfigDir, includeVisionSidecar));
       present.add(candidate.id);
       continue;
     }