@bitkyc08/opencodex 2.90.0 → 2.91.0

package/src/codex/subagent-model-fallback.ts

@@ -38,6 +38,7 @@ import {
   isCanonicalOpenAiForwardProvider,
 } from "../providers/openai-tiers";
 import { routeModel, type RouteResult } from "../router";
+import { guardFallbackHop, type FallbackAdmission } from "../routing/fallback-policy";
 import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
 import { codexAccountNamespaceForModel } from "./account-namespace-match";
 import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_MAIN_DRAIN_SENTINEL_MODELS } from "./catalog/native-models";
@@ -629,7 +630,8 @@ export function applySubagentModelFallback(
   modelEligibleAccountIdsForModel?: SubagentModelEligibleAccountIds,
   resolvedFallbackChain?: readonly string[] | null,
   restrictedRouteEligible?: SubagentFallbackRouteEligibility,
-): { from?: string; to?: string; skipped?: string[] } | null {
+  admission?: FallbackAdmission,
+): { from?: string; to?: string; skipped?: string[]; refusal?: Response } | null {
   if (!isThreadSpawnRequest(headers)) return null;
   const fallbackChain = resolvedFallbackChain === undefined
     ? resolveSubagentFallbackChain(parsed, config)
@@ -653,10 +655,31 @@ export function applySubagentModelFallback(
     ? { from: parsed.modelId, to: parsed.modelId, skipped: selection.skipped }
     : null;
   const from = parsed.modelId;
+  // OCX-11: the rewrite is a proactive hop away from an unavailable primary. Refused, the spawn
+  // keeps its model and the caller answers with the refusal instead of sending anything.
+  const hop = guardFallbackHop(config, {
+    site: "subagent",
+    route: from,
+    from: fallbackTargetOf(config, from),
+    to: fallbackTargetOf(config, selection.model),
+    trigger: "unavailable",
+    admission,
+    now,
+  });
+  if (!hop.ok) return { from, to: from, skipped: selection.skipped, refusal: hop.response };
+  // The rewrite is this site's admission: the spawn now carries the fallback model.
+  hop.commit();
   rewriteParsedModel(parsed, selection.model);
   return { from, to: selection.model, skipped: selection.skipped };
 }
 
+function fallbackTargetOf(config: OcxConfig, model: string): { provider: string; model: string } {
+  const route = tryRouteFallbackModel(config, model);
+  if (route) return { provider: route.providerName, model: route.modelId };
+  const slash = model.indexOf("/");
+  return slash > 0 ? { provider: model.slice(0, slash), model: model.slice(slash + 1) } : { provider: "", model };
+}
+
 /** Resolve the effective fallback chain once for one logical spawn request. */
 export function resolveSubagentFallbackChain(
   parsed: OcxParsedRequest,

package/src/combos/index.ts

@@ -23,6 +23,7 @@ export {
   advanceComboAfterFailure,
   clearComboSelectionState,
   comboExclusionReasons,
+  comboTargetSkipTrigger,
   NoAvailableComboTargetsError,
   noteComboFailure,
   noteComboSuccess,

package/src/combos/resolve.ts

@@ -74,6 +74,18 @@ function targetProviderIsUsable(config: OcxConfig, target: OcxComboTarget, now:
   return providerExclusionReason(config, target, now) === undefined;
 }
 
+/**
+ * OCX-11: the coarse fallback trigger for a target the picker passed over for a reason other
+ * than a cooldown (provider missing or disabled, cached quota spent, ineligible for the request).
+ */
+export function comboTargetSkipTrigger(
+  config: OcxConfig,
+  target: OcxComboTarget,
+  now = Date.now(),
+): "quota_exhausted" | "unavailable" {
+  return providerExclusionReason(config, target, now) === "quota exhausted" ? "quota_exhausted" : "unavailable";
+}
+
 /**
  * Why each target of a combo cannot be picked right now, for a zero-attempt refusal. Only the
  * configured provider/model and a coarse label are named, never account or request data.

package/src/config/diagnostics.ts

@@ -11,6 +11,7 @@ import { nativeReasoningRetentionConfigError } from "./schema/native-reasoning-r
 import { desktopCompatibilityConfigError } from "./schema/desktop-compatibility";
 import { blockedModelRedirectsError } from "./schema/blocked-model-redirects";
 import { mainAccountHardLockFallbackError } from "./schema/main-account-hard-lock-fallback";
+import { fallbackPolicyError } from "./schema/fallback-policy";
 import type { OcxConfig } from "../types";
 import { anthropicAccountPoolConfigError, anthropicOAuthInstanceConfigError, anthropicSidecarConfigError } from "./schema/anthropic-account-pool";
 import { configReasoningPinsConfigError } from "./provider-validation";
@@ -145,6 +146,7 @@ function validFileConfigDiagnostics(config: OcxConfig, rawParsed: unknown): Conf
   if (blockedModelRedirectsError(rawParsed)) warnings.push("blockedModelRedirects ignored: expected a map of nonempty model keys to nonempty string targets");
   if (nativeReasoningRetentionConfigError(rawParsed)) warnings.push("nativeReasoningRetention ignored: expected only optional boolean modelSwitch and accountSwitch fields; both remain off");
   if (mainAccountHardLockFallbackError(rawParsed)) warnings.push("codexMainAccountHardLockFallback ignored: expected a nonblank model selector and an optional declared reasoningEffort");
+  if (fallbackPolicyError(rawParsed)) warnings.push("fallback partly ignored: expected boolean model/provider switches, providers/routes/devices maps of them, and devices.<id>.localFallback; ignored leaves keep today's fallback behavior");
   const quotaAutoRefreshWarning = degradedCodexQuotaAutoRefreshWarning(rawParsed, normalized);
   if (quotaAutoRefreshWarning) warnings.push(quotaAutoRefreshWarning);
   if (rawEffort !== undefined && !isClaudeSubagentEffort(rawEffort)) {
@@ -729,6 +731,9 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
   const anthropicError = anthropicOAuthInstanceConfigError(value) ?? anthropicAccountPoolConfigError(value) ?? anthropicSidecarConfigError(value);
   if (anthropicError) return { ok: false, error: anthropicError };
   const boundaryError = blockedModelRedirectsError(value)
+    // OCX-11: the read schema degrades a malformed fallback leaf to absent, which would silently
+    // drop a refusal on the next whole-config save; the write boundary rejects it instead.
+    ?? fallbackPolicyError(value)
     ?? nativeReasoningRetentionConfigError(value)
     ?? mainAccountHardLockFallbackError(value)
     ?? compactionRecoveryConfigError(value) ?? desktopCompatibilityConfigError(value) ?? configReasoningPinsConfigError(value)

package/src/config/load-degrade.ts

@@ -7,6 +7,7 @@ import { nativeReasoningRetentionConfigError } from "./schema/native-reasoning-r
 import { desktopCompatibilityConfigError } from "./schema/desktop-compatibility";
 import { blockedModelRedirectsError } from "./schema/blocked-model-redirects";
 import { mainAccountHardLockFallbackError } from "./schema/main-account-hard-lock-fallback";
+import { fallbackPolicyError } from "./schema/fallback-policy";
 import { anthropicSidecarConfigError } from "./schema/anthropic-account-pool";
 import {
   modelPinnedEffortsConfigError,
@@ -142,6 +143,7 @@ export function warnDegradedTopLevelOptIns(rawParsed: unknown, validated: OcxCon
   if (desktopCompatibilityConfigError(rawParsed)) console.warn("Invalid desktopCompatibility startup preference ignored; no desktop compatibility service will start automatically.");
   if (blockedModelRedirectsError(rawParsed)) console.warn("⚠️  invalid blockedModelRedirects ignored; provider routing remains available");
   if (mainAccountHardLockFallbackError(rawParsed)) console.warn("⚠️  invalid codexMainAccountHardLockFallback ignored; the main-account hard lock still refuses while blocked");
+  if (fallbackPolicyError(rawParsed)) console.warn("⚠️  invalid fallback leaves ignored; those scopes keep today's fallback behavior");
   const chatgptDesktop = chatgptDesktopConfigIssue(rawParsed);
   if (chatgptDesktop) console.warn(`⚠️  config.json ${chatgptDesktop} — the whole chatgptDesktop block is ignored, so the ChatGPT desktop integration reads as off`);
   warnDegradedStreamMode(rawParsed, validated);

package/src/config/schema/config-schema.ts

@@ -8,6 +8,7 @@ import { nativeReasoningRetentionSchema } from "./native-reasoning-retention";
 import { desktopCompatibilitySchema } from "./desktop-compatibility";
 import { blockedModelRedirectsSchema } from "./blocked-model-redirects";
 import { mainAccountHardLockFallbackSchema } from "./main-account-hard-lock-fallback";
+import { fallbackPolicySchema } from "./fallback-policy";
 import {
   agentTaskRecoverySchema,
   catalogAutoRefreshSchema,
@@ -241,6 +242,8 @@ export const configSchema = z.object({
   // A malformed fallback section disables only the reroute, never the lock's refusal
   // behavior; the management write boundary still rejects the bad value.
   codexMainAccountHardLockFallback: mainAccountHardLockFallbackSchema.optional().catch(undefined),
+  // OCX-11: a malformed section reads as absent, which keeps today's fallback behavior.
+  fallback: fallbackPolicySchema.optional().catch(undefined),
   // #2999: a malformed hand edit falls back to auto detection rather than rejecting the config.
   nativeMainRefresh: z.enum(["codex", "opencodex"]).optional().catch(undefined),
   // Future versions remain opaque through passthrough-compatible whole-config saves.

package/src/config/schema/fallback-policy.ts

@@ -0,0 +1,40 @@
+import * as z from "zod/v4";
+
+/**
+ * Read schema of `fallback` (OCX-11). A malformed leaf degrades to absent, which is today's
+ * behavior, and config diagnostics name it; the management write boundary rejects it instead.
+ * Map keys are checked by the resolver's normalization, so one bad key never drops its siblings.
+ */
+const switchValue = z.boolean().optional().catch(undefined);
+const switchesSchema = z.object({ model: switchValue, provider: switchValue });
+const deviceSchema = switchesSchema.extend({ localFallback: switchValue });
+
+export const fallbackPolicySchema = z.object({
+  model: switchValue,
+  provider: switchValue,
+  providers: z.record(z.string(), switchesSchema.catch({})).optional().catch(undefined),
+  routes: z.record(z.string(), switchesSchema.catch({})).optional().catch(undefined),
+  devices: z.record(z.string(), deviceSchema.catch({})).optional().catch(undefined),
+});
+
+export const FALLBACK_DEVICE_ID = /^(?:lnk_[0-9a-f]{16}|[A-Za-z0-9][A-Za-z0-9_.:-]{0,255})$/;
+export const FALLBACK_SELECTOR = /^[^\s]{1,256}$/;
+
+const strictSwitches = z.object({ model: z.boolean().optional(), provider: z.boolean().optional() }).strict();
+const strictPolicy = z.object({
+  model: z.boolean().optional(),
+  provider: z.boolean().optional(),
+  providers: z.record(z.string().regex(FALLBACK_SELECTOR), strictSwitches).optional(),
+  routes: z.record(z.string().regex(FALLBACK_SELECTOR), strictSwitches).optional(),
+  devices: z.record(z.string().regex(FALLBACK_DEVICE_ID), strictSwitches.extend({ localFallback: z.boolean().optional() }).strict()).optional(),
+}).strict();
+
+/** Diagnostics text for a section the read schema would partly ignore, or undefined. */
+export function fallbackPolicyError(rawConfig: unknown): string | undefined {
+  if (!rawConfig || typeof rawConfig !== "object" || Array.isArray(rawConfig)) return undefined;
+  const raw = (rawConfig as Record<string, unknown>).fallback;
+  if (raw === undefined) return undefined;
+  return strictPolicy.safeParse(raw).success
+    ? undefined
+    : "schema_invalid: fallback accepts boolean model/provider switches, providers/routes/devices maps of them, and devices.<id>.localFallback";
+}