@bitkyc08/opencodex 2.10.0 → 2.10.1

package/src/codex/routing.ts

@@ -3,7 +3,7 @@ import { saveConfigPreservingClaudeCode } from "../config";
 import { isCodexAccountGenerationLive, readCodexAccountRecord } from "./account-store";
 import { codexAccountLogLabel } from "./account-label";
 import { isCodexAccountPaused } from "./account-pause";
-import { isCodexAccountUsable } from "./account-usability";
+import { isCodexAccountUsable, type CodexAccountUsabilityOptions } from "./account-usability";
 import { isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
 import {
   POOL_KEY_CODEX,
@@ -22,6 +22,7 @@ import type { OcxConfig } from "../types";
 import { captureConfigGeneration, type GenerationContext } from "../lib/state-store-sweeper";
 import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
 import { retainedUtf8Bytes } from "../lib/admission";
+import { recordUpstreamHostFailure } from "./upstream-host-health";
 
 type ThreadAffinityEntry = {
   accountId: string;
@@ -122,8 +123,8 @@ const quotaScopedHealth = new Map<string, Map<CodexQuotaScope, CodexUpstreamHeal
 let lastReconciledGeneration = 0;
 let liveHealthAccountIds = new Set<string>();
 
-export type CodexUpstreamOutcome = number | "connect_error" | "timeout";
-export type CodexUpstreamOutcomeClass = "success" | "credential" | "quota" | "transient" | "caller" | "unknown";
+export type CodexUpstreamOutcome = number | "connect_error" | "timeout" | "connect_neutral";
+export type CodexUpstreamOutcomeClass = "success" | "credential" | "quota" | "transient" | "caller" | "neutral" | "unknown";
 export type CodexCooldownSource = "retry-after" | "reset-derived" | "default";
 /**
  * Native Codex quota groups known to be independent upstream. Keep the mapping
@@ -133,6 +134,20 @@ export type CodexCooldownSource = "retry-after" | "reset-derived" | "default";
  */
 export type CodexQuotaScope = "shared" | "spark";
 
+export type CodexQuotaRecoveryProbeClaim = {
+  accountId: string;
+  scope?: CodexQuotaScope;
+  leaseId: string;
+  cooldownGeneration: number;
+  credentialGeneration: number;
+  /** Claim-time `replacedAt`; unchanged after a probe-owned refresh, stamped on external replacement. */
+  credentialReplacedAt?: number;
+};
+
+export type CodexQuotaRecoveryProbeProof = {
+  credentialGeneration?: number;
+};
+
 /**
  * Requests without a resolved native model retain the historic one-account-per-
  * thread behavior. Requests with a known quota scope get an independent
@@ -173,10 +188,20 @@ export type CodexUpstreamOutcomeMeta = {
   retryAfter?: string | null;
   resetAt?: unknown | unknown[];
   now?: number;
+  /** (provider, host) ledger key for account-neutral reachability failures (#914). */
+  hostKey?: string;
+  /** Stable transport code recorded alongside a neutral host failure. */
+  lastFailureCode?: string;
   /** Native model selected for this request; used only for confirmed scoped quotas. */
   modelId?: string;
   /** When set, clears affinity for this thread immediately on transient failure. */
   threadId?: string | null;
+  /**
+   * Suppress Pool rotation and quota/transient affinity mutations for an account-qualified
+   * request. Credential failures still sweep stale affinities because reauthentication is
+   * account-wide.
+   */
+  fixedAccount?: boolean;
   /**
    * Probe lease held by this request, when it was admitted through an active
    * quota cooldown. Only the outcome carrying the current lease may clear the
@@ -195,8 +220,14 @@ export type CodexUpstreamOutcomeMeta = {
   writerGeneration?: number;
 };
 
-function hasConfiguredPoolAccount(config: OcxConfig, accountId: string): boolean {
-  if (accountId === MAIN_CODEX_ACCOUNT_ID) return isCodexAccountUsable(config, accountId);
+function hasConfiguredPoolAccount(
+  config: OcxConfig,
+  accountId: string,
+  selectionOptions?: CodexAccountUsabilityOptions,
+): boolean {
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) {
+    return isCodexAccountUsable(config, accountId, selectionOptions);
+  }
   return (config.codexAccounts ?? [])
     .some(account => isSelectableCodexPoolAccount(account) && account.id === accountId);
 }
@@ -295,9 +326,15 @@ export function computeCodexUsageScore(quota: {
 }
 
 export function classifyCodexUpstreamOutcome(outcome: CodexUpstreamOutcome): CodexUpstreamOutcomeClass {
+  if (outcome === "connect_neutral") return "neutral";
   if (outcome === "connect_error" || outcome === "timeout") return "transient";
   if (!Number.isFinite(outcome)) return "unknown";
   if (outcome >= 200 && outcome < 300) return "success";
+  // Explicit 3xx policy (#914): a redirect response is relayed as-is and is
+  // never account or host health evidence — it proves the host is reachable
+  // and says nothing about the credential. Relayed as the neutral class so a
+  // stray 3xx cannot increment an account's transient streak.
+  if (outcome >= 300 && outcome < 400) return "neutral";
   if (outcome === 401 || outcome === 403) return "credential";
   // 402 Payment Required is treated as quota exhaustion for pool cooldown/failover
   // (same-request alternate retry records this outcome for the depleted account).
@@ -405,6 +442,135 @@ function canAcquireQuotaProbeLease(health: CodexUpstreamHealth | undefined, now:
   return now - origin >= CODEX_QUOTA_PROBE_INTERVAL_MS;
 }
 
+/**
+ * Claim due reset-derived cooldown probes without consulting account selection.
+ * Pool credentials only: the main account has no quota-refresh single-flight.
+ */
+export function claimDueCodexQuotaRecoveryProbes(
+  config: OcxConfig,
+  limit: number,
+  now = Date.now(),
+): CodexQuotaRecoveryProbeClaim[] {
+  const boundedLimit = Math.max(0, Math.floor(limit));
+  if (boundedLimit === 0) return [];
+  const candidates: Array<{
+    accountId: string;
+    scope?: CodexQuotaScope;
+    health: CodexUpstreamHealth;
+    credentialGeneration: number;
+    credentialReplacedAt?: number;
+    order: number;
+  }> = [];
+  for (const [order, account] of (config.codexAccounts ?? []).entries()) {
+    if (!isSelectableCodexPoolAccount(account)
+      || isCodexAccountPaused(config, account.id)
+      || isAccountNeedsReauth(account.id)) continue;
+    const record = readCodexAccountRecord(account.id);
+    if (!record?.credential || record.deletedAt != null) continue;
+    const due = [
+      { scope: undefined, health: upstreamHealth.get(account.id) },
+      ...[...(quotaScopedHealth.get(account.id) ?? [])].map(([scope, health]) => ({ scope, health })),
+    ].filter((entry): entry is { scope?: CodexQuotaScope; health: CodexUpstreamHealth } =>
+      // `spark` is deliberately never claimed. `GET /backend-api/wham/usage` takes no scope
+      // parameter and returns generic weekly/monthly windows, so its result can never prove a
+      // spark recovery — a claim here would spend an upstream call to settle `false` every
+      // time, and (with one claim per account per pass) delay the shared scope that CAN recover.
+      entry.scope !== "spark"
+      && entry.health?.cooldownSource === "reset-derived"
+      && canAcquireQuotaProbeLease(entry.health, now))
+      .sort((a, b) =>
+        (a.health.lastProbeAt ?? a.health.cooldownSince ?? 0)
+        - (b.health.lastProbeAt ?? b.health.cooldownSince ?? 0));
+    const candidate = due[0];
+    if (candidate) candidates.push({
+      accountId: account.id,
+      ...(candidate.scope ? { scope: candidate.scope } : {}),
+      health: candidate.health,
+      credentialGeneration: record.generation,
+      ...(record.replacedAt !== undefined ? { credentialReplacedAt: record.replacedAt } : {}),
+      order,
+    });
+  }
+  candidates.sort((a, b) => {
+    const age = (a.health.lastProbeAt ?? a.health.cooldownSince ?? 0)
+      - (b.health.lastProbeAt ?? b.health.cooldownSince ?? 0);
+    return age || a.order - b.order;
+  });
+  return candidates.slice(0, boundedLimit).map(candidate => {
+    const leaseId = randomUUID();
+    const next = {
+      ...candidate.health,
+      probeLeaseId: leaseId,
+      probeLeaseGeneration: candidate.health.cooldownGeneration ?? 0,
+      lastProbeAt: now,
+    };
+    if (candidate.scope) setScopedHealth(candidate.accountId, candidate.scope, next);
+    else upstreamHealth.set(candidate.accountId, next);
+    return {
+      accountId: candidate.accountId,
+      ...(candidate.scope ? { scope: candidate.scope } : {}),
+      leaseId,
+      cooldownGeneration: candidate.health.cooldownGeneration ?? 0,
+      credentialGeneration: candidate.credentialGeneration,
+      ...(candidate.credentialReplacedAt !== undefined
+        ? { credentialReplacedAt: candidate.credentialReplacedAt }
+        : {}),
+    };
+  });
+}
+
+/** Settle one background recovery claim without mutating account-wide outcome state. */
+export function settleCodexQuotaRecoveryProbe(
+  claim: CodexQuotaRecoveryProbeClaim,
+  recovered: boolean,
+  proof: CodexQuotaRecoveryProbeProof,
+  now = Date.now(),
+): boolean {
+  const health = claim.scope
+    ? scopedHealthFor(claim.accountId, claim.scope)
+    : upstreamHealth.get(claim.accountId);
+  if (!health || health.probeLeaseId !== claim.leaseId) return false;
+  const currentRecord = readCodexAccountRecord(claim.accountId);
+  const proofGeneration = proof.credentialGeneration;
+  // A probe-owned token refresh (getValidCodexToken) advances the credential generation by
+  // exactly one while preserving `replacedAt`; an external credential replacement bumps the
+  // generation too but stamps a fresh `replacedAt`. Accept the +1 transition only when the
+  // claim-time lineage is intact AND the generation the fresh quota was proven under is live.
+  const generationFenced = proofGeneration !== undefined
+    && (proofGeneration === claim.credentialGeneration
+      ? isCodexAccountGenerationLive(claim.accountId, proofGeneration)
+      : proofGeneration === claim.credentialGeneration + 1
+        && currentRecord?.replacedAt === claim.credentialReplacedAt
+        && isCodexAccountGenerationLive(claim.accountId, proofGeneration));
+  const fenced = (health.cooldownGeneration ?? 0) === claim.cooldownGeneration
+    && (health.probeLeaseGeneration ?? 0) === claim.cooldownGeneration
+    && generationFenced;
+  if (!recovered || !fenced) {
+    const released = withProbeLeaseReleased(health, now);
+    if (claim.scope) setScopedHealth(claim.accountId, claim.scope, released);
+    else upstreamHealth.set(claim.accountId, released);
+    return false;
+  }
+  if (claim.scope) {
+    deleteScopedHealth(claim.accountId, claim.scope);
+  } else {
+    const {
+      cooldownUntil: _until,
+      cooldownSince: _since,
+      cooldownSource: _source,
+      probeLeaseId: _leaseId,
+      probeLeaseGeneration: _leaseGeneration,
+      ...rest
+    } = health;
+    upstreamHealth.set(claim.accountId, {
+      ...rest,
+      cooldownGeneration: claim.cooldownGeneration + 1,
+      lastProbeAt: now,
+    });
+  }
+  return true;
+}
+
 /** Acquire the recovery probe for one confirmed model-specific quota group. */
 export function tryAcquireCodexQuotaScopeProbeLease(
   accountId: string,
@@ -624,11 +790,12 @@ function isCodexAccountSelectable(
   accountId: string,
   now: number,
   quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
 ): boolean {
   return !isCodexAccountPaused(config, accountId)
     && getCodexQuotaHealthSnapshot(accountId, quotaScope, now) === null
     && !isCodexAccountSoftAvoided(accountId, now)
-    && isCodexAccountUsable(config, accountId);
+    && isCodexAccountUsable(config, accountId, selectionOptions);
 }
 
 function threadAffinityScope(quotaScope?: CodexQuotaScope): ThreadAffinityScope {
@@ -736,6 +903,7 @@ function getEligiblePoolAccounts(
   excludeId?: string,
   now = Date.now(),
   quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
 ): string[] {
   const ids = (config.codexAccounts ?? [])
     .filter(account => isSelectableCodexPoolAccount(account)
@@ -744,7 +912,7 @@ function getEligiblePoolAccounts(
       && !isAccountNeedsReauth(account.id))
     .filter(account => getCodexQuotaHealthSnapshot(account.id, quotaScope, now) === null)
     .filter(account => !isCodexAccountSoftAvoided(account.id, now))
-    .filter(account => isCodexAccountUsable(config, account.id))
+    .filter(account => isCodexAccountUsable(config, account.id, selectionOptions))
     .map(account => account.id);
   // The main Codex account is not stored in config.codexAccounts; include it as a
   // first-class rotation candidate when its read-only token is usable (Option A).
@@ -754,7 +922,7 @@ function getEligiblePoolAccounts(
     && !isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)
     && getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope, now) === null
     && !isCodexAccountSoftAvoided(MAIN_CODEX_ACCOUNT_ID, now)
-    && isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID)
+    && isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID, selectionOptions)
   ) {
     ids.unshift(MAIN_CODEX_ACCOUNT_ID);
   }
@@ -765,8 +933,9 @@ function listEligibleCodexAccountIds(
   config: OcxConfig,
   now: number,
   quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
 ): string[] {
-  return getEligiblePoolAccounts(config, undefined, now, quotaScope);
+  return getEligiblePoolAccounts(config, undefined, now, quotaScope, selectionOptions);
 }
 
 function stickyLimitForConfig(config: OcxConfig): number {
@@ -790,8 +959,9 @@ function pickFillFirstCodexAccount(
   config: OcxConfig,
   now: number,
   quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
 ): string | null {
-  const eligible = listEligibleCodexAccountIds(config, now, quotaScope);
+  const eligible = listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions);
   if (eligible.length === 0) return null;
 
   const active = getEffectiveActiveCodexAccountId(config);
@@ -799,7 +969,7 @@ function pickFillFirstCodexAccount(
     return active;
   }
 
-  return pickNextFillFirstCodexAccount(config, active ?? null, eligible, now);
+  return pickNextFillFirstCodexAccount(config, active ?? null, eligible, now, selectionOptions);
 }
 
 /** Next eligible account in stable order after `afterId` (wrapping). */
@@ -808,6 +978,7 @@ function pickNextFillFirstCodexAccount(
   afterId: string | null,
   eligible = listEligibleCodexAccountIds(config, Date.now()),
   _now = Date.now(),
+  selectionOptions?: CodexAccountUsabilityOptions,
 ): string | null {
   if (eligible.length === 0) return null;
   const ordered = [...eligible].sort((a, b) => a.localeCompare(b));
@@ -820,7 +991,7 @@ function pickNextFillFirstCodexAccount(
   }
 
   const allConfigured = [
-    ...(isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID) || afterId === MAIN_CODEX_ACCOUNT_ID
+    ...(isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID, selectionOptions) || afterId === MAIN_CODEX_ACCOUNT_ID
       ? [MAIN_CODEX_ACCOUNT_ID]
       : []),
     ...(config.codexAccounts ?? []).filter(account => !account.isMain).map(account => account.id),
@@ -866,6 +1037,7 @@ function pickUnboundStrategyAccount(
   now: number,
   commit: boolean,
   quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
 ): string | null {
   const strategy = normalizeAccountPoolStrategy(config.accountPoolStrategy);
   if (strategy === "quota") return null;
@@ -873,7 +1045,7 @@ function pickUnboundStrategyAccount(
 
   let picked: string | null = null;
   if (strategy === "round-robin") {
-    const eligible = listEligibleCodexAccountIds(config, now, quotaScope);
+    const eligible = listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions);
     const limit = stickyLimitForConfig(config);
     if (!commit) {
       return peekRoundRobinAccount(poolKey, eligible, limit);
@@ -887,7 +1059,7 @@ function pickUnboundStrategyAccount(
   }
 
   if (strategy === "fill-first") {
-    picked = pickFillFirstCodexAccount(config, now, quotaScope);
+    picked = pickFillFirstCodexAccount(config, now, quotaScope, selectionOptions);
     if (!picked) return null;
     if (commit) {
       if (!isIndependentCodexQuotaScope(quotaScope)) rememberActiveCodexAccount(config, picked);
@@ -911,10 +1083,11 @@ function pickLowerUsageAccount(
   activeUsage: number,
   now: number,
   quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
 ): string {
   let best = active;
   let bestUsage = activeUsage;
-  for (const id of getEligiblePoolAccounts(config, active, now, quotaScope)) {
+  for (const id of getEligiblePoolAccounts(config, active, now, quotaScope, selectionOptions)) {
     const usage = computeCodexUsageScore(getAccountQuota(id), getPoolAccountPlan(config, id));
     if (usage < bestUsage) {
       best = id;
@@ -929,10 +1102,11 @@ export function pickLowestUsageCodexAccount(
   excludeId?: string,
   now = Date.now(),
   quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
 ): string | null {
   let best: string | null = null;
   let bestUsage = Number.POSITIVE_INFINITY;
-  for (const id of getEligiblePoolAccounts(config, excludeId, now, quotaScope)) {
+  for (const id of getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions)) {
     const usage = computeCodexUsageScore(getAccountQuota(id), getPoolAccountPlan(config, id));
     if (usage < bestUsage) {
       best = id;
@@ -952,17 +1126,18 @@ export function pickAlternateCodexAccount(
   excludeId: string,
   now = Date.now(),
   quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
 ): string | null {
   const strategy = normalizeAccountPoolStrategy(config.accountPoolStrategy);
   if (strategy === "round-robin") {
-    const eligible = listEligibleCodexAccountIds(config, now, quotaScope).filter(id => id !== excludeId);
+    const eligible = listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions).filter(id => id !== excludeId);
     return pickRoundRobinAccount(codexPoolKeyForScope(quotaScope), eligible, stickyLimitForConfig(config));
   }
   if (strategy === "fill-first") {
-    const eligible = listEligibleCodexAccountIds(config, now, quotaScope).filter(id => id !== excludeId);
-    return pickNextFillFirstCodexAccount(config, excludeId, eligible, now);
+    const eligible = listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions).filter(id => id !== excludeId);
+    return pickNextFillFirstCodexAccount(config, excludeId, eligible, now, selectionOptions);
   }
-  return pickLowestUsageCodexAccount(config, excludeId, now, quotaScope);
+  return pickLowestUsageCodexAccount(config, excludeId, now, quotaScope, selectionOptions);
 }
 
 /** Effective active: automatic runtime cursor, else operator/persisted selection. */
@@ -1027,6 +1202,7 @@ function applyQuotaAutoSwitch(
   active: string,
   now: number,
   quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
 ): string {
   const threshold = config.autoSwitchThreshold ?? 80;
   if (threshold <= 0) return active;
@@ -1036,7 +1212,7 @@ function applyQuotaAutoSwitch(
   // 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, quotaScope);
+  const best = pickLowerUsageAccount(config, active, activeUsage, now, quotaScope, selectionOptions);
   if (best !== active) {
     if (!isIndependentCodexQuotaScope(quotaScope)) setActiveCodexAccount(config, best);
     return best;
@@ -1053,9 +1229,14 @@ function shouldFailover(config: OcxConfig, accountId: string, now: number): bool
   return !!health && health.consecutiveFailures >= threshold;
 }
 
-function applyFailureFailover(config: OcxConfig, active: string, now: number): string {
+function applyFailureFailover(
+  config: OcxConfig,
+  active: string,
+  now: number,
+  selectionOptions?: CodexAccountUsabilityOptions,
+): string {
   if (!shouldFailover(config, active, now)) return active;
-  const best = pickAlternateCodexAccount(config, active, now);
+  const best = pickAlternateCodexAccount(config, active, now, undefined, selectionOptions);
   if (best) {
     promoteActiveCodexAccount(config, best);
     return best;
@@ -1086,13 +1267,14 @@ export function previewCodexAccountForRequest(
   config: OcxConfig,
   now = Date.now(),
   quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
 ): string | null {
   const entry = threadId ? getThreadAffinity(threadId, quotaScope) : undefined;
   if (threadId && entry) {
     if (
       !isThreadAffinityExpired(entry, now)
       && isThreadAffinityGenerationLive(entry)
-      && isCodexAccountSelectable(config, entry.accountId, now, quotaScope)
+      && isCodexAccountSelectable(config, entry.accountId, now, quotaScope, selectionOptions)
       && !shouldFailover(config, entry.accountId, now)
     ) {
       // Quota strategy only: non-quota strategies keep affinity for ongoing threads
@@ -1106,7 +1288,14 @@ export function previewCodexAccountForRequest(
             getPoolAccountPlan(config, entry.accountId),
           );
           if (!isUnknownUsage(usage) && usage >= threshold) {
-            const best = pickLowerUsageAccount(config, entry.accountId, usage, now, quotaScope);
+            const best = pickLowerUsageAccount(
+              config,
+              entry.accountId,
+              usage,
+              now,
+              quotaScope,
+              selectionOptions,
+            );
             if (best !== entry.accountId) return best;
           }
         }
@@ -1116,17 +1305,27 @@ export function previewCodexAccountForRequest(
     // Stale/unusable affinity is ignored for preview (no map mutation).
   }
 
-  const strategyPick = pickUnboundStrategyAccount(config, threadId, now, false, quotaScope);
+  const strategyPick = pickUnboundStrategyAccount(
+    config,
+    threadId,
+    now,
+    false,
+    quotaScope,
+    selectionOptions,
+  );
   if (strategyPick) return strategyPick;
 
   let active = getEffectiveActiveCodexAccountId(config) ?? null;
   if (!active) {
-    return pickLowestUsageCodexAccount(config, undefined, now, quotaScope);
+    return pickLowestUsageCodexAccount(config, undefined, now, quotaScope, selectionOptions);
   }
-  if (!isCodexAccountSelectable(config, active, now, quotaScope)) {
-    const fallback = pickLowestUsageCodexAccount(config, active, now, quotaScope);
+  if (!isCodexAccountSelectable(config, active, now, quotaScope, selectionOptions)) {
+    const fallback = pickLowestUsageCodexAccount(config, active, now, quotaScope, selectionOptions);
     if (fallback) active = fallback;
-    else if (hasConfiguredPoolAccount(config, active) && !isCodexAccountPaused(config, active)) return active;
+    else if (
+      hasConfiguredPoolAccount(config, active, selectionOptions)
+      && !isCodexAccountPaused(config, active)
+    ) return active;
     else return null;
   }
 
@@ -1134,19 +1333,19 @@ export function previewCodexAccountForRequest(
   if (threshold > 0) {
     const usage = computeCodexUsageScore(getAccountQuota(active), getPoolAccountPlan(config, active));
     if (!isUnknownUsage(usage) && usage >= threshold) {
-      active = pickLowerUsageAccount(config, active, usage, now, quotaScope);
+      active = pickLowerUsageAccount(config, active, usage, now, quotaScope, selectionOptions);
     }
   }
   if (shouldFailover(config, active, now)) {
-    const best = pickLowestUsageCodexAccount(config, active, now, quotaScope);
+    const best = pickLowestUsageCodexAccount(config, active, now, quotaScope, selectionOptions);
     if (best) active = best;
   }
-  if (!isCodexAccountUsable(config, active)) {
-    return hasConfiguredPoolAccount(config, active) ? active : null;
+  if (!isCodexAccountUsable(config, active, selectionOptions)) {
+    return hasConfiguredPoolAccount(config, active, selectionOptions) ? active : null;
   }
   if (isCodexAccountPaused(config, active)) return null;
   if (getCodexQuotaHealthSnapshot(active, quotaScope, now)) {
-    return hasConfiguredPoolAccount(config, active) ? active : null;
+    return hasConfiguredPoolAccount(config, active, selectionOptions) ? active : null;
   }
   return active;
 }
@@ -1156,6 +1355,7 @@ export function resolveCodexAccountForThreadDetailed(
   config: OcxConfig,
   now = Date.now(),
   quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
 ): CodexThreadResolution {
   const entry = threadId ? getThreadAffinity(threadId, quotaScope) : undefined;
   if (threadId && entry) {
@@ -1165,7 +1365,7 @@ export function resolveCodexAccountForThreadDetailed(
     }
     if (
       isThreadAffinityGenerationLive(entry)
-      && isCodexAccountSelectable(config, entry.accountId, now, quotaScope)
+      && isCodexAccountSelectable(config, entry.accountId, now, quotaScope, selectionOptions)
       // Affined threads must leave a failing account once the streak trips failover
       // (soft-avoid covers the first-hit case; this catches post-avoid residual streaks).
       && !shouldFailover(config, entry.accountId, now)
@@ -1192,7 +1392,7 @@ export function resolveCodexAccountForThreadDetailed(
         if (overThreshold || now - entry.lastReevalAt >= CODEX_THREAD_AFFINITY_REEVAL_INTERVAL_MS) {
           entry.lastReevalAt = now;
           if (overThreshold) {
-            const best = pickLowerUsageAccount(config, entry.accountId, usage, now, quotaScope);
+            const best = pickLowerUsageAccount(config, entry.accountId, usage, now, quotaScope, selectionOptions);
             if (best !== entry.accountId) {
               if (!isIndependentCodexQuotaScope(quotaScope)) setActiveCodexAccount(config, best);
               bindThreadAffinity(threadId, best, now, quotaScope); // rebinds + resets clocks
@@ -1206,35 +1406,42 @@ export function resolveCodexAccountForThreadDetailed(
     deleteThreadAffinity(threadId, quotaScope);
   }
 
-  const strategyPick = pickUnboundStrategyAccount(config, threadId, now, true, quotaScope);
+  const strategyPick = pickUnboundStrategyAccount(config, threadId, now, true, quotaScope, selectionOptions);
   if (strategyPick) return { status: "selected", accountId: strategyPick };
 
   let active = getEffectiveActiveCodexAccountId(config);
   if (!active) {
-    const selected = pickLowestUsageCodexAccount(config, undefined, now, quotaScope);
+    const selected = pickLowestUsageCodexAccount(config, undefined, now, quotaScope, selectionOptions);
     if (!selected) return { status: "none" };
     if (!isIndependentCodexQuotaScope(quotaScope)) setActiveCodexAccount(config, selected);
     active = selected;
   }
-  if (!isCodexAccountSelectable(config, active, now, quotaScope)) {
-    const fallback = pickLowestUsageCodexAccount(config, active, now, quotaScope);
+  if (!isCodexAccountSelectable(config, active, now, quotaScope, selectionOptions)) {
+    const fallback = pickLowestUsageCodexAccount(config, active, now, quotaScope, selectionOptions);
     if (fallback) {
       if (!isIndependentCodexQuotaScope(quotaScope)) setActiveCodexAccount(config, fallback);
       active = fallback;
-    } else if (hasConfiguredPoolAccount(config, active) && !isCodexAccountPaused(config, active)) {
+    } else if (
+      hasConfiguredPoolAccount(config, active, selectionOptions)
+      && !isCodexAccountPaused(config, active)
+    ) {
       return { status: "selected", accountId: active };
     } else {
       return { status: "none" };
     }
   }
-  active = applyQuotaAutoSwitch(config, active, now, quotaScope);
-  active = applyFailureFailover(config, active, now);
-  if (!isCodexAccountUsable(config, active)) {
-    return hasConfiguredPoolAccount(config, active) ? { status: "selected", accountId: active } : { status: "none" };
+  active = applyQuotaAutoSwitch(config, active, now, quotaScope, selectionOptions);
+  active = applyFailureFailover(config, active, now, selectionOptions);
+  if (!isCodexAccountUsable(config, active, selectionOptions)) {
+    return hasConfiguredPoolAccount(config, active, selectionOptions)
+      ? { status: "selected", accountId: active }
+      : { status: "none" };
   }
   if (isCodexAccountPaused(config, active)) return { status: "none" };
   if (getCodexQuotaHealthSnapshot(active, quotaScope, now)) {
-    return hasConfiguredPoolAccount(config, active) ? { status: "selected", accountId: active } : { status: "none" };
+    return hasConfiguredPoolAccount(config, active, selectionOptions)
+      ? { status: "selected", accountId: active }
+      : { status: "none" };
   }
   if (threadId) bindThreadAffinity(threadId, active, now, quotaScope);
   return { status: "selected", accountId: active };
@@ -1246,6 +1453,13 @@ export function recordCodexUpstreamOutcome(
   outcome: CodexUpstreamOutcome,
   meta: CodexUpstreamOutcomeMeta = {},
 ): void {
+  // Host-level evidence is account-independent (#914): a pre-connection
+  // reachability failure is recorded in the (provider, host) ledger even when
+  // there is no account to attribute, or the account's writer generation is
+  // stale — the early returns below must not gate it.
+  if (outcome === "connect_neutral" && meta.hostKey) {
+    recordUpstreamHostFailure(meta.hostKey, { code: meta.lastFailureCode, now: meta.now ?? Date.now() });
+  }
   if (!accountId) return;
   const writerGeneration = meta.writerGeneration ?? captureConfigGeneration();
   if (writerGeneration < lastReconciledGeneration && !liveHealthAccountIds.has(accountId)) return;
@@ -1310,6 +1524,25 @@ export function recordCodexUpstreamOutcome(
     return;
   }
 
+  if (outcomeClass === "neutral") {
+    // A proven pre-connection reachability failure (DNS / TCP refusal) or a
+    // relayed 3xx is host-level, not account evidence: rotation cannot repair
+    // it and must not happen (#914). Conclude any owned probe lease, record the
+    // failure under the (provider, host) ledger when one is named, and leave
+    // account health, thread affinity, and the active account untouched.
+    const current = upstreamHealth.get(accountId);
+    const scopedProbe = meta.probeQuotaScope
+      ? scopedHealthFor(accountId, meta.probeQuotaScope)
+      : undefined;
+    if (scopedProbe && meta.probeQuotaScope && ownsProbeLease(scopedProbe, meta)) {
+      setScopedHealth(accountId, meta.probeQuotaScope, withProbeLeaseReleased(scopedProbe, now));
+    }
+    if (ownsProbeLease(current, meta)) {
+      upstreamHealth.set(accountId, withProbeLeaseReleased(current!, now));
+    }
+    return;
+  }
+
   const lastFailureStatus = typeof outcome === "number" ? outcome : 0;
   if (outcomeClass === "credential") {
     // 401/403 quarantines the account for reauth. That supersedes quota state
@@ -1354,7 +1587,7 @@ export function recordCodexUpstreamOutcome(
       // The shared native scope is the existing account-wide native behavior:
       // threads must leave it and new requests should prefer an eligible account.
       // Spark remains isolated so a same-account Terra/Luna combo fallback can run.
-      if (quotaScope === "shared") {
+      if (quotaScope === "shared" && !meta.fixedAccount) {
         clearThreadAccountMapForAccount(accountId);
         notePoolRotationFailure(POOL_KEY_CODEX, accountId);
         if (getEffectiveActiveCodexAccountId(config) === accountId) {
@@ -1399,17 +1632,19 @@ export function recordCodexUpstreamOutcome(
           ...(prior?.lastProbeAt !== undefined ? { lastProbeAt: prior.lastProbeAt } : {}),
         }),
     });
-    clearThreadAccountMapForAccount(accountId);
-    notePoolRotationFailure(POOL_KEY_CODEX, accountId);
-    const effectiveActive = getEffectiveActiveCodexAccountId(config);
-    if (effectiveActive === accountId) {
-      // Same-request 429 retry already picked via excludeAccountId — reuse it so
-      // round-robin does not advance the ring a second time.
-      const reused = meta.promoteAccountId && meta.promoteAccountId !== accountId
-        ? meta.promoteAccountId
-        : null;
-      const fallback = reused ?? pickAlternateCodexAccount(config, accountId, now);
-      if (fallback) promoteActiveCodexAccount(config, fallback);
+    if (!meta.fixedAccount) {
+      clearThreadAccountMapForAccount(accountId);
+      notePoolRotationFailure(POOL_KEY_CODEX, accountId);
+      const effectiveActive = getEffectiveActiveCodexAccountId(config);
+      if (effectiveActive === accountId) {
+        // Same-request 429 retry already picked via excludeAccountId — reuse it so
+        // round-robin does not advance the ring a second time.
+        const reused = meta.promoteAccountId && meta.promoteAccountId !== accountId
+          ? meta.promoteAccountId
+          : null;
+        const fallback = reused ?? pickAlternateCodexAccount(config, accountId, now);
+        if (fallback) promoteActiveCodexAccount(config, fallback);
+      }
     }
     return;
   }
@@ -1454,15 +1689,17 @@ 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 (failoverReady && meta.threadId) {
+  if (!meta.fixedAccount && failoverReady && meta.threadId) {
     deleteThreadAffinitiesForAccount(meta.threadId, accountId);
   }
   // Once the account is past the failover streak, clear every thread still pinned
   // to it — matching 429 affinity behavior so "continue" cannot stay on a bad peer.
-  if (shouldFailover(config, accountId, now)) {
+  if (!meta.fixedAccount && shouldFailover(config, accountId, now)) {
     clearThreadAccountMapForAccount(accountId);
   }
-  if (getEffectiveActiveCodexAccountId(config) === accountId) applyFailureFailover(config, accountId, now);
+  if (!meta.fixedAccount && getEffectiveActiveCodexAccountId(config) === accountId) {
+    applyFailureFailover(config, accountId, now);
+  }
 }
 
 export function formatCodexProviderForLog(providerName: string, accountId: string | null, config: OcxConfig): string {