@bitkyc08/opencodex 2.64.0 → 2.65.0-preview.20260925

package/src/codex/native-residue.ts

@@ -82,6 +82,9 @@ const JOURNAL_FILE_NAME = "opencodex-journal.json";
 const ROUTED_CATALOG_DESCRIPTION_PREFIX = "Routed via opencodex → ";
 const MAX_ROLLOUT_INSPECTION_BYTES = 64 * 1024 * 1024;
 const ROLLOUT_READ_CHUNK_BYTES = 64 * 1024;
+// Bound one observation across every referenced rollout, not just each file.
+const MAX_TOTAL_ROLLOUT_INSPECTION_BYTES = 64 * 1024 * 1024;
+type RolloutInspectionBudget = { remainingBytes: number };
 
 function errorCode(error: unknown): string | undefined {
   return (error as NodeJS.ErrnoException | undefined)?.code;
@@ -424,6 +427,7 @@ function classifyPartialWrites(targetPaths: string[]): NativeRoutedResidueResult
 function classifyReferencedRollout(
   surface: "history" | "history-backup",
   reference: RolloutReference,
+  budget: RolloutInspectionBudget,
 ): NativeRoutedResidueResult {
   const resolved = resolveRegularFile(reference.path);
   if (resolved.kind === "absent") {
@@ -451,6 +455,14 @@ function classifyReferencedRollout(
         `referenced rollout exceeds the ${MAX_ROLLOUT_INSPECTION_BYTES} byte inspection limit`,
       );
     }
+    if (opened.size > budget.remainingBytes) {
+      return indeterminate(
+        surface,
+        resolved.path,
+        `referenced rollouts exceed the ${MAX_TOTAL_ROLLOUT_INSPECTION_BYTES} byte aggregate inspection limit`,
+      );
+    }
+    budget.remainingBytes -= opened.size;
     const decoder = new TextDecoder("utf-8", { ignoreBOM: true });
     const buffer = Buffer.allocUnsafe(ROLLOUT_READ_CHUNK_BYTES);
     while (totalRead < opened.size) {
@@ -528,15 +540,16 @@ function classifyReferencedRollout(
 function classifyReferencedRollouts(
   surface: "history" | "history-backup",
   references: RolloutReference[],
+  budget: RolloutInspectionBudget,
 ): NativeRoutedResidueResult {
   for (const reference of references) {
-    const result = classifyReferencedRollout(surface, reference);
+    const result = classifyReferencedRollout(surface, reference, budget);
     if (result.kind !== "clean") return result;
   }
   return { kind: "clean" };
 }
 
-function classifyHistoryDatabase(path: string): NativeRoutedResidueResult {
+function classifyHistoryDatabase(path: string, budget: RolloutInspectionBudget): NativeRoutedResidueResult {
   const resolved = resolveRegularFile(path);
   if (resolved.kind === "absent") {
     for (const suffix of ["-wal", "-shm"]) {
@@ -576,6 +589,7 @@ function classifyHistoryDatabase(path: string): NativeRoutedResidueResult {
       rows
         .filter(row => row.model_provider !== "opencodex")
         .map(row => ({ id: row.id, path: row.rollout_path })),
+      budget,
     );
     if (rollouts.kind !== "clean") return rollouts;
     const after = statSync(resolved.path);
@@ -600,7 +614,7 @@ function historyBackupPath(stateDatabasePath: string): string {
   return legacy !== canonical && existsSync(legacy) ? legacy : canonical;
 }
 
-function classifyHistoryBackup(path: string, stateDatabasePath: string): NativeRoutedResidueResult {
+function classifyHistoryBackup(path: string, stateDatabasePath: string, budget: RolloutInspectionBudget): NativeRoutedResidueResult {
   const read = readRegularFile(path);
   if (read.kind === "absent") return { kind: "clean" };
   if (read.kind === "indeterminate") return indeterminate("history-backup", path, read.reason);
@@ -630,7 +644,7 @@ function classifyHistoryBackup(path: string, stateDatabasePath: string): NativeR
   for (const entry of Object.values(validated.manifest.entries)) {
     references.push({ id: entry.id, path: entry.rolloutPath });
   }
-  const rollouts = classifyReferencedRollouts("history-backup", references);
+  const rollouts = classifyReferencedRollouts("history-backup", references, budget);
   if (rollouts.kind !== "clean") return rollouts;
   return entries.length > 0
     ? { kind: "residue", surface: "history-backup", path: read.path }
@@ -672,6 +686,7 @@ export function classifyNativeRoutedResidue(): NativeRoutedResidueResult {
     journalPath,
     ...config.catalogTargets.map(target => target.path),
   ];
+  const budget = { remainingBytes: MAX_TOTAL_ROLLOUT_INSPECTION_BYTES };
   const classifiers = [
     () => classifyPartialWrites(atomicWriteTargets),
     () => config.classification,
@@ -679,11 +694,14 @@ export function classifyNativeRoutedResidue(): NativeRoutedResidueResult {
     ...config.catalogTargets.map(target => () => classifyCatalogLike("catalog", target.path, target.configured)),
     () => classifyCatalogLike("models-cache", modelsCachePath),
     () => classifyJournal(journalPath),
-    () => classifyHistoryDatabase(stateDatabasePath),
-    () => classifyHistoryBackup(historyBackupPath(stateDatabasePath), stateDatabasePath),
+    () => classifyHistoryDatabase(stateDatabasePath, budget),
+    () => classifyHistoryBackup(historyBackupPath(stateDatabasePath), stateDatabasePath, budget),
   ];
-  const results = classifiers.map(classify => classify());
-  return results.find(result => result.kind === "indeterminate")
-    ?? results.find(result => result.kind === "residue")
-    ?? { kind: "clean" };
+  let firstResidue: NativeRoutedResidueResult = { kind: "clean" };
+  for (const classify of classifiers) {
+    const result = classify();
+    if (result.kind === "indeterminate") return result;
+    if (result.kind === "residue" && firstResidue.kind === "clean") firstResidue = result;
+  }
+  return firstResidue;
 }

package/src/codex/quota-types.ts

@@ -1,5 +1,12 @@
 /** Quota wire/storage shapes. This leaf must not import credential or config owners. */
-export const MAIN_ACCOUNT_HARD_LOCK_PERCENT = 99;
+/**
+ * Observed usage at which new identity-matched main-account requests are refused (#5694).
+ *
+ * The policy is on by default, so this constant is what every installation without an explicit
+ * `codexMainAccountHardLock: false` admits against. 98 leaves one point of headroom under the
+ * exhausted reading Codex Desktop already treats as its own disabled send button.
+ */
+export const MAIN_ACCOUNT_HARD_LOCK_PERCENT = 98;
 
 /**
  * How recently a 100% burst reading must have been observed to exclude an account when it

package/src/codex/quota.ts

@@ -29,6 +29,8 @@ type QuotaDiskFile = {
 };
 
 type MainPolicyQuota = { identityKey: string; quota: StoredAccountQuota };
+/** Fresh WHAM topology proof is consumed by the merge, never retained in a cache or DTO. */
+type MainPolicyQuotaObservation = Omit<StoredAccountQuota, "updatedAt"> & { shortWindowAbsent?: true };
 let mainPolicyQuota: MainPolicyQuota | null = null;
 let diskHydrated = false;
 let persistTimer: ReturnType<typeof setTimeout> | null = null;
@@ -199,6 +201,12 @@ function isExplicitMonthlyWindow(window: WhamUsageWindow | null | undefined): bo
     && seconds >= MONTHLY_WINDOW_MIN_SECONDS;
 }
 
+/** Same 24h short/long boundary as the parser; this includes a declared one-day window. */
+function isExplicitLongWindow(window: WhamUsageWindow | null | undefined): boolean {
+  const seconds = window?.limit_window_seconds;
+  return typeof seconds === "number" && Number.isFinite(seconds) && seconds >= WEEKLY_WINDOW_MIN_SECONDS;
+}
+
 function isExplicitMonthlyWindowMinutes(windowMinutes: unknown): boolean {
   const minutes = windowMinutes_(windowMinutes);
   return minutes !== undefined && minutes >= MONTHLY_WINDOW_MIN_MINUTES;
@@ -267,12 +275,17 @@ function snapshotHasCustom(quota: Omit<StoredAccountQuota, "updatedAt">): boolea
 function snapshotHasUsage(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
   return snapshotHasWeekly(quota) || snapshotHasMonthly(quota) || snapshotHasShort(quota) || snapshotHasCustom(quota);
 }
+/**
+ * Publish parsed display quota and separately validated main-policy evidence after writer checks.
+ * A null policy observation retains only the matching main identity's previous evidence;
+ * transient replacement markers are consumed during merging and never enter stored snapshots.
+ */
 export function setAccountQuotaFromParsed(
   accountId: string,
   quota: Omit<StoredAccountQuota, "updatedAt"> | null,
   writerGeneration = captureConfigGeneration(),
   mainWriter?: MainQuotaWriter,
-  policyQuota: Omit<StoredAccountQuota, "updatedAt"> | null = quota,
+  policyQuota: MainPolicyQuotaObservation | null = quota,
   historyEvidence?: QuotaObservationEvidence,
 ): void {
   quota = withoutRetiredCodexQuota(quota);
@@ -313,9 +326,13 @@ export function setAccountQuotaFromParsed(
   }
 }
 
-/** One partial-window merge contract for legacy quota and identity-bound policy evidence. */
+/**
+ * Merge a partial observation into the legacy or identity-bound policy snapshot.
+ * Policy mode retains omitted blocking short usage unless this observation authorizes replacement;
+ * the returned snapshot contains quota fields only, without the transient replacement marker.
+ */
 function mergeAccountQuota(
-  quota: Omit<StoredAccountQuota, "updatedAt">,
+  quota: MainPolicyQuotaObservation,
   existing: StoredAccountQuota | undefined,
   updatedAt: number,
   policyEvidence = false,
@@ -377,7 +394,7 @@ function mergeAccountQuota(
     }
     if (quota.shortResetAt !== undefined) next.shortResetAt = quota.shortResetAt;
     if (quota.shortWindowSeconds !== undefined) next.shortWindowSeconds = quota.shortWindowSeconds;
-  } else {
+  } else if (!policyEvidence || quota.shortWindowAbsent !== true) {
     // Unknown usage is not a lower reading. Retain the entire known tuple: pairing
     // its percentage with new metadata would silently extend or shorten its reset.
     // An elapsed reset is the exception. It describes a window that has already rolled over,
@@ -793,13 +810,38 @@ function filterMainPolicyMonthlyQuota(
   return hasKnownQuotaValue(filtered) || filtered.resetCredits !== undefined ? filtered : null;
 }
 
-/** Ordinary main policy rejects an entire message containing any invalid numeric window. */
-export function parseMainPolicyUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuota, "updatedAt"> | null {
+/**
+ * Parse ordinary main-policy usage, rejecting messages with invalid numeric window percentages.
+ * Mark a valid primary of at least 24h as replacement evidence only when both other windows
+ * are explicitly null or at least 24h. A null result supplies no usable policy observation.
+ */
+export function parseMainPolicyUsageQuota(data: WhamUsageResponse): MainPolicyQuotaObservation | null {
   const windows = [data.rate_limit?.primary_window, data.rate_limit?.secondary_window, data.rate_limit?.tertiary_window];
   if (windows.some(window => isInvalidPolicyUsagePercent(window?.used_percent))) return null;
-  return filterMainPolicyMonthlyQuota(parseUsageQuota(data), isThirtyDayOnlyCodexPlan(data.plan_type));
+  const quota = filterMainPolicyMonthlyQuota(parseUsageQuota(data), isThirtyDayOnlyCodexPlan(data.plan_type));
+  const [primary, secondary, tertiary] = windows;
+  // WHAM explicitly reports absent windows as null; omissions cannot prove replacement.
+  // Policy trusts one complete snapshot only when every non-null window is >=24h AND
+  // carries a valid usage reading: a long window without used_percent leaves that
+  // window's usage unknown, and unknown usage must never release a block.
+  // Headers never supply this proof, and reset time alone still cannot release a block.
+  if (quota && normalizeUsagePercent(primary?.used_percent) !== undefined && isExplicitLongWindow(primary)
+    && (secondary === null || isMeasuredLongWindow(secondary))
+    && (tertiary === null || isMeasuredLongWindow(tertiary))) {
+    return { ...quota, shortWindowAbsent: true };
+  }
+  return quota;
 }
 
+function isMeasuredLongWindow(window: WhamUsageWindow | null | undefined): boolean {
+  return isExplicitLongWindow(window) && normalizeUsagePercent(window?.used_percent) !== undefined;
+}
+
+/**
+ * Normalize WHAM windows into the display snapshot, preserving declared short-window shape.
+ * Finite percentages are clamped for compatibility; policy callers must validate raw readings
+ * separately. Return null when neither a quota value/window nor reset credits are available.
+ */
 export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuota, "updatedAt"> | null {
   const resetCredits = typeof data.rate_limit_reset_credits?.available_count === "number"
     ? data.rate_limit_reset_credits.available_count

package/src/codex/runtime.ts

@@ -4,6 +4,7 @@ import { homedir, tmpdir } from "node:os";
 import { delimiter, join } from "node:path";
 import { atomicWriteFile, getConfigDir } from "../config";
 import { codexExecInvocation, isSpawnableCodexCandidate } from "./exec-invocation";
+import { resolveCodexHomeDir } from "./home";
 import { redactSecretString, redactUserPath } from "../lib/redact";
 
 export type CodexRuntimeSource =
@@ -508,16 +509,13 @@ function pathCandidates(deps: ResolveCodexRuntimeDeps): string[] {
 function installedCodexCandidates(deps: ResolveCodexRuntimeDeps): string[] {
   const platform = deps.platform ?? process.platform;
   const env = deps.env ?? process.env;
-  if (platform === "win32") {
-    const localAppData = env.LOCALAPPDATA?.trim();
-    if (!localAppData) return [];
-    const root = join(localAppData, "OpenAI", "Codex", "bin");
-    const readDir = deps.readdirSync ?? ((path: string) => readdirSync(path));
-    const stat = deps.statSync ?? ((path: string) => statSync(path));
+  const readDir = deps.readdirSync ?? ((path: string) => readdirSync(path));
+  const stat = deps.statSync ?? ((path: string) => statSync(path));
+  /** Version directories directly under root, newest first; unreadable roots yield nothing. */
+  const versionDirectories = (root: string): string[] => {
     try {
-      const names = readDir(root);
       const dirs: Array<{ name: string; directory: string; mtimeMs: number }> = [];
-      for (const name of names) {
+      for (const name of readDir(root)) {
         const directory = join(root, name);
         try {
           const st = stat(directory);
@@ -528,18 +526,39 @@ function installedCodexCandidates(deps: ResolveCodexRuntimeDeps): string[] {
         }
       }
       dirs.sort((a, b) => b.mtimeMs - a.mtimeMs || a.name.localeCompare(b.name));
-      return dirs.map(entry => join(entry.directory, "codex.exe"));
+      return dirs.map(entry => entry.directory);
     } catch {
       return [];
     }
+  };
+  if (platform === "win32") {
+    const localAppData = env.LOCALAPPDATA?.trim();
+    if (!localAppData) return [];
+    return versionDirectories(join(localAppData, "OpenAI", "Codex", "bin"))
+      .map(directory => join(directory, "codex.exe"));
   }
   const home = env.HOME?.trim() || env.USERPROFILE?.trim() || homedir();
-  return [
+  const posix = [
     join(home, ".codex", "packages", "standalone", "current", "bin", "codex"),
     join(home, ".local", "bin", "codex"),
     "/usr/local/bin/codex",
     "/opt/homebrew/bin/codex",
   ];
+  if (platform !== "linux") return posix;
+  // Windows Codex Desktop in WSL app-server mode ships its Linux binary under the
+  // effective Codex home as bin/wsl/<version-hash>/codex, and a Desktop update replaces
+  // that hash directory. The service PATH usually has no codex (issue 5635), so these
+  // rank after PATH and the ordinary locations and are re-enumerated on every resolve
+  // rather than trusted from a remembered hash.
+  let codexHome: string;
+  try {
+    codexHome = resolveCodexHomeDir({ env });
+  } catch {
+    return posix;
+  }
+  const desktopWsl = versionDirectories(join(codexHome, "bin", "wsl"))
+    .map(directory => join(directory, "codex"));
+  return [...posix, ...desktopWsl];
 }
 
 interface RankedCandidate {
@@ -735,6 +754,8 @@ function resolveCacheKey(deps: ResolveCodexRuntimeDeps): string | null {
     localAppData: env.LOCALAPPDATA?.trim() ?? "",
     homeDir: env.HOME?.trim() ?? "",
     userProfile: env.USERPROFILE?.trim() ?? "",
+    // Linux discovery enumerates <CODEX_HOME>/bin/wsl, so the home is part of the key.
+    codexHome: env.CODEX_HOME?.trim() ?? "",
     home: process.env.OPENCODEX_HOME ?? "",
     persisted: persistedRuntimeCacheStamp(deps),
   });

package/src/combos/failover.ts

@@ -15,6 +15,7 @@ interface TargetCooldown {
 
 const DEFAULT_COOLDOWN_MS = 60_000;
 const MAX_COOLDOWN_MS = 10 * 60_000;
+const MAX_SERVER_DELAY_MS = 24 * 60 * 60_000;
 /** Short cooldown for request-rate 429s (for example provider code 1302) that omit Retry-After. */
 export const COMBO_REQUEST_RATE_COOLDOWN_MS = 5_000;
 
@@ -115,6 +116,7 @@ function parseHttpDate(value: string, now: number): number | undefined {
   );
 }
 
+/** Parse a Retry-After delay, optionally retaining an upstream delay up to one day. */
 export function parseRetryAfterMs(
   value: string | null | undefined,
   now = Date.now(),
@@ -122,11 +124,10 @@ export function parseRetryAfterMs(
 ): number | undefined {
   const text = value?.trim();
   if (!text) return undefined;
-  // A local wait ceiling must not make an explicit upstream reset expire early.
-  // Keep legacy bounded parsing for other callers. The opt-in stores a timestamp;
-  // the combo picker still independently limits how long a live request waits.
+  // Keep legacy bounded parsing for other callers. Combo cooldowns preserve
+  // multi-hour upstream delays, but never quarantine a target beyond one day.
   const maximum = options?.preserveServerDelay === true
-    ? Number.MAX_SAFE_INTEGER - Math.max(0, now)
+    ? MAX_SERVER_DELAY_MS
     : MAX_COOLDOWN_MS;
   if (/^\d+(?:\.\d+)?$/.test(text)) {
     const seconds = Number(text);
@@ -200,6 +201,7 @@ export function comboCooldownRetryAfterSeconds(comboId: string, now = Date.now()
   return String(Math.max(1, Math.ceil(remainingMs / 1000)));
 }
 
+/** Record a combo target cooldown, preferring bounded upstream retry evidence. */
 export function coolComboTarget(
   comboId: string,
   target: Pick<OcxComboTarget, "provider" | "model">,
@@ -234,8 +236,7 @@ export function coolComboTarget(
       message: options?.message,
     }) ? COMBO_REQUEST_RATE_COOLDOWN_MS : DEFAULT_COOLDOWN_MS);
   targetCooldowns.set(cooldownMapKey(comboId, target), {
-    // Only the locally chosen fallback is capped at ten minutes. An explicit
-    // server lower bound (including one hour) remains authoritative.
+    // Local fallbacks are capped at ten minutes; explicit server delays at one day.
     cooldownUntil: now + (serverDelayMs ?? Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS)),
   });
   sweepExpiredOnWrite(now);

package/src/combos/resolve.ts

@@ -359,11 +359,19 @@ export function advanceComboAfterFailure(
       });
     }
   }
+  // #5691: under `cooldownWaitPolicy: "before-last-resort"` this final synchronous pick
+  // must not dispatch an emergency target while a normal one is merely cooling. Returning
+  // null hands the decision to `pickComboTargetWithWait`, which waits a normal target out
+  // inside the combo's wait budget or dispatches the last resort when none is reachable.
+  // Without the policy the eligible set is unchanged and the pick is exactly as before.
+  const defersLastResort = combo?.cooldownWaitPolicy === "before-last-resort"
+    && combo.targets.some(target => !target.lastResort);
   return pickComboTarget(config, pick.comboId, {
     exclude: pick.attempted,
     now: options.now,
     eligible: target => !isComboTargetInCooldown(pick.comboId, target, options.now)
-      && (options.eligible?.(target) ?? true),
+      && (options.eligible?.(target) ?? true)
+      && (!defersLastResort || !target.lastResort),
   });
 }
 
@@ -382,23 +390,94 @@ export async function pickComboTargetWithWait(
   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)
+  const eligibleAt = (target: Required<OcxComboTarget>, at: number): boolean =>
+    !isComboTargetInCooldown(comboId, target, at)
     && (customEligible?.(target) ?? true);
-  const pick = pickComboTarget(config, comboId, { exclude: excluded, eligible, now });
-  if (pick || options.waitForCooldownMs <= 0 || options.abortSignal?.aborted) return pick;
+  const eligible = (target: Required<OcxComboTarget>): boolean => eligibleAt(target, now);
+  // Milliseconds already slept inside this call. `waitForCooldownMs` is documented as a cap
+  // per *selection attempt*, so a deferral wait and the ordinary wait below must share it —
+  // otherwise a 3s deferral followed by a 9s ordinary wait spends 12s against a 10s budget.
+  let spentWaitMs = 0;
+
+  // #5691: `cooldownWaitPolicy: "before-last-resort"` makes one extra attempt
+  // over the normal targets alone, so a *brief* cooldown on a preferred target
+  // waits rather than dispatching a target the operator marked emergency-only.
+  //
+  // It only ever defers. Every exit below falls through to the unchanged
+  // selection, which still sees the last-resort target — a policy that could
+  // withhold it when no normal target is reachable would turn a fallback into
+  // an outage, which is worse than the premature routing it prevents.
+  const policyCombo = getCombo(config, comboId);
+  const defersLastResort = policyCombo?.cooldownWaitPolicy === "before-last-resort"
+    && policyCombo.targets.some(target => !target.lastResort);
+  if (defersLastResort && !options.abortSignal?.aborted) {
+    const normalOnly = (target: Required<OcxComboTarget>): boolean =>
+      !target.lastResort && eligible(target);
+    const normalPick = pickComboTarget(config, comboId, {
+      exclude: excluded,
+      eligible: normalOnly,
+      now,
+    });
+    if (normalPick) return normalPick;
+
+    const waitable = policyCombo.targets.filter(target =>
+      !target.lastResort
+      && targetProviderIsUsable(config, target, now)
+      && !excluded.has(targetKey(target))
+      && isComboTargetInCooldown(comboId, target, now)
+      && (customEligible?.(target) ?? true),
+    );
+    const soonest = earliestComboCooldown(comboId, waitable, now);
+    const normalDelay = soonest === undefined ? undefined : soonest.expiry - now;
+    if (normalDelay !== undefined && normalDelay <= options.waitForCooldownMs) {
+      console.warn(
+        `[combo] ${comboId}: deferring last resort, waiting ${normalDelay}ms for ${targetKey(soonest!.target)}`,
+      );
+      try {
+        await (options.sleep ?? sleepWithAbort)(normalDelay, options.abortSignal);
+      } catch (error) {
+        if (options.abortSignal?.aborted) return null;
+        throw error;
+      }
+      spentWaitMs += normalDelay;
+      if (options.abortSignal?.aborted) return null;
+      // The combo can be deleted or renamed while this request sleeps.
+      if (!getCombo(config, comboId)) return null;
+      const waited = pickComboTarget(config, comboId, {
+        exclude: excluded,
+        now: now + normalDelay,
+        eligible: target => !target.lastResort
+          && !isComboTargetInCooldown(comboId, target, now + normalDelay)
+          && (customEligible?.(target) ?? true),
+      });
+      if (waited) return waited;
+    }
+    // No normal target is reachable. Fall through; the last resort is eligible.
+  }
+
+  // Both advance when the deferral above slept; they are identical to `now` and
+  // `options.waitForCooldownMs` when it did not, so the non-policy path is unchanged.
+  const clock = now + spentWaitMs;
+  const remainingWaitMs = options.waitForCooldownMs - spentWaitMs;
+
+  const pick = pickComboTarget(config, comboId, {
+    exclude: excluded,
+    eligible: target => eligibleAt(target, clock),
+    now: clock,
+  });
+  if (pick || remainingWaitMs <= 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, now)
+    targetProviderIsUsable(config, target, clock)
     && !excluded.has(targetKey(target))
-    && isComboTargetInCooldown(comboId, target, now)
+    && isComboTargetInCooldown(comboId, target, clock)
     && (customEligible?.(target) ?? true),
   );
-  const earliest = earliestComboCooldown(comboId, waitingTargets, now);
+  const earliest = earliestComboCooldown(comboId, waitingTargets, clock);
   if (earliest === undefined) return null;
-  const delay = earliest.expiry - now;
-  if (delay > options.waitForCooldownMs) return null;
+  const delay = earliest.expiry - clock;
+  if (delay > remainingWaitMs) 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;
@@ -416,10 +495,8 @@ export async function pickComboTargetWithWait(
   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),
+    now: clock + delay,
+    eligible: targetCandidate => eligibleAt(targetCandidate, clock + delay),
   });
 }
 

package/src/combos/types.ts

@@ -1,6 +1,6 @@
 import { isCodexReasoningEffort } from "../reasoning-effort";
 import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../codex/catalog/native-models";
-import type { OcxComboConfig, OcxComboDefaultEffort, OcxComboDefaultEffortMode, OcxComboReasoningEffortMode, OcxComboStrategy, OcxComboTarget, OcxProviderConfig } from "../types";
+import type { OcxComboConfig, OcxComboCooldownWaitPolicy, OcxComboDefaultEffort, OcxComboDefaultEffortMode, OcxComboReasoningEffortMode, OcxComboStrategy, OcxComboTarget, OcxProviderConfig } from "../types";
 import { COMBO_NAMESPACE, isValidComboId, targetKey } from "./identifiers";
 
 export const COMBO_DEFAULT_WAIT_FOR_COOLDOWN_MS = 0;
@@ -25,6 +25,8 @@ export interface NormalizedComboConfig {
   stickyLimit: number;
   cooldownMs?: number;
   waitForCooldownMs: number;
+  /** `before-last-resort` defers lastResort targets while a normal one can be waited out (#5691). */
+  cooldownWaitPolicy: OcxComboCooldownWaitPolicy | null;
   defaultEffort: OcxComboDefaultEffort | null;
   /** Client-precedence policy; `fallback` preserves legacy behavior. */
   defaultEffortMode: OcxComboDefaultEffortMode;
@@ -161,6 +163,13 @@ export function comboConfigIssues(
       || body.waitForCooldownMs > 600_000)) {
     issues.push({ path: ["waitForCooldownMs"], message: "waitForCooldownMs must be an integer from 0 to 600000" });
   }
+  if (body.cooldownWaitPolicy !== undefined && body.cooldownWaitPolicy !== null
+    && body.cooldownWaitPolicy !== "before-last-resort") {
+    issues.push({
+      path: ["cooldownWaitPolicy"],
+      message: 'cooldownWaitPolicy must be "before-last-resort" when set',
+    });
+  }
   if (body.defaultEffort !== undefined
     && body.defaultEffort !== null
     && (typeof body.defaultEffort !== "string" || !isCodexReasoningEffort(body.defaultEffort))) {
@@ -277,6 +286,12 @@ export function comboConfigIssues(
         message: `targets[${i}].weight must be an integer from 1 to 10000`,
       });
     }
+    if (target.lastResort !== undefined && typeof target.lastResort !== "boolean") {
+      issues.push({
+        path: ["targets", i, "lastResort"],
+        message: `targets[${i}].lastResort must be a boolean`,
+      });
+    }
 
     if (provider && model) {
       const key = targetKey({ provider, model });
@@ -318,6 +333,7 @@ export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig
     stickyLimit: raw.stickyLimit ?? 1,
     cooldownMs: raw.cooldownMs,
     waitForCooldownMs: raw.waitForCooldownMs ?? COMBO_DEFAULT_WAIT_FOR_COOLDOWN_MS,
+    cooldownWaitPolicy: raw.cooldownWaitPolicy === "before-last-resort" ? "before-last-resort" : null,
     defaultEffort,
     defaultEffortMode: raw.defaultEffortMode === "force" && defaultEffort !== null ? "force" : "fallback",
     reasoningEffortMode: raw.reasoningEffortMode === "adaptive" ? "adaptive" : "strict",
@@ -329,6 +345,7 @@ export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig
       provider: target.provider.trim(),
       model: target.model.trim(),
       weight: target.weight ?? 1,
+      lastResort: target.lastResort === true,
     })),
   };
 }

package/src/config/load-degrade.ts

@@ -16,6 +16,7 @@ import { isValidProviderName } from "./provider-name";
 import { MODEL_ALIAS_PATTERN } from "../providers/default-aliases";
 import { MODEL_DISCOVERY_MAX_MODELS } from "../providers/model-discovery-limits";
 import { getProviderRegistryEntry, providerMatchesRegistryTransport, registryModelServiceTierCapabilityApplies } from "../providers/registry";
+import { providerFastSwitchOff } from "../providers/fast-opt-in";
 import { isCodexReasoningEffort } from "../reasoning-effort";
 import { refreshConfigDerivedRegistries } from "./derived-registries";
 import { type OcxClaudeCodeConfig, type OcxConfig } from "../types";
@@ -835,6 +836,7 @@ export function inheritedFastWireConflictProviderNames(
   const conflicts: string[] = [];
   for (const [name, provider] of Object.entries(config.providers)) {
     if (provider.fastWire !== null || provider.supportsServiceTier === false) continue;
+    if (providerFastSwitchOff(name, provider)) continue;
     const registry = providerMatchesRegistryTransport(name, provider)
       ? getProviderRegistryEntry(name)
       : undefined;

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

@@ -60,6 +60,7 @@ import { OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
 import { modelAutoCompactTokenLimitsConfigError } from "../../providers/auto-compact-budget";
 import { hasFastWireCapabilityConflict } from "../../providers/fastwire";
 import { parseDesktopProfile } from "../../claude/desktop-profile";
+import { isInterceptBindingId, isInterceptBindingRoute } from "../../claude/intercept/model-bindings";
 import { DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES, MAX_APP_OWNED_MEMORY_BUDGET_MB, MIN_APP_OWNED_MEMORY_BUDGET_MB } from "../../lib/app-owned-memory";
 
 export const configSchema = z.object({
@@ -148,7 +149,9 @@ export const configSchema = z.object({
   // Ultra Fast is opt-in for the same reason and degrades the same way: a malformed hand
   // edit turns the tier off rather than rejecting the config that carries it.
   ultraFastTier: z.boolean().optional().catch(false),
-  codexMainAccountHardLock: z.boolean().optional().catch(false),
+  // Default-on policy (#5694): absence and malformed hand edits both mean "on", and only an
+  // explicit `false` written by the settings PUT opts out.
+  codexMainAccountHardLock: z.boolean().optional().catch(undefined),
   // Future versions remain opaque through passthrough-compatible whole-config saves.
   // Only version 1 grants deletion authority in the rebase path.
   configRebaseProvenance: z.unknown().optional(),
@@ -284,13 +287,29 @@ export const configSchema = z.object({
       if (!intercept || typeof intercept !== "object" || Array.isArray(intercept)) {
         ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept"], message: "intercept must be an object" });
       } else {
-        const { enabled, port } = intercept as { enabled?: unknown; port?: unknown };
+        const { enabled, port, picker, modelMap } = intercept as { enabled?: unknown; port?: unknown; picker?: unknown; modelMap?: unknown };
         if (enabled !== undefined && typeof enabled !== "boolean") {
           ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "enabled"], message: "intercept.enabled must be a boolean" });
         }
+        if (picker !== undefined && typeof picker !== "boolean") {
+          ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "picker"], message: "intercept.picker must be a boolean" });
+        }
         if (port !== undefined && (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535)) {
           ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "port"], message: "intercept.port must be an integer between 1 and 65535" });
         }
+        if (modelMap !== undefined) {
+          if (!modelMap || typeof modelMap !== "object" || Array.isArray(modelMap)) {
+            ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "modelMap"], message: "intercept.modelMap must be an object of picker id to route" });
+          } else {
+            for (const [id, route] of Object.entries(modelMap as Record<string, unknown>)) {
+              if (!isInterceptBindingId(id)) {
+                ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "modelMap", id], message: "intercept.modelMap keys must be claude- picker model ids" });
+              } else if (!isInterceptBindingRoute(route)) {
+                ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "modelMap", id], message: "intercept.modelMap values must be non-empty routes without whitespace" });
+              }
+            }
+          }
+        }
       }
     }
     if (claude.desktopProfile !== undefined) {

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

@@ -292,6 +292,7 @@ export const providerConfigSchema = z.object({
   annotateEmptyToolOutputs: z.boolean().optional(),
   foldDeveloperRoleToSystem: z.boolean().optional(),
   fastWire: fastWireSchema.nullable().optional(),
+  fastEnabled: z.boolean().optional(),
   supportsServiceTier: z.boolean().optional(),
   modelSupportsServiceTier: z.record(z.string().min(1), z.boolean()).optional(),
   modelSuppressSyntheticMax: z.record(z.string().min(1), z.boolean()).optional(),
@@ -311,9 +312,11 @@ export const providerConfigSchema = z.object({
   upstreamHttpVersion: z.enum(UPSTREAM_HTTP_VERSION_VALUES)
     .nullish()
     .transform(value => value ?? undefined),
-  // Opt-in upstream Responses WebSocket for OpenAI-compatible providers (e.g.
-  // aggregators whose WebSocket ingress is measurably faster than SSE). The
-  // canonical ChatGPT backend WS selection is independent of this flag.
+  // Opt-in upstream Responses WebSocket for OpenAI-compatible providers, honored only
+  // for the first-party api.openai.com/v1 upstream; other custom endpoints stay on
+  // bounded HTTP/SSE. On the canonical ChatGPT `openai` provider the same field selects
+  // the transport: omitted keeps the upstream WebSocket on eligible turns, explicit
+  // `false` sends streaming turns over HTTP/SSE, and provider management rejects `true`.
   upstreamWebsocket: z.boolean().optional(),
   directGeminiWireRenames: z.boolean().optional(),
   googleToolSchemaPolicy: z.enum(["compatible", "reject-lossy"]).optional(),