@bitkyc08/opencodex 2.72.0 → 2.73.0

package/src/oauth/anthropic-account-threshold.ts

@@ -0,0 +1,13 @@
+import type { OcxConfig } from "../types";
+import type { ProviderAccount } from "./types";
+
+/** Shared strict boundary for persisted rows and management writes. Zero is not exhaustion. */
+export function parseAnthropicAccountThreshold(value: unknown): number | null {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 100 ? value : null;
+}
+
+/** Missing or malformed legacy metadata inherits; concrete zero must survive nullish fallback. */
+export function effectiveAnthropicAccountThreshold(config: OcxConfig, account?: Pick<ProviderAccount, "autoSwitchThresholdOverride">): number {
+  return parseAnthropicAccountThreshold(account?.autoSwitchThresholdOverride)
+    ?? parseAnthropicAccountThreshold(config.anthropicAccountPool?.autoSwitchThreshold) ?? 80;
+}

package/src/oauth/anthropic-routing.ts

@@ -34,6 +34,14 @@ import type { OcxAccountPoolQuotaWindow, OcxAccountPoolRotationStrategy, OcxConf
 import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
 import { retainedUtf8Bytes } from "../lib/admission";
 import { routeCandidates, type AnthropicRouteDecision } from "./anthropic-model-routes";
+import type { ProviderQuota } from "../providers/quota-types";
+import {
+  anthropicCooldownGeneration,
+  clearAnthropicCooldownGenerations,
+  noteAnthropicCooldownMutation,
+} from "../providers/quota/anthropic-cooldown-recovery";
+import { subscribeAccountSelections, subscribeOAuthAccountPauseChanges, subscribeOAuthAccountRoutingPolicyChanges } from "../lib/account-selection-events";
+import { effectiveAnthropicAccountThreshold } from "./anthropic-account-threshold";
 
 /**
  * The read side of a `Headers` object, so a caller can pass the live upstream response's
@@ -57,6 +65,16 @@ export const ANTHROPIC_POOL_MAX_FAILOVERS_PER_REQUEST = 3;
 
 export type AnthropicAccountPoolConfig = NonNullable<OcxConfig["anthropicAccountPool"]>;
 
+/** Local admission refusal across async dispatch; never treat it as provider reachability evidence. */
+export class AnthropicAccountCooldownError extends Error {
+  constructor(readonly retryAfterSeconds: number | null, readonly routePosition?: number) {
+    super(routePosition === undefined
+      ? "All Anthropic OAuth accounts are temporarily rate-limited"
+      : "Anthropic OAuth accounts for this model route are temporarily rate-limited");
+    this.name = "AnthropicAccountCooldownError";
+  }
+}
+
 /**
  * Where a cooldown's length came from. Same vocabulary as `CodexCooldownSource`, because it
  * answers the same question for the same reason: `retry-after` is upstream answering THIS
@@ -66,10 +84,15 @@ export type AnthropicAccountPoolConfig = NonNullable<OcxConfig["anthropicAccount
  * `retry-after` would report a drained five-hour window as request-rate throttling.
  */
 type AnthropicCooldownSource = "retry-after" | "reset-derived" | "default";
+type AnthropicQuotaWindow = "five-hour" | "weekly";
 
 interface AccountHealth {
   cooldownUntil: number;
   cooldownSource: AnthropicCooldownSource;
+  /** Windows whose rejected status established a reset-derived cooldown. */
+  rejectedQuotaWindows?: AnthropicQuotaWindow[];
+  /** Monotonic fence so an older quota probe cannot erase a newer refusal. */
+  cooldownGeneration: number;
 }
 
 interface AffinityEntry {
@@ -105,6 +128,11 @@ export function anthropicAutoSwitchThreshold(config: OcxConfig): number {
   return DEFAULT_AUTO_SWITCH_THRESHOLD;
 }
 
+/** Read live policy at selection, not a credential snapshot captured before an await. */
+export function anthropicAccountAutoSwitchThreshold(config: OcxConfig, accountId: string): number {
+  return effectiveAnthropicAccountThreshold(config, getAccountSet(PROVIDER)?.accounts.find(row => row.id === accountId));
+}
+
 /** Strict parse for management APIs — returns null instead of defaulting. */
 export function parseAccountPoolQuotaWindow(raw: unknown): OcxAccountPoolQuotaWindow | null {
   if (typeof raw === "string" && VALID_QUOTA_WINDOWS.has(raw as OcxAccountPoolQuotaWindow)) {
@@ -140,11 +168,16 @@ function parseRetryAfterMs(value: string | null | undefined, now: number): numbe
 }
 
 /** Only rejected windows constrain recovery; all must reopen, so take the latest reset. */
-function parseRateLimitResetMs(headers: AnthropicRateLimitHeaders | null | undefined, now: number): number | undefined {
+function parseRateLimitReset(
+  headers: AnthropicRateLimitHeaders | null | undefined,
+  now: number,
+): { delayMs: number; rejectedQuotaWindows: AnthropicQuotaWindow[] } | undefined {
   if (!headers) return undefined;
   let latest: number | undefined;
-  for (const window of ["5h", "7d"] as const) {
+  const rejectedQuotaWindows: AnthropicQuotaWindow[] = [];
+  for (const [window, quotaWindow] of [["5h", "five-hour"], ["7d", "weekly"]] as const) {
     if (headers.get(`anthropic-ratelimit-unified-${window}-status`)?.trim() !== "rejected") continue;
+    rejectedQuotaWindows.push(quotaWindow);
     const resetSeconds = Number(headers.get(`anthropic-ratelimit-unified-${window}-reset`)?.trim());
     if (!Number.isFinite(resetSeconds) || resetSeconds <= 0) continue;
     const resetAt = resetSeconds * 1000;
@@ -152,7 +185,55 @@ function parseRateLimitResetMs(headers: AnthropicRateLimitHeaders | null | undef
     if (latest === undefined || resetAt > latest) latest = resetAt;
   }
   if (latest === undefined) return undefined;
-  return latest - now;
+  return { delayMs: latest - now, rejectedQuotaWindows };
+}
+
+export type AnthropicCooldownRecoveryClaim = Readonly<{
+  accountId: string;
+  cooldownGeneration: number;
+  claimedAt: number;
+}>;
+
+export type AnthropicCooldownRecoverySettlement = "cleared" | "retained" | "superseded";
+
+/**
+ * Capture the exact reset-derived refusal a fresh usage probe is allowed to recover.
+ *
+ * The generation fence matters because the usage request is asynchronous: a newer 429 may
+ * arrive while it is in flight, and an older answer must never erase that newer refusal.
+ */
+export function captureAnthropicCooldownRecovery(
+  accountId: string,
+  now = Date.now(),
+): AnthropicCooldownRecoveryClaim | null {
+  const entry = upstreamHealth.get(accountId);
+  if (!entry || entry.cooldownUntil <= now || entry.cooldownSource !== "reset-derived") return null;
+  return { accountId, cooldownGeneration: entry.cooldownGeneration, claimedAt: now };
+}
+
+/**
+ * Clear only the claimed reset-derived cooldown when a fresh, complete usage result proves
+ * headroom in every window that upstream previously reported as rejected.
+ */
+export function settleAnthropicCooldownRecovery(
+  claim: AnthropicCooldownRecoveryClaim,
+  quota: ProviderQuota,
+): AnthropicCooldownRecoverySettlement {
+  const entry = upstreamHealth.get(claim.accountId);
+  if (!entry || entry.cooldownSource !== "reset-derived"
+    || entry.cooldownGeneration !== claim.cooldownGeneration
+    || anthropicCooldownGeneration(claim.accountId) !== claim.cooldownGeneration
+    || !Number.isFinite(quota.updatedAt) || quota.updatedAt < claim.claimedAt) return "superseded";
+  const windows = entry.rejectedQuotaWindows;
+  if (!windows?.length) return "retained";
+  const recovered = windows.every(window => {
+    const percent = window === "five-hour" ? quota.fiveHourPercent : quota.weeklyPercent;
+    return typeof percent === "number" && Number.isFinite(percent) && percent >= 0 && percent < 100;
+  });
+  if (!recovered) return "retained";
+  upstreamHealth.delete(claim.accountId);
+  noteAnthropicCooldownMutation(claim.accountId);
+  return "cleared";
 }
 
 export function getAnthropicAccountHealthSnapshot(
@@ -163,13 +244,16 @@ export function getAnthropicAccountHealthSnapshot(
   if (!entry) return null;
   if (entry.cooldownUntil <= now) {
     upstreamHealth.delete(accountId);
+    noteAnthropicCooldownMutation(accountId);
     return null;
   }
   return { cooldownUntil: entry.cooldownUntil, cooldownSource: entry.cooldownSource };
 }
 
 export function clearAnthropicAccountCooldown(accountId: string): boolean {
-  return upstreamHealth.delete(accountId);
+  const cleared = upstreamHealth.delete(accountId);
+  if (cleared) noteAnthropicCooldownMutation(accountId);
+  return cleared;
 }
 
 export function sweepExpiredAnthropicRoutingHealth(now = Date.now()): number {
@@ -177,6 +261,7 @@ export function sweepExpiredAnthropicRoutingHealth(now = Date.now()): number {
   for (const [accountId, health] of upstreamHealth) {
     if (health.cooldownUntil > now) continue;
     upstreamHealth.delete(accountId);
+    noteAnthropicCooldownMutation(accountId);
     removed += 1;
   }
   return removed;
@@ -185,6 +270,7 @@ export function sweepExpiredAnthropicRoutingHealth(now = Date.now()): number {
 /** Test / logout helper. */
 export function clearAnthropicAccountPoolState(): void {
   upstreamHealth.clear();
+  clearAnthropicCooldownGenerations();
   sessionAffinity.clear();
   manualPreference = undefined;
   quorumCache = null;
@@ -266,7 +352,7 @@ export function getEligibleAnthropicAccounts(now = Date.now()): string[] {
   if (!set) return [];
   return set.accounts
     .filter(account =>
-      account.needsReauth !== true
+      account.paused !== true && account.needsReauth !== true
       && !isCooled(account.id, now)
       && isPoolCredentialUsable(account.id, now))
     .map(account => account.id);
@@ -301,6 +387,25 @@ export function getEligibleAnthropicAccounts(now = Date.now()): string[] {
 const QUORUM_CACHE_TTL_MS = 2_000;
 
 let quorumCache: { value: boolean; readAt: number } | null = null;
+// Pause changes eligibility, not health. Do not reset cooldowns or cancel sent turns.
+subscribeOAuthAccountPauseChanges(provider => { if (provider === PROVIDER) quorumCache = null; });
+// A threshold write must fence in-flight automatic proposals, but it does not
+// revoke an operator's one-dispatch choice. Rebase only that still-owned choice;
+// an intervening account change clears it, so an ABA selection is not resurrected.
+subscribeOAuthAccountRoutingPolicyChanges(event => {
+  if (event.provider !== PROVIDER || !manualPreference) return;
+  if (manualPreference.accountId !== event.before.accountId
+    || manualPreference.revision !== event.before.revision) return;
+  manualPreference = event.after.accountId === manualPreference.accountId ? { ...event.after } : null;
+});
+// Any non-policy selection generation supersedes the pending one-shot choice.
+// Threshold mutations rebase it first, before this generic notification runs.
+subscribeAccountSelections(event => {
+  if (event.provider !== PROVIDER || event.kind !== "oauth" || !manualPreference) return;
+  const current = captureOAuthAccountSelection(PROVIDER);
+  if (current?.accountId !== manualPreference.accountId
+    || current.revision !== manualPreference.revision) manualPreference = null;
+});
 
 /**
  * Whether a 429 has somewhere to go: two or more accounts that could serve traffic if asked.
@@ -331,7 +436,7 @@ export function hasAnthropicFailoverQuorum(now = Date.now()): boolean {
   if (set) {
     let usable = 0;
     for (const account of set.accounts) {
-      if (account.needsReauth === true) continue;
+      if (account.paused === true || account.needsReauth === true) continue;
       if (!isPoolCredentialUsable(account.id, now)) continue;
       if (++usable >= 2) { value = true; break; }
     }
@@ -355,8 +460,8 @@ export function getAnthropicPoolRetryAfterSeconds(now = Date.now(), decision: An
     && !getEligibleAnthropicAccounts(now).some(id => decision.accounts.includes(id));
   let earliest: number | null = null;
   for (const account of set.accounts) {
+    if (account.paused === true || account.needsReauth === true || !isPoolCredentialUsable(account.id, now)) continue;
     if (decision && !fallbackExpanded && !decision.accounts.includes(account.id)) continue;
-    if (fallbackExpanded && (account.needsReauth === true || !isPoolCredentialUsable(account.id, now))) continue;
     const snap = getAnthropicAccountHealthSnapshot(account.id, now);
     if (!snap?.cooldownUntil) continue;
     if (earliest === null || snap.cooldownUntil < earliest) earliest = snap.cooldownUntil;
@@ -388,8 +493,15 @@ function compareScoredAccounts(a: ScoredAccount, b: ScoredAccount): number {
 function pickLowestUsage(config: OcxConfig, excludeId: string | undefined, now: number, decision: AnthropicRouteDecision | null = null): string | null {
   const window = anthropicQuotaWindow(anthropicAccountPoolConfig(config));
   const unfiltered = routeCandidates(getEligibleAnthropicAccounts(now), decision).filter(id => id !== excludeId);
-  const available = window === "weekly" ? unfiltered.filter(id => !exhausted5h(id)) : unfiltered;
-  const eligible = available.length > 0 ? available : unfiltered;
+  const available = window === "weekly" ? unfiltered.filter(id => !exhausted5h(id)
+    || isAnthropicAccountPoolEnabled(config) && anthropicAccountAutoSwitchThreshold(config, id) === 0) : unfiltered;
+  const availableOrFallback = available.length > 0 ? available : unfiltered;
+  // Thresholds are preferences, never eligibility. Keep the old lowest-usage fallback
+  // when every candidate is drained, and keep pool-off reactive recovery policy inert.
+  const hasKnownUnderThreshold = isAnthropicAccountPoolEnabled(config)
+    && availableOrFallback.some(id => hasKnownUsage(config, id) && isActiveUnderFillFirstThreshold(config, id));
+  const eligible = hasKnownUnderThreshold
+    ? availableOrFallback.filter(id => isActiveUnderFillFirstThreshold(config, id)) : availableOrFallback;
   if (eligible.length === 0) return null;
   const scored: ScoredAccount[] = eligible.map(accountId => ({
     accountId,
@@ -422,7 +534,8 @@ function pickNextFillFirstAnthropicAccount(
   decision: AnthropicRouteDecision | null,
 ): string | null {
   const window = anthropicQuotaWindow(anthropicAccountPoolConfig(config));
-  const available = window === "weekly" ? eligible.filter(id => !exhausted5h(id)) : eligible;
+  const available = window === "weekly" ? eligible.filter(id => !exhausted5h(id)
+    || anthropicAccountAutoSwitchThreshold(config, id) === 0) : eligible;
   const candidates = available.length > 0 ? available : eligible;
   if (candidates.length === 0) return null;
   const routeOrder = usesDeclaredRouteOrder(eligible, decision);
@@ -486,6 +599,7 @@ export type AnthropicAccountSelectionReason =
   | "manual"
   | "fill-first"
   | "none"
+  | "paused"
   | "all-cooled";
 
 export interface AnthropicAccountSelection {
@@ -503,7 +617,7 @@ function anthropicPoolStrategy(config: OcxConfig): OcxAccountPoolRotationStrateg
 }
 
 function isActiveUnderFillFirstThreshold(config: OcxConfig, accountId: string): boolean {
-  const threshold = anthropicAutoSwitchThreshold(config);
+  const threshold = anthropicAccountAutoSwitchThreshold(config, accountId);
   if (threshold <= 0) return true;
   const window = anthropicQuotaWindow(anthropicAccountPoolConfig(config));
   if (window === "weekly" && exhausted5h(accountId)) return false;
@@ -568,7 +682,7 @@ function pickUnboundStrategyAccount(
 
 /**
  * Resolve which Anthropic OAuth account should serve this session.
- * When the pool is disabled, always returns the store's active account.
+ * When the pool is disabled, retain the active account unless the operator paused it.
  */
 export function resolveAnthropicAccountForSession(
   sessionKey: string | null | undefined,
@@ -579,6 +693,11 @@ export function resolveAnthropicAccountForSession(
   pruneExpiredAffinity(now);
   const set = getAccountSet(PROVIDER);
   if (!set || set.accounts.length === 0) return { accountId: null, reason: "none", ...(decision ? { routePosition: decision.position } : {}) };
+  const scoped = decision && !decision.fallback
+    ? set.accounts.filter(account => decision.accounts.includes(account.id)) : set.accounts;
+  if (scoped.length > 0 && scoped.every(account => account.paused === true)) {
+    return { accountId: null, reason: "paused", routePosition: decision?.position };
+  }
 
   if (manualPreference === undefined) {
     manualPreference = set.selectionRevision !== undefined
@@ -586,23 +705,24 @@ export function resolveAnthropicAccountForSession(
       : null;
   }
 
-  if (!isAnthropicAccountPoolEnabled(config)) {
-    return { accountId: set.activeAccountId, reason: "pool-disabled" };
+  const eligible = routeCandidates(getEligibleAnthropicAccounts(now), decision);
+  if (eligible.length === 0) {
+    // Pause, removal and reauthentication are not cooldown evidence. Classify only
+    // usable members of this strict route (or the ordinary pool after fallback widens).
+    const recoverable = set.accounts.filter(account =>
+      (!decision || decision.fallback || decision.accounts.includes(account.id))
+      && account.paused !== true && account.needsReauth !== true && isPoolCredentialUsable(account.id, now));
+    const cooled = recoverable.length > 0 && recoverable.every(account => isCooled(account.id, now));
+    if (cooled || decision) return { accountId: null, reason: cooled ? "all-cooled" : "none", routePosition: decision?.position };
   }
 
-  const eligible = routeCandidates(getEligibleAnthropicAccounts(now), decision);
-  if (decision && eligible.length === 0) {
-    let cooled: boolean;
-    if (decision.fallback) {
-      // A removed route member is not a candidate, but fallback can still use the
-      // ordinary pool once those accounts recover. Only usable stored accounts count.
-      const ordinary = set.accounts.filter(account =>
-        account.needsReauth !== true && isPoolCredentialUsable(account.id, now));
-      cooled = ordinary.length > 0 && ordinary.every(account => isCooled(account.id, now));
-    } else {
-      cooled = decision.accounts.every(id => set.accounts.some(account => account.id === id && isCooled(id, now)));
+  if (!isAnthropicAccountPoolEnabled(config)) {
+    const active = set.accounts.find(account => account.id === set.activeAccountId);
+    // Disabled proactive rotation does not authorize a paused slot or an entirely cooled pool.
+    if (active?.paused || isCooled(set.activeAccountId, now)) {
+      return { accountId: eligible[0] ?? null, reason: eligible.length > 0 ? "only-eligible" : "none" };
     }
-    return { accountId: null, reason: cooled ? "all-cooled" : "none", routePosition: decision.position };
+    return { accountId: set.activeAccountId, reason: "pool-disabled" };
   }
 
   // A manual choice is a one-dispatch preference, not a lower-priority quota hint.
@@ -626,7 +746,7 @@ export function resolveAnthropicAccountForSession(
   if (key) {
     const affined = sessionAffinity.get(key);
     if (affined && now - affined.lastUsedAt <= AFFINITY_IDLE_TTL_MS) {
-      const stillThere = set.accounts.some(a => a.id === affined.accountId && a.needsReauth !== true);
+      const stillThere = set.accounts.some(a => a.id === affined.accountId && a.paused !== true && a.needsReauth !== true);
       const stillUsable = stillThere && !isCooled(affined.accountId, now)
         && isPoolCredentialUsable(affined.accountId, now);
       if (stillUsable && eligible.includes(affined.accountId)) {
@@ -656,7 +776,7 @@ export function resolveAnthropicAccountForSession(
     return { accountId: strategyPick.accountId, reason: strategyPick.reason, routePosition: decision?.position };
   }
 
-  const threshold = anthropicAutoSwitchThreshold(config);
+  const threshold = anthropicAccountAutoSwitchThreshold(config, set.activeAccountId);
   const activeOk = set.accounts.some(a => a.id === set.activeAccountId && a.needsReauth !== true)
     && !isCooled(set.activeAccountId, now)
     && eligible.includes(set.activeAccountId);
@@ -694,13 +814,36 @@ export function resolveAnthropicAccountForSession(
   }
 
   if (!accountId) {
-    const anyCooled = set.accounts.some(a => (!decision || decision.accounts.includes(a.id)) && isCooled(a.id, now));
+    const anyCooled = set.accounts.some(a => !a.paused && (!decision || decision.accounts.includes(a.id)) && isCooled(a.id, now));
     return { accountId: null, reason: anyCooled ? "all-cooled" : "none", routePosition: decision?.position };
   }
 
   return { accountId, reason, routePosition: decision?.position };
 }
 
+/** Shared local refusal policy for Responses and native Messages after asynchronous waits. */
+export async function resolveAnthropicDispatchAccountId(
+  config: OcxConfig,
+  sessionKey: string | null = null,
+  decision: AnthropicRouteDecision | null = null,
+): Promise<string> {
+  const now = Date.now();
+  const selection = resolveAnthropicAccountForSession(sessionKey, config, now, decision);
+  if (selection.reason === "all-cooled") {
+    throw new AnthropicAccountCooldownError(getAnthropicPoolRetryAfterSeconds(now, decision), decision?.position);
+  }
+  if (selection.reason === "paused" || !selection.accountId || !getEligibleAnthropicAccounts(now).includes(selection.accountId)) {
+    const { OAuthAccountPausedError, OAuthLoginRequiredError } = await import("./index");
+    const active = getAccountSet(PROVIDER)?.activeAccountId;
+    // Pool-off fresh admission resolves the active credential first. Preserve that
+    // paused-active refusal when no usable survivor could take over from it.
+    if (selection.reason === "paused" || (!isAnthropicAccountPoolEnabled(config) && active
+      && getAccountCredentialWithStatus(PROVIDER, active)?.paused)) throw new OAuthAccountPausedError();
+    throw new OAuthLoginRequiredError(PROVIDER);
+  }
+  return selection.accountId;
+}
+
 export function bindAnthropicSessionAffinity(
   sessionKey: string | null | undefined,
   accountId: string,
@@ -736,50 +879,68 @@ export function rotateAnthropicAccountOn429(
   rateLimitHeaders?: AnthropicRateLimitHeaders | null,
   decision: AnthropicRouteDecision | null = null,
 ): string | null {
+  if (!recordAnthropicAccount429(config, failedAccountId, retryAfterHeader, now, rateLimitHeaders)) return null;
+
+  // The pool's strategy is a PROACTIVE policy. When the pool is disabled, reactive
+  // presence-only recovery must not silently reactivate round-robin/fill-first merely
+  // because those dormant values remain in config. The quota picker is the neutral
+  // recovery policy already used by the default strategy.
+  const next = isAnthropicAccountPoolEnabled(config)
+    ? pickAlternateAnthropicAccount(config, failedAccountId, now, decision)
+    : pickLowestUsage(config, failedAccountId, now);
+  if (!next) {
+    console.warn(`[anthropic-pool] ${decision ? `route:#${decision.position} ` : ""}no eligible replacement; returning 429`);
+    return null;
+  }
+
+  console.warn(
+    `[anthropic-pool] ${decision ? `route:#${decision.position} ` : ""}429 on ${formatAnthropicAccountOrdinal(failedAccountId)}; failing over to ${formatAnthropicAccountOrdinal(next)}`,
+  );
+  return next;
+}
+
+/** Record the account refusal even when this request has no remaining retry sends. */
+export function recordAnthropicAccount429(
+  config: OcxConfig,
+  failedAccountId: string,
+  retryAfterHeader: string | null | undefined,
+  now = Date.now(),
+  rateLimitHeaders?: AnthropicRateLimitHeaders | null,
+): boolean {
   // Reactive 429 failover is NOT gated on the pool flag. That flag buys PROACTIVE routing --
   // session affinity, quota-ranked new-session selection, autoSwitchThreshold, strategy -- all
   // of which move a HEALTHY request and stay opt-in. Rotating away from an account upstream has
   // just rate-limited is a different thing: it only ever runs after a refusal, and stranding a
   // 429 while a second logged-in account sits idle is a defect, not a configuration choice.
   // Presence is the activation rule, the same one an apiKeyPool of two keys already uses.
-  if (!isAnthropicAccountPoolEnabled(config) && !hasAnthropicFailoverQuorum(now)) return null;
+  // A sent turn may finish after its account is paused; its one remaining successor is
+  // still a valid reactive recovery even though the current unpaused quorum is now one.
+  if (!isAnthropicAccountPoolEnabled(config) && !hasAnthropicFailoverQuorum(now)
+    && !getAccountCredentialWithStatus(PROVIDER, failedAccountId)?.paused) return false;
 
   // Retry-After first: it is the header written FOR this decision. The rejected window's
   // reset is the fallback, because a 429 that omits Retry-After still carries it -- and
   // without that fallback such a refusal cools for the 60s default and the exhausted
   // account is back in the rotation a minute later.
   const parsedRetry = parseRetryAfterMs(retryAfterHeader, now);
-  const resetDerived = parsedRetry === undefined ? parseRateLimitResetMs(rateLimitHeaders, now) : undefined;
-  const cooldownMs = parsedRetry ?? resetDerived ?? DEFAULT_COOLDOWN_MS;
+  const resetDerived = parsedRetry === undefined ? parseRateLimitReset(rateLimitHeaders, now) : undefined;
+  const cooldownMs = parsedRetry ?? resetDerived?.delayMs ?? DEFAULT_COOLDOWN_MS;
+  const cooldownGeneration = noteAnthropicCooldownMutation(failedAccountId);
   upstreamHealth.set(failedAccountId, {
     cooldownUntil: now + cooldownMs,
     cooldownSource: parsedRetry !== undefined
       ? "retry-after"
       : resetDerived !== undefined ? "reset-derived" : "default",
+    ...(resetDerived ? { rejectedQuotaWindows: resetDerived.rejectedQuotaWindows } : {}),
+    cooldownGeneration,
   });
   sweepExpiredOnWrite(now);
   clearAnthropicSessionAffinityForAccount(failedAccountId);
   notePoolRotationFailure(POOL_KEY_ANTHROPIC, failedAccountId);
-  // A rotation means the roster in use just changed; do not answer the next activation question
-  // from a count read taken before the failure.
+  // The refused account changed the eligible roster even when no retry send remains.
   quorumCache = null;
 
-  // The pool's strategy is a PROACTIVE policy. When the pool is disabled, reactive
-  // presence-only recovery must not silently reactivate round-robin/fill-first merely
-  // because those dormant values remain in config. The quota picker is the neutral
-  // recovery policy already used by the default strategy.
-  const next = isAnthropicAccountPoolEnabled(config)
-    ? pickAlternateAnthropicAccount(config, failedAccountId, now, decision)
-    : pickLowestUsage(config, failedAccountId, now);
-  if (!next) {
-    console.warn(`[anthropic-pool] ${decision ? `route:#${decision.position} ` : ""}no eligible replacement; returning 429`);
-    return null;
-  }
-
-  console.warn(
-    `[anthropic-pool] ${decision ? `route:#${decision.position} ` : ""}429 on ${formatAnthropicAccountOrdinal(failedAccountId)}; failing over to ${formatAnthropicAccountOrdinal(next)}`,
-  );
-  return next;
+  return true;
 }
 
 export interface AnthropicSelectionRoutingOptions {
@@ -813,7 +974,7 @@ export function commitAnthropicSelectionRouting(
   committed: OAuthAccountSelection,
   options: AnthropicSelectionRoutingOptions,
 ): boolean {
-  if (committed.accountId !== accountId || (options.routeDecision
+  if (getAccountCredentialWithStatus(PROVIDER, accountId)?.paused || committed.accountId !== accountId || (options.routeDecision
     && !routeCandidates(getEligibleAnthropicAccounts(), options.routeDecision).includes(accountId))) return false;
   const current = captureOAuthAccountSelection(PROVIDER);
   if (current?.accountId !== committed.accountId || current.revision !== committed.revision) return false;
@@ -857,7 +1018,12 @@ export function resetAnthropicRoutingForManualSelection(accountId: string): void
  * as quota probes).
  */
 export async function getAnthropicPoolAccessToken(accountId: string): Promise<string> {
-  const stored = getAccountCredential(PROVIDER, accountId);
+  const row = getAccountCredentialWithStatus(PROVIDER, accountId);
+  if (row?.paused) {
+    const { OAuthAccountPausedError } = await import("./index");
+    throw new OAuthAccountPausedError();
+  }
+  const stored = row?.credential;
   if (!stored) {
     const { OAuthLoginRequiredError } = await import("./index");
     throw new OAuthLoginRequiredError(PROVIDER);
@@ -874,6 +1040,10 @@ export async function getAnthropicPoolAccessToken(accountId: string): Promise<st
 export async function getAnthropicPoolAccessSnapshot(accountId: string): Promise<OAuthAccessSnapshot> {
   const accessToken = await getAnthropicPoolAccessToken(accountId);
   const row = getAccountCredentialWithStatus(PROVIDER, accountId);
+  if (row?.paused) {
+    const { OAuthAccountPausedError } = await import("./index");
+    throw new OAuthAccountPausedError();
+  }
   if (!row || row.needsReauth || row.credential.access !== accessToken
     || row.credential.expires <= Date.now()) {
     throw new Error("Anthropic pool credential changed during account selection");
@@ -887,6 +1057,7 @@ export async function getAnthropicPoolAccessSnapshot(accountId: string): Promise
  */
 export function canRefreshAnthropicPoolAccount(accountId: string): boolean {
   const set = getAccountSet(PROVIDER);
+  if (set?.accounts.find(account => account.id === accountId)?.paused) return false;
   const cred = getAccountCredential(PROVIDER, accountId);
   if (!cred) return false;
   if (cred.source !== "local-cli") return true;

package/src/oauth/index.ts

@@ -925,8 +925,10 @@ export async function refreshAnthropicAccountWithLock(
   const now = deps.now ?? Date.now;
   const guard = await (deps.intentLock ?? createOAuthRefreshIntentLock(provider, accountId)).acquire();
   try {
-    const stored = getAccountCredential(provider, accountId);
-    if (!stored) throw new OAuthLoginRequiredError(provider);
+    const row = getAccountCredentialWithStatus(provider, accountId);
+    if (!row) throw new OAuthLoginRequiredError(provider);
+    if (row.paused) throw new OAuthAccountPausedError();
+    const stored = row.credential;
     const account = getAccountSet(provider)?.accounts.find(candidate => candidate.id === accountId);
     const generation = credentialGeneration(stored);
     let pendingIntent = readOAuthRefreshIntent(provider, accountId);

package/src/oauth/store.ts

@@ -27,13 +27,14 @@ import { atomicWriteFileNoFollowUnclaimed } from "../config/atomic-write";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { MAX_PENDING_OAUTH_MUTATIONS } from "../lib/translator-budget";
-import { publishAccountSelection, publishOAuthAccountPauseChange } from "../lib/account-selection-events";
+import { publishAccountSelection, publishOAuthAccountPauseChange, publishOAuthAccountRoutingPolicyChange } from "../lib/account-selection-events";
 import {
   captureConfigGeneration,
   type GenerationContext,
 } from "../lib/state-store-sweeper";
 import { validateCopilotApiBaseUrl } from "./github-copilot";
 import { validateDevinApiBaseUrl } from "./devin/api-base";
+import { parseAnthropicAccountThreshold } from "./anthropic-account-threshold";
 import type { OAuthAccountSelection, OAuthCredentialSource, OAuthCredentials, ProviderAccount, ProviderAccountSet } from "./types";
 
 export type AuthStore = Record<string, ProviderAccountSet>;
@@ -626,6 +627,8 @@ function normalizeAccount(value: unknown): ProviderAccount | null {
   if (typeof candidate.alias === "string" && candidate.alias.trim()) account.alias = candidate.alias.trim();
   if (candidate.needsReauth === true) account.needsReauth = true;
   if (candidate.paused === true) account.paused = true;
+  const threshold = parseAnthropicAccountThreshold(candidate.autoSwitchThresholdOverride);
+  if (threshold !== null) account.autoSwitchThresholdOverride = threshold;
   if (typeof candidate.addedAt === "number") account.addedAt = candidate.addedAt;
   if (typeof candidate.loginId === "string"
     && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(candidate.loginId)) {
@@ -783,7 +786,7 @@ function serializeMutation<T>(work: () => Promise<T>, retainedValues: readonly u
   drainOAuthMutations();
   return result;
 }
-export function mutateStore<T>(fn:(store:AuthStore)=>T|Promise<T>, retainedValues: readonly unknown[] = [], options?: { waitMs?: number; assertBeforePersist?: () => void; scrubLegacyBackup?: (result: T) => readonly string[]; finalizeResult?: (result: T, store: AuthStore) => void }):Promise<T>{return serializeMutation(async()=>{const guard=await createOAuthFileLock({path:getAuthStoreLockPath(),staleAfterMs:30000}).acquire();try{
+export function mutateStore<T>(fn:(store:AuthStore)=>T|Promise<T>, retainedValues: readonly unknown[] = [], options?: { waitMs?: number; assertBeforePersist?: () => void; scrubLegacyBackup?: (result: T) => readonly string[]; finalizeResult?: (result: T, store: AuthStore) => void; afterPersist?: (result: T) => void }):Promise<T>{return serializeMutation(async()=>{const guard=await createOAuthFileLock({path:getAuthStoreLockPath(),staleAfterMs:30000}).acquire();try{
     const { store, hadLegacy } = loadAuthStoreInternal();
     if (hadLegacy) backupLegacyOnce();
     const selections = new Map(Object.entries(store).map(([provider, set]) => [provider, {
@@ -821,6 +824,9 @@ export function mutateStore<T>(fn:(store:AuthStore)=>T|Promise<T>, retainedValue
     options?.finalizeResult?.(result, store);
     persist(store);
     if (scrubbedProviders.length > 0) scrubLegacyBackup(scrubbedProviders);
+    // A committed observer may establish ordering before the generic selection
+    // publication, but its failure can never turn a durable write into a reported failure.
+    try { options?.afterPersist?.(result); } catch { /* The authoritative write already committed. */ }
     for (const provider of changedProviders) publishAccountSelection(provider, "oauth");
     return result;
   }finally{guard.release();}}, retainedValues, options?.waitMs);
@@ -1224,6 +1230,39 @@ export type SetAccountPausedResult =
   | { status: "unchanged"; activeAccountId: string; activeAccountChanged: boolean }
   | { status: "not-found" };
 
+/** Serialize policy with refresh/removal; stale pre-wait selection proposals must retry. */
+export async function setAnthropicAccountThreshold(
+  accountId: string,
+  threshold: number | null,
+  options: { assertBeforePersist?: () => void } = {},
+): Promise<boolean> {
+  const normalizedThreshold = threshold === null ? null : parseAnthropicAccountThreshold(threshold);
+  if (threshold !== null && normalizedThreshold === null) {
+    throw new Error("threshold must be an integer 0-100 or null");
+  }
+  const result = await mutateStore(store => {
+    const set = store.anthropic;
+    const account = set?.accounts.find(row => row.id === accountId);
+    if (!set || !account) return { status: "not-found" as const };
+    if ((account.autoSwitchThresholdOverride ?? null) === normalizedThreshold) return { status: "unchanged" as const };
+    const before = accountSelection(set);
+    if (normalizedThreshold === null) delete account.autoSwitchThresholdOverride;
+    else account.autoSwitchThresholdOverride = normalizedThreshold;
+    set.selectionRevision = randomUUID();
+    return { status: "updated" as const, before, after: accountSelection(set) };
+  }, [accountId, normalizedThreshold], { assertBeforePersist: options.assertBeforePersist, afterPersist: result => {
+    if (result.status !== "updated") return;
+    // Publish the policy-owned transition before the generic selection event. This
+    // preserves an exact previous-revision manual intent without opening an ABA gap.
+    publishOAuthAccountRoutingPolicyChange(Object.freeze({
+      provider: "anthropic",
+      before: Object.freeze(result.before),
+      after: Object.freeze(result.after),
+    }));
+  } });
+  return result.status !== "not-found";
+}
+
 /** Persist an operator pause and move an active account to the next usable unpaused slot when available. */
 export async function setAccountPaused(
   provider: string,
@@ -1323,6 +1362,7 @@ export async function replaceProviderAccountSet(
         ...(account.alias ? { alias: account.alias } : {}),
         ...(account.needsReauth ? { needsReauth: true } : {}),
         ...(account.paused ? { paused: true } : {}),
+        ...(account.autoSwitchThresholdOverride !== undefined ? { autoSwitchThresholdOverride: account.autoSwitchThresholdOverride } : {}),
         ...(account.addedAt !== undefined ? { addedAt: account.addedAt } : {}),
         ...(account.loginId ? { loginId: account.loginId } : {}),
       })),
@@ -1380,4 +1420,6 @@ export async function markAccountNeedsReauth(
 }
 
 export async function mergeAccountCredential(provider:string,accountId:string,credential:OAuthCredentials,opts:{expectedGeneration?:string;afterPrePersistRead?:()=>void|Promise<void>;assertOwnership?: (store: AuthStore) => void}={}):Promise<{superseded:false}|{superseded:true;stored:OAuthCredentials}>{const safe=normalizeCredential(credential);if(!safe)throw new Error("Refusing to persist invalid OAuth credential");return await mutateStore(async store=>{await opts.afterPrePersistRead?.();const account=store[provider]?.accounts.find(x=>x.id===accountId);if(!account)throw new Error(`OAuth account disappeared before persist: ${provider}`);if(opts.expectedGeneration!==undefined&&credentialGeneration(account.credential)!==opts.expectedGeneration)return{superseded:true,stored:account.credential};opts.assertOwnership?.(store);account.credential=safe;delete account.needsReauth;return{superseded:false};},[provider,accountId,safe,opts.expectedGeneration]);}
-export async function markAccountNeedsReauthIfGeneration(provider:string,accountId:string,generation:string,writerGeneration=captureConfigGeneration()):Promise<boolean>{const key=oauthAccountKey(provider,accountId);if(writerGeneration<lastReconciledGeneration&&!liveOAuthAccountKeys.has(key))return false;return await mutateStore(store=>{const account=store[provider]?.accounts.find(x=>x.id===accountId);if(!account?.credential||credentialGeneration(account.credential)!==generation)return false;if(writerGeneration<lastReconciledGeneration&&!liveOAuthAccountKeys.has(key))return false;account.needsReauth=true;return true;},[provider,accountId,generation]);}
+// A late refresh failure must not change an operator-paused account's health. Check under
+// the mutation lock, not before awaiting it, so a concurrent pause cannot be overwritten.
+export async function markAccountNeedsReauthIfGeneration(provider:string,accountId:string,generation:string,writerGeneration=captureConfigGeneration()):Promise<boolean>{const key=oauthAccountKey(provider,accountId);if(writerGeneration<lastReconciledGeneration&&!liveOAuthAccountKeys.has(key))return false;return await mutateStore(store=>{const account=store[provider]?.accounts.find(x=>x.id===accountId);if(!account?.credential||account.paused||credentialGeneration(account.credential)!==generation)return false;if(writerGeneration<lastReconciledGeneration&&!liveOAuthAccountKeys.has(key))return false;account.needsReauth=true;return true;},[provider,accountId,generation]);}

package/src/oauth/types.ts

@@ -90,6 +90,8 @@ export interface ProviderAccount {
   needsReauth?: boolean;
   /** Operator exclusion from generic OAuth account selection until explicitly resumed. */
   paused?: boolean;
+  /** Anthropic-only usage-switch override; absent inherits its pool default, zero disables it. */
+  autoSwitchThresholdOverride?: number;
   addedAt?: number;
 }