fix(account-pool): follow-ups from the quota pacing, model route and low-quota reviews

docs-site/src/content/docs/guides/claude-code.md

@@ -37,7 +37,7 @@ reauthentication, or threshold, then advances. It is **off by default**, shows a
 and is not battle-tested — Anthropic may restrict accounts that look like automated rotation;
 rotation does not protect against provider enforcement.
 
-To bind a model to particular stored Claude accounts, add ordered `anthropicAccountPool.routes` rules while the pool is enabled. Each rule has a safe `name`, a full case-sensitive `match` glob, an `accounts` array of stored account IDs, and optional `fallback` (default `false`). The first matching rule limits active, manual, affinity, strategy and 429 recovery picks to its accounts. Without fallback, an empty route returns a local 401, or 429 with `Retry-After` when all its declared accounts are cooling, before contacting Anthropic. The client response does not name the route; the proxy log records `route:#<n>`, where `n` is the rule’s 1-based position. `fallback: true` uses the ordinary pool only when the route has no eligible account, including its ordinary fill-first successor order; if its stored accounts are all cooling, the returned 429 uses the earliest cooldown across that expanded pool, even if a saved route account has been removed. An unmatched model follows the existing pool policy; disabling the pool leaves saved rules inactive and restores active-account and presence-driven 429 behavior. A rule is an operator allowlist, not proof of model entitlement.
+To bind a model to particular stored Claude accounts, add ordered `anthropicAccountPool.routes` rules while the pool is enabled. Each rule has a safe `name`, a full case-sensitive `match` glob, an `accounts` array of stored account IDs, and optional `fallback` (default `false`). The first matching rule limits active, manual, affinity, strategy and 429 recovery picks to its accounts. A healthy affinity outside that rule is ignored for this request but kept for other models; the routed choice does not overwrite it. Without fallback, an empty route returns a local 401, or 429 with `Retry-After` when all its declared accounts are cooling, before contacting Anthropic. The client response does not name the route; the proxy log records `route:#<n>`, where `n` is the rule’s 1-based position. `fallback: true` uses the ordinary pool only when the route has no eligible account, including its ordinary fill-first successor order; if its stored accounts are all cooling, the returned 429 uses the earliest cooldown across that expanded pool, even if a saved route account has been removed. An unmatched model follows the existing pool policy; disabling the pool leaves saved rules inactive and restores active-account and presence-driven 429 behavior. A rule is an operator allowlist, not proof of model entitlement.
 
 Operational contract when enabled:
 

docs-site/src/content/docs/reference/management-api.md

@@ -570,7 +570,7 @@ outcome fields from an older server do not establish successful recovery.
 | `PUT /api/providers/keys/alias` | Set or clear a provider-key alias | 400 invalid input; 404 provider/key missing |
 | `GET, POST, PATCH, DELETE /api/keys` | List, create, edit, or delete data-plane admission keys | 400 invalid body/id; 404 key missing |
 
-For Anthropic, `routes` is an ordered array of `{name, match, accounts, fallback?}` rules on both settings endpoints. GET and write echoes include `routes` (`null` when absent); unified DTOs expose `routes: null` for other kinds. A supplied `routes` on another kind is rejected. Omission preserves rules, `[]` matches nothing, and `null` clears them. The `accounts` values are stored IDs; removed IDs remain valid in a rule so re-adding an account can restore routing. Management responses retain the configured names; request logs identify a match only as `route:#<n>` (1-based list position).
+For Anthropic, `routes` is an ordered array of `{name, match, accounts, fallback?}` rules on both settings endpoints. GET and write echoes include `routes` (`null` when absent); unified DTOs expose `routes: null` for other kinds. A supplied `routes` on another kind is rejected. Omission preserves rules, `[]` matches nothing, and `null` clears them. The `accounts` values are stored IDs; removed IDs remain valid in a rule so re-adding an account can restore routing. Management responses retain valid configured names; request logs identify a match only as `route:#<n>` (1-based list position). If a hand-edited stored rule is invalid, both settings GETs return `routes: null` and a `routesError` diagnostic instead of presenting that rule as valid; the stored value remains available for correction. Valid or absent rules omit `routesError`.
 
 Credential list responses are deliberately masked. OAuth access tokens and complete provider API
 keys are not returned to dashboard clients.

src/codex/auth-api/pool-mode-gate.ts

@@ -134,10 +134,17 @@ export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise
       const previousDelay = previous?.identity === identityGeneration && previous.credential === credential
         ? previous.delay : 0;
       if (result.quotaRefresh) {
-        const delay = nextQuotaQueryDelay(previousDelay || undefined);
-        mainHardLockRecoveryAttempt = getMainAccountHardLockStatus(config).state === "blocked"
-          ? { identity: identityGeneration, credential, delay, after: Math.max(Date.now() + delay, queryAfter) }
-          : undefined;
+        const authStatus = result.quotaRefresh.status === "http_error"
+          ? result.quotaRefresh.httpStatus : undefined;
+        const transientAuth = (authStatus === 401 || authStatus === 403)
+          && !isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+        if (transientAuth) mainHardLockRecoveryAttempt = undefined;
+        else {
+          const delay = nextQuotaQueryDelay(previousDelay || undefined);
+          mainHardLockRecoveryAttempt = getMainAccountHardLockStatus(config).state === "blocked"
+            ? { identity: identityGeneration, credential, delay, after: Math.max(Date.now() + delay, queryAfter) }
+            : undefined;
+        }
       } else if (queryAfter > Date.now()) {
         mainHardLockRecoveryAttempt = { identity: identityGeneration, credential,
           delay: previousDelay, after: queryAfter };

src/codex/quota-query-backoff.ts

@@ -101,7 +101,14 @@ export async function fetchCodexUsage<T>(
     if (!attempt.inFlight) return;
     attempt.inFlight = false;
     if (attempts.get(key) === attempt) {
-      if (usable || response?.status === 401 || response?.status === 403) attempts.delete(key);
+      if (usable || response?.status === 401 || response?.status === 403) {
+        attempts.delete(key);
+        if (usable) {
+          sharedDeadlines.delete(pacingKey);
+          if (pacingKey !== key && attempts.get(pacingKey)?.inFlight === false)
+            attempts.delete(pacingKey);
+        }
+      }
       else {
         const at = now();
         const delay = schedule.recoveryProbe ? BASE_DELAY_MS : nextQuotaQueryDelay(previous?.delay);

src/oauth/anthropic-model-routes.ts

@@ -8,6 +8,7 @@ export interface AnthropicRouteDecision {
 }
 
 type ParseResult = { ok: true; routes: AnthropicModelRoute[] } | { ok: false; error: string };
+export type AnthropicRoutesRead = { routes: AnthropicModelRoute[] | null; routesError?: string };
 const MAX_ROUTES = 32;
 const MAX_ACCOUNTS = 32;
 const MAX_TEXT = 128;
@@ -50,6 +51,13 @@ export function parseAnthropicModelRoutes(raw: unknown): ParseResult {
   return { ok: true, routes };
 }
 
+/** A malformed hand edit stays on disk for correction, but must never look valid to readers. */
+export function readAnthropicModelRoutes(raw: unknown): AnthropicRoutesRead {
+  if (raw === undefined) return { routes: null };
+  const parsed = parseAnthropicModelRoutes(raw);
+  return parsed.ok ? { routes: parsed.routes } : { routes: null, routesError: parsed.error };
+}
+
 function matches(pattern: string, modelId: string): boolean {
   // Linear wildcard matching avoids regex backtracking on operator-declared glob strings.
   let p = 0;

src/oauth/anthropic-routing.ts

@@ -627,10 +627,14 @@ export function resolveAnthropicAccountForSession(
     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);
-      if (stillThere && eligible.includes(affined.accountId)) {
+      const stillUsable = stillThere && !isCooled(affined.accountId, now)
+        && isPoolCredentialUsable(affined.accountId, now);
+      if (stillUsable && eligible.includes(affined.accountId)) {
         return { accountId: affined.accountId, reason: "affinity", routePosition: decision?.position };
       }
-      sessionAffinity.delete(key);
+      // A model route may exclude a healthy binding only for this request. Keep it for
+      // another model; remove bindings only when the account itself became unusable.
+      if (!stillUsable) sessionAffinity.delete(key);
     }
   }
 
@@ -820,7 +824,14 @@ export function commitAnthropicSelectionRouting(
       if (picked !== accountId) seedPoolRotationAccount(POOL_KEY_ANTHROPIC, accountId);
       notePoolRotationSuccess(POOL_KEY_ANTHROPIC, accountId, limit);
     }
-    bindAnthropicSessionAffinity(options.sessionKey, accountId);
+    const key = normalizeAffinityComponent(options.sessionKey);
+    const bound = key ? sessionAffinity.get(key) : undefined;
+    const eligibleAtCommit = options.routeDecision && bound ? getEligibleAnthropicAccounts() : [];
+    const preserveExcludedAffinity = options.routeDecision && bound && bound.accountId !== accountId
+      && Date.now() - bound.lastUsedAt <= AFFINITY_IDLE_TTL_MS
+      && eligibleAtCommit.includes(bound.accountId)
+      && !routeCandidates(eligibleAtCommit, options.routeDecision).includes(bound.accountId);
+    if (!preserveExcludedAffinity) bindAnthropicSessionAffinity(options.sessionKey, accountId);
   }
   if (manualPreference === undefined || (manualPreference?.accountId === expectedSelection.accountId
     && manualPreference.revision === expectedSelection.revision)) manualPreference = null;

src/oauth/pool-settings-capability.ts

@@ -2,6 +2,7 @@ import { isGenericFailoverProvider } from "./generic-account-failover";
 import { parseAccountPoolStickyLimit, parseAccountPoolStrategy, parseCodexAccountPoolStrategy } from "./pool-kernel";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 import type { AnthropicModelRoute } from "../types/config";
+import { readAnthropicModelRoutes } from "./anthropic-model-routes";
 
 /**
  * Which pool-settings contract a provider speaks (#695, slice 1).
@@ -83,6 +84,8 @@ export interface PoolSettingsDto {
   quotaWindow: string | null;
   maxConcurrentPerAccount: number | null;
   routes: AnthropicModelRoute[] | null;
+  /** Present only when stored Anthropic routes fail validation on read. */
+  routesError?: string;
 }
 
 
@@ -176,7 +179,7 @@ export function unifiedPoolSettingsDto(
       autoSwitchThreshold: parseGenericAutoSwitchThreshold(pool.autoSwitchThreshold) ?? 80,
       quotaWindow: typeof pool.quotaWindow === "string" ? pool.quotaWindow : "five-hour",
       maxConcurrentPerAccount: null,
-      routes: pool.routes ?? null,
+      ...readAnthropicModelRoutes(pool.routes),
     };
   }
   const failover = config.providers?.[provider]?.oauthAccountFailover ?? {};

src/server/management/oauth-account-routes.ts

@@ -1,4 +1,4 @@
-import { parseAnthropicModelRoutes } from "../../oauth/anthropic-model-routes";
+import { parseAnthropicModelRoutes, readAnthropicModelRoutes } from "../../oauth/anthropic-model-routes";
 import { randomBytes, randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../../codex/catalog";
@@ -659,7 +659,7 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
       strategy: normalizeAccountPoolStrategy(pool.strategy),
       stickyLimit: normalizeAccountPoolStickyLimit(pool.stickyLimit),
       quotaWindow: normalizeAccountPoolQuotaWindow(pool.quotaWindow),
-      routes: pool.routes ?? null,
+      ...readAnthropicModelRoutes(pool.routes),
       experimental: true,
     });
   }

structure/gui-and-management-api.md

@@ -1,6 +1,6 @@
 # GUI And Management API
 
-`src/server/management/oauth-account-routes.ts` exposes Anthropic `routes` through both unified `/api/pool/settings` and legacy `/api/oauth/accounts/pool`. Omitted rules survive other setting writes, `null` clears them, and other pool kinds reject supplied rules. The unified DTO declares `routes` supported only for Anthropic and reports null otherwise. Config and management responses retain route names; request logs use only the rule’s 1-based `route:#<n>` position. `src/cli/account-extended.ts` reads, replaces and clears these rules with `ocx account routes anthropic`; the server validates content.
+`src/server/management/oauth-account-routes.ts` exposes Anthropic `routes` through both unified `/api/pool/settings` and legacy `/api/oauth/accounts/pool`. Omitted rules survive other setting writes, `null` clears them, and other pool kinds reject supplied rules. The unified DTO declares `routes` supported only for Anthropic and reports null otherwise. Both Anthropic settings GETs validate saved rules before projection: malformed hand edits yield `routes: null` plus `routesError` without changing the stored value; valid and absent rules omit that diagnostic. Config and management responses retain route names; request logs use only the rule’s 1-based `route:#<n>` position. `src/cli/account-extended.ts` reads, replaces and clears these rules with `ocx account routes anthropic`; the server validates content.
 
 
 Automatic activation retains its existing settings controls; dashboard quota queries remain independent. See the [quota activation contract](providers/openai-tiers.md#public-provider-contract).

structure/providers-and-adapters.md

@@ -1,6 +1,6 @@
 # Providers And Adapters
 
-For Anthropic OAuth, `src/oauth/anthropic-routing.ts` applies the first matching `anthropicAccountPool.routes` rule to every eligible pick. The declared account order is stable while its candidates remain eligible; active, manual, affinity, quota and strategy preferences only choose inside that set. An explicit fallback widens an empty route to the ordinary pool, and fill-first then advances in ordinary pool order from the active account. A missing eligible route fails locally without that fallback. The rules are operator allowlists, not provider entitlement evidence. Request logs use `route:#<n>` for the 1-based rule position, not the operator name.
+For Anthropic OAuth, `src/oauth/anthropic-routing.ts` applies the first matching `anthropicAccountPool.routes` rule to every eligible pick. The declared account order is stable while its candidates remain eligible; active, manual, affinity, quota and strategy preferences only choose inside that set. A healthy session affinity outside a model route is ignored for that request and retained for later unrouted or differently routed models; the routed commit does not overwrite it. An explicit fallback widens an empty route to the ordinary pool, and fill-first then advances in ordinary pool order from the active account. A missing eligible route fails locally without that fallback. The rules are operator allowlists, not provider entitlement evidence. Request logs use `route:#<n>` for the 1-based rule position, not the operator name.
 
 
 The coding-agent stream parser buffers each tool-use block by its content-block index

structure/providers/openai-tiers.md

@@ -25,8 +25,9 @@ receive its settled result; only a confirmed reset-credit consume selects the se
 proof epoch. Its failure deadline is also recorded for ordinary main reads under the same credential,
 so the epoch never bypasses pacing. Holding a native-main shared claim by itself does not bypass it.
 Outside Pool mode, main usage reads retain their independent forced-refresh behavior.
-A valid Retry-After can extend the delay under the existing bounded cooldown parser. Usable usage clears
-failure pacing; 401/403 retain the existing authentication recovery policy. Keys are scoped to
+A valid Retry-After can extend the delay under the existing bounded cooldown parser. Usable published
+usage, including a post-reset epoch result, clears failure pacing for the same credential only;
+401/403 retain the existing authentication recovery policy. Keys are scoped to
 configuration home, config generation and credential generation; no credentials are retained.
 Deferred calls publish neither fresh quota nor dispatch proof and do not advance quota timestamps.
 The bounded process-local failure cache resets on restart; active reads are never evicted to admit
@@ -333,6 +334,8 @@ the physical bearer is reconciled before checking the delay, and late results ca
 a replacement credential. A longer valid Retry-After from any main usage reader is checked for the
 current credential before the recovery worker takes a profile lease or prepares a token; a replacement
 credential has a separate key and may proceed immediately.
+Nonterminal 401/403 responses do not arm the successful-but-blocked recovery delay; the next
+sweep may retry, while terminal authentication failure keeps its reauth quarantine.
 Only fresh lower usage releases the lock; no inference or reset-credit consumption is added. Failed,
 missing, non-finite or out-of-range readings do not release the block. Policy validation precedes
 legacy clamping. Supplementary monthly data cannot become the fallback governing window without a

tests/adapters/anthropic/anthropic-model-routes.test.ts

@@ -4,9 +4,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { acquireOwnedSpendHome } from "../../helpers/owned-spend-home";
 import { removeTreeWithRetry } from "../../helpers/remove-tree";
-import { clearAnthropicAccountPoolState, bindAnthropicSessionAffinity, getAnthropicPoolRetryAfterSeconds, resolveAnthropicAccountForSession, rotateAnthropicAccountOn429 } from "../../../src/oauth/anthropic-routing";
+import { clearAnthropicAccountPoolState, bindAnthropicSessionAffinity, getAnthropicPoolAccessSnapshot, getAnthropicPoolRetryAfterSeconds, promoteAnthropicActiveAccount, resolveAnthropicAccountForSession, rotateAnthropicAccountOn429 } from "../../../src/oauth/anthropic-routing";
 import { parseAnthropicModelRoutes, resolveAnthropicModelRoute } from "../../../src/oauth/anthropic-model-routes";
-import { getAccountSet, saveCredential, setActiveAccount } from "../../../src/oauth/store";
+import { captureOAuthAccountSelection, getAccountSet, saveCredential, setActiveAccount } from "../../../src/oauth/store";
 import { clearAccountQuotaCache, setCachedProviderAccountQuotaForTests } from "../../../src/providers/quota";
 import { clearResponseStateForTests } from "../../../src/responses/state";
 import { handleResponses } from "../../../src/server/responses";
@@ -237,6 +237,25 @@ test("an out-of-route affinity and manual active account cannot preempt the mode
   expect(sends[0]).not.toContain("synthetic-access-0");
 });
 
+test("a routed pick preserves an excluded session affinity for a later unrouted model", async () => {
+  const ids = await seed();
+  const cfg = config(ids, () => answer());
+  bindAnthropicSessionAffinity("same-session", ids[0]!);
+  const route = resolveAnthropicModelRoute(cfg, "claude-sonnet-4-5").decision!;
+  const expected = captureOAuthAccountSelection("anthropic");
+  const routed = resolveAnthropicAccountForSession("same-session", cfg, Date.now(), route);
+  expect(route.accounts).toContain(routed.accountId!);
+  expect(routed.accountId).not.toBe(ids[0]);
+  const snapshot = await getAnthropicPoolAccessSnapshot(routed.accountId!);
+  expect(await promoteAnthropicActiveAccount(routed.accountId!, expected, {
+    config: cfg, sessionKey: "same-session", reason: routed.reason,
+    routeDecision: route, expectedCredentialGeneration: snapshot.generation,
+  })).not.toBeNull();
+
+  const unrouted = resolveAnthropicAccountForSession("same-session", cfg);
+  expect(unrouted).toMatchObject({ accountId: ids[0], reason: "affinity" });
+});
+
 test("disabled routes do not change the historical active-account selection", async () => {
   const ids = await seed();
   const cfg = config(ids, () => answer());