@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/combos/failover.ts

@@ -1,3 +1,4 @@
+import { parseResetCooldownMs } from "../codex/routing";
 import { classifyError, isCyberPolicyCode } from "../lib/errors";
 import type { OcxComboTarget } from "../types";
 import { targetKey } from "./types";
@@ -197,6 +198,7 @@ export function coolComboTarget(
   target: Pick<OcxComboTarget, "provider" | "model">,
   options?: {
     retryAfter?: string | null;
+    resetAt?: unknown | unknown[];
     now?: number;
     cooldownMs?: number;
     writerGeneration?: number;
@@ -209,8 +211,12 @@ export function coolComboTarget(
   const writerGeneration = options?.writerGeneration ?? captureConfigGeneration();
   const ownerKey = `${comboId}::${targetKey(target)}`;
   if (writerGeneration < lastReconciledGeneration && !liveComboTargets.has(ownerKey)) return;
-  const cooldownMs = options?.cooldownMs
-    ?? parseRetryAfterMs(options?.retryAfter, now)
+  // A server-provided Retry-After is authoritative, including an immediate `0` directive.
+  // A quota reset is the next-most-specific signal (#3256); configured and default cooldowns
+  // are only fallbacks when upstream supplied neither usable value.
+  const cooldownMs = parseRetryAfterMs(options?.retryAfter, now, { preserveImmediate: true })
+    ?? parseResetCooldownMs(options?.resetAt, now)
+    ?? options?.cooldownMs
     ?? (isTransientRequestRateLimit({
       status: options?.status,
       code: options?.code,
@@ -222,6 +228,32 @@ export function coolComboTarget(
   sweepExpiredOnWrite(now);
 }
 
+export function earliestComboCooldown(
+  comboId: string,
+  targets: Iterable<Pick<OcxComboTarget, "provider" | "model">>,
+  now = Date.now(),
+): { expiry: number; target: Pick<OcxComboTarget, "provider" | "model"> } | undefined {
+  let earliest: { expiry: number; target: Pick<OcxComboTarget, "provider" | "model"> } | undefined;
+  for (const target of targets) {
+    const key = cooldownMapKey(comboId, target);
+    const entry = targetCooldowns.get(key);
+    if (!entry || entry.cooldownUntil <= now) continue;
+    if (earliest === undefined || entry.cooldownUntil < earliest.expiry) {
+      earliest = { expiry: entry.cooldownUntil, target };
+    }
+  }
+  return earliest;
+}
+
+/** Public convenience wrapper returning only the earliest cooldown expiry. */
+export function earliestComboCooldownExpiry(
+  comboId: string,
+  targets: Iterable<Pick<OcxComboTarget, "provider" | "model">>,
+  now = Date.now(),
+): number | undefined {
+  return earliestComboCooldown(comboId, targets, now)?.expiry;
+}
+
 export function reconcileComboTargetCooldowns(context: GenerationContext): number {
   if (context.generation <= lastReconciledGeneration) return 0;
   liveComboTargets = new Set(context.comboTargets);
@@ -253,7 +285,7 @@ export function clearComboTargetCooldowns(comboId?: string): void {
 }
 
 export type ComboFailureDecision = "hop" | "stop";
-export type ComboFailureCooldownScope = "target" | "provider";
+export type ComboFailureCooldownScope = "none" | "target" | "provider";
 
 function normalizedFailureCode(code?: string | null): string {
   return code?.trim().toLowerCase().replaceAll("-", "_") ?? "";
@@ -272,17 +304,71 @@ function isProviderScopedQuotaCap(
   ) {
     return true;
   }
-  return normalizedCode === "free_rate_limited"
-    || text.includes("err_free_prompt_cap")
+  return text.includes("err_free_prompt_cap")
     || (text.includes("free tier") && text.includes("single request"));
 }
 
+/**
+ * A free-tier cap the upstream evaluates PER REQUEST rather than per account window. These
+ * needles used to reach only `isProviderScopedQuotaCap`, so a single oversized free-tier prompt
+ * cooled the whole provider for every other combo — including the shorter requests that same
+ * provider would still have served. `free_rate_limited` also left the provider-scoped predicate
+ * for the same reason; it stays a hop signal, but stops recording provider-wide evidence.
+ */
+function isRequestLocalFreePromptCap(
+  status: number | undefined,
+  message: string,
+  code?: string | null,
+): boolean {
+  if (status !== 400) return false;
+  const text = message.toLowerCase();
+  if (normalizedFailureCode(code) === "free_rate_limited") return true;
+  if (text.includes("err_free_prompt_cap")) return true;
+  return text.includes("free tier") && (text.includes("single request") || text.includes("prompt"));
+}
+
+/**
+ * Failures that describe the SHAPE of this request rather than the health of the target.
+ * Cooling anything for these is wrong twice over: the target is fine, and the next request
+ * (shorter prompt, smaller tool catalog) would have succeeded against it.
+ */
+const REQUEST_SHAPE_FAILURE_CODES = new Set([
+  "input_admission_refused",
+  "context_length_exceeded",
+  "tool_catalog_too_large",
+  "cursor_root_envelope_limit",
+  "target_incompatible",
+]);
+
+/** Credential/billing failures that every target sharing the provider inherits. */
+const PROVIDER_SCOPED_FAILURE_CODES = new Set([
+  "invalid_api_key",
+  "insufficient_quota",
+  "subscription_required",
+  "payment_required",
+  "billing_error",
+  "insufficient_balance",
+]);
+
 export function comboFailureCooldownScope(
   status: number,
   message: string,
   options?: { code?: string | null },
 ): ComboFailureCooldownScope {
-  return isProviderScopedQuotaCap(status, message, options?.code) ? "provider" : "target";
+  const code = normalizedFailureCode(options?.code);
+  // Request-shape refusals first: an oversized request must not cool a healthy target.
+  if (
+    status === 413
+    || REQUEST_SHAPE_FAILURE_CODES.has(code)
+    || isRequestLocalFreePromptCap(status, message, options?.code)
+    || isProviderTargetContextOverflow(status, message, options?.code)
+  ) return "none";
+  if (isProviderScopedQuotaCap(status, message, options?.code)) return "provider";
+  // A rejected or unpaid credential is provider-wide evidence: every target that routes
+  // through the same provider row carries the same key and will fail identically.
+  if (status === 401 || status === 402 || status === 403) return "provider";
+  if (PROVIDER_SCOPED_FAILURE_CODES.has(code)) return "provider";
+  return "target";
 }
 
 function isModelLifecycleGone(
@@ -307,6 +393,19 @@ function isModelLifecycleGone(
   );
 }
 
+function isProviderTargetContextOverflow(
+  status: number,
+  message: string,
+  code?: string | null,
+): boolean {
+  if (status !== 400) return false;
+  const normalizedCode = normalizedFailureCode(code);
+  const text = message.toLowerCase();
+  if (text.includes("invalid_request_prompt_too_long")) return true;
+  return normalizedCode === "5059"
+    && /\bprompt\s+\d+\s*>\s*\d+\s+maximum context length\b/i.test(message);
+}
+
 export function comboFailureDecision(
   status: number,
   message: string,
@@ -324,6 +423,10 @@ export function comboFailureDecision(
   if (isModelLifecycleGone(status, message, options?.code)) return "hop";
   const error = classifyError(status, "upstream_error", message);
   if (isCyberPolicyCode(error.code)) return "stop";
+  // A provider can expose its own target hard cap with a non-semantic vendor code
+  // (for example 5059 + invalid_request_prompt_too_long). That is evidence that this
+  // target is too small, not that every later combo target is incapable of serving it.
+  if (isProviderTargetContextOverflow(status, message, options?.code)) return "hop";
   // A local input-admission refusal (#1524) says "this candidate cannot fit the request",
   // not "the request is impossible": the next candidate may have a larger context window.
   //
@@ -347,15 +450,30 @@ export function comboFailureDecision(
   if (isProviderScopedQuotaCap(status, message, options?.code || error.code)) {
     return "hop";
   }
+  // A model-scoped rejection is target-local: this provider does not serve THIS model, which
+  // says nothing about the next combo target. Structured code only, plus the explicit prose
+  // form upstreams emit when they carry no code, so an unrelated 400 stays terminal.
+  const failureCode = normalizedFailureCode(options?.code || error.code);
+  if (["model_not_found", "model_unavailable", "unsupported_model"].includes(failureCode)) {
+    return "hop";
+  }
+  // `free_rate_limited` no longer routes through `isProviderScopedQuotaCap` (it is a
+  // per-request cap, not provider-wide evidence), so keep its hop verdict explicit here.
+  if (failureCode === "free_rate_limited") return "hop";
   if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
     return "stop";
   }
-  if ([401, 403, 404, 408, 429].includes(status) || status >= 500) return "hop";
+  // 402 (payment required) and 425 (too early) are provider-state signals, not verdicts about
+  // the request: another combo target can still serve it.
+  if ([401, 402, 403, 404, 408, 425, 429].includes(status) || status >= 500) return "hop";
   if ([
     "permission_denied",
     "subscription_required",
     "invalid_api_key",
     "insufficient_quota",
+    "payment_required",
+    "billing_error",
+    "insufficient_balance",
     "rate_limit_exceeded",
     "server_is_overloaded",
     "upstream_server_error",

package/src/combos/identifiers.ts

@@ -0,0 +1,89 @@
+import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../codex/catalog/native-models";
+import type { OcxComboConfig, OcxComboTarget, OcxConfig } from "../types";
+
+export const COMBO_NAMESPACE = "combo";
+
+export function preservesPhysicalComboProvider(
+  config: Pick<OcxConfig, "providers" | "combos">,
+): boolean {
+  return Object.hasOwn(config.providers, COMBO_NAMESPACE)
+    && Object.keys(config.combos ?? {}).length === 0;
+}
+
+const COMBO_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/** True only for an explicitly opted-in bare native-family alias. */
+export function isNativeAliasCombo(
+  combo: { alias?: string | null; nativeAlias?: boolean },
+): boolean {
+  const alias = typeof combo.alias === "string" ? combo.alias.trim() : "";
+  return combo.nativeAlias === true
+    && SUPPORTED_NATIVE_OPENAI_SLUGS.has(alias);
+}
+
+export function targetKey(target: Pick<OcxComboTarget, "provider" | "model">): string {
+  return `${target.provider}/${target.model}`;
+}
+
+export function parseComboModelId(modelId: string): string | null {
+  const slash = modelId.indexOf("/");
+  if (slash <= 0 || modelId.slice(0, slash) !== COMBO_NAMESPACE) return null;
+  const id = modelId.slice(slash + 1);
+  return id.length > 0 ? id : null;
+}
+
+export function comboModelId(id: string): string {
+  return `${COMBO_NAMESPACE}/${id}`;
+}
+
+/** Public model id clients request: the alias when set, else the default `combo/<id>`. */
+export function comboPublicModelId(id: string, combo: { alias?: string | null }): string {
+  const alias = typeof combo.alias === "string" ? combo.alias.trim() : "";
+  return alias || comboModelId(id);
+}
+
+/**
+ * Persisted selector that hides a combo from discovery. Native aliases keep the canonical
+ * `combo/<id>` selector because their bare public id remains the native OpenAI disable key.
+ */
+export function comboDisabledModelId(
+  id: string,
+  combo: { alias?: string | null; nativeAlias?: boolean },
+): string {
+  return isNativeAliasCombo(combo) ? comboModelId(id) : comboPublicModelId(id, combo);
+}
+
+/** Every persisted selector that can refer to this combo in `disabledModels`. */
+export function comboDisabledModelSelectors(
+  id: string,
+  combo: { alias?: string | null; nativeAlias?: boolean },
+): string[] {
+  const canonical = comboModelId(id);
+  const preferred = comboDisabledModelId(id, combo);
+  return preferred === canonical ? [canonical] : [canonical, preferred];
+}
+
+/**
+ * Resolve a client-requested model id to a combo config key. The canonical `combo/<id>`
+ * form wins first (back-compat); otherwise an exact alias match across configured combos.
+ */
+export function resolveComboId(
+  config: { combos?: Record<string, OcxComboConfig> },
+  modelId: string,
+): string | null {
+  const direct = parseComboModelId(modelId);
+  if (direct) return direct;
+  const combos = config.combos;
+  if (!combos) return null;
+  for (const [id, raw] of Object.entries(combos)) {
+    if (!raw || typeof raw !== "object") continue;
+    const alias = typeof raw.alias === "string" ? raw.alias.trim() : "";
+    if (alias && alias === modelId) return id;
+  }
+  return null;
+}
+
+
+export function isValidComboId(id: string): boolean {
+  return COMBO_ID_PATTERN.test(id);
+}

package/src/combos/index.ts

@@ -1,4 +1,5 @@
 export {
+  COMBO_DEFAULT_WAIT_FOR_COOLDOWN_MS,
   COMBO_NAMESPACE,
   comboAliasIssues,
   comboConfigError,
@@ -25,6 +26,7 @@ export {
   noteComboFailure,
   noteComboSuccess,
   pickComboTarget,
+  pickComboTargetWithWait,
   tryPickComboModel,
   UnknownComboError,
   type ComboPick,
@@ -34,6 +36,8 @@ export {
   comboCooldownRetryAfterSeconds,
   COMBO_REQUEST_RATE_COOLDOWN_MS,
   coolComboTarget,
+  earliestComboCooldown,
+  earliestComboCooldownExpiry,
   isComboTargetInCooldown,
   isTransientRequestRateLimit,
   parseRetryAfterMs,

package/src/combos/resolve.ts

@@ -1,7 +1,13 @@
 import type { OcxComboTarget, OcxConfig } from "../types";
 import { getCachedProviderQuota } from "../providers/quota-routing-cache";
 import type { ProviderQuota } from "../providers/quota-types";
-import { coolComboTarget, isComboTargetInCooldown, type ComboFailureCooldownScope } from "./failover";
+import { sleepWithAbort } from "../lib/upstream-retry";
+import {
+  coolComboTarget,
+  earliestComboCooldown,
+  isComboTargetInCooldown,
+  type ComboFailureCooldownScope,
+} from "./failover";
 import { quotaResetRemainingMs } from "./reset-window";
 import { getCombo, resolveComboId, targetKey } from "./types";
 import type { NormalizedComboConfig } from "./types";
@@ -155,6 +161,7 @@ export function pickComboTarget(
   const eligible = (target: Required<OcxComboTarget>): boolean =>
     targetProviderIsUsable(config, target)
     && !cachedProviderQuotaIsExhausted(getCachedProviderQuota(target.provider, now), now)
+    && !isComboTargetInCooldown(comboId, target, now)
     && !excluded.has(targetKey(target))
     && (options.eligible?.(target) ?? true);
 
@@ -274,7 +281,9 @@ export function advanceComboAfterFailure(
   pick: ComboPick,
   options: {
     retryAfter?: string | null;
+    resetAt?: unknown | unknown[];
     now?: number;
+    cooldownMs?: number;
     eligible?: (target: Required<OcxComboTarget>) => boolean;
     cooldownScope?: ComboFailureCooldownScope;
     status?: number;
@@ -284,14 +293,19 @@ export function advanceComboAfterFailure(
 ): ComboPick | null {
   noteComboFailure(pick.comboId, pick.target, pick.writerGeneration);
   const combo = getCombo(config, pick.comboId);
-  const cooldownTargets = options.cooldownScope === "provider" && combo
-    ? combo.targets.filter(target => target.provider === pick.target.provider)
-    : [pick.target];
-  for (const target of cooldownTargets) {
-    coolComboTarget(pick.comboId, target, {
-      ...options,
-      writerGeneration: pick.writerGeneration,
-    });
+  // "none" records no cooldown at all: the failure described the request, not the target, so
+  // the target must stay immediately selectable for the next (differently shaped) request.
+  if (options.cooldownScope !== "none") {
+    const cooldownTargets = options.cooldownScope === "provider" && combo
+      ? combo.targets.filter(target => target.provider === pick.target.provider)
+      : [pick.target];
+    for (const target of cooldownTargets) {
+      coolComboTarget(pick.comboId, target, {
+        ...options,
+        cooldownMs: options.cooldownMs ?? combo?.cooldownMs,
+        writerGeneration: pick.writerGeneration,
+      });
+    }
   }
   return pickComboTarget(config, pick.comboId, {
     exclude: pick.attempted,
@@ -301,6 +315,63 @@ export function advanceComboAfterFailure(
   });
 }
 
+export async function pickComboTargetWithWait(
+  config: OcxConfig,
+  comboId: string,
+  options: {
+    exclude?: Iterable<string>;
+    eligible?: (target: Required<OcxComboTarget>) => boolean;
+    waitForCooldownMs: number;
+    abortSignal?: AbortSignal;
+    now?: number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  },
+): Promise<ComboPick | null> {
+  const now = options.now ?? Date.now();
+  const excluded = new Set(options.exclude ?? []);
+  const customEligible = options.eligible;
+  const eligible = (target: Required<OcxComboTarget>): boolean =>
+    !isComboTargetInCooldown(comboId, target, now)
+    && (customEligible?.(target) ?? true);
+  const pick = pickComboTarget(config, comboId, { exclude: excluded, eligible, now });
+  if (pick || options.waitForCooldownMs <= 0 || options.abortSignal?.aborted) return pick;
+  const combo = getCombo(config, comboId);
+  if (!combo) throw new UnknownComboError(comboId);
+  const waitingTargets = combo.targets.filter(target =>
+    targetProviderIsUsable(config, target)
+    && !cachedProviderQuotaIsExhausted(getCachedProviderQuota(target.provider, now), now)
+    && !excluded.has(targetKey(target))
+    && isComboTargetInCooldown(comboId, target, now)
+    && (customEligible?.(target) ?? true),
+  );
+  const earliest = earliestComboCooldown(comboId, waitingTargets, now);
+  if (earliest === undefined) return null;
+  const delay = earliest.expiry - now;
+  if (delay > options.waitForCooldownMs) return null;
+  // The expiry computation above is the single source of truth for the wait budget.
+  // Its target preserves configured order for ties.
+  const target = earliest.target;
+  console.warn(
+    `[combo] ${comboId}: all targets cooling, waiting ${delay}ms for ${targetKey(target)}`,
+  );
+  try {
+    await (options.sleep ?? sleepWithAbort)(delay, options.abortSignal);
+  } catch (error) {
+    if (options.abortSignal?.aborted) return null;
+    throw error;
+  }
+  if (options.abortSignal?.aborted) return null;
+  // Management updates can delete or rename the combo while this request sleeps.
+  if (!getCombo(config, comboId)) return null;
+  return pickComboTarget(config, comboId, {
+    exclude: excluded,
+    now: now + delay,
+    eligible: targetCandidate =>
+      !isComboTargetInCooldown(comboId, targetCandidate, now + delay)
+      && (customEligible?.(targetCandidate) ?? true),
+  });
+}
+
 export function reconcileComboRotationState(context: GenerationContext): number {
   if (context.generation <= lastReconciledGeneration) return 0;
   let removed = 0;

package/src/combos/types.ts

@@ -1,25 +1,11 @@
 import { isCodexReasoningEffort } from "../reasoning-effort";
 import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../codex/catalog/native-models";
-import type {
-  OcxComboConfig,
-  OcxComboDefaultEffort,
-  OcxComboReasoningEffortMode,
-  OcxComboStrategy,
-  OcxComboTarget,
-  OcxConfig,
-  OcxProviderConfig,
-} from "../types";
+import type { OcxComboConfig, OcxComboDefaultEffort, OcxComboReasoningEffortMode, OcxComboStrategy, OcxComboTarget, OcxProviderConfig } from "../types";
+import { COMBO_NAMESPACE, isValidComboId, targetKey } from "./identifiers";
 
-export const COMBO_NAMESPACE = "combo";
+export const COMBO_DEFAULT_WAIT_FOR_COOLDOWN_MS = 0;
+export { COMBO_NAMESPACE, preservesPhysicalComboProvider, isNativeAliasCombo, targetKey, parseComboModelId, comboModelId, comboPublicModelId, comboDisabledModelId, comboDisabledModelSelectors, resolveComboId, isValidComboId } from "./identifiers";
 
-export function preservesPhysicalComboProvider(
-  config: Pick<OcxConfig, "providers" | "combos">,
-): boolean {
-  return Object.hasOwn(config.providers, COMBO_NAMESPACE)
-    && Object.keys(config.combos ?? {}).length === 0;
-}
-
-const COMBO_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 /**
  * Public alias shape: one optional "/" segment, each segment id-shaped. Bare aliases
  * (no "/") are the masquerade case — the combo answers to a mandated model id with no
@@ -37,6 +23,8 @@ export interface ComboValidationIssue {
 export interface NormalizedComboConfig {
   strategy: OcxComboStrategy;
   stickyLimit: number;
+  cooldownMs?: number;
+  waitForCooldownMs: number;
   defaultEffort: OcxComboDefaultEffort | null;
   /** Picker-ladder derivation policy; `strict` preserves the legacy intersection rule. */
   reasoningEffortMode: OcxComboReasoningEffortMode;
@@ -51,77 +39,6 @@ export interface NormalizedComboConfig {
   targets: Array<Required<OcxComboTarget>>;
 }
 
-/** True only for an explicitly opted-in bare native-family alias. */
-export function isNativeAliasCombo(
-  combo: { alias?: string | null; nativeAlias?: boolean },
-): boolean {
-  const alias = typeof combo.alias === "string" ? combo.alias.trim() : "";
-  return combo.nativeAlias === true
-    && SUPPORTED_NATIVE_OPENAI_SLUGS.has(alias);
-}
-
-export function targetKey(target: Pick<OcxComboTarget, "provider" | "model">): string {
-  return `${target.provider}/${target.model}`;
-}
-
-export function parseComboModelId(modelId: string): string | null {
-  const slash = modelId.indexOf("/");
-  if (slash <= 0 || modelId.slice(0, slash) !== COMBO_NAMESPACE) return null;
-  const id = modelId.slice(slash + 1);
-  return id.length > 0 ? id : null;
-}
-
-export function comboModelId(id: string): string {
-  return `${COMBO_NAMESPACE}/${id}`;
-}
-
-/** Public model id clients request: the alias when set, else the default `combo/<id>`. */
-export function comboPublicModelId(id: string, combo: { alias?: string | null }): string {
-  const alias = typeof combo.alias === "string" ? combo.alias.trim() : "";
-  return alias || comboModelId(id);
-}
-
-/**
- * Persisted selector that hides a combo from discovery. Native aliases keep the canonical
- * `combo/<id>` selector because their bare public id remains the native OpenAI disable key.
- */
-export function comboDisabledModelId(
-  id: string,
-  combo: { alias?: string | null; nativeAlias?: boolean },
-): string {
-  return isNativeAliasCombo(combo) ? comboModelId(id) : comboPublicModelId(id, combo);
-}
-
-/** Every persisted selector that can refer to this combo in `disabledModels`. */
-export function comboDisabledModelSelectors(
-  id: string,
-  combo: { alias?: string | null; nativeAlias?: boolean },
-): string[] {
-  const canonical = comboModelId(id);
-  const preferred = comboDisabledModelId(id, combo);
-  return preferred === canonical ? [canonical] : [canonical, preferred];
-}
-
-/**
- * Resolve a client-requested model id to a combo config key. The canonical `combo/<id>`
- * form wins first (back-compat); otherwise an exact alias match across configured combos.
- */
-export function resolveComboId(
-  config: { combos?: Record<string, OcxComboConfig> },
-  modelId: string,
-): string | null {
-  const direct = parseComboModelId(modelId);
-  if (direct) return direct;
-  const combos = config.combos;
-  if (!combos) return null;
-  for (const [id, raw] of Object.entries(combos)) {
-    if (!raw || typeof raw !== "object") continue;
-    const alias = typeof raw.alias === "string" ? raw.alias.trim() : "";
-    if (alias && alias === modelId) return id;
-  }
-  return null;
-}
-
 /**
  * Cross-combo alias checks that need the full combos map (uniqueness). Kept separate
  * from `comboConfigIssues` so config-file validation and the management API share it.
@@ -230,6 +147,18 @@ export function comboConfigIssues(
       || body.stickyLimit > 100)) {
     issues.push({ path: ["stickyLimit"], message: "stickyLimit must be an integer from 1 to 100" });
   }
+  if (body.cooldownMs !== undefined
+    && (typeof body.cooldownMs !== "number" || !Number.isInteger(body.cooldownMs)
+      || body.cooldownMs < 1
+      || body.cooldownMs > 600_000)) {
+    issues.push({ path: ["cooldownMs"], message: "cooldownMs must be an integer from 1 to 600000" });
+  }
+  if (body.waitForCooldownMs !== undefined
+    && (typeof body.waitForCooldownMs !== "number" || !Number.isInteger(body.waitForCooldownMs)
+      || body.waitForCooldownMs < 0
+      || body.waitForCooldownMs > 600_000)) {
+    issues.push({ path: ["waitForCooldownMs"], message: "waitForCooldownMs must be an integer from 0 to 600000" });
+  }
   if (body.defaultEffort !== undefined
     && body.defaultEffort !== null
     && (typeof body.defaultEffort !== "string" || !isCodexReasoningEffort(body.defaultEffort))) {
@@ -367,6 +296,8 @@ export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig
   return {
     strategy: raw.strategy ?? "failover",
     stickyLimit: raw.stickyLimit ?? 1,
+    cooldownMs: raw.cooldownMs,
+    waitForCooldownMs: raw.waitForCooldownMs ?? COMBO_DEFAULT_WAIT_FOR_COOLDOWN_MS,
     defaultEffort: raw.defaultEffort ?? null,
     reasoningEffortMode: raw.reasoningEffortMode === "adaptive" ? "adaptive" : "strict",
     imageInput: raw.imageInput === "disabled" ? "disabled" : "auto",
@@ -393,10 +324,6 @@ export function comboDefaultEffort(
     : null;
 }
 
-export function isValidComboId(id: string): boolean {
-  return COMBO_ID_PATTERN.test(id);
-}
-
 export function listComboIds(config: { combos?: Record<string, OcxComboConfig> }): string[] {
   return Object.keys(config.combos ?? {}).sort((a, b) => a.localeCompare(b));
 }

package/src/config/subagent-models.ts

@@ -0,0 +1,24 @@
+import type { OcxConfig } from "../types";
+import { NATIVE_GPT6_ASTRA_MODEL } from "../codex/catalog/native-models";
+
+export const SUBAGENT_MODELS_VERSION = 1;
+
+/** Native featured defaults; Codex advertises at most five picker-visible rows. */
+export const DEFAULT_SUBAGENT_MODELS = [
+  NATIVE_GPT6_ASTRA_MODEL, "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5",
+];
+
+/** One-time upgrade; later user edits (including removing Astra) remain authoritative. */
+export function migrateSubagentModels(config: OcxConfig): boolean {
+  if ((config.subagentModelsVersion ?? 0) >= SUBAGENT_MODELS_VERSION) return false;
+  if (config.subagentModels === undefined) {
+    config.subagentModels = [...DEFAULT_SUBAGENT_MODELS];
+  } else {
+    const retained = [...new Set([NATIVE_GPT6_ASTRA_MODEL, ...config.subagentModels])].slice(0, 5);
+    // Cap first: do not rescue a fifth old choice. Retained 5.5 belongs at the bottom.
+    config.subagentModels = retained.filter(model => model !== "gpt-5.5");
+    if (retained.includes("gpt-5.5")) config.subagentModels.push("gpt-5.5");
+  }
+  config.subagentModelsVersion = SUBAGENT_MODELS_VERSION;
+  return true;
+}