@bitkyc08/opencodex 2.7.41 → 2.7.42

package/src/codex/catalog/aggregation.ts

@@ -38,6 +38,37 @@ export const openAiApiCollisionWarnings = new Set<string>();
 
 export const comboCatalogWarningSignatures = new Map<string, string>();
 
+/**
+ * Why `deriveComboCatalogModel` rejected a configured combo (#484 / #516).
+ * Distinguishes unresolved/incomplete member metadata from a complete but empty
+ * modality intersection so diagnostics do not send operators to the wrong fix.
+ */
+export type ComboCatalogOmissionReason =
+  | "incomplete_metadata"
+  | "incompatible_modalities";
+
+/** Combos omitted from the catalog during the most recent `gatherRoutedModels` call (#484). */
+export interface ComboCatalogOmission {
+  id: string;
+  targets: string[];
+  reason: ComboCatalogOmissionReason;
+  message: string;
+}
+
+let lastComboCatalogOmissions: ComboCatalogOmission[] = [];
+
+export function clearLastComboCatalogOmissions(): void {
+  lastComboCatalogOmissions = [];
+}
+
+export function getLastComboCatalogOmissions(): readonly ComboCatalogOmission[] {
+  return lastComboCatalogOmissions;
+}
+
+export function replaceLastComboCatalogOmissions(items: readonly ComboCatalogOmission[]): void {
+  lastComboCatalogOmissions = [...items];
+}
+
 export function intersectStrings(values: readonly string[][]): string[] {
   if (values.length === 0) return [];
   const rest = values.slice(1).map(value => new Set(value));
@@ -60,28 +91,50 @@ export function effectiveComboDefault(
   return atOrBelow.at(-1)?.effort ?? ranked[0]!.effort;
 }
 
-export function deriveComboCatalogModel(
-  id: string,
+/**
+ * Classify a combo derivation failure. Returns `null` when the combo would catalog.
+ * Callers that already know derivation failed can map the reason into diagnostics.
+ */
+export function comboCatalogOmissionReason(
   combo: NormalizedComboConfig,
   members: readonly CatalogModel[],
-): CatalogModel | null {
-  if (combo.targets.length === 0) return null;
-  if (new Set(combo.targets.map(targetKey)).size !== combo.targets.length) return null;
-  if (members.length !== combo.targets.length) return null;
+): ComboCatalogOmissionReason | null {
+  if (combo.targets.length === 0) return "incomplete_metadata";
+  if (new Set(combo.targets.map(targetKey)).size !== combo.targets.length) {
+    return "incomplete_metadata";
+  }
+  if (members.length !== combo.targets.length) return "incomplete_metadata";
   if (!members.every((member, index) => (
     `${member.provider}/${member.id}` === targetKey(combo.targets[index]!)
-  ))) return null;
+  ))) {
+    return "incomplete_metadata";
+  }
   const contexts = members.map(member => member.contextWindow);
-  if (contexts.some(value => typeof value !== "number" || value <= 0)) return null;
+  if (contexts.some(value => typeof value !== "number" || value <= 0)) {
+    return "incomplete_metadata";
+  }
+
+  const inputModalities = intersectStrings(
+    members.map(member => member.inputModalities ?? ["text"]),
+  );
+  if (inputModalities.length === 0) return "incompatible_modalities";
+  return null;
+}
+
+export function deriveComboCatalogModel(
+  id: string,
+  combo: NormalizedComboConfig,
+  members: readonly CatalogModel[],
+): CatalogModel | null {
+  if (comboCatalogOmissionReason(combo, members) !== null) return null;
 
   const inputModalities = intersectStrings(
     members.map(member => member.inputModalities ?? ["text"]),
   );
-  if (inputModalities.length === 0) return null;
   const reasoningEfforts = intersectStrings(
     members.map(member => member.reasoningEfforts ?? []),
   );
-  const contextWindow = Math.min(...contexts as number[]);
+  const contextWindow = Math.min(...members.map(member => member.contextWindow!));
   const maxInputTokens = Math.min(
     ...members.map(member => member.maxInputTokens ?? member.contextWindow!),
   );
@@ -136,20 +189,62 @@ export function comboCatalogWarningSignature(
   }).sort((a, b) => a.key.localeCompare(b.key)));
 }
 
-export function warnUncataloguedComboOnce(
+export function comboCatalogOmissionDetail(reason: ComboCatalogOmissionReason): string {
+  return reason === "incompatible_modalities"
+    ? "members have no common input modalities"
+    : "member capabilities are incomplete";
+}
+
+/** One-line sync/CLI summary that respects the actual omission reason(s). */
+export function summarizeComboCatalogOmissions(
+  omissions: readonly Pick<ComboCatalogOmission, "reason">[],
+): string {
+  const n = omissions.length;
+  const prefix = `${n} combo${n === 1 ? "" : "s"} omitted from the catalog`;
+  if (n === 0) return prefix + ".";
+  const reasons = new Set(omissions.map(item => item.reason));
+  if (reasons.size === 1) {
+    return `${prefix} because ${comboCatalogOmissionDetail([...reasons][0]!)}.`;
+  }
+  return `${prefix}.`;
+}
+
+export function buildComboCatalogOmission(
   id: string,
   combo: NormalizedComboConfig,
   members: readonly CatalogModel[],
-): void {
-  const signature = comboCatalogWarningSignature(combo, members);
-  if (comboCatalogWarningSignatures.get(id) === signature) return;
-  comboCatalogWarningSignatures.set(id, signature);
+): ComboCatalogOmission {
   const targets = combo.targets
     .map(target => safeCatalogWarningLabel(targetKey(target)))
     .sort((a, b) => a.localeCompare(b));
-  console.warn(
-    `[opencodex] Combo "${safeCatalogWarningLabel(id)}" is omitted from the catalog because member capabilities are incomplete: ${targets.join(", ")}.`,
-  );
+  const reason = comboCatalogOmissionReason(combo, members) ?? "incomplete_metadata";
+  return {
+    id,
+    targets,
+    reason,
+    message: `[opencodex] Combo "${safeCatalogWarningLabel(id)}" is omitted from the catalog because ${comboCatalogOmissionDetail(reason)}: ${targets.join(", ")}.`,
+  };
+}
+
+/**
+ * Record a combo omitted from `/v1/models` + on-disk catalog and warn once per signature.
+ * Callers that need a race-free list (catalog sync) pass a local `sink` from the same
+ * gather invocation instead of reading process-global state afterward (#484 review).
+ */
+export function warnUncataloguedComboOnce(
+  id: string,
+  combo: NormalizedComboConfig,
+  members: readonly CatalogModel[],
+  sink: ComboCatalogOmission[] = lastComboCatalogOmissions,
+): ComboCatalogOmission {
+  const omission = buildComboCatalogOmission(id, combo, members);
+  sink.push(omission);
+  const signature = comboCatalogWarningSignature(combo, members);
+  if (comboCatalogWarningSignatures.get(id) !== signature) {
+    comboCatalogWarningSignatures.set(id, signature);
+    console.warn(omission.message);
+  }
+  return omission;
 }
 
 export function exactComboCatalogSlugs(

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

@@ -47,11 +47,8 @@ import upstreamModelsSnapshot from "../data/upstream-models.json";
 import { JAWCODE_CATALOG_AUGMENT_PROVIDERS, catalogModelSlug, shouldExposeRoutedModel } from "./parsing";
 import type { CatalogModel } from "./parsing";
 import { disabledNativeSlugs, hasComboTargets, nativeInputModalities, nativeOpenAiContextWindow, nativeOpenAiSlugs, nativeParallelToolCalls, nativeReasoningEfforts } from "./metadata";
-import { deriveComboCatalogModel, normalizedOpenAiApiSignature, openAiApiCollisionWarnings, warnUncataloguedComboOnce } from "./aggregation";
-
-type OcxProviderConfigWithReasoningSummaries = OcxProviderConfig & {
-  modelSupportsReasoningSummaries?: Record<string, boolean>;
-};
+import { deriveComboCatalogModel, normalizedOpenAiApiSignature, openAiApiCollisionWarnings, replaceLastComboCatalogOmissions, warnUncataloguedComboOnce } from "./aggregation";
+import type { ComboCatalogOmission } from "./aggregation";
 
 export type ProviderModelsApiItem = {
   id: string;
@@ -89,6 +86,13 @@ export function configuredMaxInputTokens(prov: OcxProviderConfig, id: string): n
   return typeof configured === "number" && configured > 0 ? configured : undefined;
 }
 
+function configuredReasoningSummarySupport(prov: OcxProviderConfig | undefined, id: string): boolean | undefined {
+  if (!prov) return undefined;
+  const explicit = modelRecordValue(prov.modelSupportsReasoningSummaries, id);
+  if (explicit !== undefined) return explicit;
+  return modelRecordValue(prov.modelReasoningSummaryDelivery, id) !== undefined ? true : undefined;
+}
+
 export function applyProviderConfigHints(name: string, prov: OcxProviderConfig, model: CatalogModel, providerCap?: number): CatalogModel {
   void name;
   const configuredCap = configuredContextWindow(prov, model.id);
@@ -104,10 +108,7 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
   }
   const reasoningEfforts = configuredReasoningEfforts(prov, model.id);
   const defaultReasoningEffort = modelRecordValue(prov.modelDefaultReasoningEfforts, model.id) ?? model.defaultReasoningEffort;
-  const supportsReasoningSummaries = modelRecordValue(
-    (prov as OcxProviderConfigWithReasoningSummaries).modelSupportsReasoningSummaries,
-    model.id,
-  );
+  const supportsReasoningSummaries = configuredReasoningSummarySupport(prov, model.id);
   const hinted = {
     ...model,
     ...(configuredCap !== undefined
@@ -464,7 +465,12 @@ export function filterCatalogVisibleModels(
   });
 }
 
-export async function gatherRoutedModels(config: OcxConfig): Promise<CatalogModel[]> {
+export async function gatherRoutedModels(
+  config: OcxConfig,
+  options?: { comboOmissions?: ComboCatalogOmission[] },
+): Promise<CatalogModel[]> {
+  // Per-invocation list: sync passes `comboOmissions` so overlapping gathers cannot race.
+  const localOmissions: ComboCatalogOmission[] = [];
   const ttlMs = config.modelCacheTtlMs ?? DEFAULT_MODEL_CACHE_TTL_MS;
   // Persisted provider entries can predate newer registry fields (noVisionModels,
   // modelInputModalities, ...). The ROUTER merges registry seeds at request time
@@ -542,15 +548,20 @@ export async function gatherRoutedModels(config: OcxConfig): Promise<CatalogMode
       .filter((member): member is CatalogModel => member !== undefined);
     const derived = deriveComboCatalogModel(id, combo, members);
     if (derived) all.push(derived);
-    else warnUncataloguedComboOnce(id, combo, members);
+    else warnUncataloguedComboOnce(id, combo, members, localOmissions);
+  }
+  replaceLastComboCatalogOmissions(localOmissions);
+  if (options?.comboOmissions) {
+    options.comboOmissions.length = 0;
+    options.comboOmissions.push(...localOmissions);
   }
   all.sort((a, b) => (a.provider === b.provider ? a.id.localeCompare(b.id) : a.provider.localeCompare(b.provider)));
   // Enriched (registry-hydrated) provider clones, keyed by name — the same view used above so
   // custom rows get the same noVisionModels / inputModalities treatment as discovered rows.
   const enrichedByName = new Map(activeProviders);
   const customModels = (config.customModels ?? []).map(cm => {
-    const rawProvider = config.providers[cm.provider] as OcxProviderConfigWithReasoningSummaries | undefined;
-    const supportsReasoningSummaries = modelRecordValue(rawProvider?.modelSupportsReasoningSummaries, cm.modelId);
+    const rawProvider = config.providers[cm.provider];
+    const supportsReasoningSummaries = configuredReasoningSummarySupport(rawProvider, cm.modelId);
     const base: CatalogModel = {
       id: cm.modelId,
       provider: cm.provider,

package/src/codex/catalog/sync.ts

@@ -37,7 +37,8 @@ import { applyNativeVisibility, disabledNativeSlugs, isUnsupportedOpenAiNativeSl
 import { loadCatalogForSync, resetBundledCatalogCacheForTests } from "./bundled";
 import { applyCatalogModelMetadata, applyReasoningLevels, catalogEntryEfforts, clampCatalogModelsToCodexSupport, ensureGpt56ReasoningLevels, ensureUltraReasoningLevel, isGpt56NativeSlug } from "./effort";
 import { filterCatalogVisibleModels, gatherRoutedModels, lastDropWarnSignature } from "./provider-fetch";
-import { comboCatalogWarningSignatures, comboMasqueradeCollisionWarnings, exactComboCatalogSlugs, openAiApiCollisionWarnings, resolveSlugAliasCollisions, slugAliasCollisionWarnings, warnComboMasqueradeCollisionOnce } from "./aggregation";
+import { clearLastComboCatalogOmissions, comboCatalogWarningSignatures, comboMasqueradeCollisionWarnings, exactComboCatalogSlugs, openAiApiCollisionWarnings, resolveSlugAliasCollisions, slugAliasCollisionWarnings, warnComboMasqueradeCollisionOnce } from "./aggregation";
+import type { ComboCatalogOmission } from "./aggregation";
 
 export const MAX_SPAWN_AGENT_MODEL_OVERRIDES = 5;
 
@@ -293,6 +294,7 @@ export function resetCatalogRuntimeStateForTests(): void {
   comboCatalogWarningSignatures.clear();
   slugAliasCollisionWarnings.clear();
   comboMasqueradeCollisionWarnings.clear();
+  clearLastComboCatalogOmissions();
   clearModelCache();
 }
 
@@ -452,14 +454,20 @@ export function mergeCatalogEntriesForSync(
   return applyMultiAgentMode(applyNativeVisibility(mergedEntries, disabledNative), multiAgentMode);
 }
 
-export async function syncCatalogModels(config: OcxConfig): Promise<{ added: number; path: string }> {
+export async function syncCatalogModels(config: OcxConfig): Promise<{
+  added: number;
+  path: string;
+  catalogWritten: boolean;
+  comboOmissions: ComboCatalogOmission[];
+}> {
   const catalogPath = readCodexCatalogPath();
   const catalog = loadCatalogForSync(catalogPath);
-  if (!catalog) return { added: 0, path: catalogPath };
+  if (!catalog) return { added: 0, path: catalogPath, catalogWritten: false, comboOmissions: [] };
 
   const template = findNativeTemplate(catalog);
 
-  const goModels = await gatherRoutedModels(config);
+  const comboOmissions: ComboCatalogOmission[] = [];
+  const goModels = await gatherRoutedModels(config, { comboOmissions });
   try {
     // Once-only: preserve the PRISTINE pre-opencodex catalog as the native-priority baseline
     // (later syncs would otherwise overwrite it with featured-modified priorities).
@@ -493,7 +501,7 @@ export async function syncCatalogModels(config: OcxConfig): Promise<{ added: num
   clampCatalogModelsToCodexSupport(catalog.models);
 
   atomicWriteFile(catalogPath, JSON.stringify(catalog, null, 2) + "\n");
-  return { added: goEntries.length, path: catalogPath };
+  return { added: goEntries.length, path: catalogPath, catalogWritten: true, comboOmissions };
 }
 
 export function restoreCodexCatalog(): { removed: number; kept: number; path: string } {
@@ -524,10 +532,11 @@ export function restoreCodexCatalog(): { removed: number; kept: number; path: st
   return { removed, kept: native.length, path: catalogPath };
 }
 
-export function invalidateCodexModelsCache(): void {
+/** Force Codex's models_cache stale from the on-disk catalog. Returns whether a cache write occurred. */
+export function invalidateCodexModelsCache(): boolean {
   try {
     const catalogPath = readCodexCatalogPath();
-    if (!existsSync(catalogPath)) return;
+    if (!existsSync(catalogPath)) return false;
     const catalog = JSON.parse(readFileSync(catalogPath, "utf8"));
     const models = catalog.models ?? catalog;
     const wrapper = {
@@ -536,5 +545,8 @@ export function invalidateCodexModelsCache(): void {
       models,
     };
     atomicWriteFile(activeCodexModelsCachePath(), JSON.stringify(wrapper, null, 2) + "\n");
-  } catch { /* best-effort */ }
+    return true;
+  } catch {
+    return false;
+  }
 }

package/src/codex/catalog.ts

@@ -6,6 +6,7 @@ export { NATIVE_OPENAI_MODELS, nativeOpenAiContextWindow, disabledNativeSlugs, v
 export { isSpawnableCodexCandidate, codexExecInvocation, loadBundledCodexCatalog, materializeBundledCodexCatalog, loadCatalogTemplate } from "./catalog/bundled";
 export { nativeEffortClamp, shouldApplyNativeEffortClamp, catalogModelEfforts, codexSupportedReasoningEfforts, clampedDefaultEffort, clampEntryToCodexSupportedEfforts, clampCatalogModelsToCodexSupport } from "./catalog/effort";
 export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithJawcodeMetadata } from "./catalog/provider-fetch";
-export { deriveComboCatalogModel, exactComboCatalogSlugs, resetOpenAiApiCatalogWarningStateForTests, uniqueCatalogModelsForPublicList, uniqueCatalogModelsForRawPublicList } from "./catalog/aggregation";
+export { deriveComboCatalogModel, exactComboCatalogSlugs, getLastComboCatalogOmissions, resetOpenAiApiCatalogWarningStateForTests, uniqueCatalogModelsForPublicList, uniqueCatalogModelsForRawPublicList, buildComboCatalogOmission, comboCatalogOmissionReason, summarizeComboCatalogOmissions } from "./catalog/aggregation";
+export type { ComboCatalogOmission, ComboCatalogOmissionReason } from "./catalog/aggregation";
 export { MAX_SPAWN_AGENT_MODEL_OVERRIDES, effectiveSubagentRoster, buildCatalogEntries, resetCatalogRuntimeStateForTests, orderForSubagents, mergeCatalogEntriesForSync, syncCatalogModels, restoreCodexCatalog, invalidateCodexModelsCache } from "./catalog/sync";
 export type { SpawnAgentSurface, SubagentRosterExclusionReason, EffectiveSubagentModel, SubagentRosterExclusion, EffectiveSubagentRoster } from "./catalog/sync";

package/src/codex/refresh.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { invalidateCodexModelsCache, syncCatalogModels } from "./catalog";
+import type { ComboCatalogOmission } from "./catalog/aggregation";
 import { CODEX_MODELS_CACHE_PATH } from "./paths";
 import { atomicWriteFile } from "../config";
 import type { OcxConfig } from "../types";
@@ -8,7 +9,9 @@ export interface CodexCatalogRefreshResult {
   added: number;
   path: string;
   catalogExists: boolean;
+  catalogWritten: boolean;
   cacheSynced: boolean;
+  comboOmissions: ComboCatalogOmission[];
 }
 
 interface RefreshDeps {
@@ -40,7 +43,11 @@ export async function refreshCodexModelCatalog(
 ): Promise<CodexCatalogRefreshResult> {
   const result = await deps.syncCatalogModels(config);
   const catalogExists = deps.existsSync(result.path);
-  if (!catalogExists) return { ...result, catalogExists, cacheSynced: false };
-  deps.invalidateCodexModelsCache();
-  return { ...result, catalogExists, cacheSynced: true };
+  const catalogWritten = result.catalogWritten === true;
+  const comboOmissions = result.comboOmissions ?? [];
+  if (!catalogExists) {
+    return { ...result, catalogExists, catalogWritten: false, cacheSynced: false, comboOmissions };
+  }
+  const cacheSynced = deps.invalidateCodexModelsCache();
+  return { ...result, catalogExists, catalogWritten, cacheSynced, comboOmissions };
 }

package/src/codex/routing.ts

@@ -305,6 +305,16 @@ function preservedCooldownFields(health: CodexUpstreamHealth | undefined): Parti
   return cooldownFields;
 }
 
+/** Manual selection resets transient routing evidence without bypassing a real 429 cooldown. */
+export function resetCodexRoutingForManualSelection(accountId: string): void {
+  clearThreadAccountMap();
+  const current = upstreamHealth.get(accountId);
+  if (!current) return;
+  const preserved = preservedCooldownFields(current);
+  if (Object.keys(preserved).length === 0) upstreamHealth.delete(accountId);
+  else upstreamHealth.set(accountId, { consecutiveFailures: 0, ...preserved });
+}
+
 export function getCodexAccountCooldownUntil(accountId: string, now = Date.now()): number | null {
   const cooldownUntil = upstreamHealth.get(accountId)?.cooldownUntil;
   return typeof cooldownUntil === "number" && Number.isFinite(cooldownUntil) && cooldownUntil > now ? cooldownUntil : null;
@@ -491,21 +501,14 @@ function isUnknownUsage(usage: number): boolean {
   return usage >= CODEX_UNKNOWN_USAGE_SCORE;
 }
 
-// Round-robin among eligible unknown-quota candidates. `getEligiblePoolAccounts`
-// already returns a deterministic order (config order, main unshifted first) and
-// excludes the active id, so taking the first eligible unknown is a stable rotation
-// without any new per-account state.
-function pickNextUnknownAccount(config: OcxConfig, active: string, now: number): string | null {
-  const eligible = getEligiblePoolAccounts(config, active, now)
-    .filter(id => isUnknownUsage(computeCodexUsageScore(getAccountQuota(id), getPoolAccountPlan(config, id))));
-  return eligible.length > 0 ? eligible[0]! : null;
-}
-
 function applyQuotaAutoSwitch(config: OcxConfig, active: string, now: number): string {
   const threshold = config.autoSwitchThreshold ?? 80;
   if (threshold <= 0) return active;
   const quota = getAccountQuota(active);
   const activeUsage = computeCodexUsageScore(quota, getPoolAccountPlan(config, active));
+  // Unknown usage is not evidence that a user's explicit selection crossed the
+  // threshold. Wait for quota priming instead of rotating among guesses.
+  if (isUnknownUsage(activeUsage)) return active;
   if (activeUsage < threshold) return active;
   const best = pickLowerUsageAccount(config, active, activeUsage, now);
   if (best !== active) {
@@ -513,21 +516,6 @@ function applyQuotaAutoSwitch(config: OcxConfig, active: string, now: number): s
     return best;
   }
 
-  // Deadlock guard: active is over threshold but no candidate scored strictly
-  // lower. When the active itself is unknown, every candidate is likely unknown
-  // too (100 < 100 never fires), which pins the pool to one account whose real
-  // usage we cannot see (e.g. quota never primed on WSL). Rotate to the next
-  // eligible unknown so rotation is not stuck; known-but-saturated accounts are
-  // intentionally left alone so a genuinely hot pool stays visible.
-  if (isUnknownUsage(activeUsage)) {
-    const next = pickNextUnknownAccount(config, active, now);
-    if (next) {
-      console.warn(`[codex-routing] quota unknown for active "${active}"; rotating to "${next}" (all candidates unknown, threshold=${threshold})`);
-      setActiveCodexAccount(config, next);
-      return next;
-    }
-    console.warn(`[codex-routing] quota unknown for active "${active}" and no eligible rotation target; staying put`);
-  }
   return active;
 }
 
@@ -585,7 +573,7 @@ export function previewCodexAccountForRequest(
           getAccountQuota(entry.accountId),
           getPoolAccountPlan(config, entry.accountId),
         );
-        if (usage >= threshold) {
+        if (!isUnknownUsage(usage) && usage >= threshold) {
           const best = pickLowerUsageAccount(config, entry.accountId, usage, now);
           if (best !== entry.accountId) return best;
         }
@@ -609,7 +597,7 @@ export function previewCodexAccountForRequest(
   const threshold = config.autoSwitchThreshold ?? 80;
   if (threshold > 0) {
     const usage = computeCodexUsageScore(getAccountQuota(active), getPoolAccountPlan(config, active));
-    if (usage >= threshold) {
+    if (!isUnknownUsage(usage) && usage >= threshold) {
       active = pickLowerUsageAccount(config, active, usage, now);
     }
   }
@@ -657,7 +645,7 @@ export function resolveCodexAccountForThreadDetailed(
             getAccountQuota(entry.accountId),
             getPoolAccountPlan(config, entry.accountId),
           );
-          if (usage >= threshold) {
+          if (!isUnknownUsage(usage) && usage >= threshold) {
             const best = pickLowerUsageAccount(config, entry.accountId, usage, now);
             if (best !== entry.accountId) {
               setActiveCodexAccount(config, best);
@@ -807,12 +795,13 @@ export function recordCodexUpstreamOutcome(
   const hardCooldownUntil = getCodexAccountCooldownUntil(accountId, now) ?? undefined;
   // Soft avoid + affinity clears are part of failover. When threshold is 0, leave
   // sticky sessions alone (same as shouldFailover / applyFailureFailover no-ops).
-  const failoverEnabled = (config.upstreamFailoverThreshold ?? 3) > 0;
+  const failoverThreshold = config.upstreamFailoverThreshold ?? 3;
   const consecutiveFailures = stale ? 1 : (current?.consecutiveFailures ?? 0) + 1;
+  const failoverReady = failoverThreshold > 0 && consecutiveFailures >= failoverThreshold;
   const escalationMs = CODEX_TRANSIENT_SOFT_AVOID_ESCALATION_MS[
-    Math.min(consecutiveFailures, CODEX_TRANSIENT_SOFT_AVOID_ESCALATION_MS.length) - 1
+    Math.min(Math.max(consecutiveFailures - failoverThreshold, 0), CODEX_TRANSIENT_SOFT_AVOID_ESCALATION_MS.length - 1)
   ]!;
-  const softAvoidUntil = failoverEnabled
+  const softAvoidUntil = failoverReady
     ? Math.max(
       getCodexAccountSoftAvoidUntil(accountId, now) ?? 0,
       now + escalationMs,
@@ -831,7 +820,7 @@ export function recordCodexUpstreamOutcome(
   // thread is still pinned to the FAILING account — a late failure from account A
   // must not delete a newer healthy binding to account B (race: T→A, A fails,
   // T→B, late A failure must not delete B's mapping).
-  if (failoverEnabled && meta.threadId) {
+  if (failoverReady && meta.threadId) {
     const bound = threadAccountMap.get(meta.threadId);
     if (bound?.accountId === accountId) threadAccountMap.delete(meta.threadId);
   }

package/src/codex/sync.ts

@@ -4,15 +4,18 @@ import { refreshCodexModelCatalog } from "./refresh";
 import { applyProxyEnv, loadConfig } from "../config";
 import type { OcxConfig } from "../types";
 import { collectOrcaCodexHomeDiagnostic } from "./home";
+import { summarizeComboCatalogOmissions, type ComboCatalogOmission } from "./catalog/aggregation";
 
 export interface CodexSyncResult {
   ok: boolean;
   added: number;
   catalogPath: string | null;
   catalogExists: boolean;
+  catalogWritten: boolean;
   cacheSynced: boolean;
   message: string;
   warning?: string;
+  comboOmissions?: ComboCatalogOmission[];
   projectConfigWarnings?: ProjectCodexConfigWarning[];
   projectConfigGrouped?: { path: string; issues: string[]; bypass: string }[];
 }
@@ -59,6 +62,7 @@ export async function syncModelsToCodex(
       added: 0,
       catalogPath: null,
       catalogExists: false,
+      catalogWritten: false,
       cacheSynced: false,
       message: result.message,
     };
@@ -69,22 +73,33 @@ export async function syncModelsToCodex(
   let catalogPath: string | null = null;
   let catalogPathForInjection: string | null | undefined;
   let catalogExists = false;
+  let catalogWritten = false;
   let cacheSynced = false;
   let warning: string | undefined;
+  let comboOmissions: ComboCatalogOmission[] = [];
 
   try {
     const cat = await deps.refreshCodexModelCatalog(config);
     added = cat.added;
     catalogExists = cat.catalogExists;
+    catalogWritten = cat.catalogWritten;
     cacheSynced = cat.cacheSynced;
     catalogPathForInjection = cat.catalogExists ? cat.path : null;
     catalogPath = catalogPathForInjection;
+    comboOmissions = cat.comboOmissions ?? [];
     if (cat.added > 0) {
       log?.log(`   + ${cat.added} models appended to Codex catalog (${cat.path})`);
     } else if (!cat.catalogExists) {
       warning = "catalog sync skipped: no Codex catalog source found; keeping Codex's native catalog.";
       log?.error(warning);
     }
+    if (comboOmissions.length > 0) {
+      // Individual omission lines already went through console.warn during gather;
+      // keep a single summary on the sync logger to avoid duplicate stderr noise.
+      const summary = summarizeComboCatalogOmissions(comboOmissions);
+      log?.error(summary);
+      warning = warning ? `${warning} ${summary}` : summary;
+    }
   } catch (e) {
     warning = `catalog sync skipped: ${e instanceof Error ? e.message : String(e)}`;
     log?.error(warning);
@@ -99,9 +114,11 @@ export async function syncModelsToCodex(
     added,
     catalogPath,
     catalogExists,
+    catalogWritten,
     cacheSynced,
     message: result.message,
     ...(warning ? { warning } : {}),
+    ...(comboOmissions.length > 0 ? { comboOmissions } : {}),
     ...(projectConfigWarnings.length > 0 ? {
       projectConfigWarnings,
       projectConfigGrouped: groupProjectCodexConfigWarningsByPath(projectConfigWarnings),

package/src/config.ts

@@ -11,11 +11,13 @@ import {
   isWirePinnedModel,
   MODEL_ADAPTER_OVERRIDE_ALLOWED,
   OPENAI_PROVIDER_TIER_VERSION,
+  REASONING_SUMMARY_DELIVERY_VALUES,
   type OcxConfig,
   type OcxProviderConfig,
 } from "./types";
 import { isCanonicalOpenAiForwardProvider } from "./providers/openai-tiers";
 import { parseDesktopProfile } from "./claude/desktop-profile";
+import { modelRecordValue } from "./reasoning-effort";
 
 let _atomicSeq = 0;
 
@@ -442,6 +444,34 @@ export function booleanRecordConfigError(value: unknown, field: string): string
   return null;
 }
 
+const REASONING_SUMMARY_DELIVERY_SET = new Set<string>(REASONING_SUMMARY_DELIVERY_VALUES);
+
+export function reasoningSummaryDeliveryRecordConfigError(
+  value: unknown,
+  supportsReasoningSummaries: unknown,
+  field = "modelReasoningSummaryDelivery",
+): string | null {
+  if (value === undefined) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return `${field} must be a plain object with own properties`;
+
+  const supports = booleanRecordConfigError(supportsReasoningSummaries, "modelSupportsReasoningSummaries") === null
+    && supportsReasoningSummaries && typeof supportsReasoningSummaries === "object"
+    ? supportsReasoningSummaries as Record<string, boolean>
+    : undefined;
+  for (const [key, entry] of Object.entries(value)) {
+    if (!key.trim()) return `${field} keys must be nonblank model ids`;
+    if (typeof entry !== "string" || !REASONING_SUMMARY_DELIVERY_SET.has(entry)) {
+      return `${field}.${key} must be one of: ${REASONING_SUMMARY_DELIVERY_VALUES.join(", ")}`;
+    }
+    if (modelRecordValue(supports, key) === false) {
+      return `${field}.${key} conflicts with modelSupportsReasoningSummaries=false`;
+    }
+  }
+  return null;
+}
+
 /**
  * Validate a provider's per-model wire override map (#404).
  *
@@ -605,6 +635,17 @@ const configSchema = z.object({
         message: reasoningSummariesError,
       });
     }
+    const reasoningSummaryDeliveryError = reasoningSummaryDeliveryRecordConfigError(
+      (provider as { modelReasoningSummaryDelivery?: unknown }).modelReasoningSummaryDelivery,
+      (provider as { modelSupportsReasoningSummaries?: unknown }).modelSupportsReasoningSummaries,
+    );
+    if (reasoningSummaryDeliveryError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", name, "modelReasoningSummaryDelivery"],
+        message: reasoningSummaryDeliveryError,
+      });
+    }
     const defaultMaxOutputError = positiveIntegerConfigError(
       (provider as { defaultMaxOutputTokens?: unknown }).defaultMaxOutputTokens,
       "defaultMaxOutputTokens",
@@ -820,6 +861,13 @@ function schemaDiagnosticsError(error: z.ZodError): string {
   return details.length > 0 ? `schema_invalid: ${details.join("; ")}` : "schema_invalid";
 }
 
+/** Validate an in-memory config candidate without touching disk. Used by headless CLI import/set. */
+export function validateConfigCandidate(value: unknown): { ok: true; config: OcxConfig } | { ok: false; error: string } {
+  const result = configSchema.safeParse(value);
+  if (result.success) return { ok: true, config: result.data as OcxConfig };
+  return { ok: false, error: schemaDiagnosticsError(result.error) };
+}
+
 export function readConfigDiagnostics(): ConfigDiagnostics {
   const configPath = getConfigPath();
   if (!existsSync(configPath)) {

package/src/generated/jawcode-model-metadata.ts

@@ -29,7 +29,8 @@ const PROVIDER_ALIASES: Record<string, string> = {
   "gemini-antigravity": "google",
   "moonshot": "moonshot",
   "minimax": "minimax",
-  "minimax-cn": "minimax"
+  "minimax-cn": "minimax",
+  "zhipu-bigmodel": "zai"
 } as const;
 
 type Row = readonly [id: string, contextWindow?: number | null, maxTokens?: number | null, input?: string | null, reasoning?: 0 | 1 | null, wireModelId?: string | null, costInput?: number | null, costOutput?: number | null, costCacheRead?: number | null, costCacheWrite?: number | null];