import { getEffectiveCodexAutoSwitchThreshold } from "../account-auto-switch";
import { codexAccountUsesCreditsAfterLimit, isCodexAccountHeldForCredits } from "../account-credit-use";
import { isCodexAccountPaused } from "../account-pause";
import { pinnedCodexAccountId } from "../account-priority";
import { codexSelectionPriorityLookup } from "../account-preservation";
import { isSelectableCodexPoolAccount } from "../account-id";
import { isAccountNeedsReauth } from "../account-runtime-state";
import { isCodexAccountUsable, type CodexAccountUsabilityOptions } from "../account-usability";
import { isCodexPoolRefreshCooling } from "../pool-refresh-backoff";
import {
  normalizeAccountPoolStickyLimit,
  normalizeCodexAccountPoolStrategy,
  notePoolRotationSuccess,
  peekRoundRobinAccount,
  pickRoundRobinAccount,
  selectPriorityTier,
} from "../pool-rotation";
import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, resetAtToMs } from "../quota";
import { codexPlanKey } from "../plan";
import { MAIN_CODEX_ACCOUNT_ID, getMainAccountPlan } from "../main-account";
import type { OcxConfig } from "../../types";
import { CODEX_FAILURE_WINDOW_MS, computeCodexUsageScore } from "./cooldown-math";
import { failureWindowSteersNewThreads } from "./failure-window";
import {
  codexPoolKeyForScope,
  dropSpentCredentialFailure,
  getAccountHealth,
  getCodexQuotaHealthSnapshot,
  hasUnrecoveredCodexQuotaRefusal,
  isCodexAccountSoftAvoided,
  isCodexQuotaAvoided,
  isIndependentCodexQuotaScope,
  type CodexQuotaScope,
} from "./health-store";
import { bindThreadAffinity, type CodexAffinityReason } from "./thread-affinity";
import { resetNearWeightOf } from "../../routing/machine-weighted-routing";
import { codexQuotaUsageObservedAt } from "../quota-observation-freshness";
import {
  getEffectiveActiveCodexAccountId,
  manualPreferenceBlocks,
  promoteActiveCodexAccount,
  rememberActiveCodexAccount,
  setActiveCodexAccount,
  unspentManualPreference,
} from "./active-account";

/**
 * Plan keys the operator excluded from automatic rotation. Absent or empty means no policy, so an
 * existing install rotates exactly as before. Compared with `codexPlanKey` because the stored plan
 * is an unrestricted provider string whose casing this repository does not control.
 */
function excludedCodexPoolPlanKeys(config: OcxConfig): ReadonlySet<string> | undefined {
  const configured = config.codexPool?.excludedPlans;
  if (!configured?.length) return undefined;
  const keys = configured
    .map(plan => codexPlanKey(plan))
    .filter((key): key is string => key !== undefined);
  return keys.length > 0 ? new Set(keys) : undefined;
}

/**
 * Whether the operator's plan policy removes this account from automatic selection.
 *
 * Modelled on pause rather than usability: an excluded account keeps its credential, quota history,
 * and affinity, stays visible on the account surface, and is still reachable by explicit account
 * selection. Only automatic rotation skips it, which is the distinction #4211 asked for.
 *
 * It is checked in the same two places pause is checked, and that is not redundancy. The eligible
 * list is consulted only when routing picks a NEW account; an already-active or already-affined
 * account is served straight from {@link isCodexAccountSelectable}. A lapsed subscription leaves
 * behind exactly that account, so a policy that filtered only the eligible list would miss the case
 * it exists for.
 *
 * `__main__` is exempt. {@link getPoolAccountPlanForSelection} withholds the main plan during a
 * selection-only drain so routing never reads the fenced native credential for it, so a rule that
 * covered main would disagree with itself between drain and ordinary routing.
 */
export function isCodexAccountPlanExcluded(
  config: OcxConfig,
  accountId: string,
  precomputed?: ReadonlySet<string>,
): boolean {
  if (accountId === MAIN_CODEX_ACCOUNT_ID) return false;
  // Callers that test a whole list pass the set once rather than rebuilding it per row.
  const excluded = precomputed ?? excludedCodexPoolPlanKeys(config);
  if (!excluded) return false;
  const plan = codexPlanKey(getPoolAccountPlan(config, accountId));
  return plan !== undefined && excluded.has(plan);
}

/**
 * Whether the operator turned credits off for this account and one of its usage windows is full
 * now (#6334). Checked wherever plan exclusion is checked, for the reason given there: an account
 * that is already active or bound is served without passing through the eligible list.
 */
export function isCodexAccountHeldAtUsageLimit(
  config: OcxConfig,
  accountId: string,
  now: number,
  selectionOptions?: CodexAccountUsabilityOptions,
): boolean {
  return isCodexAccountHeldForCredits(
    config,
    accountId,
    getAccountQuota(accountId),
    getPoolAccountPlanForSelection(config, accountId, selectionOptions),
    now,
  );
}

/** The automatic-rotation policies that also bind the legacy keep-the-active-account fallback. */
export function isCodexAccountRotationExcluded(
  config: OcxConfig,
  accountId: string,
  now: number,
  selectionOptions?: CodexAccountUsabilityOptions,
): boolean {
  return isCodexAccountPlanExcluded(config, accountId)
    || isCodexAccountHeldAtUsageLimit(config, accountId, now, selectionOptions);
}

export function isCodexAccountSelectable(
  config: OcxConfig,
  accountId: string,
  now: number,
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
): boolean {
  return !isCodexAccountPaused(config, accountId)
    && !isCodexAccountPlanExcluded(config, accountId)
    && !isCodexAccountHeldAtUsageLimit(config, accountId, now, selectionOptions)
    && getCodexQuotaHealthSnapshot(accountId, quotaScope, now) === null
    && !isCodexQuotaAvoided(accountId, quotaScope, now)
    && !isCodexAccountSoftAvoided(accountId, now)
    && !isCodexPoolRefreshCooling(accountId, now)
    && isCodexAccountUsable(config, accountId, selectionOptions);
}

/**
 * Which guard in {@link isCodexAccountSelectable} refused this account, if any.
 *
 * Deliberately the same predicates in the same order as that function, because the point is to
 * REPORT the guard that actually fired rather than to re-derive a plausible-looking cause. An
 * earlier version of the release reason checked only a subset and let a paused, plan-excluded,
 * cooled-down or quota-avoided release fall through to a quota fallback, which named something
 * routing never used -- a diagnostic that is confidently wrong in exactly the cases an operator
 * would consult it for (#4598).
 */
export function codexAccountBlockReason(
  config: OcxConfig,
  accountId: string,
  now: number,
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
): CodexAffinityReason | undefined {
  if (isCodexAccountPaused(config, accountId)) return "paused";
  if (isCodexAccountPlanExcluded(config, accountId)) return "plan_excluded";
  if (isCodexAccountHeldAtUsageLimit(config, accountId, now, selectionOptions)) return "credits_off";
  if (getCodexQuotaHealthSnapshot(accountId, quotaScope, now) !== null) return "cooldown";
  if (isCodexQuotaAvoided(accountId, quotaScope, now)) return "quota_avoided";
  if (isCodexAccountSoftAvoided(accountId, now)) return "transient";
  if (isCodexPoolRefreshCooling(accountId, now)) return "transient";
  if (!isCodexAccountUsable(config, accountId, selectionOptions)) return "unusable";
  return undefined;
}

/**
 * Drop accounts a confirmed roster says cannot serve this model, unless that leaves nothing.
 *
 * The restore-on-empty is the whole safety argument, not a defensive afterthought. Roster
 * evidence can be wrong in the direction that matters: a shard that has not caught up reports a
 * denial for a model the account genuinely owns, and #3022 is what happens when absence is
 * allowed to remove a model outright. Because this can only ever return a non-empty subset of a
 * list the caller already computed, no pool that would have found a working account can be left
 * without one — the worst case is the selection that ships today.
 *
 * It is an ordering rule rather than an eligibility one for the same reason. Nothing below
 * reports `model_not_entitled`, nothing refuses before dispatch, and the existing bounded
 * alternate-account retry on an exact unsupported-model 400 stays exactly where it is as the
 * safety net. This only stops the pool from CHOOSING an account that has already told us it
 * cannot serve the model (#4768).
 *
 * An operator's manual pin is never dropped. Roster evidence orders the pool's own discretion;
 * it does not overrule an explicit human choice, and removing the pinned account here would do
 * more than demote it -- `selectPriorityTier` reads the pin to lower the tier ceiling, so a pin
 * filtered out beforehand stops acting as a ceiling at all and silently re-enables tiers the
 * operator had excluded. An operator who pins an account upstream will refuse still gets the
 * alternate-account retry; what they do not get is the pool quietly deciding they were wrong.
 */
export function withoutModelDeniedAccounts(
  ids: readonly string[],
  denied: ReadonlySet<string> | undefined,
  pinned?: string,
): readonly string[] {
  if (denied === undefined || ids.length === 0) return ids;
  const remaining = ids.filter(id => !denied.has(id) || id === pinned);
  return remaining.length > 0 ? remaining : ids;
}

export function getEligiblePoolAccounts(
  config: OcxConfig,
  excludeId?: string,
  now = Date.now(),
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
  skipFailoverReadyCandidates = false,
): readonly string[] {
  const excludedPlans = excludedCodexPoolPlanKeys(config);
  const ids = (config.codexAccounts ?? [])
    .filter(account => isSelectableCodexPoolAccount(account)
      && account.id !== excludeId
      && !isCodexAccountPaused(config, account.id)
      && !isCodexAccountPlanExcluded(config, account.id, excludedPlans)
      && !isCodexAccountHeldAtUsageLimit(config, account.id, now, selectionOptions)
      && !isAccountNeedsReauth(account.id)
      && (!skipFailoverReadyCandidates || !shouldFailover(config, account.id, now)))
    .filter(account => getCodexQuotaHealthSnapshot(account.id, quotaScope, now) === null)
    .filter(account => !isCodexAccountSoftAvoided(account.id, now))
    .filter(account => !failureWindowSteersNewThreads(config, account.id, now))
    .filter(account => !isCodexQuotaAvoided(account.id, quotaScope, now))
    .filter(account => !isCodexPoolRefreshCooling(account.id, now))
    .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).
  if (
    excludeId !== MAIN_CODEX_ACCOUNT_ID
    && !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
    && getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope, now) === null
    && !isCodexAccountSoftAvoided(MAIN_CODEX_ACCOUNT_ID, now)
    && !failureWindowSteersNewThreads(config, MAIN_CODEX_ACCOUNT_ID, now)
    // The main login is not in `config.codexAccounts`, so it never passes through the
    // filters above and this is the only place an avoidance window can exclude it. Without
    // this the window a refusal announced applies to the pool but not to the account that
    // earned it: the cooldown caps at fifteen minutes, the window runs up to six hours, and
    // in between the main account returns as a first-class candidate.
    && !isCodexQuotaAvoided(MAIN_CODEX_ACCOUNT_ID, quotaScope, now)
    && !isCodexPoolRefreshCooling(MAIN_CODEX_ACCOUNT_ID, now)
    && !isCodexAccountHeldAtUsageLimit(config, MAIN_CODEX_ACCOUNT_ID, now, selectionOptions)
    && (!skipFailoverReadyCandidates || !shouldFailover(config, MAIN_CODEX_ACCOUNT_ID, now))
    && isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID, selectionOptions)
  ) {
    ids.unshift(MAIN_CODEX_ACCOUNT_ID);
  }
  // Single choke point for selection order: every strategy, failover, and preview
  // reaches the pool through here, so tiering applies once rather than per picker.
  // Eligibility above is unchanged — this only narrows an already-eligible list.
  //
  // Model entitlement is applied BEFORE the priority tier, because a tier is a quota-ordering
  // question and an account that cannot serve the model at all should not be the reason a tier
  // is selected. Both steps narrow an already-eligible list and neither can empty it.
  const pinned = pinnedCodexAccountId(config);
  return selectPriorityTier(
    withoutModelDeniedAccounts(ids, selectionOptions?.deniedModelAccountIds, pinned),
    codexSelectionPriorityLookup(config),
    id => hasCodexQuotaHeadroom(config, id, selectionOptions, now),
    pinned,
  );
}

function listEligibleCodexAccountIds(
  config: OcxConfig,
  now: number,
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
): readonly string[] {
  return getEligiblePoolAccounts(config, undefined, now, quotaScope, selectionOptions);
}

/** Shared reset timestamps are not evidence for independent model-quota groups. */
export function accountPoolStrategyForScope(config: OcxConfig, quotaScope?: CodexQuotaScope) {
  const strategy = normalizeCodexAccountPoolStrategy(config.accountPoolStrategy);
  if (!isIndependentCodexQuotaScope(quotaScope)) return strategy;
  if (strategy === "reset-first") return "quota";
  return strategy === "reset-near-weighted" ? "round-robin" : strategy;
}

function codexResetNearWeightOf(eligible: readonly string[], now: number) {
  return resetNearWeightOf(eligible, id => {
    const quota = getAccountQuota(id);
    if (quota?.shortWindowSeconds !== 5 * 60 * 60) return null;
    return {
      weeklyPercent: quota.weeklyPercent,
      weeklyResetAt: quota.weeklyResetAt,
      weeklyObservedAt: codexQuotaUsageObservedAt(quota, "weeklyPercent"),
      fiveHourPercent: quota.shortPercent,
      fiveHourResetAt: quota.shortResetAt,
      fiveHourObservedAt: codexQuotaUsageObservedAt(quota, "shortPercent"),
    };
  }, now);
}

function stickyLimitForConfig(config: OcxConfig): number {
  return normalizeAccountPoolStickyLimit(config.accountPoolStickyLimit);
}

/**
 * Whether an account still has quota to give under the auto-switch threshold.
 *
 * Fill-first and the priority tier filter share this predicate, and share both of
 * its escape hatches. A disabled threshold means only health, pause, and reauth
 * may drain an account; unknown usage is a guess, so it must neither force
 * fill-first off the active account nor drain a tier that was simply never
 * primed. A genuinely exhausted account 429s into cooldown and leaves
 * eligibility on its own.
 */
export function hasCodexQuotaHeadroom(
  config: OcxConfig,
  accountId: string,
  selectionOptions?: CodexAccountUsabilityOptions,
  now: number = Date.now(),
): boolean {
  const threshold = getEffectiveCodexAutoSwitchThreshold(config, accountId);
  if (threshold <= 0) return true;
  const usage = computeCodexUsageScore(
    getAccountQuota(accountId),
    getPoolAccountPlanForSelection(config, accountId, selectionOptions),
    now,
    codexAccountUsesCreditsAfterLimit(config, accountId),
  );
  if (isUnknownUsage(usage)) return true;
  return usage < threshold;
}

/**
 * Where round-robin may place a NEW conversation: the eligible accounts that still have headroom
 * under their own threshold, or the whole eligible list when none does.
 *
 * Rotation by count alone put a fresh conversation on an account already at 95%. The conversation
 * binds there, and when the account runs out it has to move to another account with a cold prompt
 * cache. Preferring headroom at placement avoids that hop without touching anything already bound:
 * live bindings never reach this function, and failover ({@link pickAlternateCodexAccount}) keeps
 * plain ring order because leaving a failing account is not a placement.
 *
 * The score is {@link hasCodexQuotaHeadroom}, the one fill-first and the priority tier already use,
 * so a threshold of 0 or unknown usage counts as headroom. It is a preference, never eligibility:
 * when every account is at or over its threshold the ring sees the full list, exactly as before.
 *
 * An operator's unspent manual selection for this scope stays in the list whatever its usage.
 * Manual selection seeds the ring so the next placement lands on the chosen account, and a
 * preference must not overrule a person's explicit choice: dropping it here would clear that seed.
 * Once a dispatch on it succeeds the selection is spent and the account is treated like any other.
 */
function roundRobinPlacementCandidates(
  config: OcxConfig,
  eligible: readonly string[],
  now: number,
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
): readonly string[] {
  const operatorChoice = unspentManualPreference(codexPoolKeyForScope(quotaScope));
  const withHeadroom = eligible.filter(id =>
    id === operatorChoice || hasCodexQuotaHeadroom(config, id, selectionOptions, now));
  return withHeadroom.length > 0 ? withHeadroom : eligible;
}

/**
 * Is a live binding held for its prompt cache?
 *
 * Unset means yes. Cache affinity shipped as an opt-in flag (#4292) and then #4546 measured
 * what the default costs: a pool whose accounts all sit in the 80-99% band hands a bound
 * conversation from account to account, and because provider prompt caches are account-isolated
 * every hop re-sends the entire prefix. An install that has never heard of this flag is exactly
 * the install that gets hurt by it, so the protection cannot be something you have to find.
 *
 * `false` restores capacity-first routing byte-for-byte. It is a real choice -- a pinned thread
 * on a busy account pays latency -- and it stays available; it is just no longer the default.
 */
export function isCacheAffinityEnabled(config: OcxConfig): boolean {
  return config.pool?.cacheAffinity !== false;
}

/**
 * Whether quota may retire shared state while cache affinity is active.
 *
 * A threshold crossing is a hint that an account is getting busy, not evidence it cannot
 * serve — the same bar {@link mayRebindAffinityForQuota} applies to a live binding. Shared
 * state held across a model detour gets that exhaustion boundary for the same reason: the
 * detour is request-scoped, so retiring the binding over a hint pays a cold prefix for
 * nothing. New/unbound selection still reads {@link hasCodexQuotaHeadroom}; only
 * preservation of an existing shared selection or thread binding qualifies here. Like the
 * live-binding rule, the configured threshold plays no role once retention applies: a
 * genuinely exhausted (>=100%) account releases even with threshold switching disabled,
 * while the fallback above keeps a disabled threshold's "never drained on quota alone".
 */
export function hasCodexSharedStateQuotaHeadroom(
  config: OcxConfig,
  accountId: string,
  quotaScope: CodexQuotaScope | undefined,
  selectionOptions?: CodexAccountUsabilityOptions,
  now: number = Date.now(),
): boolean {
  if (
    !isCacheAffinityEnabled(config)
    || accountPoolStrategyForScope(config, quotaScope) !== "quota"
  ) {
    return hasCodexQuotaHeadroom(config, accountId, selectionOptions, now);
  }
  const usage = computeCodexUsageScore(
    getAccountQuota(accountId),
    getPoolAccountPlanForSelection(config, accountId, selectionOptions),
    now,
    codexAccountUsesCreditsAfterLimit(config, accountId),
  );
  return isUnknownUsage(usage) || usage < 100;
}

/** Earliest future shared short/weekly reset; missing evidence and ties use usage order. */
export function pickResetFirstCodexAccount(
  config: OcxConfig,
  ids: readonly string[],
  now: number,
  selectionOptions?: CodexAccountUsabilityOptions,
): string | null {
  const available = ids.filter(id => hasCodexQuotaHeadroom(config, id, selectionOptions, now));
  if (available.length === 0) return pickLowestUsageAmong(config, ids, selectionOptions, now);
  let earliest = Number.POSITIVE_INFINITY;
  let candidates: string[] = [];
  for (const id of available) {
    const quota = getAccountQuota(id);
    const resets = [quota?.shortResetAt, quota?.weeklyResetAt]
      .filter((reset): reset is number => typeof reset === "number" && Number.isFinite(reset))
      .map(resetAtToMs)
      .filter(reset => reset > now);
    const next = Math.min(...resets);
    if (next < earliest) {
      earliest = next;
      candidates = [id];
    } else if (next === earliest) candidates.push(id);
  }
  return pickLowestUsageAmong(config, candidates, selectionOptions, now);
}

/**
 * Fill-first: keep selectable active under threshold; otherwise advance to the next
 * eligible id in stable sorted order after the current active (wrapping).
 */
function pickFillFirstCodexAccount(
  config: OcxConfig,
  now: number,
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
): string | null {
  const eligible = listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions);
  if (eligible.length === 0) return null;

  const active = getEffectiveActiveCodexAccountId(config);
  if (active && eligible.includes(active) && hasCodexQuotaHeadroom(config, active, selectionOptions, now)) {
    return active;
  }

  return pickNextFillFirstCodexAccount(config, active ?? null, eligible, now, selectionOptions);
}

/** Next eligible account in stable order after `afterId` (wrapping). */
function pickNextFillFirstCodexAccount(
  config: OcxConfig,
  afterId: string | null,
  eligible: readonly string[] = 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));
  if (!afterId) {
    // Prefer an under-threshold account when starting with no active cursor.
    for (const id of ordered) {
      if (hasCodexQuotaHeadroom(config, id, selectionOptions, now)) return id;
    }
    return ordered[0] ?? null;
  }

  const allConfigured = [
    ...(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),
  ];
  const stableAll = [...new Set(allConfigured)].sort((a, b) => a.localeCompare(b));
  const startIdx = stableAll.indexOf(afterId);
  if (startIdx < 0) {
    for (const id of ordered) {
      if (hasCodexQuotaHeadroom(config, id, selectionOptions, now)) return id;
    }
    return ordered[0] ?? null;
  }

  // Skip successors that are also at/above threshold (known drained usage).
  let fallback: string | null = null;
  for (let step = 1; step <= stableAll.length; step++) {
    const candidate = stableAll[(startIdx + step) % stableAll.length]!;
    if (!eligible.includes(candidate)) continue;
    if (!fallback) fallback = candidate;
    if (hasCodexQuotaHeadroom(config, candidate, selectionOptions, now)) return candidate;
  }
  return fallback ?? ordered[0] ?? null;
}

/**
 * Unbound new-session pick for round-robin / fill-first. Returns null to fall through
 * to the legacy quota path (or when the strategy is quota).
 *
 * When `commit` is true (resolve path), advances RR state. `commitSharedActive`
 * and `commitAffinity` independently control the two cross-request side effects:
 * model-scoped entitlement selection can bind a new task without replacing an
 * existing task binding or global active choice. Preview remains a dry-run peek.
 *
 * Automatic strategy picks never sync-write config; only manual selection persists active.
 *
 * Known limitation (follow-up): when a subagent preview peeks an RR account and the request
 * then falls back to a non-Codex provider, the ring is not reserved/committed. Prefer seeding
 * the peeked account if that path becomes load-bearing.
 */
export function pickUnboundStrategyAccount(
  config: OcxConfig,
  threadId: string | null,
  now: number,
  commit: boolean,
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
  commitSharedActive = commit,
  commitAffinity = commit,
): string | null {
  const strategy = accountPoolStrategyForScope(config, quotaScope);
  if (strategy === "quota") return null;
  const poolKey = codexPoolKeyForScope(quotaScope);

  let picked: string | null = null;
  const resetNearWeighted = strategy === "reset-near-weighted";
  if (strategy === "round-robin" || resetNearWeighted) {
    const eligible = roundRobinPlacementCandidates(
      config,
      listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions),
      now,
      quotaScope,
      selectionOptions,
    );
    const weightOf = resetNearWeighted ? codexResetNearWeightOf(eligible, now) : undefined;
    const limit = stickyLimitForConfig(config);
    if (!commit) {
      return peekRoundRobinAccount(poolKey, eligible, limit, weightOf);
    }
    picked = pickRoundRobinAccount(poolKey, eligible, limit, weightOf);
    if (!picked) return null;
    if (commitSharedActive && sharesActiveSelection(picked, selectionOptions)) {
      if (!isIndependentCodexQuotaScope(quotaScope)
        && !manualPreferenceBlocks(codexPoolKeyForScope(quotaScope), picked)) {
        rememberActiveCodexAccount(config, picked);
      }
    }
    if (commitAffinity && threadId) bindThreadAffinity(threadId, picked, now, quotaScope);
    notePoolRotationSuccess(poolKey, picked, limit);
    return picked;
  }

  if (strategy === "fill-first" || strategy === "reset-first") {
    picked = strategy === "reset-first"
      ? pickResetFirstCodexAccount(config, listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions), now, selectionOptions)
      : pickFillFirstCodexAccount(config, now, quotaScope, selectionOptions);
    if (!picked) return null;
    if (commitSharedActive && sharesActiveSelection(picked, selectionOptions)) {
      if (!isIndependentCodexQuotaScope(quotaScope)
        && !manualPreferenceBlocks(codexPoolKeyForScope(quotaScope), picked)) {
        rememberActiveCodexAccount(config, picked);
      }
    }
    if (commitAffinity && threadId) bindThreadAffinity(threadId, picked, now, quotaScope);
    return picked;
  }

  return null;
}

export function getPoolAccountPlan(config: OcxConfig, accountId: string): string | undefined {
  if (accountId === MAIN_CODEX_ACCOUNT_ID) return getMainAccountPlan();
  return (config.codexAccounts ?? [])
    .find(account => isSelectableCodexPoolAccount(account) && account.id === accountId)?.plan;
}

/**
 * Selection-only main routing must not lazily read the fenced native credential for its plan, and
 * neither may a request whose main candidacy comes from its own bearer (#5019): that request is
 * forbidden to read the physical main credential, so main is ranked without a plan.
 */
export function getPoolAccountPlanForSelection(
  config: OcxConfig,
  accountId: string,
  selectionOptions?: CodexAccountUsabilityOptions,
): string | undefined {
  if (
    accountId === MAIN_CODEX_ACCOUNT_ID
    && (selectionOptions?.nativeMainSelectionOnly === true
      || selectionOptions?.requestOwnedMainCredential === true)
  ) {
    return undefined;
  }
  return getPoolAccountPlan(config, accountId);
}

/** Shared routing state must ignore a request-scoped entitlement roster. */
export function sharedStateSelectionOptions(
  selectionOptions?: CodexAccountUsabilityOptions,
): Pick<
  CodexAccountUsabilityOptions,
  "nativeMainSelectionOnly" | "isMainAccountTokenLive" | "requestOwnedMainCredential"
> | undefined {
  if (!selectionOptions) return undefined;
  return {
    ...(selectionOptions.nativeMainSelectionOnly !== undefined
      ? { nativeMainSelectionOnly: selectionOptions.nativeMainSelectionOnly }
      : {}),
    ...(selectionOptions.isMainAccountTokenLive
      ? { isMainAccountTokenLive: selectionOptions.isMainAccountTokenLive }
      : {}),
    ...(selectionOptions.requestOwnedMainCredential !== undefined
      ? { requestOwnedMainCredential: selectionOptions.requestOwnedMainCredential }
      : {}),
  };
}

/**
 * A main that is live only through this request's own credential serves this request alone.
 * Recording it as the shared active account would route later requests through a credential
 * they do not carry (see CodexAccountUsabilityOptions.requestOwnedMainCredential).
 */
export function sharesActiveSelection(
  accountId: string,
  selectionOptions?: CodexAccountUsabilityOptions,
): boolean {
  return !(accountId === MAIN_CODEX_ACCOUNT_ID && selectionOptions?.requestOwnedMainCredential === true);
}

export function pickLowerUsageAccount(
  config: OcxConfig,
  active: string,
  activeUsage: number,
  now: number,
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
  skipFailoverReadyCandidates = false,
): string {
  let best = active;
  let bestUsage = activeUsage;
  for (const id of getEligiblePoolAccounts(
    config,
    active,
    now,
    quotaScope,
    selectionOptions,
    skipFailoverReadyCandidates,
  )) {
    const usage = computeCodexUsageScore(
      getAccountQuota(id),
      getPoolAccountPlanForSelection(config, id, selectionOptions),
      now,
      codexAccountUsesCreditsAfterLimit(config, id),
    );
    if (usage < bestUsage) {
      best = id;
      bestUsage = usage;
    }
  }
  return best;
}

/** Coolest account in an already-selected candidate list; first index wins ties. */
export function pickLowestUsageAmong(
  config: OcxConfig,
  ids: readonly string[],
  selectionOptions?: CodexAccountUsabilityOptions,
  now: number = Date.now(),
): string | null {
  let best: string | null = null;
  let bestUsage = Number.POSITIVE_INFINITY;
  for (const id of ids) {
    const usage = computeCodexUsageScore(
      getAccountQuota(id),
      getPoolAccountPlanForSelection(config, id, selectionOptions),
      now,
      codexAccountUsesCreditsAfterLimit(config, id),
    );
    if (usage < bestUsage) {
      best = id;
      bestUsage = usage;
    }
  }
  return best;
}

export function pickLowestUsageCodexAccount(
  config: OcxConfig,
  excludeId?: string,
  now = Date.now(),
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
): string | null {
  return pickLowestUsageAmong(
    config,
    getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions),
    selectionOptions,
    now,
  );
}

/**
 * Strategy-aware alternate after a cooled/excluded account (same-request 429 retry
 * and active promotion). Quota keeps lowest-usage; fill-first advances stable order;
 * round-robin takes the next ring pick (caller should have noted the failure).
 */
export function pickAlternateCodexAccount(
  config: OcxConfig,
  excludeId: string,
  now = Date.now(),
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
): string | null {
  const strategy = accountPoolStrategyForScope(config, quotaScope);
  // The exclusion is passed into eligibility rather than post-filtered off its
  // result: when the excluded account is the only healthy member of the top
  // tier, the tier walk must be free to descend instead of selecting that tier
  // and then handing back an empty list.
  if (strategy === "round-robin" || strategy === "reset-near-weighted") {
    const eligible = getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions);
    const weightOf = strategy === "reset-near-weighted" ? codexResetNearWeightOf(eligible, now) : undefined;
    return pickRoundRobinAccount(codexPoolKeyForScope(quotaScope), eligible, stickyLimitForConfig(config), weightOf);
  }
  if (strategy === "fill-first") {
    const eligible = getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions);
    return pickNextFillFirstCodexAccount(config, excludeId, eligible, now, selectionOptions);
  }
  if (strategy === "reset-first") {
    return pickResetFirstCodexAccount(config, getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions), now, selectionOptions);
  }
  return pickLowestUsageCodexAccount(config, excludeId, now, quotaScope, selectionOptions);
}

/**
 * The account {@link pickAlternateCodexAccount} WOULD return, without returning it.
 *
 * Only the round-robin branch has a side effect -- `pickRoundRobinAccount` commits the pick and
 * advances the ring -- so every other strategy delegates rather than growing a second copy of
 * the selection rule that could drift from it.
 *
 * This exists because preview and resolve have to agree on the FIRST transient detour, not just
 * on later ones. Preview feeds subagent model-availability scoring, so a preview that reported
 * the bound account while resolve was about to serve from a cool sibling could retire a model
 * over usage the request would never have touched.
 */
export function peekAlternateCodexAccount(
  config: OcxConfig,
  excludeId: string,
  now: number,
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
): string | null {
  const strategy = accountPoolStrategyForScope(config, quotaScope);
  if (strategy === "round-robin" || strategy === "reset-near-weighted") {
    const eligible = getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions);
    const weightOf = strategy === "reset-near-weighted" ? codexResetNearWeightOf(eligible, now) : undefined;
    return peekRoundRobinAccount(codexPoolKeyForScope(quotaScope), eligible, stickyLimitForConfig(config), weightOf);
  }
  return pickAlternateCodexAccount(config, excludeId, now, quotaScope, selectionOptions);
}

export function isUnknownUsage(usage: number): boolean {
  return usage >= CODEX_UNKNOWN_USAGE_SCORE;
}

/**
 * Correct a shared cursor that names an account this model's own roster denies (#4768).
 *
 * {@link getEligiblePoolAccounts} is not the only door into selection. An account that is already
 * ACTIVE is served straight from {@link isCodexAccountSelectable} and never passes through the
 * eligible list, so ordering that list alone left the exact case the issue reports: once the Free
 * account becomes the cursor, every Sol/Astra request keeps going to it and keeps taking the
 * upstream unsupported-model 400. {@link pickPriorityPreemption} does not cover it either -- it
 * refuses to move toward a tier that does not strictly outrank the active one, which is the usual
 * shape here.
 *
 * Three properties keep this inside "order the already-eligible set" rather than widening it.
 * It admits nothing: the replacement comes from {@link getEligiblePoolAccounts}, so every
 * eligibility guard has already passed on it. It cannot fail: with no entitled alternative the
 * active account is returned unchanged, so this can never turn a served request into `none`.
 * And it changes nothing without evidence: absent `deniedModelAccountIds`, or an active account
 * nobody denied, it is the identity function.
 *
 * The caller must NOT persist the result. This is one request's correction for one model, in the
 * same spirit as a model detour; the operator's cursor is theirs. A pinned active account is
 * exempt outright, for the reason {@link withoutModelDeniedAccounts} gives.
 */
export function preferModelEntitledAccount(
  config: OcxConfig,
  active: string,
  now: number,
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
): string {
  const denied = selectionOptions?.deniedModelAccountIds;
  if (denied === undefined || !denied.has(active)) return active;
  if (pinnedCodexAccountId(config) === active) return active;
  // The eligible list restores denied members when filtering would empty it, so re-filter here:
  // moving from one denied account to another buys nothing and costs the warm prefix.
  const entitled = getEligiblePoolAccounts(config, active, now, quotaScope, selectionOptions)
    .filter(id => !denied.has(id));
  return pickLowestUsageAmong(config, entitled, selectionOptions, now) ?? active;
}

/**
 * Move an unbound request back up when a higher tier regains headroom — the
 * weekly-reset case. Returns null when nothing should change.
 *
 * Downward moves are deliberately left to {@link applyQuotaAutoSwitch}: this only
 * fires when the tier filter has already excluded `active`, and only toward a
 * tier that strictly outranks it. Bound threads reach it only through explicit priority failback.
 */
export function pickPriorityPreemption(
  config: OcxConfig,
  active: string,
  now: number,
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
): string | null {
  const eligible = getEligiblePoolAccounts(config, undefined, now, quotaScope, selectionOptions);
  if (eligible.length === 0 || eligible.includes(active)) return null;
  const pinned = pinnedCodexAccountId(config);
  // A live pin already lowered the tier ceiling; never preempt past an explicit
  // operator choice. Same liveness test the tier filter applies, so preview and
  // resolve agree even before the pin is garbage-collected.
  if (
    pinned !== undefined
    && eligible.includes(pinned)
    && hasCodexQuotaHeadroom(config, pinned, selectionOptions, now)
  ) return null;
  const priorityOf = codexSelectionPriorityLookup(config);
  if (priorityOf(eligible[0]!) <= priorityOf(active)) return null;
  // Members without headroom are in the tier only because a sibling has some;
  // picking one would hand the request straight back to a drained account.
  return pickLowestUsageAmong(
    config,
    eligible.filter(id => hasCodexQuotaHeadroom(config, id, selectionOptions, now)),
    selectionOptions,
    now,
  );
}

export function applyQuotaAutoSwitch(
  config: OcxConfig,
  active: string,
  now: number,
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
  commitSharedSelection = true,
): string {
  const threshold = getEffectiveCodexAutoSwitchThreshold(config, active);
  if (threshold <= 0) return active;
  const quota = getAccountQuota(active);
  const activeUsage = computeCodexUsageScore(
    quota,
    getPoolAccountPlanForSelection(config, active, selectionOptions),
    now,
    codexAccountUsesCreditsAfterLimit(config, active),
  );
  // Unknown usage is not evidence that a user's explicit selection crossed the
  // threshold. Wait for quota priming instead of rotating among guesses.
  if (isUnknownUsage(activeUsage)) return active;
  if (activeUsage < threshold) return active;
  const best = pickLowerUsageAccount(config, active, activeUsage, now, quotaScope, selectionOptions);
  if (best !== active) {
    if (commitSharedSelection && !isIndependentCodexQuotaScope(quotaScope)
      && sharesActiveSelection(best, selectionOptions)) {
      setActiveCodexAccount(config, best);
    }
    return best;
  }

  return active;
}

export function shouldFailover(config: OcxConfig, accountId: string, now: number): boolean {
  const threshold = config.upstreamFailoverThreshold ?? 3;
  if (threshold <= 0) return false;
  dropSpentCredentialFailure(accountId);
  const health = getAccountHealth(accountId);
  if (health?.lastFailureAt && now - health.lastFailureAt > CODEX_FAILURE_WINDOW_MS) return false;
  return !!health && health.consecutiveFailures >= threshold;
}

export function isHealthySharedCodexSelection(
  config: OcxConfig,
  accountId: string,
  now: number,
  quotaScope: CodexQuotaScope | undefined,
  selectionOptions: CodexAccountUsabilityOptions | undefined,
): boolean {
  return isCodexAccountSelectable(config, accountId, now, quotaScope, selectionOptions)
    && hasCodexSharedStateQuotaHeadroom(config, accountId, quotaScope, selectionOptions, now)
    && !hasUnrecoveredCodexQuotaRefusal(accountId, quotaScope)
    && !shouldFailover(config, accountId, now);
}

export function strategySelectionOptionsForModelDetour(
  config: OcxConfig,
  now: number,
  quotaScope: CodexQuotaScope | undefined,
  selectionOptions: CodexAccountUsabilityOptions | undefined,
): CodexAccountUsabilityOptions | undefined {
  if (selectionOptions?.modelEligibleAccountIds === undefined) return selectionOptions;
  const sharedSelectionOptions = sharedStateSelectionOptions(selectionOptions) ?? {};
  return {
    ...selectionOptions,
    modelEligibleAccountIds: new Set(
      [...selectionOptions.modelEligibleAccountIds].filter(accountId =>
        isHealthySharedCodexSelection(
          config,
          accountId,
          now,
          quotaScope,
          sharedSelectionOptions,
        )
      ),
    ),
  };
}

export function applyFailureFailover(
  config: OcxConfig,
  active: string,
  now: number,
  quotaScope?: CodexQuotaScope,
  selectionOptions?: CodexAccountUsabilityOptions,
  commitSharedSelection = true,
): string {
  if (!shouldFailover(config, active, now) && !failureWindowSteersNewThreads(config, active, now)) return active;
  const best = pickAlternateCodexAccount(config, active, now, quotaScope, selectionOptions);
  if (best) {
    // The scope still routes away from the failing account — that is this request's
    // own decision — but an independent one must not persist a new shared active
    // account. recordCodexUpstreamOutcome only suppresses the promotion it makes at
    // the moment of the failure; the streak outlives the soft avoid, so a later
    // scoped resolve reaches here with the streak still tripped and would otherwise
    // move the shared cursor after all.
    if (commitSharedSelection && !isIndependentCodexQuotaScope(quotaScope)
      && sharesActiveSelection(best, selectionOptions)) {
      promoteActiveCodexAccount(config, best);
    }
    return best;
  }
  return active;
}
